Design Tokens
Design token architecture, CSS custom properties, and theme system implementation.
When to Use This Skill
| Use this skill when... | Use another skill instead when... |
|---|---|
| Setting up a design token system | Writing individual component styles |
| Implementing light/dark theme switching | Accessibility auditing (use accessibility skills) |
| Organizing CSS custom properties | CSS layout or responsive design |
| Integrating tokens with Tailwind/frameworks | Framework-specific component patterns |
Core Expertise
- Token Architecture: Organizing design tokens for scalability
- CSS Custom Properties: Variable patterns and inheritance
- Theme Systems: Light/dark mode, user preferences
- Component Integration: Applying tokens consistently
Token Structure
Three-Tier Architecture
/* 1. Primitive tokens (raw values) */
:root {
--color-blue-50: #eff6ff;
--color-blue-100: #dbeafe;
--color-blue-500: #3b82f6;
--color-blue-600: #2563eb;
--color-blue-700: #1d4ed8;
--spacing-1: 0.25rem;
--spacing-2: 0.5rem;
--spacing-4: 1rem;
--spacing-8: 2rem;
--font-size-sm: 0.875rem;
--font-size-base: 1rem;
--font-size-lg: 1.125rem;
}
/* 2. Semantic tokens (purpose-based) */
:root {
--color-primary: var(--color-blue-600);
--color-primary-hover: var(--color-blue-700);
--color-background: white;
--color-surface: var(--color-gray-50);
--color-text: var(--color-gray-900);
--color-text-muted: var(--color-gray-600);
--spacing-component: var(--spacing-4);
--spacing-section: var(--spacing-8);
}
/* 3. Component tokens (specific usage) */
.button {
--button-padding-x: var(--spacing-4);
--button-padding-y: var(--spacing-2);
--button-bg: var(--color-primary);
--button-bg-hover: var(--color-primary-hover);
--button-text: white;
padding: var(--button-padding-y) var(--button-padding-x);
background: var(--button-bg);
color: var(--button-text);
}
.button:hover {
background: var(--button-bg-hover);
}
Token Categories
:root {
/* Colors */ --color-{name}-{shade}: value;
/* Typography */ --font-family-{name}: value;
--font-size-{name}: value;
--font-weight-{name}: value;
--line-height-{name}: value;
/* Spacing */ --spacing-{scale}: value;
/* Borders */ --border-width-{name}: value;
--border-radius-{name}: value;
/* Shadows */ --shadow-{name}: value;
/* Transitions */ --duration-{name}: value;
--easing-{name}: value;
/* Z-index */ --z-{name}: value;
}
Theme Implementation
Light/Dark Mode
/* Default (light) theme */
:root {
--color-background: #ffffff;
--color-surface: #f9fafb;
--color-text: #111827;
--color-text-muted: #6b7280;
--color-border: #e5e7eb;
}
/* Dark theme */
[data-theme="dark"] {
--color-background: #111827;
--color-surface: #1f2937;
--color-text: #f9fafb;
--color-text-muted: #9ca3af;
--color-border: #374151;
}
/* System preference */
@media (prefers-color-scheme: dark) {
:root:not([data-theme="light"]) {
--color-background: #111827;
--color-surface: #1f2937;
--color-text: #f9fafb;
--color-text-muted: #9ca3af;
--color-border: #374151;
}
}
File Organization
Recommended Structure
styles/
├── tokens/
│ ├── primitives.css # Raw values
│ ├── semantic.css # Purpose-based tokens
│ └── index.css # Combines all tokens
├── themes/
│ ├── light.css # Light theme overrides
│ └── dark.css # Dark theme overrides
├── base/
│ ├── reset.css # CSS reset
│ └── typography.css # Base typography
└── components/
├── button.css
└── card.css
Component Integration
Component-Level Tokens
/* Card component with local tokens */
.card {
--card-padding: var(--spacing-4, 1rem);
--card-radius: var(--border-radius-lg, 0.5rem);
--card-shadow: var(--shadow-md);
--card-bg: var(--color-surface);
--card-border: var(--color-border);
padding: var(--card-padding);
border-radius: var(--card-radius);
box-shadow: var(--card-shadow);
background: var(--card-bg);
border: 1px solid var(--card-border);
}
/* Variant via token override */
.card--elevated {
--card-shadow: var(--shadow-lg);
}
.card--outlined {
--card-shadow: none;
--card-border: var(--color-border-strong);
}
Agentic Optimizations
| Context | Command |
|---|---|
| Find all CSS variables | grep -r '--[a-z]' styles/ --include='*.css' |
| Check token usage | grep -r 'var(--color-primary)' src/ --include='*.css' --include='*.tsx' |
| Find hardcoded colors | grep -rn '#[0-9a-fA-F]\{3,8\}' src/ --include='*.css' |
| List all token files | find styles/tokens -name '*.css' |
| Validate CSS syntax | npx stylelint 'styles/**/*.css' |
For detailed examples, advanced patterns, and best practices, see REFERENCE.md.
References
- CSS Custom Properties: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascading_variables
- Design Tokens Format: https://design-tokens.github.io/community-group/format/
- Style Dictionary: https://styledictionary.com/
- Tailwind CSS: https://tailwindcss.com/docs/customizing-colors