@neuravision/construct 2.0.3 → 2.1.2

package/docs/behaviors.md

@@ -0,0 +1,122 @@
+# 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, optional `inertBackground` |
+| `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 (`aria-pressed`, or `aria-checked` radio semantics for single groups authored with `role="radiogroup"`/`role="radio"`), roving tabindex, orientation-aware arrows, controlled programmatic value |
+| `createDropdownController` | ARIA menu button, first/last focus, arrows, Home/End, typeahead (open and closed), outside/Escape dismissal, menu item selection |
+| `createSelectMenuController` | Button/listbox selection, active option, typeahead, PageUp/PageDown, Tab commits the active option, keyboard opening and dismissal, value synchronization |
+| `createComboboxController` | Editable combobox, virtual listbox focus, optional local filtering, active descendant, Alt+Arrow open/close, IME-safe key handling, 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.
+
+### What the caller still owns (accessible names and live regions)
+
+Controllers wire state attributes, but accessible names and announcement targets come from your markup. Missing ones are reported as console warnings in the browser:
+
+| Controller | You must provide |
+| --- | --- |
+| Modal / Drawer | `aria-labelledby` or `aria-label` on the dialog element |
+| Dropdown | `aria-label` or `aria-labelledby` on the `role="menu"` element |
+| Toggle group | `aria-label` or `aria-labelledby` on the group/radiogroup/toolbar root |
+| Select menu | A visible label or `aria-labelledby` for the trigger, and labels on options |
+| Combobox | A `<label>` for the input, an `aria-label` on the listbox, and a visually hidden live-region element passed as `options.status` — without it filter results are never announced |
+| Tooltip | A keyboard-focusable trigger (natively focusable or `tabindex="0"`) and text content in the tooltip element |
+| Popover | An accessible name when using `role="dialog"` content |
+
+### Documented deviations from APG
+
+- Select menu and dropdown arrow navigation wraps at the ends (APG select-only combobox specifies no wrap); wrapping matches Construct's menu behavior and is intentional.
+- Typing on a closed select menu commits the matching value immediately, mirroring native `<select>` on Windows, instead of opening the listbox first.
+
+## 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.
+
+Pass `inertBackground: true` to additionally set `inert` on the container's DOM siblings while the dialog is open — a belt-and-suspenders layer on top of `aria-modal` for legacy screen-reader virtual cursors. Content portaled into the DOM after opening (for example popup layers) is unaffected.
+
+## 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,11 +15,12 @@ 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
 
 - Don't rely on color alone for status information without text or icons
+- Don't rely on hue alone to distinguish chart series — use direct labels, ordered legends, and the always-present data-table fallback; several series pairs are near-identical in luminance for color-blind users
 - Don't create custom controls without ARIA roles and keyboard support
 - Don't use fixed pixel layouts for content that can grow
 - Don't use low-contrast text or disabled states that are unreadable
@@ -28,34 +29,47 @@ A consistent, accessible, professional design system for modern web applications
 ## Accessibility Rules (Minimum)
 
 - **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
+- **Labels**: Every form input must have a label. Prefer a visible `<label>`; use `aria-label` only when a visible label is impossible, and never let it differ from visible text (2.5.3 Label in Name — note that `aria-label` overrides an associated `<label>` when both are present)
+- **Headings**: Keep `h1`–`h6` in order without skipping levels, including inside cards, modals, and shells
+- **Landmarks**: Wrap navigation lists in `<nav>` (also inside `<aside>` sidebars), label repeated landmarks (`aria-label`), and provide a skip link to `main` (see `skip-link.css`)
+- **Truncation**: `nowrap` + ellipsis on essential text (titles, values, labels) needs a way to reach the full text — a tooltip, a wrapping variant, or full text elsewhere on the page
+- **Status colors**: Semantic color (toast, banner, alert, badge) must be paired with an icon or explicit wording; the tinted border alone is decorative and intentionally not contrast-gated
+- **Sticky chrome**: Products using `--sticky`/`--fixed` navbar, toolbar, or banner variants must set `--ct-scroll-offset-top`/`--ct-scroll-offset-bottom` on `:root` so focused elements are never scrolled underneath (2.4.11); the app shells set their own scroll padding automatically
+- **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
@@ -78,9 +92,10 @@ A consistent, accessible, professional design system for modern web applications
 - **Backdrop**: Click closes drawer
 
 ### Tooltip
-- **Open**: On hover and focus
+- **Open**: On hover and keyboard focus (the trigger must be focusable)
 - **Close**: On blur and Esc
 - **Role**: `role="tooltip"` with `aria-describedby`
+- **Implementation**: The CSS `:hover`/`:focus-within` styles alone do not satisfy WCAG 1.4.13 — Esc dismissal and hover persistence require `createTooltipController` or an equivalent adapter
 
 ### Tree (`ct-tree`)
 
@@ -93,7 +108,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 +118,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 +128,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 +166,31 @@ 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.
+
+## The Datum
+
+Construct's signature is one orange reference line — "the datum" — that marks what is focused, active,
+current, or the reference value. The grammar lives in `components/datum.css` (eyebrow, scale, frame,
+metrics), in active leading edges (list, sidebar, card, table rows), in the tab indicator and sorted
+column, and in the chart reference line. Its dimensions are component tokens (`--component-datum-*`).
+
+Rules that keep the signature strong and accessible:
+
+- **One datum per surface.** Orange marks exactly one thing per view region — the current, active, or
+  reference element. Never let two orange edges compete; if everything is highlighted, nothing is.
+- **Orange is never text.** Labels and values stay on `--color-text-*` neutrals; orange is carried by
+  non-text ticks, edges, rules, and lines.
+- **Edges are `--color-brand-accent`; meaning-bearing fills are `--color-brand-accent-strong`**
+  (validated ≥3:1 against muted/canvas/surface tracks per theme). A decorative rule may use plain
+  accent; anything that encodes a value (progress, chart reference) uses strong.
+- **The datum enters, it never pops.** State changes draw the edge in from its origin
+  (`--duration-fast` / `--easing-standard`); `prefers-reduced-motion` disables this globally.
+- **Forced colors re-encode edges as borders.** Inset box-shadow edges are dropped by forced colors —
+  every new edge needs a `SelectedItem` border fallback.
 
 ## Breakpoints & Media Queries
 
@@ -181,20 +222,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');

package/foundations.css

@@ -1,4 +1,3 @@
-@import url('https://fonts.googleapis.com/css2?family=Lato:wght@400;700;900&family=JetBrains+Mono:wght@400;500;600;700&display=swap');
 @import './tokens/tokens.css';
 
 :root {
@@ -19,6 +18,12 @@
 html {
   height: 100%;
   text-size-adjust: 100%;
+  /* WCAG 2.4.11 Focus Not Obscured contract: sticky/fixed chrome (navbar,
+     toolbar, banner) does not know the document, so products publish its
+     height by setting --ct-scroll-offset-top/-bottom on :root/html. Scroll
+     operations then keep focused or anchored content clear of the bars. */
+  scroll-padding-block-start: var(--ct-scroll-offset-top, 0px);
+  scroll-padding-block-end: var(--ct-scroll-offset-bottom, 0px);
 }
 
 body {
@@ -231,6 +236,14 @@ button {
   color: var(--color-text-muted);
 }
 
+.ct-truncate {
+  display: block;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
 .ct-text-center {
   text-align: center;
 }