@neuravision/construct 2.0.3 → 2.1.1

package/components/switch.css

@@ -43,7 +43,7 @@
 
 @media (hover: hover) {
   .ct-switch__input:not(:disabled):hover {
-    background: color-mix(in srgb, var(--color-border-strong) 85%, black);
+    background: color-mix(in srgb, var(--color-border-strong) 85%, var(--color-text-primary));
   }
 
   .ct-switch__input:checked:not(:disabled):hover {
@@ -61,13 +61,14 @@
   outline-offset: 2px;
 }
 
-/* Invisible touch-target expansion (WCAG 2.5.8: 44×44px minimum) */
+/* Construct 44×44 target policy: meets the size in WCAG 2.2 SC 2.5.5
+   (AAA) and exceeds the AA minimum in SC 2.5.8. */
 @media (pointer: coarse) {
   .ct-switch__input::before {
     content: '';
     position: absolute;
     inset-block: calc((var(--ct-switch-height) - 44px) / 2);
-    inset-inline: 0;
+    inset-inline: calc((var(--ct-switch-width) - 44px) / 2);
   }
 }
 

package/components/tooltip.css

@@ -41,16 +41,20 @@
   --_tt-open: 1;
   opacity: 1;
   visibility: visible;
+  pointer-events: auto;
   transition: opacity var(--duration-fast) var(--easing-standard),
     transform var(--duration-fast) var(--easing-standard),
     visibility 0s linear 0s;
 }
 
 @media (hover: hover) {
+  .ct-tooltip[data-state='open'] .ct-tooltip__content,
+  .ct-tooltip:focus-within .ct-tooltip__content,
   .ct-tooltip:hover .ct-tooltip__content {
     --_tt-open: 1;
     opacity: 1;
     visibility: visible;
+    pointer-events: auto;
     transition: opacity var(--duration-fast) var(--easing-standard),
       transform var(--duration-fast) var(--easing-standard),
       visibility 0s linear 0s;

package/docs/architecture.md

@@ -0,0 +1,79 @@
+# Construct Architecture
+
+Construct separates reusable design decisions, visual component contracts, interaction behavior, and product integration. That separation lets a vanilla page and a framework application share the same public contract without coupling Construct to either runtime.
+
+```text
+primitive tokens
+      │
+      ▼
+semantic tokens ─── built-in/custom theme scopes
+      │
+      ▼
+component tokens ── stable component decisions
+      │
+      ├──────────────► component CSS ──► DOM + ARIA/data state
+      │                                      ▲
+      └──────────────► JS/TS token exports   │
+                                             │
+optional headless behaviors ─────────────────┘
+                                             │
+framework adapter / application data ───────┘
+```
+
+## Token layers
+
+1. **Primitives** are raw, context-free scales such as palette steps, spacing, type sizes, and motion durations.
+2. **Semantic tokens** express intent such as canvas, primary text, danger surface, or focus ring. Themes override this layer.
+3. **Component tokens** express stable component decisions such as button height or control border. They reference semantic or primitive tokens and are re-declared in theme scopes so nested container themes resolve correctly.
+
+Source files live in `tokens/*.json`; `tokens/tokens.css`, `.json`, `.js`, and `.ts` are generated. Schemas in `schemas/` define the accepted source and product-theme contracts.
+
+## CSS layers and entry points
+
+| Entry point | Purpose |
+| --- | --- |
+| `@neuravision/construct/tokens/tokens.css` | Tokens only |
+| `@neuravision/construct/foundations.css` | Network-free reset, typography, and layout utilities |
+| `@neuravision/construct/fonts.css` | Optional hosted-font request; import only with explicit privacy/CSP approval |
+| `@neuravision/construct/components/components.css` | Complete component bundle |
+| `@neuravision/construct/components/<name>.css` | Generated standalone component entry with tokens and shared component contracts |
+| `@neuravision/construct/components/core.css` | Tokens and shared component contracts without a concrete component |
+
+Files under `standalone/` are generated package adapters. Authored component CSS remains in `components/`; it is never copied into a second implementation. This keeps full-bundle and selective-import behavior on one source.
+
+## Behavior layer
+
+Construct CSS styles ARIA and `data-*` state; it cannot implement a focus trap, roving tabindex, typeahead, Escape handling, or focus restoration. The optional `@neuravision/construct/behaviors` ESM entry provides dependency-free controllers for those state machines.
+
+Controllers enhance caller-owned DOM. They synchronize semantics, emit cancellable `ct:before*` and post-change `ct:*` events where relevant, expose programmatic methods, and return a `destroy()` lifecycle. Rendering and product data stay in the application or framework adapter.
+
+Importing the behavior entry has no side effect. A controller starts only when its factory is called, and destroying it restores the attributes it owned.
+
+## Product themes
+
+A product theme is a validated override, not a copy of the generated stylesheet. It names a built-in base, supplies known semantic and/or component paths, and declares any product-specific contrast pairs.
+
+```bash
+npx construct-theme \
+  --theme ./brand.theme.json \
+  --out-dir ./src/generated/construct
+```
+
+The compiler validates schemas, unknown paths, references, complete resolved shapes, selector/value safety, duplicate selectors, typed CSS values, and contrast before writing the same CSS/JSON/JS/TS formats as the built-in build. Keep the theme input under product source control and treat its output as generated.
+
+The consuming stylesheet must load the generated `tokens.css` after foundations and all full or standalone Construct component entries. Those entries include the built-in token sheet; putting the generated theme last gives its root and scoped declarations deterministic precedence. Product-specific overrides may follow it.
+
+## Framework boundary
+
+Framework adapters own references, mount/unmount lifecycle, controlled application state, and rendering. They should initialize a controller after the relevant DOM exists and call `destroy()` during cleanup. They must not reproduce the controller's keyboard or focus logic in parallel.
+
+Construct does not own routing, remote data, authorization, analytics, localization, or product-specific responsive decisions. Components expose explicit slots, attributes, tokens, and controller callbacks so those concerns can remain at the product layer.
+
+## Generated and compatibility files
+
+- Edit token source JSON and run the build; never hand-edit `tokens/tokens.*`.
+- Edit `components/index.css` and authored component files; regenerate `standalone/`.
+- A compatibility entry may import a canonical implementation, but duplicated component implementations are not maintained.
+- Public exports are checked against real files before packaging.
+
+See [Governance and Definition of Done](governance.md) for change ownership, review requirements, and release gates.

package/docs/behaviors.md

@@ -0,0 +1,101 @@
+# Headless Behaviors
+
+Construct's optional behavior package enhances existing DOM with accessible state machines. It has no framework or runtime dependency and does not render markup or styles.
+
+```js
+import {
+  createModalController,
+  createTabsController,
+} from '@neuravision/construct/behaviors';
+```
+
+Every factory validates its DOM contract, returns the existing controller when initialized twice for the same root/trigger, and exposes an idempotent `destroy()` method. Call `destroy()` before the owning view unmounts.
+
+## Controllers
+
+| Factory | Behavior contract |
+| --- | --- |
+| `createModalController` | Dialog semantics, initial focus, focus trap, Escape/backdrop dismissal, nested overlay ordering, scroll lock, focus return |
+| `createDrawerController` | Modal drawer behavior with the same focus/dismissal invariants and toggle trigger support |
+| `createTabsController` | Roving tabindex, horizontal/vertical arrows, Home/End, automatic or manual activation |
+| `createToggleGroupController` | Single/multiple pressed state, roving tabindex, orientation-aware arrows, controlled programmatic value |
+| `createDropdownController` | ARIA menu button, first/last focus, arrows, Home/End, typeahead, outside/Escape dismissal, menu item selection |
+| `createSelectMenuController` | Button/listbox selection, active option, typeahead, keyboard opening and dismissal, value synchronization |
+| `createComboboxController` | Editable combobox, virtual listbox focus, optional local filtering, active descendant, announcements, selection |
+| `createTooltipController` | Focus and hover timing, touch toggle, Escape/outside dismissal, described-by wiring |
+| `createPopoverController` | Non-modal popup disclosure, optional focus entry, hover/focus modes, outside/Escape dismissal, focus return |
+
+The package includes TypeScript declarations for options, callbacks, controller methods, and event-detail types.
+
+## Modal example
+
+```html
+<button id="open-settings" class="ct-button" type="button">Settings</button>
+
+<div id="settings-modal" class="ct-modal" data-state="closed" hidden>
+  <section class="ct-modal__dialog" aria-labelledby="settings-title">
+    <header class="ct-modal__header">
+      <h2 id="settings-title">Settings</h2>
+      <button class="ct-button ct-button--ghost" type="button" data-ct-dismiss>Close</button>
+    </header>
+    <div class="ct-modal__body">
+      <label class="ct-field">
+        <span class="ct-field__label">Display name</span>
+        <input class="ct-input" type="text" autofocus />
+      </label>
+    </div>
+  </section>
+</div>
+```
+
+```js
+import { createModalController } from '@neuravision/construct/behaviors';
+
+const modal = document.querySelector('#settings-modal');
+const controller = createModalController({
+  container: modal,
+  dialog: modal.querySelector('.ct-modal__dialog'),
+  trigger: document.querySelector('#open-settings'),
+});
+
+// When the owning view is removed:
+controller.destroy();
+```
+
+Buttons with `data-ct-dismiss` are discovered automatically. The caller still owns the accessible name through `aria-labelledby` or `aria-label` and owns the action performed after confirmation.
+
+## Tabs example
+
+```js
+import { createTabsController } from '@neuravision/construct/behaviors';
+
+const tablist = document.querySelector('[role="tablist"]');
+const tabs = createTabsController({
+  tablist,
+  activation: 'automatic',
+  onSelect({ index }) {
+    analytics.track('settings_tab_selected', { index });
+  },
+});
+```
+
+The controller can discover tabs from `[role="tab"]` or `[data-ct-tab]`. Panels can be linked with `aria-controls` or passed explicitly. Disabled tabs use native `disabled` or `aria-disabled="true"` and are skipped by keyboard movement.
+
+## State and events
+
+Controllers synchronize the attributes consumed by Construct CSS, including `data-state`, `aria-expanded`, `aria-selected`, `aria-pressed`, `aria-activedescendant`, `tabindex`, and `hidden` as applicable.
+
+State changes dispatch cancellable `ct:beforeopen`, `ct:beforeclose`, `ct:beforeselect`, or `ct:beforevaluechange` events where relevant. Preventing the event prevents the transition. Successful transitions dispatch the corresponding `ct:open`, `ct:close`, `ct:select`, or `ct:valuechange` event and invoke the typed callback option.
+
+Programmatic methods accept a `reason` string. Use stable product-specific reasons when analytics or application policy needs to distinguish pointer, keyboard, routing, and remote-data transitions.
+
+## Lifecycle rules
+
+- Initialize after all managed elements exist.
+- Keep one controller per mounted widget; repeated factory calls for the same owner return it.
+- Do not update controller-owned ARIA attributes from a second state machine.
+- Call `destroy()` during framework cleanup. It removes listeners, overlay registrations, timers, scroll locks, and owned temporary attributes.
+- Recreate the controller when the managed item collection changes. `ComboboxController.refresh()` is the exception for filter/result refresh within its fixed managed collection.
+- Prefer native `<details>`, `<select>`, and `<dialog>` where their platform behavior fully meets the product requirement.
+
+See the [React example](../examples/react/README.md) for framework lifecycle integration and [Component usage](../components/README.md) for the corresponding markup and CSS classes.

package/docs/fonts.md

@@ -0,0 +1,70 @@
+# Fonts
+
+Construct foundations are network-free. They declare font-family tokens with resilient system fallbacks, but they do not download font files.
+
+## System-font fallback
+
+No extra step is required. Import the normal foundation stylesheet and the browser uses a locally installed Lato or JetBrains Mono face when available, then the generated system fallback stack.
+
+```css
+@import '@neuravision/construct/foundations.css';
+```
+
+This is the default for strict Content Security Policy, privacy-sensitive, offline, and embedded applications.
+
+## Optional hosted preset
+
+Projects that explicitly accept Google-hosted font requests can import the opt-in preset before foundations:
+
+```css
+@import '@neuravision/construct/fonts.css';
+@import '@neuravision/construct/foundations.css';
+```
+
+The preset requests Lato 400/700/900 and JetBrains Mono 400/500/600/700. Do not use it when the product's privacy or CSP policy forbids third-party font requests.
+
+## Self-hosting
+
+Host the licensed font files in the product and define the faces in application CSS. The URLs below are examples; Construct intentionally does not publish third-party font binaries.
+
+```css
+@font-face {
+  font-family: 'Lato';
+  src: url('/fonts/lato-regular.woff2') format('woff2');
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'Lato';
+  src: url('/fonts/lato-bold.woff2') format('woff2');
+  font-style: normal;
+  font-weight: 700;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'Lato';
+  src: url('/fonts/lato-black.woff2') format('woff2');
+  font-style: normal;
+  font-weight: 900;
+  font-display: swap;
+}
+```
+
+Add the JetBrains Mono faces only if the application renders code or tabular data with the mono token. Preload only the files needed above the fold; indiscriminate preloading delays other critical resources.
+
+## Product typefaces
+
+A product can keep Construct's sizing and hierarchy while replacing the families. Override both primitive family variables after the Construct imports; the semantic aliases continue to follow them.
+
+```css
+:root {
+  --font-family-brand: 'Company Sans', 'Segoe UI', sans-serif;
+  --font-family-text: 'Company Sans', 'Segoe UI', sans-serif;
+  --font-family-mono: 'Company Mono', 'SFMono-Regular', Menlo, monospace;
+}
+```
+
+Verify every available weight, text reflow at 200% zoom, fallback metrics during loading, and contrast in all supported themes before release.

package/docs/governance.md

@@ -0,0 +1,85 @@
+# Construct Governance and Definition of Done
+
+Construct is a reusable product contract, not a collection of project-specific styles. Changes must keep the token, CSS, behavior, accessibility, documentation, and package surfaces aligned.
+
+## Ownership boundaries
+
+| Layer | Owns | Must not own |
+| --- | --- | --- |
+| Primitive tokens | Raw scales and values | Product meaning or component selectors |
+| Semantic tokens | Theme-aware intent | Component anatomy |
+| Component tokens | Stable component decisions | DOM event handling |
+| Component CSS | Appearance and attribute-driven states | Focus management or keyboard state machines |
+| Headless behaviors | ARIA synchronization, keyboard interaction, focus, open/close state | Product data or visual styling |
+| Framework adapters | Rendering, lifecycle integration, application data | Private forks of Construct behavior |
+
+Product-specific rules belong in the consuming application. A pattern that is useful across products should first be expressed as a general Construct contract and covered by the quality gates below.
+
+## Definition of Done
+
+A change is complete only when every applicable item is satisfied.
+
+### Tokens and themes
+
+- Source JSON is changed instead of generated `tokens/tokens.*` files.
+- Primitive, semantic, and component-token responsibilities remain distinct.
+- References resolve without cycles or missing targets.
+- Built-in theme structures stay compatible with the light-theme contract.
+- Custom-theme input is schema-valid, only overrides known tokens, and passes its declared contrast checks.
+- Generated CSS, JSON, JavaScript, and TypeScript outputs are rebuilt together before checks and packaging. They are intentionally ignored in this repository and produced in clean CI/prepack runs; source JSON and schemas are the reviewed files.
+- Token additions, removals, or value changes follow the documented versioning policy.
+
+### Components and CSS
+
+- The public anatomy, modifiers, sizes, and supported ARIA/data attributes are documented.
+- Default, hover, focus-visible, active, selected/open, disabled, invalid, loading, and empty states are handled where they apply.
+- Covered compact controls follow Construct's 44×44 CSS-pixel coarse-pointer policy; custom controls are tested separately.
+- Motion has a `prefers-reduced-motion` path and essential meaning does not depend on animation.
+- Essential controls and states remain perceivable with `forced-colors: active`.
+- CSS uses Construct tokens, logical properties where direction matters, and no unresolved custom properties.
+- The component works through both the full bundle and its standalone package import.
+- A Storybook story covers representative states and the accessibility addon reports no serious violation.
+
+### Interactive behavior
+
+- Native HTML is preferred where it already provides the required semantics.
+- ARIA state and visible state share one source of truth.
+- Keyboard behavior follows the relevant WAI-ARIA Authoring Practices pattern.
+- Focus entry, containment where required, Escape behavior, outside interaction, and focus restoration are explicit.
+- Disabled items are not activated, and composite widgets maintain a valid focus model.
+- Initialization is safe, teardown removes every listener and temporary attribute, and repeated initialization does not leak state.
+- Behavior modules have no framework dependency and expose a documented controller contract.
+- Unit tests cover the keyboard and lifecycle invariants; Storybook verifies the integrated markup and styles.
+
+### Documentation and release
+
+- README, component usage, token guidance, and Storybook prose do not overstate what CSS alone provides.
+- A framework example is updated when a public behavior or markup contract changes.
+- The changelog explains consumer-visible additions, migrations, and accessibility implications.
+- `package.json`, its lockfile, examples, issue templates, and visible version labels agree on the release version.
+- Package exports and the packed file list are verified before release.
+
+## Required quality gates
+
+Run these from the Construct package root:
+
+```bash
+npm run audit
+npm run build
+npm run check
+npm test
+npm run storybook:build
+npm pack --dry-run
+```
+
+The audit gate includes development tooling and rejects high or critical dependency advisories. Run `npm run build` before the non-mutating `npm run check`, including in a clean checkout where ignored token outputs do not exist. The check verifies generated token and standalone outputs, token/theme validity, contrast declarations, CSS-variable closure, and package export targets. `npm test` verifies headless behavior, Storybook interactions/accessibility, and the real coarse-pointer browser contract.
+
+Manual review is still required for visual hierarchy, zoom and reflow, screen-reader announcements, keyboard order, and product-context language. Automated checks support that review; they do not replace it.
+
+## Versioning
+
+- **Major:** remove or rename a public token, selector, behavior export, or required markup/attribute contract.
+- **Minor:** add a token, component, variant, optional behavior, theme capability, or backward-compatible state.
+- **Patch:** fix an implementation without changing the documented consumer contract.
+
+Deprecations must identify the replacement and removal release. Compatibility files may forward to a canonical implementation, but must not maintain a second divergent copy.

package/docs/guidelines.md

@@ -15,7 +15,7 @@ A consistent, accessible, professional design system for modern web applications
 - Maintain clear state logic (hover, focus, active, disabled, error)
 - Use consistent sizes (sm, md, lg) for form controls and buttons
 - Establish clear hierarchies (Primary vs. Secondary actions)
-- Test all components with keyboard navigation (Tab, Shift+Tab, Enter, Space)
+- Test all interactive functionality with keyboard navigation (Tab, Shift+Tab, Enter, Space)
 
 ### Don't
 
@@ -29,33 +29,41 @@ A consistent, accessible, professional design system for modern web applications
 
 - **Visible Focus**: All interactive elements must have visible focus indication
 - **Labels**: Every form input must have a label (explicit `<label>` or `aria-label`)
-- **Keyboard Navigation**: Full support for dropdowns, tabs, modals, tooltips, datepickers
+- **Keyboard Navigation**: Use the tested headless controller for supported composite widgets; framework adapters must implement the documented pattern for others such as Datepicker and Tree
 - **ARIA**: Use ARIA attributes only where semantic HTML isn't sufficient
 - **Links**: Links must be distinguishable without color alone (e.g., underline)
-- **Contrast**: Text, icons, and focus rings must meet WCAG AA standards
+- **Contrast**: Text, icons, component boundaries, and focus rings must meet applicable WCAG 2.2 AA requirements
 - **Themes**: Support light, dark, and high-contrast modes; respect user preferences
 - **Disabled States**: Must be recognizable, but content should remain readable
 - **Motion**: Respect `prefers-reduced-motion` for animations
-- **Live Regions**: Use `aria-live` for toasts and status messages
+- **Live Regions**: Use a polite live region only when a dynamic update must be announced; do not make static status labels noisy
 - **Modal**: Requires `aria-modal`, `role="dialog"`, and focus trap
+- **Targets**: Covered compact controls follow Construct's 44×44 CSS-pixel coarse-pointer policy; custom controls require their own checks
+- **Forced colors**: Essential focus, boundary, selected, and status meaning must remain perceivable
 
 ## Keyboard Patterns for Composite Components
 
+Construct provides typed controllers for Modal, Drawer, Tabs, Toggle Group, Dropdown, Select Menu,
+Combobox, Tooltip, and Popover through `@neuravision/construct/behaviors`. Use those controllers or a
+framework adapter with equivalent tested semantics; CSS state selectors alone do not implement behavior.
+
 ### Tabs
 - **Arrow keys**: Move focus between tabs
 - **Home/End**: Jump to first/last tab
 - **Enter/Space**: Activate tab
 - **Implementation**: Use roving tabindex (active tab `tabindex="0"`, others `tabindex="-1"`)
 
-### Dropdown (Action-List)
+### Generic disclosure / action list (Popover)
+- **Use for**: Ordinary links, buttons, form controls, or mixed content that should retain native semantics
 - **Trigger**: Uses `aria-expanded` and `aria-controls`
-- **Open**: Focus moves to first item
-- **Esc**: Closes and returns focus to trigger
-- **Items**: Normal buttons/links in tab order
+- **Focus**: Content remains in its natural Tab order; optional focus entry and focus return depend on the product flow
+- **Behavior**: Use `createPopoverController` or an equivalent adapter for Escape, outside dismissal, and state synchronization
+- **Roles**: Do not add `menu` / `menuitem` roles to generic disclosure content
 
-### Dropdown (Role=menu)
-- **Only use if implementing**: Arrow-key navigation, Home/End, typeahead, and roving tabindex
-- Most dropdowns should use Action-List pattern instead
+### Dropdown action menu (`role="menu"`)
+- **Use for**: A menu button whose popup contains application commands
+- **Behavior**: Use `createDropdownController` for first/last focus, Arrow keys, Home/End, typeahead, roving tabindex, Tab dismissal, Escape, and focus return
+- **Naming**: Give the menu an accessible name with `aria-label` or `aria-labelledby`
 
 ### Datepicker
 - **Arrow keys**: Move by day in calendar grid
@@ -93,7 +101,7 @@ Hierarchical disclosure following the [WAI-ARIA Tree View pattern](https://www.w
 - Expandable nodes carry `aria-expanded="true|false"`. Leaf nodes omit the attribute.
 
 **Indent**
-Set `--ct-level` inline on each `.ct-tree__row` (matches the node's `aria-level`). The bundled JS controller used in Storybook fills it in automatically; framework wrappers should generate it during render.
+Set `--ct-level` inline on each `.ct-tree__row` (matches the node's `aria-level`). The Storybook reference implementation fills it in automatically; framework wrappers should generate it during render.
 
 **Keyboard**
 - `↑` / `↓`: focus previous / next visible row
@@ -103,6 +111,7 @@ Set `--ct-level` inline on each `.ct-tree__row` (matches the node's `aria-level`
 - `Enter`: activate (consumer-defined; emit `ct-tree:activate`)
 - `Space`: toggle selection (multi/single) or activate (no selection)
 - `*`: expand all siblings on the same level
+- `F2`: move focus into the current row's action buttons; Arrow keys move between actions and `Escape` returns to the treeitem
 - Type-ahead (`A`–`Z`): focus next row whose label starts with the typed prefix; buffer resets after 500 ms
 
 **Roving tabindex**
@@ -112,24 +121,24 @@ Exactly one `<li role="treeitem">` carries `tabindex="0"`. All others carry `tab
 The `.ct-tree__toggle` is a non-focusable `<span aria-hidden="true">`. Expand/collapse is reachable via keyboard through `←`/`→` on the row and via mouse through clicking the chevron. We deliberately avoid making the toggle a `<button>`: a focusable button inside a focusable row violates `aria-hidden-focus` / `nested-interactive`, and the row already provides the keyboard affordance.
 
 **Row actions**
-Buttons in the `.ct-tree__actions` slot live inside the focusable treeitem. Give them `tabindex="-1"` so the tree exposes a single Tab stop, as required by the WAI-ARIA Tree View pattern. Reach them via mouse, or expose a row-level action hotkey from the consuming framework.
+Buttons in the `.ct-tree__actions` slot live inside the focusable treeitem. Give them `tabindex="-1"` so the tree exposes a single Tab stop, as required by the WAI-ARIA Tree View pattern. Storybook's reference controller uses `F2` to focus the first enabled action, Arrow keys to traverse the action set, and `Escape` to restore focus to the treeitem. Consumer implementations that expose row actions must provide the same reachable keyboard path or an explicitly documented equivalent.
 
 **Selection**
 - `aria-selected="true|false"` on the `<li role="treeitem">` (only when selection is active).
-- For multi-selection, the container needs `aria-multiselectable="true"`. The Storybook controller (`attachTree`) sets and tears this down automatically when invoked with `selection: 'multi'`.
+- For multi-selection, the container needs `aria-multiselectable="true"`. Storybook's `attachTree` reference implementation sets and tears this down when invoked with `selection: 'multi'`; it is not exported from `@neuravision/construct/behaviors`.
 - Construct only styles selection — the consumer decides whether to clear other rows (`single`) or keep them (`multi`).
 
 **Async children**
 Set `aria-busy="true"` on the `<li role="treeitem">` while its children are loading. The chevron switches to a spinner via the existing `ct-spin` keyframe and the toggle becomes non-interactive while busy.
 
 **Disabled nodes**
-Use `aria-disabled="true"` on the `<li>`. Do **not** use the HTML `disabled` attribute — `treeitem` is not a form control. The Storybook controller skips activation, selection and toggle for disabled nodes; arrow-key navigation still passes through them so screen readers can announce them.
+Use `aria-disabled="true"` on the `<li>`. Do **not** use the HTML `disabled` attribute — `treeitem` is not a form control. Storybook's reference implementation skips activation, selection and toggle for disabled nodes; arrow-key navigation still passes through them so screen readers can announce them.
 
 **Orphan state**
 For sub-nodes whose parent reference is missing in the data set, render them on the root level with the `.ct-tree__node--orphan` modifier. They get a warning-tinted surface and a dashed border so the data inconsistency is visible without breaking the tree.
 
-**Custom events**
-The Storybook controller emits four bubbling `CustomEvent`s on the focused treeitem so consumers can wire up application logic without re-implementing the keyboard model:
+**Reference events**
+Storybook's non-public `attachTree` reference implementation emits four bubbling `CustomEvent`s on the focused treeitem. Consumer wrappers may adopt the same event shape, but these events and `attachTree` are examples rather than a published behavior API:
 
 | Event | Detail | Fires on |
 |---|---|---|
@@ -150,6 +159,10 @@ Use these attributes for state management:
 - **selected**: `aria-selected="true"`
 - **current**: `aria-current="page"`
 - **expanded**: `aria-expanded="true|false"`
+- **loading**: `aria-busy="true"`; loading buttons also use `data-loading="true"` and native `disabled`
+
+Never use `aria-disabled="true"` alone to block a native button: it announces state but does not suppress
+activation. Use the native `disabled` attribute whenever the HTML element supports it.
 
 ## Breakpoints & Media Queries
 
@@ -181,20 +194,26 @@ CSS custom properties cannot be used inside `@media` queries. Use the raw pixel
 - Always use `max-width: <token - 1>px` to target viewports *below* a breakpoint
 - Always add a reference comment noting the breakpoint name and token value
 - Only use values derived from the token system — never arbitrary pixel values
-- Current components use two breakpoints: `< sm` (599px) and `< md` (899px)
+- Current components use the `sm`, `md`, and `lg` contracts (599px, 899px, and 1199px maximums). App Shell V1 and V2 use `< md` for compact overlay navigation and `< lg` for rail/panel behavior.
 
 ## Fonts
 
-- **Default**: Fonts are loaded via Google Fonts in `foundations.css` (Manrope for display + body, JetBrains Mono for code/data)
-- **Self-hosting**: For CSP or privacy requirements, replace Google Fonts import with local `@font-face` rules
-- **Weights**: Ensure 400, 500, 600, 700, and 800 are available
+- **Default**: `foundations.css` makes no network request and uses resilient local/system fallback stacks.
+- **Hosted opt-in**: Import `fonts.css` before foundations only when Google-hosted requests satisfy product privacy and CSP policy.
+- **Self-hosting**: Host licensed files in the application; Construct intentionally does not publish third-party binaries.
+- **Lato weights**: Provide 400, 700, and 900. JetBrains Mono uses 400, 500, 600, and 700.
+
+See [Fonts](fonts.md) for complete hosted, self-hosted, and product-family examples.
 
 ## Governance
 
-- **New components require**: Design tokens, state definitions, accessibility notes, Storybook story
-- **Before merge**: Visual QA + keyboard testing + contrast check
+- **New components require**: owning token layer, state definitions, accessibility notes, Storybook coverage, and public import verification
+- **Interactive changes require**: keyboard/focus lifecycle tests and complete controller cleanup
+- **Before merge**: `npm run check`, `npm test`, Storybook build, visual/keyboard/screen-reader review
 - **Review process**: At least one accessibility review for new interactive components
 
+The normative checklist is [Governance and Definition of Done](governance.md).
+
 ---
 
 **Construct** - Build accessible design constructs

package/examples/react/README.md

@@ -0,0 +1,20 @@
+# React integration example
+
+This example keeps React responsible for rendering and lifecycle while Construct owns visual and interaction contracts.
+
+1. Install `@neuravision/construct` alongside the application's existing React dependencies.
+2. Import `construct.css` once from the application entry.
+3. Render `SettingsModal`.
+
+The effect creates the controller after the DOM refs exist and returns `controller.destroy` through its cleanup. This is safe with React Strict Mode's development setup/cleanup cycle and prevents listeners, focus state, or scroll locks from surviving an unmount.
+
+The controller owns open/closed state, dialog semantics, focus trapping, Escape/backdrop dismissal, and focus return. React still owns form values, validation, persistence, routing, and product feedback. Wire the Save action to application state; do not create a second open/close state machine around the same DOM.
+
+For a full component bundle, replace the selective component imports with:
+
+```css
+@import '@neuravision/construct/foundations.css';
+@import '@neuravision/construct/components/components.css';
+```
+
+See [Headless behaviors](../../docs/behaviors.md) for the complete controller API and lifecycle rules.

package/examples/react/SettingsModal.jsx

@@ -0,0 +1,66 @@
+import { useEffect, useRef } from 'react';
+
+import { createModalController } from '@neuravision/construct/behaviors';
+
+export function SettingsModal() {
+  const triggerRef = useRef(null);
+  const containerRef = useRef(null);
+  const dialogRef = useRef(null);
+
+  useEffect(() => {
+    const controller = createModalController({
+      container: containerRef.current,
+      dialog: dialogRef.current,
+      trigger: triggerRef.current,
+      initialFocus: '#display-name',
+    });
+
+    return () => controller.destroy();
+  }, []);
+
+  return (
+    <>
+      <button ref={triggerRef} className="ct-button" type="button">
+        Edit settings
+      </button>
+
+      <div ref={containerRef} className="ct-modal" data-state="closed" hidden>
+        <section
+          ref={dialogRef}
+          className="ct-modal__dialog"
+          aria-labelledby="settings-title"
+        >
+          <header className="ct-modal__header">
+            <h2 id="settings-title">Settings</h2>
+            <button
+              className="ct-button ct-button--ghost ct-button--icon"
+              type="button"
+              aria-label="Close settings"
+              data-ct-dismiss
+            >
+              <span aria-hidden="true">×</span>
+            </button>
+          </header>
+
+          <div className="ct-modal__body">
+            <div className="ct-field">
+              <label className="ct-field__label" htmlFor="display-name">
+                Display name
+              </label>
+              <input id="display-name" className="ct-input" autoComplete="name" />
+            </div>
+          </div>
+
+          <footer className="ct-modal__footer">
+            <button className="ct-button ct-button--secondary" type="button" data-ct-dismiss>
+              Cancel
+            </button>
+            <button className="ct-button" type="button">
+              Save
+            </button>
+          </footer>
+        </section>
+      </div>
+    </>
+  );
+}

package/examples/react/construct.css

@@ -0,0 +1,5 @@
+@import '@neuravision/construct/foundations.css';
+@import '@neuravision/construct/components/button.css';
+@import '@neuravision/construct/components/field.css';
+@import '@neuravision/construct/components/input.css';
+@import '@neuravision/construct/components/modal.css';

package/fonts.css

@@ -0,0 +1,10 @@
+/*
+ * Optional Construct web-font preset.
+ *
+ * Foundations never make a network request. Import this file before
+ * foundations.css only when Google-hosted fonts fit the product's privacy,
+ * CSP, and offline requirements. Self-hosted applications can omit it and
+ * provide @font-face rules for "Lato" and "JetBrains Mono" themselves, or
+ * override the generated --font-family-* custom properties.
+ */
+@import url('https://fonts.googleapis.com/css2?family=Lato:wght@400;700;900&family=JetBrains+Mono:wght@400;500;600;700&display=swap');