# Design-token styling contract Tokens are defined in three layers under `src/presentation/design-system/tokens/`: `primitive.css` holds the raw palette and scales, `semantic.css` maps them to roles (surface, content, border, action, status) and overrides those roles for the dark theme, and `component.css` maps roles to per-component values. `src/presentation/styles/theme.css` only imports the three files and the style files under `src/presentation/styles/theme/`. Components consume semantic color, spacing, typography, status, and radius tokens through static classes. The executable token and primitive gallery is the workshop story `src/presentation/design-system/galleries.stories.tsx` (`corepack pnpm storybook`). ## Rules a rebrand must keep `check:design-system` (`scripts/check-design-system.ts`) fails when a token edit breaks one of these. The reasons are next to each rule in `scripts/lib/design-system-rules.ts`. - UI-01: `--color-focus` has at least 3:1 contrast against every surface a focus ring can sit on, in both themes. Those tokens must resolve to opaque `oklch()` values so the contrast can be computed. - UI-02: `color-mix()` mixes in `oklab`, never in a hue-based space. - UI-03: every component token is read by some style. - UI-05: `--font-sans` starts with a generic family or one the repository ships with `@font-face`. The same check requires the token names in `token-contract.ts`, the dark overrides of the core semantic roles, a forced-colors fallback in `component.css`, no raw palette values outside the token files, and no direct headless-library imports. ## Theme contract The supported public preference is the closed set `system`, `light`, and `dark`. `ThemeProvider` reads and writes `COLOR_SCHEME` through the application storage port; it does not access a raw storage key. `system` subscribes to `prefers-color-scheme` changes. Bootstrap applies the persisted preference before React paints. Components use semantic tokens such as `--color-panel`, `--color-content`, `--color-border`, `--color-action`, and status surface/content/border triples. They must not hard-code a light-only panel or text color. Both light and dark surfaces are included in automated axe checks. ## Included primitives - `Button`: primary, secondary, danger, and ghost intent - `TextField`: label, help text, required state, and associated validation error - `Card`: labelled surface with optional footer - `Alert` and `Badge`: non-color-only status feedback - `Dialog`: native modal semantics, Escape/backdrop close, and trigger focus restoration - async and access state surfaces: loading, refresh, empty, terminal error, auth required, forbidden, and not found Arbitrary-value policy: - prefer a named semantic token - bracket values are allowed only for one-off platform constraints that cannot be expressed by the current scale - a repeated bracket value must be promoted into `@theme` - user-controlled or runtime-composed class strings are forbidden - class variants must be selected from a closed static map The removable reference feature may demonstrate tokens, but generic production starter modules do not import its domain, application, adapter, or presentation implementation. This file documents the currently implemented token and primitive baseline. The [design-system platform contract](./design-system-platform.md) defines the target token layers, component catalog, local Lucide/headless-library facades, page patterns, accessibility and internationalization rules, isolated workshop, and component-authoring recipe. Items in that target document are not treated as implemented until their acceptance tests pass.