Design Tokens for Color Systems

What Are Design Tokens?

Design tokens are named variables that store design decisions like colors, typography, spacing, and more. Instead of hardcoding #3B82F6 throughout your app, you use a semantic token like --color-primary that can be updated globally.

Think of tokens as a single source of truth: change the value once, update everywhere.

Why Color Tokens Matter

• Consistency: One color definition, used everywhere. No more "Why do we have 3 different blues?"
• Maintainability: Rebrand your product by updating tokens, not hunting through code
• Scalability: Add themes (light/dark), platforms (web/mobile), or brands without duplicating logic
• Developer-Designer Sync: Designers define tokens in Figma, developers consume them as code
• Platform Agnostic: Export to CSS, Tailwind, React Native, iOS, Android from one source

Tokens vs CSS Variables

Anatomy of Color Tokens

Good color tokens follow a clear naming convention:

// ❌ Bad: Implementation-focused
--blue-500: #3B82F6;
--red-dark: #DC2626;

// ✅ Good: Purpose-focused (semantic)
--color-primary: #3B82F6;
--color-error: #DC2626;
--color-text-default: #1F2937;
--color-surface-elevated: #FFFFFF;

Token Naming Structure

Category + Role + Variant

color-primary-hover, color-text-muted

Common Categories

color, spacing, typography, border, shadow, animation

Common Roles (for color)

primary, secondary, accent, background, surface, text, error, success, warning

Token Export Formats

Design tokens can be exported to multiple formats for different platforms:

1. CSS Variables

:root {
  --color-primary: oklch(70% 0.15 200);
  --color-background: oklch(98% 0.02 90);
  --color-text: oklch(20% 0.02 90);
}

button {
  background: var(--color-primary);
  color: var(--color-text);
}

2. Tailwind Config

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: 'oklch(70% 0.15 200)',
        background: 'oklch(98% 0.02 90)',
        text: 'oklch(20% 0.02 90)',
      }
    }
  }
}

3. JSON Tokens

{
  "color": {
    "primary": {
      "value": "oklch(70% 0.15 200)",
      "type": "color"
    },
    "background": {
      "value": "oklch(98% 0.02 90)",
      "type": "color"
    }
  }
}

4. React Native / JavaScript

export const colors = {
  primary: '#3B82F6',
  background: '#FAFAFA',
  text: '#1F2937',
};

Best Practices

• Use semantic names: Name tokens by purpose (primary, error), not appearance (blue, red)
• Start small: Begin with 10-15 core tokens. Expand as needed
• Version your tokens: Track changes like code (Git, semantic versioning)
• Document context: Explain when to use each token (e.g., "Use text-muted for secondary info")
• Automate transformations: Use tools like Style Dictionary to generate platform-specific code
• Test across themes: Ensure tokens work in light, dark, and high-contrast modes

Common Pitfalls

• Over-tokenizing: Don't create a token for every single color. Group related values
• Naming inconsistency: Pick a convention (kebab-case, camelCase) and stick to it
• Hard-coded overrides: Avoid bypassing tokens with inline styles or magic values
• No governance: Without clear ownership, tokens proliferate and become messy

Exporting with Tonal Field

Tonal Field makes token generation effortless. After defining your color system in the Studio, export your palette as:

• CSS Custom Properties (CSS Variables)
• Tailwind Config (tailwind.config.js)
• JSON Design Tokens (W3C spec)
• Material UI Theme (JavaScript)
• Figma Plugins, Sketch, VS Code themes
• Apple .clr format for iOS/macOS

No manual conversion needed. Build once, export everywhere.

Next Steps

Ready to build your token-based color system? Head to the Tonal Field Studio to create your palette and export production-ready design tokens in seconds.