chore: initialize from frontend template 4dc033c

docs/styling/design-tokens.md

@@ -0,0 +1,49 @@
+# 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](./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.