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
```css
[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