clean-architecture-frontend-template/docs/styling/design-tokens.md

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 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.