Problem
Three issues affect the visual design system — token naming, dark/light switching, and colour contrast validation.
1. CSS colour tokens in index.css have no documented naming convention
Tokens like --color-ink, --color-surface, --color-brand are used throughout but are not documented anywhere. New contributors adding components guess at token names or introduce one-off hardcoded values. A DESIGN_TOKENS.md or a comment block in index.css would serve as a living reference.
2. No CSS class or data attribute to toggle light/dark mode
The library is dark-first with no documented light mode. Adding data-theme="light" on <html> or a .light class should toggle the CSS variables to a light palette. Currently there is no light mode variable set defined anywhere in the codebase.
3. No colour contrast audit — some text/background combinations may fail WCAG 1.4.3
text-ink-3 over bg-surface-2, text-ink-4 over bg-surface, and the text-[9px] badge text have never been audited for 4.5:1 (normal text) or 3:1 (large text) contrast. An automated contrast check in CI (e.g. using @axe-core/cli) would catch failures.
Solution
- Add a
## Design Tokens comment block to index.css documenting each token group with example values.
- Add a
[data-theme="light"] rule block in index.css with overridden light-mode values for the core tokens.
- Add
@axe-core/cli to devDependencies and a CI step that runs axe against the built demo app.
Acceptance Criteria
Note for Contributors: Write a clear PR description. Include side-by-side screenshots in dark and light mode, and the axe CI output showing zero critical violations.
Problem
Three issues affect the visual design system — token naming, dark/light switching, and colour contrast validation.
1. CSS colour tokens in
index.csshave no documented naming conventionTokens like
--color-ink,--color-surface,--color-brandare used throughout but are not documented anywhere. New contributors adding components guess at token names or introduce one-off hardcoded values. ADESIGN_TOKENS.mdor a comment block inindex.csswould serve as a living reference.2. No CSS class or data attribute to toggle light/dark mode
The library is dark-first with no documented light mode. Adding
data-theme="light"on<html>or a.lightclass should toggle the CSS variables to a light palette. Currently there is no light mode variable set defined anywhere in the codebase.3. No colour contrast audit — some text/background combinations may fail WCAG 1.4.3
text-ink-3overbg-surface-2,text-ink-4overbg-surface, and thetext-[9px]badge text have never been audited for 4.5:1 (normal text) or 3:1 (large text) contrast. An automated contrast check in CI (e.g. using@axe-core/cli) would catch failures.Solution
## Design Tokenscomment block toindex.cssdocumenting each token group with example values.[data-theme="light"]rule block inindex.csswith overridden light-mode values for the core tokens.@axe-core/clitodevDependenciesand a CI step that runsaxeagainst the built demo app.Acceptance Criteria
index.csshas a documentation comment block for each token groupdata-theme="light"to<html>switches the app to a light paletteaxeCI step runs and reports no critical contrast violationsnpm run buildpasses