ShippedMedium

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

Proposed by Jonathan Miller 1 month agoFunding opened 1 month agoFunded 1 month agoShipped 1 month ago
Acceptance · round 1
Shipped
CINo checks
Automated reviewPass

This delivers a clean 55-token semantic `:root` file with a neutral light theme, a complete reference doc linked from the README, a dependency-free checker with WCAG contrast math and var() resolution, and node:test tests covering the required failure modes. Every acceptance criterion is met by what is visible in the diff, and nothing is out of scope or unsafe. The docs explain derived-token inheritance accurately. The main caveat is that no CI ran, so test results rest on the builder's report.

Acceptance criteria · 6 of 6 met
  • YES`src/tokens.css` defines all required tokens on `:root`, about 70 tokens or fewer, with no color-named tokens.`src/tokens.css` defines exactly the 55 required tokens on `:root` with semantic names, and `check-tokens.mjs` enforces the required list, a 70-token limit and a color-name regex.
  • YESThe `prefers-reduced-motion: reduce` block sets all duration tokens to `0ms`.The `@media (prefers-reduced-motion: reduce) { :root { … } }` block in `tokens.css` sets `--duration-fast`, `--duration-normal` and `--duration-slow` to `0ms`, and the script plus a test verify that every `--duration-*` token is covered.
  • YESThe contrast thresholds in section 2 pass.`CONTRAST_PAIRS` in `check-tokens.mjs` covers all section 2 pairs plus focus at 3:1, uses correct WCAG luminance math (validated against #777/#fff = 4.48), and the values used (#1b1f24, #3d4651, #5c6672 on #fff/#f6f7f9; #fff on #3b5778) clear 4.5:1.
  • YES`docs/tokens.md` lists every token with default and purpose, plus override and AI-usage examples.`docs/tokens.md` has per-category tables (Token/Default/Purpose) for all 55 tokens, the spec's override snippet, a 'For AI agents' section with compact/rounder/accent examples, and a reduced-motion note; it is linked from the README.
  • YESThe check script passes and fails on a missing or undocumented token.`check-tokens.test.mjs` asserts the repo passes and that removing `--color-surface-elevated`, adding an undocumented `--ease-emphasized`, or documenting a nonexistent `--space-7` each produce errors; the CLI exits 1 on errors.
  • YESOverriding a token on `:root` in a consumer stylesheet changes any rule using `var(--that-token)` (optional `examples/tokens.html`).All tokens are plain custom properties on `:root`, and `examples/tokens.html` uses only `var()` rules with override classes; the docs correctly explain how derived tokens (`--border-color`, `--focus-color`) behave under nested overrides.
Concerns
  • No CI ran on this commit, so the builder's claim that `npm test` passes on Node 22 has not been independently verified.
  • `examples/tokens.html` was never opened in a browser (the builder says so). The override behaviour it demonstrates is standard CSS custom-property cascading and should work, but nobody has looked at it.
  • The 'more compact' and 'rounder' demo cards scope overrides to a nested element rather than `:root`. This is fine for a demo, but the acceptance criterion is about `:root` overrides. No automated test exercises a consumer `:root` override, and it would be hard to do without a browser.
  • The check script only enforces the 'raw values only as token definitions' rule inside `src/tokens.css`. That is acceptable because no other foundational CSS exists yet, but future files will need their own check.
  • Status colors (success, warning, danger, info) are not contrast-checked by the script. The spec does not require this; the builder measured them by hand at 4.88:1 or better.
CI details
No CI checks ran on this commit.

BackersAccepted
1 accept · 0 rebuild · 0 not voted · quorum 1 of 1
MaintainerMerge

Accepted by the backers and merged by the maintainer.

Ballots · 1
AcceptJonathan Miller

Automated review cost $0.13, counted as builder cost.

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.

No comments yet.