# 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 A feature may demonstrate tokens, but generic production starter modules do not import a feature's 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.