design-tokens

Design Tokens - Comprehensive Reference

Version: 2.0.0 Purpose: Generate and maintain design system tokens across all project surfaces (UI, emails, PDFs, CLI, charts, docs)

---

Overview

This skill provides comprehensive guidance for initializing and maintaining design tokens in design/systems/tokens.json and tokens.css. Supports both brownfield (scan existing code) and greenfield (generate new palette) modes.

Coverage:

• UI components (React/Vue/Svelte)
• MJML/HTML emails
• PDF styling (WeasyPrint, Puppeteer)
• CLI colors (chalk/colorette)
• Data visualization (d3, Chart.js, Recharts)
• Documentation assets (MD/MDX)

---

What Changed in v2

Non-UI surface coverage:

• MJML/HTML emails (inline CSS)
• PDF styling (WeasyPrint, Puppeteer CSS)
• CLI colors (chalk/colorette)
• Data visualization palettes (d3, Chart.js, Recharts)
• Documentation assets (MD/MDX)

Brownfield scan improvements:

• Source-agnostic: JSX/TSX, CSS/SCSS, CSS-in-JS, MD/MDX, MJML, Python/JS PDF styles
• Scans 10+ file types
• Detects arbitrary Tailwind values (bg-[#xxx])

Contrast enforcement:

• Auto-nudges OKLCH lightness until WCAG 2.1 passes (≥4.5:1)
• Uses colorjs.io for perceptually accurate contrast calculation

Tailwind v4 alignment:

• Theme variables as CSS variables (not hardcoded palette)
• Validates tokens.css import in globals.css

Color-blind-safe palettes:

• Okabe-Ito categorical palette for charts
• 8 colors scientifically validated for color-blind users

---

Mental Model

Flow: detect mode → scan/generate → consolidate → validate wiring → contrast fixups → emit artifacts → report debt

Brownfield: Scan existing code for patterns across UI, emails, PDFs, CLI, charts, docs. Consolidate duplicates and propose migrations.

Greenfield: Ask minimal questions, generate OKLCH palette with contrast validation.

---

Prerequisites

Dependencies:

{
  "devDependencies": {
    "colorjs.io": "^0.5.0",
    "picocolors": "^1.0.0",
    "fs-extra": "^11.2.0"
  }
}