CSS Design Tokens

Token Structure

/* tokens.css / :root { / Colors - Semantic */ --color-primary: #2563eb; --color-primary-hover: #1d4ed8; --color-secondary: #64748b; --color-success: #22c55e; --color-warning: #f59e0b; --color-error: #ef4444;

/* Colors - Neutral */ --color-background: #ffffff; --color-surface: #f8fafc; --color-border: #e2e8f0; --color-text: #1e293b; --color-text-muted: #64748b;

/* Spacing Scale (4px base) / --space-1: 0.25rem; / 4px / --space-2: 0.5rem; / 8px / --space-3: 0.75rem; / 12px / --space-4: 1rem; / 16px / --space-5: 1.25rem; / 20px / --space-6: 1.5rem; / 24px / --space-8: 2rem; / 32px / --space-10: 2.5rem; / 40px / --space-12: 3rem; / 48px / --space-16: 4rem; / 64px */

/* Typography */ --font-sans: 'Inter', system-ui, sans-serif; --font-mono: 'JetBrains Mono', monospace;

--text-xs: 0.75rem; /* 12px / --text-sm: 0.875rem; / 14px / --text-base: 1rem; / 16px / --text-lg: 1.125rem; / 18px / --text-xl: 1.25rem; / 20px / --text-2xl: 1.5rem; / 24px / --text-3xl: 1.875rem; / 30px */

--leading-tight: 1.25; --leading-normal: 1.5; --leading-relaxed: 1.75;

--font-normal: 400; --font-medium: 500; --font-semibold: 600; --font-bold: 700;

/* Borders */ --radius-sm: 0.25rem; --radius-md: 0.375rem; --radius-lg: 0.5rem; --radius-xl: 0.75rem; --radius-full: 9999px;

/* Shadows */ --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05); --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1); --shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);

/* Transitions */ --duration-fast: 150ms; --duration-normal: 250ms; --duration-slow: 350ms; --ease-default: cubic-bezier(0.4, 0, 0.2, 1); }

Dark Mode

[data-theme="dark"] { --color-primary: #3b82f6; --color-primary-hover: #60a5fa;

--color-background: #0f172a; --color-surface: #1e293b; --color-border: #334155; --color-text: #f1f5f9; --color-text-muted: #94a3b8;

--shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.3); --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.4); }

Usage in Components

// Button.tsx const buttonStyles: CSSProperties = { backgroundColor: 'var(--color-primary)', color: 'var(--color-background)', padding: 'var(--space-2) var(--space-4)', borderRadius: 'var(--radius-md)', fontSize: 'var(--text-sm)', fontWeight: 'var(--font-medium)', transition: background-color var(--duration-fast) var(--ease-default), };

/* Button.css */ .btn { background-color: var(--color-primary); color: var(--color-background); padding: var(--space-2) var(--space-4); border-radius: var(--radius-md); font-size: var(--text-sm); font-weight: var(--font-medium); transition: background-color var(--duration-fast) var(--ease-default); }

.btn:hover { background-color: var(--color-primary-hover); }

Token Naming Convention

--{category}-{property}-{variant}

Examples: --color-primary --color-primary-hover --space-4 --text-lg --radius-md --shadow-lg

Component Token Mapping

Component Tokens

Button --color-primary , --space-2/4 , --radius-md , --text-sm

Input --color-border , --space-2/3 , --radius-md , --text-base

Card --color-surface , --space-4 , --radius-lg , --shadow-md

Badge --color-* , --space-1/2 , --radius-full , --text-xs

Theme Provider Pattern

// ThemeProvider.tsx type Theme = 'light' | 'dark' | 'system';

export const ThemeProvider: FC<{ children: ReactNode }> = ({ children }) => { const [theme, setTheme] = useState<Theme>('system');

useEffect(() => { const root = document.documentElement; const systemDark = window.matchMedia('(prefers-color-scheme: dark)').matches; const resolved = theme === 'system' ? (systemDark ? 'dark' : 'light') : theme; root.setAttribute('data-theme', resolved); }, [theme]);

return ( <ThemeContext.Provider value={{ theme, setTheme }}> {children} </ThemeContext.Provider> ); };

Best Practices

• Use semantic names (--color-primary ) over literal (--color-blue )

• Define scales with consistent ratios (4px spacing, modular type)

• Keep token count minimal but comprehensive

• Document token purpose in comments

• Test all tokens in both light/dark modes