@neuravision/construct 2.0.2 → 2.1.1

package/CHANGELOG.md

@@ -0,0 +1,272 @@
+# Changelog
+
+All notable changes to `@neuravision/construct` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.1.1] - 2026-07-16
+
+### Changed
+
+## [2.1.0] - 2026-07-15
+
+### Added
+
+- A validated three-layer token contract (primitive → semantic → component) with 40 component tokens, published JSON Schemas, typed JS/TS exports, and complete nested theme scopes.
+- The `construct-theme` CLI for external theme inputs, including unknown-path, reference, shape, selector, and contrast validation. Built-in themes now verify 57 contrast pairs each.
+- Optional, dependency-free, typed headless controllers for modal, drawer, tabs, toggle group, dropdown, select menu, combobox, tooltip, and popover.
+- Generic live/connection status, metric, and segmented meter contracts; loading-button behavior; a compact responsive navbar; and shared App Shell sizing/motion hooks.
+- Generated standalone package entry points for all 49 component styles plus a public component core entry.
+- Automated CSS-variable closure, package-export, version, token negative-case, real coarse-pointer, and forced-colors contracts.
+- Architecture, behavior, font/self-hosting, governance/Definition-of-Done documentation and a React lifecycle example.
+
+### Changed
+
+- `foundations.css` is network-free. Hosted Lato and JetBrains Mono loading moved to the explicit opt-in `fonts.css` entry.
+- Explicit light, dark, high-contrast, and custom theme scopes emit complete semantic and component contracts, making arbitrary nested container themes deterministic.
+- Light accent interaction colors, light solid success/warning colors, dark muted text, and high-contrast active accent were adjusted to satisfy the expanded contrast matrix.
+- App Shell V2 is the recommended shell; V1 remains supported through compatibility aliases instead of a divergent public token vocabulary.
+- The verified development baseline is Node.js 22.12+ (or 24+) with Storybook 10.5, Vitest 4.1, and Playwright 1.61; the unused coverage package and vulnerable legacy test-tool chain were removed, and CI/publish preflights now reject high or critical dependency advisories.
+
+### Fixed
+
+- Added the missing `--font-size-2xs`, `--color-bg-subtle`, and `--color-border-muted` contracts and removed the Datepicker's undeclared global pseudo-token.
+- Prevented light component aliases and inherited semantic values from leaking into nested dark, high-contrast, light, or custom theme containers.
+- Expanded the small Switch coarse-pointer hit area on both axes and enforced the 44×44 Construct target policy for default/small actions and compact controls.
+- Preserved meaningful borders, state indicators, and focus visibility in forced-colors mode.
+- Raised the default light/dark boundary colors and added compiler gates for control borders against canvas, surface, elevated, and control backgrounds.
+- Rejected negative component dimensions, radii, font metrics, and shadow blur radii while preserving valid negative letter spacing, shadow offsets, and spread values.
+- Preserved the existing `_keyframes.css`, `_shared.css`, and `_shell-shared.css` package subpaths while public component imports move to generated standalone adapters.
+
+### Accessibility
+
+- Composite-widget behavior now has tested keyboard, focus, dismissal, typeahead, nested-overlay, cleanup, and ARIA synchronization contracts instead of relying on CSS documentation alone.
+- Status meaning is conveyed with visible text plus a non-text indicator; semantic state color is no longer used as small text on an unrelated surface.
+
+
+## [2.0.4] - 2026-06-28
+
+### Added
+
+- **Datum grammar — the signature, now spoken by components.** The orange "datum"
+  (Construct's reference line for focus / active / current state) was promoted from focus
+  rings and bespoke docs CSS into reusable, opt-in component vocabulary in a new
+  `components/datum.css`:
+  - `.ct-eyebrow` — a mono kicker with a leading datum tick, for labelling sections.
+  - `.ct-datum-scale` — a measured reference line (a ruler with minor/major ticks and an
+    orange "origin" segment) for section headers.
+  - `.ct-specs` / `.ct-spec` (+ `.ct-spec--origin`) — an engineering datasheet for key figures.
+  - Card modifiers in `card.css`: `.ct-card--datum` (a corner registration mark) and an
+    active state (`.ct-card--active` / `[data-state="active"]`) that carries the same orange
+    leading edge as `.ct-list__item` and `.ct-sidebar`, so every active surface reads as one system.
+
+### Accessibility
+
+- Eyebrow and spec labels use `--color-text-secondary` (≥7:1 on every surface across light,
+  dark and high-contrast); orange is reserved for non-text edges/ticks (`--color-brand-accent`,
+  ≥3:1 as a graphic object). Default cards and existing `aria-selected` card behaviour are unchanged.
+
+## [2.0.3] - 2026-06-28
+
+### Fixed
+
+- **Lato typeface was declared but never loaded.** The 2.0.2 switch updated the font-family
+  tokens to Lato but left the Google Fonts `@import` in `foundations.css` pointing at Manrope,
+  so consumers loaded Manrope (unused) while Lato fell back to a system sans-serif. The
+  `@import` now loads `Lato:wght@400;700;900` (JetBrains Mono unchanged). Documentation
+  (`DesignTokens`, `Accessibility`, `Introduction`) updated from Manrope to Lato.
+
+### Notes
+
+- Lato ships only in 400/700/900 — it has no 500/600/800. The `medium` (500) and `semibold`
+  (600) weight tokens therefore resolve to the nearest available face (400 and 700), and
+  `extrabold` (800) to 900. This is inherent to Lato; `font-synthesis: none` keeps these as
+  real faces (no faux weights).
+
+## [2.0.2] - 2026-06-28
+
+### Changed
+
+- Switch primary typeface from Manrope to Lato (400/700/900)
+
+## [2.0.1] - 2026-06-27
+
+### Fixed
+
+- **Navbar height token.** The navbar referenced a non-existent `--control-height-xl` primitive (the control-height scale ends at `lg`), so the navbar fell back to an undefined height. Introduced a dedicated `layout.navbar.height` primitive (`--navbar-height`, 56px) and pointed `.ct-navbar` at it. The control-height scale stays reserved for form controls.
+
+
+## [2.0.0] - 2026-06-27
+
+A new visual identity — *"engineered for everyone."* Construct moves from a generic tech-blue/slate look to a distinctive system: warm concrete neutrals, an ink-steel primary, and a safety-orange accent that acts as a single recurring **"datum"** marking what is focused / active / selected / current. Verified WCAG AA across light, dark, and high-contrast themes.
+
+**BREAKING CHANGES:**
+
+- **Neutral primitive ramp renamed `slate` → `stone`.** Consumers referencing `color.slate.*` or `--color-slate-*` must migrate to `stone.*`. The neutral palette is now warm concrete/graphite instead of cool blue-grey.
+- **Default typefaces changed** from Sora + Source Sans 3 to **Manrope** (display + body). The Google Fonts import in `foundations.css` was updated accordingly; self-hosting consumers must update their font files.
+
+### Added
+
+- **The "datum" signature** — the orange accent now marks focus rings, active tab underlines, checked selection controls, slider fills, selected chips, the current pagination page, and active navigation (leading edge) across all components.
+- New semantic tokens: `color.brand.onAccent`, `color.text.onPrimary`, `color.state.onSolid` (theme-aware foregrounds for solid fills), and the `font.weight.extrabold` (800) display weight.
+- New `orange` primitive ramp (structural safety orange).
+
+### Changed
+
+- State ramps retuned to widen hue separation from the brand orange: `ocean` → blueprint blue (info), `amber` → gold (warning), `red` → crimson (danger).
+- Shadows warmed (warm-ink instead of cool blue); display headings now use weight 800.
+- Solid chips and solid banners now use a theme-aware foreground (`state.onSolid`) so their labels meet AA contrast in dark and high-contrast themes.
+
+
+## [1.4.0] - 2026-06-27
+
+### Added
+
+- **Tooling — design-sync for [claude.ai/design](https://claude.ai/design):** Construct can now be synced to a Claude Design project so Claude's design agent builds with the real Construct components. Because Construct is a pure CSS/token system, an off-script generator (`.design-sync/build.mjs`) flattens the authored CSS into one bundle and builds one preview card per component from the true Storybook-rendered HTML, plus per-component usage docs and a class-vocabulary README header. Sync state lives under `.design-sync/`; no change to the published package surface.
+
+
+## [1.3.1] - 2026-06-17
+
+### Fixed
+
+- **a11y / focus:** Raised the `--color-focus-ring` contrast so the focus indicator meets the WCAG 2.2 ≥ 3:1 non-text-contrast minimum against the canvas and surface backgrounds. The `light` ring (`teal.400`, 2.59:1 on canvas) → `teal.600` (5.09:1) and the `high-contrast` ring (`amber.400`, 2.07:1) → `amber.700` (6.68:1); the `dark` ring already passed and is unchanged. Affects every component that uses the shared focus token (24 files).
+
+
+## [1.3.0] - 2026-06-17
+
+### Added
+
+- Chart styling skin (`ct-chart`) — a framework-agnostic theme layer for SVG data-visualisation primitives (line/area, bar, donut, sparkline, gauge). Provides series colour mapping (`.ct-chart__series--{1..8}` via `currentColor`), grid/axis, legend, donut/gauge text, and a visually-hidden **accessible data-table fallback** (`.ct-chart__table`, revealed with `.ct-chart--show-table`). Geometry is supplied by the consuming layer; this file only themes the result. `prefers-reduced-motion` and `forced-colors` supported.
+- New categorical chart palette tokens `--color-chart-series-{1..8}`, defined for `light`, `dark`, and `high-contrast` themes. Every series colour meets the WCAG 1.4.11 non-text contrast minimum (≥ 3:1) against both the canvas and surface backgrounds.
+- Storybook coverage for `ct-chart` (`Chart.stories.js`): line/area, bar, donut, gauge, sparkline, empty state, the interactive data-table toggle (documenting the `aria-expanded`/`aria-controls` contract), and an optional keyboard-focusable-marks example. All stories pass the a11y addon in `error` mode.
+
+### Fixed
+
+- `ct-chart`: interactive marks (`.ct-chart__bar`, `.ct-chart__slice`, `.ct-chart__dot`) now have `:focus-visible` parity with their `:hover` affordance, so consumer-focusable data points show a visible focus ring.
+- `ct-chart`: hoisted `--ct-chart-gauge-width` into the `.ct-chart` config block (was an inline `var()` fallback duplicated across two rules), making it discoverable and overridable like the other `--ct-chart-*` properties.
+- `ct-chart`: consistent `forced-colors` behaviour — data marks (line, area, dots, bars, slices, legend marker, gauge) now uniformly preserve their series/state colour via `forced-color-adjust: none`, so a coloured legend no longer describes monochrome lines in Windows High Contrast. Grid and axes still follow the user's forced palette, and the data-table fallback remains the fully compliant path.
+
+## [1.2.0] - 2026-05-07
+
+### Added
+
+- Tree component (`ct-tree`) implementing the WAI-ARIA Tree View pattern: n-level nesting, roving tabindex, full keyboard navigation (↑/↓/→/←/Home/End/`*`/type-ahead), single & multi selection, async loading state (`aria-busy`), and an orphan-node modifier (`.ct-tree__node--orphan`) for hierarchies with missing parents. Modifiers: `--guides`, `--dense`, `--bordered`. Forced-colors and `prefers-reduced-motion` supported. (#86)
+
+## [1.1.6] - 2026-04-09
+
+### Changed
+
+### Added
+
+- Avatar seeded color palette: `.ct-avatar[data-seed-color="N"]` (N = 1–8) selects a deterministic background/foreground pair from the palette, letting consumers give each user a stable color. Avatars without the attribute keep the existing default — fully backwards compatible. (#85)
+- New semantic tokens `--color-avatar-seed-{1..8}-{bg,fg}` and component-level `--ct-avatar-seed-{1..8}-{bg,fg}` aliases, defined for `light`, `dark`, and `high-contrast` themes. Every pair meets WCAG AA (≥ 4.5:1, lowest measured 6.48:1).
+- New color primitives `purple` and `pink` (50–900 scales) feeding the seed palette.
+- Storybook story `Data Display/Avatar/Seeded Colors` showcasing the palette and confirming the unseeded fallback.
+
+## [1.1.5] - 2026-04-03
+
+### Changed
+
+## [1.1.4] - 2026-03-27
+
+### Changed
+
+## [1.1.3] - 2026-03-27
+
+### Changed
+
+## [1.1.2] - 2026-03-21
+
+### Changed
+
+## [1.1.1] - 2026-03-21
+
+### Changed
+
+## [1.1.0] - 2026-03-21
+
+### Added
+
+-
+
+## [0.2.0] - 2026-03-12
+
+### Added
+
+- Toolbar component (`ct-toolbar`) with brand, navigation, and action slots
+- Sidebar component (`ct-sidebar`) with side, over, and push modes
+- Progress bar component (`ct-progress-bar`) with determinate, indeterminate, and size/variant modifiers
+- Toggle group component (`ct-toggle-group`) with single/multiple selection and size variants
+- Nav list component (`ct-nav-list`, `ct-nav-item`) for sidebar navigation
+- Icon component (`ct-icon`) with sm, md, lg, xl sizes
+- `prefers-reduced-motion` support in components layer for self-contained usage
+- Explicit `:focus-visible` styles for all interactive components (button, form controls, checkbox, radio, switch, tabs, dropdown items, pagination, datepicker, table sort, nav items, toolbar links)
+
+### Fixed
+
+- Inconsistent focus indicators across components (standardized to `outline: 2px solid` with appropriate offsets)
+- Missing focus styles on `.ct-button`, `.ct-check__input`, `.ct-radio__input`, `.ct-switch__input`, `.ct-tabs__trigger`
+- Form controls now show both border-color change and outline ring on focus for WCAG 2.1 AA compliance
+
+## [0.1.1] - 2026-03-12
+
+### Changed
+
+- Updated `.gitignore` to exclude internal documentation and mock data
+- Project configuration and metadata cleanup
+
+## [0.1.0] - 2026-01-31
+
+### Added
+
+- Initial release of the Construct Design System
+- Two-tier token pipeline (primitives + semantic) with CSS, JSON, and TypeScript outputs
+- Three theme modes: light (default), dark, high-contrast
+- System preference fallback via `prefers-color-scheme` and `prefers-contrast`
+- Foundation styles: CSS reset, typography scale, layout utilities
+- Component library with `ct-` prefix and BEM naming:
+  - Button (primary, secondary, outline, ghost, accent, danger, link variants; sm/md/lg sizes)
+  - Form controls: input, select, textarea with field wrapper, hints, and error states
+  - Selection controls: checkbox, radio, switch
+  - Card with header, body, footer, and interactive variant
+  - Table with striped, compact, sortable, and numeric cell variants
+  - Data table with header, toolbar, filters, search, pagination, and footer
+  - Modal and confirmation dialog
+  - Toast notifications with info, success, warning, danger variants
+  - Tooltip with top, bottom, left, right positioning
+  - Tabs with trigger and panel
+  - Dropdown menu with items, labels, separators
+  - Pagination with navigation links
+  - Breadcrumbs
+  - Datepicker with calendar grid
+  - Badge and chip with variant and interactive modifiers
+  - File upload with drag-and-drop dropzone and file list
+  - Spinner, skeleton loader, and loading overlay
+- Accessibility: ARIA attribute-driven states, semantic HTML patterns
+- Storybook with HTML Vite, a11y addon (error-level), theme switching, autodocs
+- Story-driven testing via Vitest + Playwright
+- GitHub Actions workflow for Storybook deployment to GitHub Pages
+- Token build script with `--check` mode for CI validation
+
+[2.1.1]: https://github.com/Samyssmile/construct/compare/v2.1.0...v2.1.1
+[2.1.0]: https://github.com/Samyssmile/construct/compare/v2.0.4...v2.1.0
+[2.0.4]: https://github.com/Samyssmile/construct/compare/v2.0.3...v2.0.4
+[2.0.3]: https://github.com/Samyssmile/construct/compare/v2.0.2...v2.0.3
+[2.0.2]: https://github.com/Samyssmile/construct/compare/v2.0.1...v2.0.2
+[2.0.1]: https://github.com/Samyssmile/construct/compare/v2.0.0...v2.0.1
+[2.0.0]: https://github.com/Samyssmile/construct/compare/v1.4.0...v2.0.0
+[1.4.0]: https://github.com/Samyssmile/construct/compare/v1.3.1...v1.4.0
+[1.3.1]: https://github.com/Samyssmile/construct/compare/v1.3.0...v1.3.1
+[1.3.0]: https://github.com/Samyssmile/construct/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/Samyssmile/construct/compare/v1.1.6...v1.2.0
+[1.1.6]: https://github.com/Samyssmile/construct/compare/v1.1.5...v1.1.6
+[1.1.5]: https://github.com/Samyssmile/construct/compare/v1.1.4...v1.1.5
+[1.1.4]: https://github.com/Samyssmile/construct/compare/v1.1.3...v1.1.4
+[1.1.3]: https://github.com/Samyssmile/construct/compare/v1.1.2...v1.1.3
+[1.1.2]: https://github.com/Samyssmile/construct/compare/v1.1.1...v1.1.2
+[1.1.1]: https://github.com/Samyssmile/construct/compare/v1.1.0...v1.1.1
+[1.1.0]: https://github.com/Samyssmile/construct/compare/v1.0.0...v1.1.0
+[0.2.0]: https://github.com/Samyssmile/construct/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/Samyssmile/construct/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/Samyssmile/construct/releases/tag/v0.1.0

package/README.md

@@ -1,230 +1,226 @@
-# Construct - Design System
+<div align="center">
 
-> Build accessible design constructs for modern web applications
+[![Construct — token-based, framework-agnostic, accessible UI](.github/assets/banner.png)](https://samyssmile.github.io/construct/)
 
-**Construct** is an open-source, token-based design system foundation that provides a consistent, accessible UI across Angular, React, Svelte, and vanilla HTML/CSS.
+# Construct
 
-## ✨ Features
+**A token-based, framework-agnostic design system for accessible, modern web UI.**
 
-- **Design Tokens** - Single source of truth for colors, typography, spacing, and more
-- **Framework-Agnostic CSS** - Works with any framework or vanilla HTML
-- **Accessibility First** - WCAG 2.1 AA compliant, keyboard navigation, ARIA support
-- **Themes** - Light, dark, and high-contrast modes with system preference support
-- **Token Pipeline** - Automated build system (JSON → CSS Variables + TypeScript)
-- **Comprehensive Components** - 16+ production-ready components
-- **Storybook Documentation** - Interactive component explorer with a11y testing
-- **TypeScript Support** - Full type definitions for tokens
+[![npm version](https://img.shields.io/npm/v/@neuravision/construct?color=F4581C&label=npm&logo=npm)](https://www.npmjs.com/package/@neuravision/construct)
+[![npm downloads](https://img.shields.io/npm/dm/@neuravision/construct?color=F4581C)](https://www.npmjs.com/package/@neuravision/construct)
+[![Storybook](https://img.shields.io/badge/Storybook-live-FF4785?logo=storybook&logoColor=white)](https://samyssmile.github.io/construct/)
+[![Deploy](https://img.shields.io/github/actions/workflow/status/Samyssmile/construct/deploy-storybook.yml?branch=main&label=storybook%20build)](https://github.com/Samyssmile/construct/actions/workflows/deploy-storybook.yml)
+[![WCAG 2.2 AA target](https://img.shields.io/badge/WCAG_2.2-AA_target-2ea44f)](docs/guidelines.md)
+[![License: MIT](https://img.shields.io/npm/l/@neuravision/construct?color=2ea44f)](LICENSE)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-2ea44f)](CONTRIBUTING.md)
 
-## 🚀 Quick Start
+[**Live Storybook**](https://samyssmile.github.io/construct/) · [Components](#-components) · [Design Tokens](#-design-tokens) · [Accessibility](#-accessibility) · [Contributing](CONTRIBUTING.md)
+
+</div>
+
+---
+
+## Why Construct?
 
-### Installation
+Construct is a **single source of design truth** that ships portable CSS, validated design tokens, and opt-in headless behaviors — without framework lock-in. Style values live once as JSON tokens and compile to CSS custom properties, JSON, and typed TypeScript exports. Components use `ct-` classes and ARIA/data state, so they work anywhere that renders DOM.
+
+- 🎯 **Three token layers** — primitive, semantic, and component contracts with schema and contrast validation
+- 🧩 **Framework-agnostic** — 49 standalone component style entries and a full CSS bundle
+- ♿ **Accessibility first** — WCAG 2.2 AA targets, tested ARIA/keyboard controllers, focus and forced-colors contracts
+- ⚙️ **Optional behavior** — nine typed, dependency-free ESM controllers; importing CSS never starts JavaScript
+- 🎨 **Three themes** — `light`, `dark`, `high-contrast`, with system-preference fallback
+- 📐 **The "datum" grammar** — a signature orange reference line for focus / active / current state
+- 🛠️ **Typed tokens** — autocomplete-friendly TypeScript exports
+- 📖 **Interactive docs** — every component documented & a11y-tested in [Storybook](https://samyssmile.github.io/construct/)
+
+## 📦 Installation
 
 ```bash
 npm install @neuravision/construct
 ```
 
-### Usage
+Using Angular? Reach for the official wrapper [**@neuravision/ng-construct**](https://github.com/Samyssmile/ng-construct) — typed, signal-based components built on top of these styles.
 
-Import the foundation styles and components:
+## 🚀 Quick Start
+
+Import the foundation styles and the component bundle once (e.g. in your global stylesheet):
 
 ```css
 @import "@neuravision/construct/foundations.css";
 @import "@neuravision/construct/components/components.css";
 ```
 
-Use the components in your HTML:
+Then use the classes in your markup:
 
 ```html
-<button class="ct-button">Primary Button</button>
-<button class="ct-button ct-button--secondary">Secondary</button>
+<button class="ct-button" type="button">Primary</button>
+<button class="ct-button ct-button--secondary" type="button">Secondary</button>
+
+<div class="ct-field">
+  <label class="ct-field__label" for="email">Email</label>
+  <input class="ct-input" id="email" type="email" placeholder="name@company.com" />
+</div>
 ```
 
-Or use design tokens directly:
+Or build custom UI directly on the tokens:
 
 ```css
-.custom-component {
-  background: var(--color-brand-primary);
+.custom-card {
+  background: var(--color-bg-surface);
+  color: var(--color-text-primary);
   padding: var(--space-4);
   border-radius: var(--radius-control);
 }
 ```
 
-### Themes
+> 💡 Need a smaller bundle? Import a generated standalone style entry such as
+> `@import "@neuravision/construct/components/button.css";`. Related public patterns can share an
+> entry: Radio is included in `checkbox.css`, and Metric is included in `datum.css`.
 
-Set a theme on the root element (or any container) to switch modes:
+Composite widgets can use the optional behavior entry instead of reimplementing keyboard and focus state machines:
 
-```html
-<html data-theme="dark">
-  ...
-</html>
+```js
+import { createModalController } from '@neuravision/construct/behaviors';
 ```
 
-Available values:
-- `light` (default)
-- `dark`
-- `high-contrast`
+Foundations make no network request. Import `@neuravision/construct/fonts.css` before foundations only when the product explicitly accepts the hosted-font privacy and CSP tradeoff; self-hosting is documented in [docs/fonts.md](docs/fonts.md).
 
-If no `data-theme` is set, system preferences are respected:
-- `prefers-color-scheme: dark` → dark theme
-- `prefers-contrast: more` → high-contrast theme
+## 🎨 Theming
 
-## 📦 What's Included
+Set `data-theme` on the root element (or any container) to switch modes:
 
-```
-@neuravision/construct/
-├── tokens/                     # Design tokens (JSON, CSS, JS, TS)
-│   ├── primitives.json         # Base values (colors, sizes)
-│   ├── semantic.light.json     # Semantic mappings
-│   ├── semantic.dark.json      # Dark theme overrides
-│   ├── semantic.high-contrast.json # High-contrast theme overrides
-│   ├── tokens.css              # CSS Custom Properties
-│   ├── tokens.json             # Resolved JSON output
-│   ├── tokens.js               # JavaScript exports
-│   └── tokens.ts               # TypeScript exports
-├── components/                 # Framework-agnostic styles
-│   ├── components.css          # All component styles
-│   └── README.md               # Component documentation
-├── foundations.css             # Reset, typography, layout utilities
-└── docs/                       # Guidelines & best practices
-    └── guidelines.md
+```html
+<html data-theme="dark"> … </html>
 ```
 
-## 🎨 Design Tokens
+| Value | Description |
+|-------|-------------|
+| `light` | Default theme |
+| `dark` | Dark theme |
+| `high-contrast` | Maximum-contrast theme |
 
-Construct uses a two-tier token system:
-
-### Primitives
-Raw design values (colors, spacing, typography)
-
-```json
-{
-  "color": {
-    "stone": {
-      "950": "#16130F"
-    },
-    "orange": {
-      "500": "#F4581C"
-    }
-  },
-  "space": {
-    "4": 8
-  }
-}
-```
+With **no** `data-theme` set, Construct respects system preferences automatically:
+`prefers-color-scheme: dark` → dark, `prefers-contrast: more` → high-contrast.
 
-### Semantic
-Contextual aliases that reference primitives
+Validated product themes can extend a built-in theme without copying generated CSS:
 
-```json
-{
-  "color": {
-    "brand": {
-      "primary": "{color.stone.950}"
-    }
-  }
-}
+```bash
+npx construct-theme --theme ./brand.theme.json --out-dir ./src/generated/construct
 ```
 
-### Build Pipeline
+Load the generated token stylesheet after all Construct style entries, because foundations and component entries include the built-in token sheet themselves:
 
-The token build system automatically generates:
-- **CSS Variables** (`--color-brand-primary`)
-- **TypeScript exports** with type definitions
-- **Resolved JSON** for tooling
-
-```bash
-npm run build
+```css
+@import '@neuravision/construct/foundations.css';
+@import '@neuravision/construct/components/components.css';
+@import './generated/construct/tokens.css';
 ```
 
+Application-specific overrides may follow it. Keeping the generated theme last among Construct imports ensures its root and scoped values win deterministically.
+
 ## 🧩 Components
 
-### Base Components
-- Button (6 variants, 3 sizes)
-- Input (text, email, password, search)
-- Select (native dropdown)
-- Textarea
-- Checkbox
-- Radio
-- Switch
-
-### Complex Components
-- Card
-- Table / Data Table
-- Modal
-- Toast (notifications)
-- Tabs
-- Dropdown
-- Pagination
-- Breadcrumbs
-- Datepicker
-
-[View all components in Storybook](https://samyssmile.github.io/construct/)
+49 standalone component style entries, documented and accessibility-tested in [Storybook](https://samyssmile.github.io/construct/).
 
-## ♿ Accessibility
+| Category | Components |
+|----------|-----------|
+| **Actions** | Button · Toggle Group · Toolbar |
+| **Forms & Inputs** | Field · Input · Textarea · Select · Select Menu · Checkbox · Radio · Switch · Slider · Combobox · Chip · File Upload · Datepicker |
+| **Data Display** | Table · Data Table · List · Tree · Avatar · Badge · Icon · Tooltip · Chart · Metric · Meter |
+| **Feedback** | Alert · Banner · Toast · Spinner · Skeleton · Progress Bar · Status · Empty State |
+| **Navigation** | Navbar · Breadcrumbs · Tabs · Pagination · Sidebar · Skip Link |
+| **Overlays** | Modal · Drawer · Popover · Dropdown |
+| **Layout** | Card · Divider · Accordion · App Shell (V1 compatibility + V2 recommended) |
 
-Accessibility is a core principle of Construct:
+→ [**Explore every component in the live Storybook**](https://samyssmile.github.io/construct/)
 
-- ✅ Semantic HTML
-- ✅ ARIA attributes where needed
-- ✅ Full keyboard navigation
-- ✅ Focus management
-- ✅ WCAG 2.1 AA contrast standards
-- ✅ Screen reader support
-- ✅ Respects `prefers-reduced-motion`
-- ✅ Live regions for dynamic content
+## 🎨 Design Tokens
 
-See [Guidelines](docs/guidelines.md) for detailed accessibility rules.
+Construct uses a **three-layer token system**: raw *primitives*, theme-aware *semantic* aliases, and stable *component* decisions.
 
-## 🛠️ Development
+```jsonc
+// primitives — raw values
+{ "color": { "orange": { "500": "#F4581C" }, "stone": { "950": "#16130F" } }, "space": { "4": 8 } }
 
-### Run Storybook
+// semantic — contextual aliases that reference primitives
+{ "color": { "brand": { "primary": "{color.stone.950}", "accent": "{color.orange.500}" } } }
 
-```bash
-npm run storybook
+// component — reusable component decisions
+{ "button": { "height": "{size.controlHeight.md}", "radius": "{radius.control}" } }
 ```
 
-Open http://localhost:6006
+The build pipeline (`npm run build`) compiles `tokens/*.json` into:
 
-### Build Tokens
+- **`tokens.css`** — CSS custom properties (`--color-brand-accent`)
+- **`tokens.json`** — resolved values for tooling
+- **`tokens.ts` / `tokens.js`** — typed exports
 
-```bash
-npm run build
-```
+> ⚠️ Never hand-edit generated files (`tokens/tokens.*`). Edit the source JSON and run `npm run build`.
+
+## ♿ Accessibility
 
-### Check Token Outputs
+Accessibility is a first-class requirement, not an afterthought:
+
+- ✅ Semantic HTML and explicit ARIA/data-state markup contracts
+- ✅ Optional tested keyboard behavior (roving tabindex, focus traps, arrows, typeahead, focus return)
+- ✅ Visible focus indicators (the orange "datum")
+- ✅ Automated WCAG contrast pairs across built-in and custom themes
+- ✅ Screen-reader semantics and documented live-region patterns for dynamic content
+- ✅ Respects `prefers-reduced-motion`
+
+The Storybook a11y addon is configured to **fail the build on violations**. See [docs/guidelines.md](docs/guidelines.md) for the detailed patterns.
+
+## 🧰 Tech & Tooling
+
+| | |
+|---|---|
+| **Distribution** | Plain CSS + design tokens + optional dependency-free ESM behaviors |
+| **Docs & tests** | Storybook 10 · Vitest 4 · Playwright (story-driven) |
+| **a11y testing** | `@storybook/addon-a11y` (fails on violations) |
+| **Token build** | Custom pipeline (`scripts/build-tokens.mjs`) |
+
+## 🛠️ Local Development
 
 ```bash
-npm run check
+npm install              # install dependencies
+npm run storybook        # dev server → http://localhost:6006
+npm run audit            # reject high/critical dependency advisories
+npm run build            # build token and standalone CSS outputs
+npm run check            # verify generated, schema, contrast, CSS, export & version contracts
+npm test                 # run behavior, Storybook, touch & forced-colors browser tests
 ```
 
 ## 🎯 Framework Support
 
-### Current: CSS/HTML
-All components work with vanilla HTML and can be used with any framework.
-
-### Planned: Framework Libraries
-- Angular (standalone components)
-- React (React 18+)
-- Svelte (Svelte 4+)
+| Framework | Status |
+|-----------|--------|
+| **Vanilla HTML / CSS** | ✅ Available — use the `ct-` classes directly |
+| **Angular** | ✅ Available — [`@neuravision/ng-construct`](https://github.com/Samyssmile/ng-construct) |
+| **React** | ✅ CSS + headless controllers; [lifecycle example](examples/react/README.md) |
+| **Svelte** | ✅ CSS + headless controllers |
 
 ## 📖 Documentation
 
-- [Design Guidelines](docs/guidelines.md) - Do/Don'ts, accessibility rules
-- [Component Usage](components/README.md) - HTML patterns and examples
-- [Token Details](tokens/README.md) - Token structure and naming
+- [Design Guidelines](docs/guidelines.md) — do's, don'ts & accessibility patterns
+- [Component Usage](components/README.md) — HTML patterns and examples
+- [Token Reference](tokens/README.md) — token structure & naming
+- [Architecture](docs/architecture.md) — package layers and ownership boundaries
+- [Headless Behaviors](docs/behaviors.md) — typed controllers and lifecycle
+- [Fonts](docs/fonts.md) — network-free defaults, hosted opt-in, self-hosting
+- [Governance](docs/governance.md) — Definition of Done and release gates
+- [Changelog](CHANGELOG.md) — release history
 
 ## 🤝 Contributing
 
-Contributions are welcome! Please read our contributing guidelines (coming soon).
+Contributions are welcome! Please read the [Contributing Guide](CONTRIBUTING.md) and our
+[Code of Conduct](CODE_OF_CONDUCT.md) before opening a PR. Found a security issue? See [SECURITY.md](SECURITY.md).
 
 ## 📄 License
 
-MIT License - see LICENSE file for details
-
-## 🙏 Credits
-
-Built with accessibility and modern design principles in mind.
+[MIT](LICENSE) © Construct contributors
 
 ---
 
-**Construct** - Build accessible design constructs
+<div align="center">
+<sub>Built with accessibility and modern design principles in mind · <a href="https://samyssmile.github.io/construct/">Live Storybook</a></sub>
+</div>