--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -9,9 +9,28 @@
 
 - Keep React components readable and small.
 - Use token variables from `src/styles/tokens.css`; do not hardcode brand colors in component files.
+- Use `--color-text-inverse` (not raw `#fff`) for text on brand-colored surfaces.
+- Use spacing tokens (`--space-*`) for all padding, margin, and gap values; no raw px except borders and font sizes listed in the a11y guidelines.
 - Preserve keyboard and screen reader behavior when editing interactive UI.
+
+## UI style baseline (current production)
+
+- Typography: `--font-sans` for UI, `--font-mono` for data. Body ≥16px, metadata ≥14px.
+- Colors: semantic token names only (`--color-brand`, `--color-success`, etc.). Dark-mode overrides live in `tokens.css` — never add one-off media queries in components.
+- Radius: `--radius-sm` (buttons, inputs), `--radius-md` (cards), `--radius-lg` (panels/modals).
+- Elevation: `--shadow-card` for raised surfaces. No additional shadows without review.
+- Motion: keep under 180ms via `--motion-fast`. `prefers-reduced-motion` blanket is enforced globally — do not add component-level motion overrides.
+
+## Accessibility requirements (WCAG 2.1 AA)
+
+- Every interactive element must have a visible `:focus-visible` indicator using `--color-focus`.
+- Information must never rely on color alone — always pair with text labels or icons.
+- Semantic HTML first: use `<button>`, `<a>`, `<article>`, `<section aria-label>`, etc.
+- Use `aria-live="polite"` for async data refresh notifications.
+- Inline styles cannot express pseudo-classes; interactive focus/hover states must be defined in CSS (global base or CSS modules).
 
 ## Handoff expectations
 
 - If a UI PR changes visual hierarchy, include before/after screenshots.
 - If accessibility behavior changes, include a short testing note for keyboard-only flow.
+- If new tokens are added to `tokens.css`, include dark-mode counterparts.