Design Tokens

Design tokens are platform-agnostic variables that store design decisions like colors, spacing, typography, and shadows. They bridge design and code by replacing hardcoded values with named references.

Category: Design (also: Software Engineering)

Author: Atomic Glue Editorial Team

## Definition

Design tokens are the atomic building blocks of a design system's visual language. They are named entities that store design decisions (a specific color, a spacing unit, a font size) in a platform-agnostic format, typically JSON or YAML. Instead of writing #0066ff or 16px directly in code, teams reference a token like color.brand.primary or spacing.md. When the token value changes, every usage updates automatically across platforms. Tokens are the shared vocabulary that eliminates the gap between design mockups and production code, ensuring what a designer specifies is exactly what a developer ships.

## Token Naming Conventions

Good token names follow a structured hierarchy: category.usage.variant. Material Design uses a category-property-component scheme (md.sys.color.primary, md.ref.palette.blue50). Token Studio and other tools follow similar patterns. The most important rule is to name tokens by their purpose, not their value. Call it color.brand.primary, not color.blue. This allows the brand color to change without renaming every reference.

## Global Tokens vs Alias Tokens vs Component Tokens

Global (or reference) tokens store raw values like a specific hex color or pixel value (color.blue.500: #0066ff). Alias (or system) tokens map global tokens to semantic purposes (color.brand.primary: {color.blue.500}). Component tokens apply to specific components (button.primary.bg: {color.brand.primary}). This three-layer system lets you change a global value once and have it propagate through the system predictably.

## Design Token Tooling

Tools like Style Dictionary, Token Studio (Figma plugin), Specify, and Supernova transform tokens stored in JSON into platform-specific output: CSS custom properties for web, Compose variables for Android, Swift UI constants for iOS. The token file is the single source of truth. The build tool generates the format each platform needs. This eliminates manual synchronization between design and code.

## In code

/* Design tokens in JSON */
{
  "color": {
    "brand": {
      "primary": { "value": "#0066ff" },
      "primary-hover": { "value": "#0052cc" },
      "secondary": { "value": "#7c3aed" }
    },
    "semantic": {
      "success": { "value": "#10b981" },
      "error": { "value": "#ef4444" }
    },
    "neutral": {
      "100": { "value": "#f3f4f6" },
      "700": { "value": "#374151" },
      "900": { "value": "#111827" }
    }
  },
  "spacing": {
    "xs": { "value": "4px" },
    "sm": { "value": "8px" },
    "md": { "value": "16px" },
    "lg": { "value": "24px" }
  }
}

/* Generated CSS custom properties */
:root {
  --color-brand-primary: #0066ff;
  --color-brand-primary-hover: #0052cc;
  --spacing-md: 16px;
}

## Common questions

Q: Are design tokens only for large teams?

A: No. Even a solo designer and one developer benefit from design tokens. They eliminate redundant decisions, reduce the risk of color inconsistency, and make it trivial to test a new brand color across the entire interface. The overhead of setting up tokens is minimal compared to the cost of manual inconsistency.

Q: How do tokens handle dark mode?

A: Dark mode is handled by having separate alias tokens for light and dark themes that both reference the same global tokens. For example, color.surface.bg maps to global token color.neutral.50 in light mode but color.neutral.900 in dark mode. The component tokens never change. Only the alias mapping switches per theme.

## Key takeaways

• Design tokens are named variables that store every design decision (color, spacing, typography, shadow).
• They replace hardcoded values with a shared vocabulary between design and development.
• Maintain a three-layer system: global tokens, alias tokens, component tokens.
• Name tokens by purpose, not value. Never name a token after the color it holds.
• Tokens enable dark mode, theming, and cross-platform consistency with a single source of truth.

## Related entries

• [Design System](atomicglue.co/glossary/design-system-front-end)
• [Color Palette](atomicglue.co/glossary/color-palette)
• [Brand Guidelines](atomicglue.co/glossary/brand-guidelines)
• [Typography (Serif / Sans-Serif / Variable Font)](atomicglue.co/glossary/typography-serif-sans-serif-variable-font)

Last updated July 2026. Permalink: atomicglue.co/glossary/design-tokens