49 lines
2.2 KiB
Markdown
49 lines
2.2 KiB
Markdown
# 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.
|