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