chore: design system colour tokens, primitives & Storybook#6883
Open
talissoncosta wants to merge 15 commits intomainfrom
Open
chore: design system colour tokens, primitives & Storybook#6883talissoncosta wants to merge 15 commits intomainfrom
talissoncosta wants to merge 15 commits intomainfrom
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
github-actions
bot
added
the
front-end
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #6883 +/- ##
=======================================
Coverage 98.33% 98.33%
=======================================
Files 1335 1335
Lines 49943 49943
=======================================
Hits 49113 49113
Misses 830 830 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Contributor
Author
|
Blocker: #6866 (Decouple Button from Redux store) should land before or alongside this PR — Button's dependency on |
This was referenced Mar 9, 2026
7 tasks
talissoncosta
force-pushed
the
chore/design-system-tokens
branch
from
42b4c1e to
87a4eae
Compare
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Single source of truth: common/theme/tokens.json defines all 109 design tokens (41 colour + 68 non-colour) with values, dark mode overrides, and usage descriptions. Codegen script (scripts/generate-tokens.mjs) generates: - common/theme/tokens.ts — TypeScript exports - web/styles/_tokens.scss — CSS custom properties (:root + .dark) - documentation/TokenReference.generated.stories.tsx — flat JSX for MCP Token categories: - Colour: surface, text, border, icon (with light/dark variants) - Spacing: Tailwind naming convention (--space-1 = 4px, --space-4 = 16px) - Border radius: none through full (8 values) - Typography: headings h1-h6, body, caption, label, font weights - Elevation: 4 shadow levels with dark mode overrides - Motion: 3 durations + 3 easing curves Primitive colour palette (_primitives.scss) provides 7 families (slate, purple, red, green, gold, blue, orange) with 50-950 scales. lint-staged auto-runs codegen when tokens.json is committed. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Set up Storybook 10 with webpack5, SWC compiler, and a11y addon. Chromatic CI workflow captures visual regression on every PR. Storybook UI respects OS colour scheme preference (light/dark). Chromatic modes capture every component story in both themes. Components with stories: - Banner — 4 variants (success, warning, danger, info) with CTA - Button — 7 themes, 4 sizes, disabled states, icon variants - Switch — on, off, disabled, controlled - Skeleton — text, badge, circle variants - SettingRow — pattern component using React 19 useId() - Icons — categorised searchable catalogue of all 61 icons New components: - Banner — variant-driven alert with semantic colour tokens - SettingRow — accessible settings toggle with ARIA labels - Skeleton — loading placeholder with reduced motion support - RequireFeatureOwnershipSetting — project setting (#4432) Shared Storybook utilities: - DocPage, ScaleRow, Swatch, TokenGroup helper components - docs.scss dogfooding 79 token references (spacing, colour, font, radius, motion) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Visual stories for each token category: - Palette — primitive colour scales (auto-generated from _primitives.scss) - Semantic Colour Tokens — runtime CSS var reading with theme toggle - Tag & Project Colours — categorical swatches - Spacing, Border Radius, Elevation, Motion — import from tokens.ts Token Reference (MCP) — auto-generated flat JSX with all 109 tokens inlined for Storybook MCP consumption by AI agents. All documentation stories have Chromatic snapshots disabled. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Introduction — welcome page with getting started guide - Decision Framework — where does a new colour go? + how to create a semantic token (HTML tables for MDX3 compat) - Token Maintenance — codegen workflow, adding/modifying/removing tokens - Typography — token reference for --font-* tokens (audit findings moved to Notion/Slides, issue #7077 for future components) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add _token-utilities.scss with utility classes consuming the design tokens for colours, borders, icons, radius, shadows, font weights, and transitions. These fill the gap Bootstrap doesn't cover — semantic surface colours, icon colours, border radius tokens, etc. Remove spacing tokens entirely — Bootstrap handles spacing via its existing utility classes. This avoids two competing sources of truth for the same concern. - Create web/styles/_token-utilities.scss (no !important, no spacing) - Remove space key from tokens.json - Update generate-tokens.mjs to skip spacing generation - Delete SpacingTokens.stories.tsx - Regenerate _tokens.scss, tokens.ts, and MCP reference story - Update TokenMaintenance.mdx and docs.scss Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add utility class generation to the codegen pipeline. When tokens.json changes, the pre-commit hook now generates _token-utilities.scss alongside _tokens.scss, tokens.ts, and the MCP reference story. Adding a new token to tokens.json automatically creates its utility class — no manual SCSS to write. - Add generateUtilities() to generate-tokens.mjs - Update lint-staged to auto-stage _token-utilities.scss - Update TokenMaintenance.mdx to document the 4-file pipeline Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The text-on-fill token was the only token that described a surface
context rather than a semantic role, breaking the consistent
{category}-{role} naming pattern. It also had no dark mode variant
(always #ffffff), unlike other semantic tokens.
Removed from tokens.json, _tokens.scss, _token-utilities.scss,
tokens.ts, and all documentation references.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Font tokens (family, h1–h6, body, caption, label, weights) were added prematurely. Typography is listed as future work in the proposal and the approach hasn't been agreed on yet. Remove from tokens.json, generated SCSS, utility classes, and codegen script. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
These were removed from tokens.ts in a previous commit but the barrel export in index.ts wasn't updated, causing type errors. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The lockfile had a corrupted $@types/react reference that broke npm ci on CI. Restored from main and re-ran npm install. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add all 77 primitive colours (slate, purple, red, green, gold, blue, orange) plus slate-1000 (#000000) to tokens.json as the single source of truth. This enables the generator to output var() references instead of resolved hex values in semantic tokens. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…utput Update the token generator to: - Output primitive CSS custom properties in :root - Replace resolved hex values with var(--primitive) references - Convert rgba() alpha variants to oklch(from var(--primitive) l c h / alpha) - Show primitive references in the Storybook MCP story Semantic tokens now trace back to primitives — zero raw hex or rgba in the colour layer. Addresses review feedback on PR #6883. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The Icon token group was missing from the ORDER array and GROUP_LABELS map, so --color-icon-* tokens were not displayed in the Semantic Colour Tokens story. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Storybook MCP is the source of truth for the design system. Claude should query it before grepping source files to find components. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
docs/if required so people know about the feature.Changes
Contributes to #6606
Design system token foundation with Storybook, Chromatic visual regression, and MCP integration for AI-assisted development.
1. Token architecture
Single source of truth:
common/theme/tokens.jsondefines all tokens with values, dark mode overrides, and usage descriptions. A codegen script (scripts/generate-tokens.mjs) generates four output files —tokens.ts,_tokens.scss,_token-utilities.scss, and a flat JSX MCP reference story. lint-staged auto-runs the codegen on commit.Primitive → Semantic reference chain:
var(--primitive)— zero raw hex in the semantic layeroklch(from var(--purple-600) l c h / 0.08)Colour tokens (40): Surface, text, border, and icon categories with light/dark variants. Primitive palette (
_primitives.scss) provides 7 colour families (slate, purple, red, green, gold, blue, orange) with 50–950+ tonal scales.Non-colour tokens (18):
Token utility classes (
_token-utilities.scss): Auto-generated CSS classes consuming tokens —bg-surface-*,text-*,border-*,icon-*,rounded-*,shadow-*,transition-*.2. Storybook + Chromatic
var(--purple-600)) not resolved hex values3. Component stories
4. New components
5. Documentation (MDX + token stories)
6. Dogfooding
documentation/docs.scssuses token references across all categories (spacing, colour, font, radius, motion).How did you test this code?
npm run storybook— all stories render correctly in light and dark modenpm run build-storybook— builds without errorsnpm run generate:tokens— codegen produces correct output, idempotent (running twice gives same result)npm run typecheck— no new type errors from token filesENV=local npm run dev— app renders identically (no visual regression)get-documentation