Add core semantic CSS design tokens (:root), default light theme, token reference docs and check script

Motivation

SynthCSS needs a small, semantic set of CSS custom properties that every future component and layout primitive consumes. AI agents should be able to restyle an interface by changing a handful of clearly named variables, e.g. "more compact, larger radius, different primary color".

Scope

1. Token file

Create src/tokens.css (assumption: if the repo has an existing source layout, follow it instead). All tokens are defined on :root. Names are unprefixed, short and semantic. No color-named tokens such as --blue-500. Use at most about 70 tokens in total.

Required tokens. Exact values are the agent's choice, within the constraints below.

• Color: --color-background, --color-surface, --color-surface-elevated, --color-text, --color-text-secondary, --color-text-muted, --color-border, --color-primary, --color-primary-hover, --color-on-primary (text on primary; assumption, needed for contrast), --color-success, --color-warning, --color-danger, --color-info.
• Spacing: --space-1 … --space-6. Use a monotonically increasing rem scale (assumption: 0.25, 0.5, 0.75, 1, 1.5, 2rem).
• Typography:
  • Font families: --font-sans, --font-mono (system font stacks, no web-font loading).
  • Sizes: --text-sm, --text-base, --text-lg, --text-xl, --text-2xl, --text-3xl.
  • Weights: --weight-normal, --weight-medium, --weight-semibold, --weight-bold.
  • Line heights: --leading-tight, --leading-normal, --leading-relaxed.
• Radius: --radius-sm, --radius-md, --radius-lg, --radius-full.
• Borders: --border-width, --border-color. --border-color defaults to var(--color-border).
• Shadows: --shadow-sm, --shadow-md, --shadow-lg. Keep them subtle and low-opacity.
• Sizing: --control-height, --input-height, --container-width, --content-width.
• Focus: --focus-color, --focus-width, --focus-offset. --focus-color must contrast at least 3:1 against --color-background.
• Motion: --duration-fast, --duration-normal, --duration-slow, --ease-standard. Inside @media (prefers-reduced-motion: reduce), all --duration-* tokens are overridden to 0ms on :root.

2. Default light theme

The values in :root form a neutral light theme with no brand coupling and a desaturated primary. Contrast must meet WCAG AA:

• --color-text and --color-text-secondary on --color-background and --color-surface: at least 4.5:1.
• --color-text-muted on --color-background: at least 4.5:1.
• --color-on-primary on --color-primary: at least 4.5:1.

Hard-coded raw values (hex, px etc.) may appear only as token definitions. Any other foundational CSS in the repo must use var(--…) where a token exists.

3. Documentation

Add docs/tokens.md (assumption) and link it from the README. It contains:

• A reference table per category: token, default value, intended purpose.
• An override example:

  :root { --color-primary: #YOUR_COLOR; --radius-md: 0.5rem; --space-3: 0.75rem; }
  

• A short "For AI agents" section: always use var(--token) instead of raw values, and show which tokens to change for "more compact", "rounder" and "different accent".
• A note on reduced-motion behavior.

4. Verification script

Add a dependency-free Node script (e.g. scripts/check-tokens.mjs, runnable via npm test or npm run check:tokens) that:

• Parses src/tokens.css and confirms every required token above is defined.
• Confirms every defined token appears in docs/tokens.md, and every documented token exists.
• Confirms the reduced-motion media block overrides all --duration-* tokens.
• Computes the contrast ratios listed in section 2 and fails if any is below threshold.

Acceptance criteria

• src/tokens.css defines all required tokens on :root, about 70 tokens or fewer, with no color-named tokens.
• The prefers-reduced-motion: reduce block sets all duration tokens to 0ms.
• The contrast thresholds in section 2 pass.
• docs/tokens.md lists every token with default and purpose, plus override and AI-usage examples.
• The check script passes and fails on a missing or undocumented token.
• Overriding a token on :root in a consumer stylesheet changes any rule using var(--that-token). A small examples/tokens.html demonstrating this is optional.

Out of scope

• Dark theme or multiple themes.
• Components, utility classes or layout primitives.
• Build or minification pipeline, beyond a minimal package.json if none exists.
• Web fonts.
• A JS theming API.