Implementation and Conformance Gates

Token sources, the deterministic generator, the runtime appearance provider, and the accessibility provider are all landed. This page describes the current implementation structure and the conformance gates that remain in force.

Directory structure

frontend/packages/materials/src/tokens/
|-- source/
|   |-- reference.tokens.json
|   |-- system.tokens.json
|   |-- component.tokens.json
|   `-- themes/*.tokens.json
`-- generated/
    |-- tokens.css
    |-- tokens.ts
    `-- tokens.schema.json

The generation flow is:

Canonical JSON
  -> schema validation
  -> color conversion and gamut validation
  -> CSS, TypeScript, and schema output
  -> shadcn compatibility aliases
  -> application runtime injection
  -> component and visual tests

Implementation progress

Step	Status
Create Source, schema, and a deterministic generator in `packages/materials`	Done
Generate Reference, System, Component, and Compatibility CSS	Done
Inject Mode, Brand, and Density once at the Web application root	Done (AppearanceProvider)
Four accessibility override axes (fontScale, contrast, colorVision, reduceMotion)	Done (AccessibilityProvider)
Migrate the old widgets theme and login variables into the compatibility path	Done
Build List, Detail, Edit, Wizard, Dashboard, and Identity recipes	Identity delivered as a tracer bullet; others proceed slice by slice
Add token lint, WCAG, keyboard, state, and visual-regression gates	Ongoing

Conformance gates

A frontend release can claim Design System 1.2 conformant only when:

one source generates Hex, OKLCH, CSS, TypeScript, and schema without drift;
Light x Dark x six Brands x four Densities resolves without missing or cyclic values;
text, links, buttons, status, focus rings, and control boundaries pass WCAG 2.2 targets;
Button, Input, Select, Table, Dialog, Sidebar, and Form have tested state matrices;
Side collapse, Top More, and 1024/768 behavior have regressions;
Managed Tabs test overflow, pinning, dirty state, and restore;
Advanced Filter and Query Studio test cancellation, errors, and keyboard paths;
Loading, Empty, Filter-empty, Error, Unauthorized, and Stale are represented;
visual tests use real HTML/CSS and stable fonts;
Frontend Design Guardian reports pass.

Commands that exist today

Run these from frontend/:

# These are the real repository gates available today.
yarn install --immutable
yarn lint
yarn typecheck
yarn build

yarn scaffold:page, yarn dev:ui, and yarn ui:check are frozen developer-experience targets. They are not implemented yet and must not be placed in CI as if they already exist.

Sweep checks

# Expect no raw colors outside generated output or registered exceptions.
rg -n '#[0-9A-Fa-f]{3,8}|rgb\\(|hsl\\(|oklch\\(' \
  apps packages --glob '!**/generated/**'

# Pages and widgets must not consume Reference tokens directly.
rg -n -- '--ref-' apps packages/widgets

# Token generation drift detection; expect no diff.
node packages/materials/scripts/generate-tokens.mjs --check

Continue with page development and frontend tooling.