Tokens, not pixels

Don't let your codebase end up with #3b82f6 hard-coded in 47 files. Use tokens to avoid this.

Design tokens are the single source of truth for visual decisions in a product ecosystem. They replace hardcoded values (like #1A73E8 or 16px) with abstract, named variables (like color-brand-primary or spacing-md). This centralizes styling across design tools like Figma and code repositories for Web, iOS, and Android.

The discipline is that consumers don't hard-code values. They reference tokens. Then the token is the only thing that has to change when the system changes.

1. Structure the 3-Tier Architecture

Do not map raw values directly to components. Implement a strict, directional consumption pattern (Primitives → Semantics → Components) to ensure scalability.

Primitive Layer (Raw Values): The raw palette of your system. Holds the hardcoded hex codes, pixel sizes, and font families. Store every raw option here but never use them directly in layout screens.

color.blue.500: #007BFF
dimension.scale-4: 16px

Semantic Layer (Alias / Purpose): Translates raw values into functional choices. Decisions mapped to generic context or intent. Reference primitive tokens via aliases to handle themes like Dark Mode seamlessly.

color.background.primary-action: alias(color.blue.500)
color.text-primary: alias(color.neutral.900)
spacing.layout-md: alias(dimension.scale-4)

Component Layer (Scoped De-coupling): Overrides tied tightly to explicit elements. Isolate complex UI elements so visual revisions do not leak out.

button.primary.bg: alias(color.background.primary-action)
card.border-radius-default: alias(radius.interactive-sm)

2. Standardize Naming Syntax Globally

Engineering cannot automate token translation if naming schemas are unpredictable. Use a strict Category → Context → Property → Variant/State strategy to name every token systematically.

Token Name = [Category] → [Context] → [Property] → [Variant/State]

• Category: Core style type — color, spacing, font, elevation.
• Context: Architectural target — sys, surface, button, input.
• Property: CSS characteristic — bg, text, border, radius.
• Variant/State: State flag — default, hover, active, disabled, md.

3. Build the Automated Handoff Pipeline

Never hand over tokens by manually copying values from Figma into GitHub. Engineering teams will ignore them if they add manual maintenance overhead.

Maintain the Source: Designers manage attributes inside Figma Variables or Tokens Studio.

Export to JSON: Export design decisions into a structural, human-readable format. Maintain raw design token sets within standard JSON structures following the W3C Design Tokens Community Group Specification:

{
  "color": {
    "brand": {
      "primary": {
        "$value": "{color.blue.500}",
        "$type": "color",
        "$description": "Primary action background fill for main buttons"
      }
    }
  }
}

Transform via Style Dictionary: Utilize an open-source build tool like Amazon's Style Dictionary. It consumes the single JSON source and compiles it into platform-specific code scripts (.css, .scss, Android .xml, iOS .swift) automatically.

• Web: CSS Custom Properties (--color-bg-interactive-hover)
• iOS: Swift constants (colorBgInteractiveHover)
• Android: Compose variables

4. Enforce System Governance

Tokens will experience "brand drift" if the workflow allows outside styling rules to creep back into the codebase.

Block Hardcoded Values: Configure code linters (like Stylelint or ESLint) to flag and fail builds if an engineer inputs raw hex codes (#FFF) or explicit pixel dimensions (padding: 13px).

Design Rule Validity: Test token schemas using tools like the Variables Visualizer plugin in Figma. This helps track dependency loops and breaks before exporting files.

Treat Tokens as a Product: Do not slip token edits quietly into feature updates. Introduce proper semantic versioning (v1.2.0) via an internal NPM package so developers can track, update, or roll back breaking changes cleanly.