Design Tokens and Theming Architecture

Design tokens encode design decisions as platform-agnostic data, enabling consistent UI across web, iOS, and Android from a single source of truth. This article covers the token taxonomy, semantic layering for theming, multi-platform transformation pipelines, and governance strategies that make enterprise design systems maintainable at scale.

Abstract

Design tokens are named entities storing visual design attributes—colors, spacing, typography—that serve as the atomic building blocks of a design system. The core mental model:

• Primitives answer “what values exist?” (raw palette: blue-500: #2563eb)
• Semantic tokens answer “what does this value mean?” (purpose: color-action-primary)
• Component tokens answer “where is this used?” (specificity: button-background)

Theming works by swapping semantic layers while primitives remain constant. A dark theme redefines color-background from {gray-50} to {gray-900}—components referencing the semantic token adapt automatically.

The W3C Design Tokens Community Group (DTCG) specification (v2025.10) standardizes the JSON format with $value, $type, and $description properties. Tools like Style Dictionary transform this source into platform-specific outputs (CSS custom properties, Swift UIColor, Android XML resources).

Token Taxonomy

The three-tier token hierarchy emerged from Salesforce’s Lightning Design System work (2014-2015), where Jina Anne and Jon Levine needed to scale design decisions across platforms and partner implementations.

Primitive Tokens (Reference/Global)

Primitives define the raw design palette with no semantic meaning attached. They answer “what options exist?” and form the foundation that semantic tokens reference.

1
{
2
  "color": {
3
    "blue": {
4
      "100": { "$value": "#dbeafe", "$type": "color" },
5
      "500": { "$value": "#3b82f6", "$type": "color" },
6
      "900": { "$value": "#1e3a8a", "$type": "color" }
7
    },
8
    "gray": {
9
      "50": { "$value": "#f9fafb", "$type": "color" },
10
      "900": { "$value": "#111827", "$type": "color" }
11
    }
12
  },
13
  "spacing": {
14
    "100": { "$value": "4px", "$type": "dimension" },
15
    "200": { "$value": "8px", "$type": "dimension" },
16
    "400": { "$value": "16px", "$type": "dimension" }
17
  }
18
}

Naming convention: Primitives use appearance-based names (blue-500, gray-50) because they carry no semantic intent. The value itself is the identity.

Scale design: Avoid sequential integers (shadow-1, shadow-2) which leave no room for insertion. Use:

• Numeric scales: 100, 200, 400, 800 (doubling allows interpolation)
• T-shirt sizes: xs, sm, md, lg, xl, 2xl
• Named variants: subtle, default, strong

Semantic Tokens (Alias/Purpose)

Semantic tokens assign meaning to primitives. They answer “how should this value be used?” and create the indirection layer that enables theming.

1
{
2
  "color": {
3
    "background": {
4
      "default": { "$value": "{color.gray.50}", "$type": "color" },
5
      "surface": { "$value": "#ffffff", "$type": "color" },
6
      "inverse": { "$value": "{color.gray.900}", "$type": "color" }
7
    },
8
    "text": {
9
      "primary": { "$value": "{color.gray.900}", "$type": "color" },
10
      "secondary": { "$value": "{color.gray.600}", "$type": "color" },
11
      "inverse": { "$value": "#ffffff", "$type": "color" }
12
    },
13
    "action": {
14
      "primary": { "$value": "{color.blue.500}", "$type": "color" },
15
      "primary-hover": { "$value": "{color.blue.600}", "$type": "color" }
16
    }
17
  }
18
}

The curly brace syntax {color.gray.50} creates an alias—the DTCG spec’s reference mechanism. When the primitive changes, all semantic tokens referencing it update automatically.

Naming convention: Semantic tokens use purpose-based names. The pattern {category}.{concept}.{variant} yields names like color.action.primary or spacing.layout.gutter. This decouples the “what” (blue) from the “why” (primary action).

Component Tokens (Specific/Application)

Component tokens map semantic values to specific UI component parts. They answer “where exactly is this used?”

1
{
2
  "button": {
3
    "primary": {
4
      "background": { "$value": "{color.action.primary}", "$type": "color" },
5
      "background-hover": { "$value": "{color.action.primary-hover}", "$type": "color" },
6
      "text": { "$value": "{color.text.inverse}", "$type": "color" },
7
      "border-radius": { "$value": "{spacing.100}", "$type": "dimension" },
8
      "padding-x": { "$value": "{spacing.400}", "$type": "dimension" },
9
      "padding-y": { "$value": "{spacing.200}", "$type": "dimension" }
10
    }
11
  }
12
}

When to use component tokens: They add significant maintenance overhead. Only introduce this tier when you need:

• Multi-brand theming: Different brands require different component appearances beyond color swaps
• Granular component customization: Consumers need to override specific component parts
• White-labeling: Partners skin components while core semantics stay constant

Most design systems operate well with just primitives and semantic tokens. Component tokens multiply the token count significantly—a system with 200 semantic tokens might balloon to 2000+ with component tokens.

Tier Trade-offs

Naming Conventions

The Category-Type-Item (CTI) pattern from Style Dictionary provides hierarchical, predictable token names that transform cleanly across platforms.

Full Naming Structure

A fully qualified token: acme-color-action-background-primary-hover

Practical Naming Rules

For primitives: Use appearance descriptors.

• blue-500, gray-100 ✓
• primary-blue, link-color ✗ (semantic meaning doesn’t belong in primitives)

For semantic tokens: Use purpose descriptors.

• color-text-primary, color-action-danger ✓
• color-blue, dark-gray ✗ (appearance doesn’t belong in semantics)

Forbidden characters: The DTCG spec prohibits {, }, and . in token names—these are reserved for the reference syntax. Use hyphens or underscores as delimiters.

Case conventions by platform:

Style Dictionary handles these transformations automatically via name transforms.

Theming Architecture

Theming swaps semantic token values while keeping primitives constant. The semantic layer acts as a “switchboard” between raw values and component consumption.

Theme Structure

1
{
2
  "color": {
3
    "background": {
4
      "default": { "$value": "{color.gray.50}" },
5
      "surface": { "$value": "#ffffff" },
6
      "elevated": { "$value": "#ffffff" }
7
    },
8
    "text": {
9
      "primary": { "$value": "{color.gray.900}" },
10
      "secondary": { "$value": "{color.gray.600}" }
11
    }
12
  }
13
}

1
{
2
  "color": {
3
    "background": {
4
      "default": { "$value": "{color.gray.900}" },
5
      "surface": { "$value": "{color.gray.800}" },
6
      "elevated": { "$value": "{color.gray.700}" }
7
    },
8
    "text": {
9
      "primary": { "$value": "#ffffff" },
10
      "secondary": { "$value": "{color.gray.300}" }
11
    }
12
  }
13
}

CSS Implementation

Theme switching via CSS custom properties and a data attribute:

1
:root {
2
  /* Primitives - constant */
3
  --color-blue-500: #3b82f6;
4
  --color-gray-50: #f9fafb;
5
  --color-gray-900: #111827;
6
}
7

8
/* Light theme (default) */
9
:root,
10
[data-theme="light"] {
11
  --color-background-default: var(--color-gray-50);
12
  --color-text-primary: var(--color-gray-900);
13
}
14

15
/* Dark theme */
16
[data-theme="dark"] {
17
  --color-background-default: var(--color-gray-900);
18
  --color-text-primary: #ffffff;
19
}

2 collapsed lines
1
// Theme toggle implementation
2
function setTheme(theme) {
3
  document.documentElement.setAttribute("data-theme", theme)
4
  localStorage.setItem("theme", theme)
5
}

Multi-Dimensional Theming

Production systems often need multiple orthogonal theme dimensions:

These dimensions compose. A “dark + partner-a + compact” theme combines three orthogonal token sets. The implementation typically uses multiple data attributes or CSS class composition:

1
[data-mode="dark"][data-brand="partner-a"][data-density="compact"] {
2
  /* Composed token values */
3
}

Dark Mode Pitfalls

Dark mode isn’t color inversion. Common mistakes:

Saturated colors fail contrast: A vibrant #3b82f6 blue meets WCAG 4.5:1 contrast on white but fails on dark backgrounds. Dark themes require desaturated color variants.

Elevation reverses direction: In light mode, elevation increases brightness (shadows lift elements). In dark mode, elevation increases brightness too—not darkness. Material Design 3 uses “surface tint” overlays that lighten elevated surfaces.

Don’t invert the entire palette: Simply swapping gray-100 ↔ gray-900 breaks visual hierarchy. Dark themes need deliberate surface level definitions.

Contrast Validation

The USWDS (U.S. Web Design System) “magic number” approach: token values include a contrast grade (0-100). Any pair with a difference of 40+ passes WCAG AA for large text, 50+ for normal text.

1
{
2
  "gray": {
3
    "5": { "$value": "#f0f0f0", "contrast-grade": 5 },
4
    "90": { "$value": "#1b1b1b", "contrast-grade": 90 }
5
  }
6
}

90 - 5 = 85 → Passes AAA (70+ required).

Distribution Pipeline

Style Dictionary (originally from Amazon) is the industry standard for token transformation. It parses source tokens, applies transforms, and outputs platform-specific formats.

Pipeline Architecture

Style Dictionary Configuration

3 collapsed lines
1
// Configuration for multi-platform token build
2
import StyleDictionary from "style-dictionary"
3

4
export default {
5
  source: ["tokens/**/*.json"],
6
  platforms: {
7
    css: {
8
      transformGroup: "css",
9
      buildPath: "dist/css/",
10
      files: [
11
        {
12
          destination: "tokens.css",
13
          format: "css/variables",
14
          options: {
15
            outputReferences: true, // Preserve aliases in output
16
          },
17
        },
18
      ],
19
    },
20
    scss: {
21
      transformGroup: "scss",
22
      buildPath: "dist/scss/",
23
      files: [
24
        {
25
          destination: "_tokens.scss",
26
          format: "scss/variables",
27
        },
28
      ],
29
    },
30
    ios: {
31
      transformGroup: "ios-swift",
32
      buildPath: "dist/ios/",
33
      files: [
34
        {
16 collapsed lines
35
          destination: "Tokens.swift",
36
          format: "ios-swift/class.swift",
37
          className: "DesignTokens",
38
        },
39
      ],
40
    },
41
    // Android configuration
42
    android: {
43
      transformGroup: "android",
44
      buildPath: "dist/android/",
45
      files: [
46
        {
47
          destination: "tokens.xml",
48
          format: "android/resources",
49
        },
50
      ],
51
    },
52
  },
53
}

Transform Types

Platform-Specific Value Transformations

The same token requires different representations per platform:

Style Dictionary v4 (current) supports transitive transforms—resolving reference chains iteratively. A component token referencing a semantic token referencing a primitive resolves correctly through the chain.

CI/CD Integration

5 collapsed lines
1
# GitHub Actions workflow for token builds
2
name: Build Tokens
3
on:
4
  push:
5
    paths: ["tokens/**"]
6

7
jobs:
8
  build:
9
    runs-on: ubuntu-latest
10
    steps:
11
      - uses: actions/checkout@v4
12

13
      - uses: actions/setup-node@v4
14
        with:
15
          node-version: "20"
16

17
      - run: npm ci
18

19
      - run: npm run build:tokens
20

21
      - name: Publish to npm
22
        run: npm publish
23
        env:
24
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
11 collapsed lines
25

26
      # Upload artifacts for other platforms
27
      - uses: actions/upload-artifact@v4
28
        with:
29
          name: ios-tokens
30
          path: dist/ios/
31

32
      - uses: actions/upload-artifact@v4
33
        with:
34
          name: android-tokens
35
          path: dist/android/

Tokens Studio Integration

Tokens Studio (Figma plugin) enables designers to define tokens in Figma and sync to Git. The workflow:

1. Designer creates/updates tokens in Figma using Tokens Studio plugin
2. Plugin pushes changes to GitHub/GitLab (JSON format)
3. CI triggers Style Dictionary build
4. Platform outputs published to package registries
5. Consuming apps update dependency version

Tokens Studio supports 24+ token types—more than native Figma Variables (which only support color, number, boolean, string). As of v1.37, Tokens Studio can sync plugin tokens with native Figma Variables for broader tool compatibility.

Version Management

Design tokens follow semantic versioning with domain-specific considerations for breaking changes.

Semantic Versioning for Tokens

Deprecation Strategy

The DTCG spec includes a $deprecated property for staged removal:

1
{
2
  "color-accent": {
3
    "$value": "{color.action.primary}",
4
    "$type": "color",
5
    "$deprecated": "Use color.action.primary instead. Removal in v3.0.0."
6
  }
7
}

Deprecation workflow:

1. Mark deprecated: Add $deprecated with migration guidance
2. Emit warnings: Build tooling warns on deprecated token usage
3. Maintain alias: Point deprecated token to replacement value
4. Stage removal: Give consumers 1-2 minor versions to migrate
5. Remove: Major version bump with changelog documentation

Migration Tooling

For large codebases, automated migration via codemods:

5 collapsed lines
1
// Example jscodeshift codemod for token renames
2
// Run: npx jscodeshift -t codemod-rename-token.js src/
3

4
const tokenRenames = {
5
  "color-accent": "color-action-primary",
6
  "color-accent-hover": "color-action-primary-hover",
7
}
8

9
export default function transformer(file, api) {
10
  const j = api.jscodeshift
11

12
  return j(file.source)
13
    .find(j.Literal)
14
    .filter((path) => tokenRenames[path.value])
15
    .forEach((path) => {
16
      path.replace(j.literal(tokenRenames[path.value]))
17
    })
18
    .toSource()
19
}

Changelog Requirements

Token changelogs should include:

• Added: New tokens with intended use case
• Changed: Value modifications with before/after
• Deprecated: Tokens marked for removal with migration path
• Removed: Tokens deleted (major version only)

1
## [2.0.0] - 2025-01-15
2

3
### Removed
4

5
- `color-accent` - Use `color.action.primary`
6

7
### Changed
8

9
- `color.blue.500` - #3b82f6 → #2563eb (improved contrast)
10

11
## [1.5.0] - 2024-12-01
12

13
### Deprecated
14

15
- `color-accent` - Will be removed in v2.0. Use `color.action.primary`
16

17
### Added
18

19
- `color.action.primary-subtle` - Low-emphasis action color

Governance

Effective token governance requires clear ownership, change processes, and quality gates.

Ownership Model

Change Process

1. Proposal: RFC describing token addition/change with rationale
2. Design Review: Visual validation against brand guidelines
3. Accessibility Review: Contrast ratios, color blindness simulation
4. Technical Review: Naming convention compliance, platform impact
5. Approval: Sign-off from design system team
6. Implementation: Token file changes with tests
7. Release: Version bump, changelog, communication

Quality Gates (CI)

8 collapsed lines
1
# Validation checks for token PRs
2
name: Token Validation
3
on:
4
  pull_request:
5
    paths: ["tokens/**"]
6

7
jobs:
8
  validate:
9
    runs-on: ubuntu-latest
10
    steps:
11
      - uses: actions/checkout@v4
12

13
      - name: Validate JSON Schema
14
        run: npx ajv validate -s schema/dtcg.json -d "tokens/**/*.json"
15

16
      - name: Check Naming Conventions
17
        run: npm run lint:tokens
18

19
      - name: Validate Contrast Ratios
20
        run: npm run test:contrast
21

22
      - name: Build All Platforms
23
        run: npm run build:tokens
24

25
      - name: Check for Breaking Changes
26
        run: npm run check:breaking

Linting Rules

Enforce conventions programmatically:

• Naming: Token names match CTI pattern
• Values: Colors in valid hex/rgb format, dimensions include units
• References: All aliases resolve to existing tokens
• Completeness: Semantic tokens have light and dark variants
• Documentation: Required tokens have $description

Real-World Design System Examples

Salesforce Lightning Design System

The pioneer of design tokens (2014). SLDS evolved from version 1 (design tokens as build-time values) to SLDS 2 with “styling hooks”—CSS custom properties exposed at runtime for component customization.

Styling hooks pattern:

1
/* Consumer overrides at component level */
2
.my-context .slds-button {
3
  --slds-c-button-brand-color-background: var(--my-brand-color);
4
}

Adobe Spectrum

Spectrum publishes tokens in @adobe/spectrum-tokens (v12+). Their Token Visualizer tool provides searchable token documentation. Spectrum uses DTCG-compatible format with Tokens Studio data export.

Token structure follows:

• Global tokens: Platform-wide values (spectrum-global-color-blue-500)
• Alias tokens: Semantic mappings (spectrum-alias-background-color-default)
• Component tokens: Per-component CSS custom properties

IBM Carbon

Carbon defines 52 universal color variables per theme (White, Gray 10, Gray 90, Gray 100). Token categories:

• Color: $interactive-01, $ui-background, $text-primary
• Typography: $productive-heading-01, $body-long-01
• Spacing: $spacing-01 through $spacing-13
• Motion: $duration-fast-01, $easing-standard-productive

Google Material Design 3

Material 3 introduced dynamic color—algorithmic palette generation from a source color. Token types:

• Color: Primary, secondary, tertiary, neutral palettes
• Typography: Type scale tokens (display-large, body-medium)
• Shape: Corner radius tokens per component size

Material’s token structure uses tonal palettes (0-100 lightness scale) enabling precise contrast calculation.

Conclusion

Design tokens succeed when they encode design intent, not just design values. The three-tier hierarchy (primitive → semantic → component) creates the right abstraction layers: primitives for the design palette, semantic tokens for meaning and theming, component tokens for granular customization when needed.

The DTCG specification (v2025.10) provides the standardized JSON format the industry lacked. Style Dictionary transforms this source into platform-specific outputs. The governance model—clear ownership, change processes, automated validation—prevents the drift that undermines design system value.

Start with primitives and semantic tokens. Add component tokens only when multi-brand or white-label requirements demand them. Version tokens like code: semantic versioning, deprecation staging, automated migration. The goal is a single source of truth that scales across platforms without manual synchronization.

Appendix

Prerequisites

• CSS custom properties (variables) syntax and cascade
• Build tool basics (npm scripts, CI pipelines)
• JSON/JSON5 file formats

Terminology

Summary

• Design tokens are named entities storing design attributes as platform-agnostic data
• Three-tier hierarchy: primitives (values) → semantic (meaning) → component (specificity)
• DTCG specification (v2025.10) standardizes JSON format with $value, $type, $description
• Theming works by swapping semantic token layers; primitives stay constant
• Style Dictionary transforms source tokens into platform-specific outputs (CSS, Swift, Android)
• Version tokens with SemVer; deprecate before removing; provide migration codemods

References

Specifications

• DTCG Design Tokens Specification - W3C Community Group specification (v2025.10)
• Design Tokens Community Group - Official DTCG site

Tools Documentation

• Style Dictionary - Token transformation pipeline documentation
• Tokens Studio - Figma plugin for token management
• Terrazzo - DTCG-native transformation tool
• Theo - Salesforce’s original token generator

Design Systems

• Adobe Spectrum Design Tokens - Spectrum token documentation
• IBM Carbon Themes - Carbon theme architecture
• Material Design 3 Tokens - Google’s token structure
• Salesforce SLDS Styling Hooks - SLDS CSS custom properties

Core Maintainer Content

• Jina Anne on Design Tokens - Smashing Podcast with the design tokens pioneer
• Nathan Curtis - Naming Tokens in Design Systems - Comprehensive naming conventions guide
• Nathan Curtis - Tokens in Design Systems - 10 tips for token architecture
• Brad Frost - Design Tokens + Atomic Design - Integration with atomic design methodology