Design Tokens Skill
siteConfig.brand → full design system. Zero guessing.
Purpose
Generate the complete design system (Tailwind config + CSS variables) from siteConfig.brand and siteConfig.fonts. This skill does NOT define colors or fonts — it expands them into a full token system.
Source of Truth
siteConfigis the source. This skill is the transformer. - Colors come fromsiteConfig.brand(primary, secondary, accent, dark, light) - Fonts come fromsiteConfig.fonts(heading, body) - This skill expands them into full scales, semantic tokens, and Tailwind config
What siteConfig provides → what this skill generates
| siteConfig field | This skill generates |
|---|---|
brand.primary (#2563EB) | primary-50 through primary-950 (full scale) |
brand.accent (#F59E0B) | accent, accent-hover, accent-light |
brand.dark (#1F2937) | neutral-50 through neutral-900 |
brand.light (#F9FAFB) | Light section backgrounds |
brand.secondary | Secondary element tokens |
brand.surface | Card/surface backgrounds (if set) |
fonts.heading | Heading font stack |
fonts.body | Body font stack with system fallbacks |
Output
tokens_generated: true
tailwind_config: "tailwind.config.mjs"
css_variables: "src/styles/tokens.css"
design_token_verdict: PASS | WARN | FAILGeneration Process
Step 1: Read siteConfig.brand
import { config } from '@/config/siteConfig.example';
const { primary, secondary, accent, dark, light, surface } = config.brand;
const { heading, body } = config.fonts;Step 2: Generate full primary scale from base color
From brand.primary, generate shades 50–950 using HSL lightness shifts:
| Shade | Lightness shift | Use |
|---|---|---|
| 50 | Very light (95%) | Subtle backgrounds |
| 100 | Light (90%) | Section backgrounds |
| 200 | (80%) | Borders on dark |
| 300 | (70%) | Disabled states |
| 400 | (55%) | Placeholder text |
| 500 | Base color | — |
| 600 | (40%) | Hover states |
| 700 | (30%) | Secondary text |
| 800 | (20%) | Headings |
| 900 | (15%) | Body text, headlines |
| 950 | Very dark (10%) | Maximum contrast |
Step 3: Generate Tailwind config + CSS variables
Write tailwind.config.mjs with all tokens mapped from siteConfig, and src/styles/tokens.css with CSS custom properties.
Token Categories
| Type | Tokens | Usage |
|---|---|---|
| Semantic | primary-*, accent, neutral-* | Use in components |
| Utility | spacing.*, font-*, shadow-* | Internal mapping only |
Rule: Components use semantic tokens. Utility for internal only.
Token Usage Scope
| Token | Allowed | Forbidden |
|---|---|---|
accent | CTAs, links, highlights | Body text, backgrounds |
primary-900 | Headlines, body text | Buttons |
primary-100 | Section backgrounds | Text |
neutral-200 | Borders, dividers | CTAs |
Wrong scope = WARN.
Forbidden Raw Values
| Type | Forbidden | Use Instead |
|---|---|---|
| Colors | #FF6B35, rgb() | bg-accent, text-primary-900 |
| Spacing | mt-[23px] | mt-6 |
| Font sizes | text-[18px] | text-lg |
| Shadows | shadow-[...] | shadow-card |
| Radius | rounded-[12px] | rounded-lg |
Any raw value in component = FAIL.
A11y Contrast Requirements
| Combination | Min Ratio | Standard |
|---|---|---|
| Body text on white | 4.5:1 | AA |
| Body text on primary-100 | 4.5:1 | AA |
| Large text (≥18px) | 3:1 | AA |
| CTA text on accent | 4.5:1 | AA |
| UI components | 3:1 | AA |
Contrast fail = FAIL.
Color Contrast (WCAG AA — Mandatory)
Every text/background color pair MUST meet minimum contrast ratios:
| Text Type | Min Ratio | Example |
|---|---|---|
| Normal text (<18px, or <14px bold) | 4.5:1 | Body text on backgrounds |
| Large text (≥18px, or ≥14px bold) | 3:1 | Headlines on colored sections |
| UI components (icons, borders) | 3:1 | Icon on background |
Common failure patterns to avoid:
- White text on medium-tone accent backgrounds (e.g.
text-whiteon#C4704B= 3.2:1 FAIL) - Semi-transparent text (
text-white/80,text-white/75) on colored backgrounds — the reduced opacity lowers contrast further - Light gray text on white backgrounds (
text-gray-400onwhite= often FAIL)
Validation: Use https://webaim.org/resources/contrastchecker/ for every text/background pair.
Rule: When choosing accent colors, always verify that white text passes 4.5:1 on the accent background. If it fails, darken the accent or use primary-900 text instead.
Typography (Fluid Scale)
Font family derived from siteConfig.fonts:
- Heading:
config.fonts.heading→system-ui→sans-serif - Body:
config.fonts.body→system-ui→sans-serif
| Token | Range | Use |
|---|---|---|
text-base | 16-18px | Body |
text-lg | 18-20px | Lead |
text-2xl | 24-32px | H3 |
text-3xl | 30-40px | H2 |
text-4xl/5xl | 36-64px | H1 |
Spacing (8px Grid)
| Token | Value | Use |
|---|---|---|
py-12 md:py-20 | 48/80px | Section padding Y |
px-4 md:px-8 | 16/32px | Section padding X |
gap-6 md:gap-8 | 24/32px | Component gap |
p-4 md:p-6 | 16/24px | Card padding |
Design Token Verdict
design_token_verdict: PASS | WARN | FAIL
issues: []| Condition | Verdict |
|---|---|
| Raw value in component | FAIL |
| Contrast fail | FAIL |
| Missing required token | FAIL |
| Token doesn't trace back to siteConfig | FAIL |
| Wrong token scope | WARN |
| Missing shade in scale | WARN |
| All rules pass | PASS |
FAIL States
| Condition | | --- | | Hardcoded hex in component | | Arbitrary spacing [Xpx] | | Contrast ratio below AA | | Missing primary scale | | Missing accent colors | | Color/font not derived from siteConfig |
WARN States
| Condition | | --- | | Token used in wrong scope | | Missing optional shades | | Non-standard font loaded |
Definition of Done
tailwind.config.mjsgenerated from siteConfig.brand + siteConfig.fontstokens.csswith CSS variables mapped to siteConfig values- Primary has full scale (50-950) generated from
brand.primary - Accent has hover + light generated from
brand.accent - Neutral scale generated from
brand.dark - Font stacks use
config.fonts.headingandconfig.fonts.body - Contrast passes AA for all generated combinations
- No raw values in components
- No hardcoded colors/fonts that bypass siteConfig
- design_token_verdict = PASS