Plan a migration from CSS variables to design tokens in Style Dictionary while…
- User
Plan a migration from CSS variables to design tokens in Style Dictionary while maintaining runtime overrides.
- Assistant
Migration Plan: CSS Variables to Style Dictionary Design Tokens (with Runtime Overrides)
Migrating from ad-hoc CSS custom properties (variables) to managed design tokens via Style Dictionary (SD) centralizes your design system, enables multi-platform outputs (CSS, JS, Android/iOS, etc.), and enforces consistency via transforms, aliases, and semantics. Crucially, we'll output tokens as CSS custom properties to preserve runtime overrides (e.g.,
document.documentElement.style.setProperty('--primary-color', '#ff0000')via JS/themes). No loss of dynamic theming.This is a low-risk, phased migration assuming a modern build tool (Webpack/Vite/Next.js) and Git. Estimated effort: 1-2 weeks for a mid-sized system (100-500 tokens).
Phase 0: Preparation (1-2 days)
-
Audit Existing CSS Variables
- Scan your CSS/JS for all
--[a-z-]*declarations (use regex: grep -r --include='.css' --include='.scss' '--.*:' src/ | grep ':root|:global'). - Tools:
Tool Command/Example VS Code Extension: "CSS Peek" or regex search --(\w+):CLI find src -name "*.css*" -exec grep -oP '\-\-(\w+)' {} \; | sort | uniqPurgeCSS/uncss Analyze usage to prune unused vars. - Export to CSV/JSON: Columns:
name(e.g.,--primary-color),value,file,usage-count,category(color/space/etc.). - Identify patterns: e.g.,
--color-primary-500,--spacing-md.
- Scan your CSS/JS for all
-
Install & Setup Style Dictionary
npm init style-dictionary@latest my-design-tokens # scaffolds project cd my-design-tokens npm install- Key deps:
style-dictionary,@tokens-studio/sd-transforms(for Figma sync),style-dictionary-utils.
- Key deps:
-
Define Token Taxonomy
- Use atomic, semantic structure (e.g., Amazon-style: category/type/item/size).
- Example
tokens/color.json(from audit):{ "color": { "primary": { "100": { "value": "#e3f2fd" }, "500": { "value": "#1976d2" }, // Maps to --color-primary-500 "value": "{color.primary.500}" // Alias for default } } } - Categories:
color,spacing,font-size,radius,shadow,breakpoint. - Support themes:
tokens/themes/light.json&dark.jsonwith"$themes": ["light", "dark"].
Phase 1: Build Tokens from CSS (2-3 days)
-
Convert CSS Vars to JSON Tokens
- Script it (Node.js):
// extract-css-vars.js const css = require('css'); // npm i css const fs = require('fs'); // Parse CSS, extract :root vars → tokens JSON // Run: node extract-css-vars.js > tokens/base.json - Manual refine: Add semantics, aliases (
"value": "{size.medium}"), references.
- Script it (Node.js):
-
Style Dictionary Config (
config.json){ "source": ["tokens/**/*.json"], "platforms": { "css": { "transformGroup": "css", "buildPath": "dist/", "files": [{ "destination": "_variables.css", "format": "css/variables", "options": { "outputReferences": true, // For debugging: --var: #hex /* {ref} */ "selector": ":root, :root[data-theme='light']" // Theme support } }] }, "json": { /* For JS runtime if needed */ } } }- Transforms:
name/cti/kebab→--color-primary-500. - Themes: Use
prefix: {themeName}or SD's theme transform.
- Transforms:
-
Build & Validate
npm run build # Generates dist/_variables.css- Diff old vs. new CSS: Ensure 1:1 match.
- Lint tokens:
style-dictionary build --lint.
Phase 2: Integrate into Build Pipeline (1-2 days)
-
Monorepo/Shared Package
- Move
my-design-tokensto/packages/tokens. - Publish as internal NPM:
npm publish --access restricted. - Or Git submodules/CDN for dist/.
- Move
-
Webpack/Vite/Next.js Integration
Build Tool Integration Vite import variables from 'tokens/dist/variables.css';+import('./tokens/dist/variables.css');Webpack css-loaderwithstyle-dictionaryplugin.Next.js next-transpile-modulesorimport '@org/tokens/dist/variables.css';in_app.js.- PostCSS:
@import 'tokens/dist/variables.css';in global CSS.
- PostCSS:
-
Runtime Overrides Preserved
- Output is identical CSS vars:
:root { --color-primary-500: #1976d2; } - JS theming unchanged:
// Switch theme document.documentElement.setAttribute('data-theme', 'dark'); // Or direct override document.documentElement.style.setProperty('--color-primary-500', '#ff5722'); - Fallbacks: Use
var(--color-primary-500, #1976d2)in components.
- Output is identical CSS vars:
Phase 3: Gradual Rollout & Testing (3-5 days)
-
Feature Flags
- Toggle: Build with
--use-tokensflag. - Shadow DOM/iframe test: Load old/new CSS side-by-side.
- Toggle: Build with
-
Testing Checklist
Test How Pass Criteria Visual Regression Percy/Chromatic/backstopjs Pixel-perfect match pre/post. Runtime Overrides Cypress/Puppeteer: cy.get('html').invoke('style', 'setProperty', '--var', 'newval'); cy.get('.test').should('have.css', 'color', 'rgb(newval)');Theme Switching Toggle data-theme, assert vars update.Cross-Browser Safari/Chrome/Firefox: CSS vars support ≥96%. Performance Bundle analyzer: SD output ~5-10KB gzipped. Token Coverage 100% of audited vars mapped; prune unused. -
Rollout Strategy
- Week 1: Migrate non-critical (spacing/fonts).
- Week 2: Colors/shadows; A/B test.
- CI/CD: Add
style-dictionary buildto pipeline; fail on token lint.
Phase 4: Post-Migration Enhancements (Ongoing)
- Figma Sync: Tokens Studio plugin → JSON → SD.
- JS Runtime Tokens: Output
tokens.jsonforcss-vars-ponyfill(IE11). - Overrides Build-Time: SD
"overrides": { "high-contrast": { ... } }. - Monitoring: Sentry for CSS errors; token usage heatmap.
- Scale: Multi-brand (
$brand: { "nike": { ... } }).
Risks & Mitigations
Risk Mitigation Token drift Immutable refs/aliases; CI diffs. Build perf Cache SD builds; incremental. Team adoption Docs: "Use var(--color-primary-500), not hex!" + ESLint plugin. Legacy IE Ponyfill if needed. This plan ensures zero downtime for runtime overrides while unlocking SD's power (e.g., TypeScript types from tokens). Audit your vars first—share a sample CSV if you need a custom extraction script. Questions? The game's afoot.
-
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.