# Design-token styling contract

`src/presentation/styles/theme.css` is the styling SSOT. Components consume
semantic color, spacing, typography, status, and radius tokens through static
classes. `/examples/ui` is the executable token and primitive gallery.

## 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 sample may demonstrate tokens, but production starter modules do
not import from `src/sample/contract-fixture`.

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.