tomevault-io Design Tokens Skill
This skill helps you create, organize, and manage design tokens for scalable design systems. I'll guide you through token architecture, naming conventions, and implementation across different formats.
What Are Design Tokens?
Design tokens are named entities that store visual design attributes. They create a single source of truth for design decisions and enable consistent styling across platforms and tools.
Token Hierarchy
Global Tokens (Foundation)
↓
Semantic Tokens (Purpose/Context)
↓
Component Tokens (Specific Usage)
Token Categories
Color Tokens
- Brand colors
- Semantic colors (success, error, warning)
- Text colors
- Background colors
- Border colors
- State colors (hover, active, disabled)
Spacing Tokens
- Margin and padding scales
- Gap values
- Layout spacing
- Component spacing
Typography Tokens
- Font families
- Font sizes
- Font weights
- Line heights
- Letter spacing
Size Tokens
- Width and height values
- Min/max constraints
- Breakpoints
- Container sizes
Border Tokens
- Border widths
- Border radius values
- Border styles
Shadow Tokens
- Box shadows
- Elevation levels
- Text shadows
Animation Tokens
- Durations
- Timing functions
- Delays
Token Naming Convention
Pattern: [category]-[property]-[variant]-[state]
/* Color tokens */
--color-primary /* Brand primary */
--color-primary-hover /* Hover state */
--color-primary-light /* Variant */
--color-text-primary /* Primary text */
--color-text-secondary /* Secondary text */
--color-bg-primary /* Primary background */
--color-bg-secondary /* Secondary background */
/* Spacing tokens */
--spacing-1 /* Smallest */
--spacing-4 /* Base */
--spacing-8 /* Large */
/* Typography tokens */
--font-size-sm /* Small */
--font-size-base /* Base */
--font-size-lg /* Large */
--font-weight-normal /* 400 */
--font-weight-bold /* 700 */
/* Component tokens */
--button-padding-x
--button-padding-y
--button-bg-primary
--button-text-primary
--card-padding
--card-radius
--card-shadow
Global Tokens (Foundation)
:root {
/* Color primitives */
--color-blue-50: #eff6ff;
--color-blue-100: #dbeafe;
--color-blue-200: #bfdbfe;
--color-blue-300: #93c5fd;
--color-blue-400: #60a5fa;
--color-blue-500: #3b82f6;
--color-blue-600: #2563eb;
--color-blue-700: #1d4ed8;
--color-blue-800: #1e40af;
--color-blue-900: #1e3a8a;
--color-gray-50: #f9fafb;
--color-gray-100: #f3f4f6;
--color-gray-200: #e5e7eb;
--color-gray-300: #d1d5db;
--color-gray-400: #9ca3af;
--color-gray-500: #6b7280;
--color-gray-600: #4b5563;
--color-gray-700: #374151;
--color-gray-800: #1f2937;
--color-gray-900: #111827;
/* Spacing scale (4px base) */
--spacing-0: 0;
--spacing-1: 0.25rem; /* 4px */
--spacing-2: 0.5rem; /* 8px */
--spacing-3: 0.75rem; /* 12px */
--spacing-4: 1rem; /* 16px */
--spacing-5: 1.25rem; /* 20px */
--spacing-6: 1.5rem; /* 24px */
--spacing-8: 2rem; /* 32px */
--spacing-10: 2.5rem; /* 40px */
--spacing-12: 3rem; /* 48px */
--spacing-16: 4rem; /* 64px */
/* Font sizes (modular scale 1.25) */
--font-size-xs: 0.75rem; /* 12px */
--font-size-sm: 0.875rem; /* 14px */
--font-size-base: 1rem; /* 16px */
--font-size-lg: 1.125rem; /* 18px */
--font-size-xl: 1.25rem; /* 20px */
--font-size-2xl: 1.5rem; /* 24px */
--font-size-3xl: 1.875rem; /* 30px */
--font-size-4xl: 2.25rem; /* 36px */
--font-size-5xl: 3rem; /* 48px */
/* Font weights */
--font-weight-thin: 100;
--font-weight-light: 300;
--font-weight-normal: 400;
--font-weight-medium: 500;
--font-weight-semibold: 600;
--font-weight-bold: 700;
--font-weight-black: 900;
/* Line heights */
--line-height-none: 1;
--line-height-tight: 1.25;
--line-height-snug: 1.375;
--line-height-normal: 1.5;
--line-height-relaxed: 1.625;
--line-height-loose: 2;
/* Border radius */
--radius-none: 0;
--radius-sm: 0.125rem;
--radius-base: 0.25rem;
--radius-md: 0.375rem;
--radius-lg: 0.5rem;
--radius-xl: 0.75rem;
--radius-2xl: 1rem;
--radius-full: 9999px;
/* Shadows */
--shadow-xs: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
--shadow-sm: 0 1px 3px 0 rgba(0, 0, 0, 0.1);
--shadow-base: 0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06);
--shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
--shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
--shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.1);
--shadow-2xl: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
/* Animation */
--duration-fast: 150ms;
--duration-base: 250ms;
--duration-slow: 350ms;
--duration-slower: 500ms;
--ease-in: cubic-bezier(0.4, 0, 1, 1);
--ease-out: cubic-bezier(0, 0, 0.2, 1);
--ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
}
Semantic Tokens (Purpose)
:root {
/* Color semantics */
--color-primary: var(--color-blue-600);
--color-primary-hover: var(--color-blue-700);
--color-primary-active: var(--color-blue-800);
--color-primary-light: var(--color-blue-50);
--color-secondary: var(--color-gray-600);
--color-success: var(--color-green-600);
--color-warning: var(--color-yellow-600);
--color-error: var(--color-red-600);
--color-info: var(--color-blue-500);
/* Text colors */
--color-text-primary: var(--color-gray-900);
--color-text-secondary: var(--color-gray-600);
--color-text-tertiary: var(--color-gray-500);
--color-text-disabled: var(--color-gray-400);
--color-text-inverse: var(--color-white);
/* Surface colors */
--color-surface-primary: var(--color-white);
--color-surface-secondary: var(--color-gray-50);
--color-surface-tertiary: var(--color-gray-100);
--color-surface-overlay: rgba(0, 0, 0, 0.5);
/* Border colors */
--color-border: var(--color-gray-300);
--color-border-hover: var(--color-gray-400);
--color-border-focus: var(--color-primary);
/* Spacing semantics */
--spacing-xs: var(--spacing-2);
--spacing-sm: var(--spacing-3);
--spacing-md: var(--spacing-4);
--spacing-lg: var(--spacing-6);
--spacing-xl: var(--spacing-8);
/* Typography semantics */
--text-xs: var(--font-size-xs);
--text-sm: var(--font-size-sm);
--text-base: var(--font-size-base);
--text-lg: var(--font-size-lg);
--text-xl: var(--font-size-xl);
}
Component Tokens (Specific)
:root {
/* Button */
--button-padding-x: var(--spacing-4);
--button-padding-y: var(--spacing-2);
--button-font-size: var(--font-size-base);
--button-font-weight: var(--font-weight-semibold);
--button-radius: var(--radius-md);
--button-transition: var(--duration-base) var(--ease-in-out);
--button-primary-bg: var(--color-primary);
--button-primary-bg-hover: var(--color-primary-hover);
--button-primary-text: var(--color-text-inverse);
--button-secondary-bg: transparent;
--button-secondary-border: var(--color-border);
--button-secondary-text: var(--color-text-primary);
/* Input */
--input-padding-x: var(--spacing-3);
--input-padding-y: var(--spacing-2);
--input-font-size: var(--font-size-base);
--input-border: 1px solid var(--color-border);
--input-border-focus: 2px solid var(--color-border-focus);
--input-radius: var(--radius-md);
--input-bg: var(--color-surface-primary);
/* Card */
--card-padding: var(--spacing-6);
--card-bg: var(--color-surface-primary);
--card-border: 1px solid var(--color-border);
--card-radius: var(--radius-lg);
--card-shadow: var(--shadow-md);
/* Modal */
--modal-width: 32rem;
--modal-padding: var(--spacing-6);
--modal-bg: var(--color-surface-primary);
--modal-radius: var(--radius-lg);
--modal-shadow: var(--shadow-2xl);
--modal-overlay-bg: var(--color-surface-overlay);
}
Multi-Format Token Output
CSS Custom Properties
/* tokens.css */
:root {
--color-primary: #2563eb;
--spacing-4: 1rem;
--font-size-base: 1rem;
}
Sass Variables
// tokens.scss
$color-primary: #2563eb;
$spacing-4: 1rem;
$font-size-base: 1rem;
// Map format
$colors: (
'primary': #2563eb,
'secondary': #6b7280,
);
$spacing: (
'4': 1rem,
'6': 1.5rem,
);
JavaScript/TypeScript
// tokens.js
export const tokens = {
color: {
primary: '#2563eb',
secondary: '#6b7280',
},
spacing: {
4: '1rem',
6: '1.5rem',
},
fontSize: {
base: '1rem',
lg: '1.125rem',
},
};
// TypeScript
export interface Tokens {
color: {
primary: string;
secondary: string;
};
spacing: {
4: string;
6: string;
};
}
JSON
{
"color": {
"primary": {
"value": "#2563eb",
"type": "color"
},
"secondary": {
"value": "#6b7280",
"type": "color"
}
},
"spacing": {
"4": {
"value": "1rem",
"type": "dimension"
}
}
}
Theme Variations
Light & Dark Themes
:root {
/* Light theme (default) */
--color-bg: #ffffff;
--color-text: #111827;
--color-primary: #2563eb;
--color-surface: #f9fafb;
--color-border: #e5e7eb;
}
[data-theme="dark"] {
/* Dark theme overrides */
--color-bg: #111827;
--color-text: #f9fafb;
--color-primary: #60a5fa;
--color-surface: #1f2937;
--color-border: #374151;
}
[data-theme="high-contrast"] {
/* High contrast theme */
--color-bg: #000000;
--color-text: #ffffff;
--color-primary: #ffff00;
--color-surface: #1a1a1a;
--color-border: #ffffff;
}
Brand Themes
[data-brand="acme"] {
--color-primary: #ff6b35;
--font-family-display: "Montserrat", sans-serif;
--radius-base: 0.5rem;
}
[data-brand="widgets-inc"] {
--color-primary: #4caf50;
--font-family-display: "Roboto", sans-serif;
--radius-base: 0;
}
Token Documentation Template
## Color Tokens
### Primary
- **Token**: `--color-primary`
- **Value**: `#2563eb` (Blue 600)
- **Usage**: Primary actions, links, brand elements
- **Contrast**: 7.02:1 on white (AAA)
- **Related**:
- `--color-primary-hover`: #1d4ed8
- `--color-primary-light`: #eff6ff
### Text
- **Token**: `--color-text-primary`
- **Value**: `#111827` (Gray 900)
- **Usage**: Main body text, headings
- **Contrast**: 16.04:1 on white (AAA)
## Spacing Tokens
### Base Unit
- **Token**: `--spacing-4`
- **Value**: `1rem` (16px)
- **Usage**: Base spacing unit, component padding
## Component Tokens
### Button
- **Padding**: `--button-padding-x` (1rem), `--button-padding-y` (0.5rem)
- **Font**: `--button-font-size` (1rem), `--button-font-weight` (600)
- **Radius**: `--button-radius` (0.375rem)
- **Colors**:
- Primary: `--button-primary-bg`, `--button-primary-text`
- Secondary: `--button-secondary-border`, `--button-secondary-text`
Token Best Practices
✓ Do
- Use hierarchical token structure
- Name tokens by purpose, not value
- Document all tokens with usage guidelines
- Version tokens with design system
- Test tokens in all themes
- Provide fallback values
- Group related tokens
- Use semantic naming
❌ Don't
- Name tokens by appearance (--color-blue)
- Skip documentation
- Create tokens for single-use values
- Mix naming conventions
- Hardcode values in components
- Create too many token levels
- Use inconsistent scales
Example: Complete Token System
:root {
/* 1. GLOBAL TOKENS (Foundation) */
/* Colors - Raw values */
--color-blue-600: #2563eb;
--color-gray-900: #111827;
--color-white: #ffffff;
/* Spacing - Base scale */
--spacing-2: 0.5rem;
--spacing-4: 1rem;
/* 2. SEMANTIC TOKENS (Purpose) */
/* Colors - Meaning */
--color-primary: var(--color-blue-600);
--color-text-primary: var(--color-gray-900);
--color-surface: var(--color-white);
/* Spacing - Context */
--spacing-sm: var(--spacing-2);
--spacing-md: var(--spacing-4);
/* 3. COMPONENT TOKENS (Specific) */
/* Button */
--button-bg-primary: var(--color-primary);
--button-text-primary: var(--color-surface);
--button-padding-x: var(--spacing-md);
--button-padding-y: var(--spacing-sm);
}
/* 4. USAGE */
.button--primary {
background: var(--button-bg-primary);
color: var(--button-text-primary);
padding: var(--button-padding-y) var(--button-padding-x);
}
Just Ask!
Tell me what you need:
- "Create a design token system"
- "Generate spacing tokens"
- "Set up color tokens"
- "Create component tokens for buttons"
- "Convert tokens to Sass format"
- "Set up dark theme tokens"
I'll help you build scalable design token systems!
Converted and distributed by TomeVault — claim your Tome and manage your conversions.