Design System Tokens: Building Scalable Design Language

Design tokens abstract design decisions (colors, typography, spacing) into reusable, maintainable units that synchronize design and code.

### Token Categories

• Color: Brand colors, semantic colors, state variants
• Typography: Font families, sizes, weights, line heights
• Spacing: Padding, margin, gap values in standardized increments
• Sizing: Component dimensions, width/height scales
• Border: Radius values, stroke widths
• Shadow: Depth and elevation patterns
• Animation: Timing functions, durations, easing curves
• Opacity: Transparency layers for hierarchy

### Semantic vs. Primitive Tokens

• Primitives: Base values (primary-blue-500, large-font-size)
• Semantic: Context-specific (button-background, text-muted, alert-error)
• Map primitives to semantic tokens for flexibility
• Use semantic tokens in components, primitives for theming

### Structure

• Use kebab-case for token names (button-primary-background)
• Organize hierarchically: category/type/state/property
• Example: color/primary/on-dark/background
• Keep names descriptive but concise

### Color Token Naming

• Semantic: button-primary, text-secondary, border-disabled
• Tonal: color-neutral-50 through color-neutral-950
• State variants: hover, active, disabled, focus
• Example: action-primary-default, action-primary-hover

### Spacing Token Naming

• Use scale: spacing-xs, spacing-sm, spacing-md, spacing-lg, spacing-xl
• Or numeric: spacing-4, spacing-8, spacing-12, spacing-16, spacing-24
• Reference scale (4px, 8px increments for consistency)
• Example: spacing-md = 12px, spacing-lg = 16px

### Typography Token Naming

• By scale: text-xs, text-sm, text-md, text-lg, text-xl
• By use: heading-1, heading-2, body-lg, label-sm
• Include weight: text-md-regular, text-md-bold
• Example: body-lg = 18px / 28px line-height / 400 weight

### Figma Tokens Plugin

• Install Tokens Studio plugin in Figma
• Create tokens.json file with organized structure
• Group tokens by category in plugin interface
• Define sets for light/dark modes
• Export as JSON for developer use

### JSON Structure ```json {

"color": {

"primary": {

"50": {"value": "#f0f7ff"},

"500": {"value": "#0066cc"},

"900": {"value": "#001a4d"}

},

"semantic": {

"button-primary": {"value": "{color.primary.500}"}

} },

"spacing": {

"sm": {"value": "8px"},

"md": {"value": "12px"},

"lg": {"value": "16px"}

} } ```

### Token Documentation

• Document usage context for each semantic token
• Explain when to use primitive vs. semantic
• Provide rationale for values (why 12px, not 10px)
• Create visual token library page
• Link tokens to components using them

### Light/Dark Modes

• Create separate token sets for each theme
• Define theme-specific colors only (keep sizing consistent)
• Use token references to map between themes
• Document fallback behavior if theme switches
• Test contrast ratios for accessibility

### Multi-Brand Support

• Create token sets per brand if needed
• Override only brand-specific values
• Inherit common spacing and sizing
• Use consistent semantic naming across brands
• Document brand-specific decisions

### Platform Variants

• Create separate sets for web, iOS, Android if needed
• Use consistent naming across platforms
• Adjust values for platform conventions (larger touch targets on mobile)
• Document platform-specific overrides
• Keep consistent semantic structure

### Component Mapping

• Apply tokens to all component variants
• Document which tokens affect which properties
• Create consistent interaction patterns via tokens
• Use semantic tokens in component main components
• Avoid hardcoding values in component fills

### Updating Tokens

• Change value in Figma token once
• All components referencing token update automatically
• Document change reason and date
• Version tokens for breaking changes
• Communicate significant token changes to team

### Export Formats

• JSON: Raw token structure for custom processing
• CSS Custom Properties: --color-primary, --spacing-md
• SCSS Variables: $color-primary, $spacing-md
• JavaScript Objects: export const tokens = { ... }
• Format per platform and developer preference

### Export Tools

• Token Studio: Export to JSON, CSS, SCSS, JavaScript
• Figma Plugins: Style Dictionary, Tokens for design systems
• Custom scripts: Transform JSON to target format
• CI/CD integration: Auto-generate token files on updates

### Documentation for Developers

• Provide token JSON schema with examples
• Document how to reference tokens (CSS vars vs. imports)
• Explain semantic vs. primitive structure
• Include theme switching logic if applicable
• Provide fallback values for missing tokens

### Version Control

• Store tokens.json in version control
• Track token changes in commit history
• Mark breaking changes clearly
• Maintain changelog of token evolution
• Tag releases when major token updates deploy

### Governance

• Define process for proposing new tokens
• Require approval for token value changes
• Audit unused tokens periodically
• Document deprecation process for old tokens
• Keep design and dev teams synchronized

### Auditing Tokens

• Identify duplicate or redundant tokens
• Check for unused tokens and remove if obsolete
• Verify values match brand guidelines
• Test accessibility (color contrast, font sizes)
• Review for completeness against component needs

• Start with primitives, add semantic tokens gradually
• Use reference values ({color.primary.500}) for DRY principles
• Keep token values aligned to project design specs
• Use consistent units (px or rem, not mixed)
• Document rationale and context for values
• Version tokens for major changes
• Sync design and code tokens regularly

• Too many tokens without clear organization
• Naming inconsistency across categories
• Hardcoding values in components instead of using tokens
• Not versioning tokens before breaking changes
• Forgetting to update documentation after token changes
• Creating tokens without developer input on format
• Over-abstracting with too many semantic layers

• Figma Tokens Studio: Primary token management
• Style Dictionary: Transform tokens to code
• Storybook: Display token usage documentation
• GitHub/GitLab: Version control for token files
• Automation: GitHub Actions to publish updated tokens