test: harden starter experience quality contract

docs/styling/design-tokens.md

@@ -1,8 +1,32 @@
 # Design-token styling contract
 
 `src/presentation/styles/theme.css` is the styling SSOT. Components consume
-semantic color, spacing, typography, and radius tokens through static Tailwind
-classes.
+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:
 
@@ -13,5 +37,5 @@ Arbitrary-value policy:
 - 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 product modules must not
-import from `src/sample/contract-fixture`.
+The removable sample may demonstrate tokens, but production starter modules do
+not import from `src/sample/contract-fixture`.