Update AI instructions with layout patterns and testing guidance

.github/copilot-instructions.md

@@ -41,7 +41,7 @@ npm run screenshots:all    # All themes
 - `css/` - SCSS framework (`@microsoft/atlas-css`) - tokens, mixins, atomics, components
 - `js/` - TypeScript behaviors (`@microsoft/atlas-js`) - behaviors, elements, utilities
 - `site/` - Documentation site built with Parcel and Markdown
-- `site/src/scaffold` - Contains SCSS and JS that is not appropriate for publishing in our npm packages and is for the site only
+- `site/src/scaffold` - Contains HTML page templates, SCSS, and JS that is not appropriate for publishing in our npm packages and is for the site only
 - `integration/` - Playwright tests for visual regression and accessibility
 - `extension/` - VS Code extension for class IntelliSense
 - `plugins/stylelint-config-atlas/` - Shared Stylelint configuration

.github/instructions/css.instructions.md

@@ -186,4 +186,18 @@ Screen sizes are represented by one of the following strings:
 
 Use a mobile first approach when using Atomics, including the universally applicable class (i.e. the one that does not have a screensize at the end), and when necessary overwrite its values on larger screens.
 
+## CSS Custom Properties for Component Customization
+
+Complex components like `layout` expose CSS custom properties so consumers can tune dimensions without rewriting grid templates. These properties are declared in `src/tokens/` and given default values in the component file. For example, the layout component defines properties such as `--layout-menu-expanded-target-width`, `--layout-aside-expanded-target-width`, and `--layout-flyout-width-desktop`.
+
+When adding customizable dimensions to a component:
+
+1. Declare the property name variable in the relevant tokens file with `!default`.
+2. Set a default value on the component's root selector using `var()`.
+3. Document the available custom properties in the site documentation.
+
+## Layout Modifier Classes
+
+Layout modifier classes (e.g., `.layout-menu-collapsed`, `.layout-aside-collapsed`, `.layout-flyout-active`, `.layout-constrained`) are applied directly to the `.layout` element rather than being nested inside it. This keeps specificity flat and allows the modifiers to adjust CSS custom property values at the component root, which then cascade into the grid definitions.
+
 ## Remember! Adding any new CSS in the /css folder means updating documentation in the /site folder too.

.github/instructions/integration.instructions.md

@@ -68,9 +68,31 @@ Before running tests:
 1. Install Playwright: `npx playwright install`
 2. Start the site server: `npm run start` (in site folder, port 1111)
 
+## Testing CSS Component Behavior
+
+Some integration tests verify CSS-driven behavior (e.g., layout collapsing, height constraints) rather than JavaScript behavior. These tests work by:
+
+1. **Navigating to the component's documentation page** — The site's interactive controls (buttons with `data-*` attributes like `data-set-layout`, `data-menu-collapse-toggle`, `data-aside-collapse-toggle`) toggle CSS classes on the page.
+2. **Measuring CSS state** — Use `page.evaluate()` to read computed dimensions (e.g., `getBoundingClientRect().width`, `scrollHeight`) before and after toggling.
+3. **Asserting the change** — Compare measurements to verify the CSS took effect (e.g., aside width decreased after collapse).
+
+### Viewport-Based Test Skipping
+
+Tests that depend on a specific screen size use `testInfo.project.name` to skip:
+
+```typescript
+test.skip(
+	testInfo.project.name !== 'Widescreen Chromium',
+	'Skip test if display screen is not widescreen'
+);
+```
+
+Tag test titles with `@desktop` or `@narrow` to indicate the intended viewport.
+
 ## When Making Changes
 
 1. Add new pages to accessibility test list
 2. Update visual baselines if intentional visual changes are made
 3. Write integration tests for new JavaScript behaviors
-4. Run full test suite before submitting changes
+4. When adding CSS modifier classes (e.g., collapse toggles), add integration tests that verify the modifier's visual effect at the appropriate viewport size
+5. Run full test suite before submitting changes

.github/instructions/site.instructions.md

@@ -34,6 +34,19 @@ site/
 - `npm run toc` - Regenerate table of contents
 - `npm run lint` - Run ESLint on TypeScript files
 
+## Scaffold Templates and Scripts
+
+The `site/src/scaffold/` folder contains more than just SCSS — it holds the **HTML page templates** (e.g., `standard.html`, `token.html`) that wrap every documentation page, and **TypeScript scripts** in `site/src/scaffold/scripts/` that power interactive demos on documentation pages.
+
+Scaffold scripts handle behaviors like:
+
+- Toggling layout classes (e.g., switching between `layout-holy-grail` and `layout-twin`)
+- Collapsing/expanding menu and aside containers
+- Full-screen toggle for component demos
+- Height constraint toggling
+
+These scripts are site-only (not published in `@microsoft/atlas-js`). When adding new interactive controls to documentation pages, add the behavior script here and wire it up via `data-*` attributes in the HTML templates.
+
 ## Content Guidelines
 
 ### Markdown Files