Design Tokens 101: Color Tokens Without the Buzzwords

Three layers: primitive, semantic, component

• Primitive: `blue-500: #1e88e5`. Just the value, no opinion.
• Semantic: `color-action-primary: var(--blue-500)`. Decision: this is the action color.
• Component: `button-primary-bg: var(--color-action-primary)`. Application: this token feeds the Button component.

Always layer. If you skip semantic and reference primitives directly from components, every theme change requires rewriting every component.

The W3C DTCG format

The Design Tokens Community Group (DTCG) defined a JSON schema to share tokens across tools. Figma Variables, Style Dictionary, Tokens Studio and others all read it.

{
  "color": {
    "blue": {
      "500": { "$value": "#1e88e5", "$type": "color" }
    },
    "action": {
      "primary": { "$value": "{color.blue.500}", "$type": "color" }
    }
  }
}

Note the `{color.blue.500}` reference syntax - it preserves the "semantic points to primitive" relationship even after export.

Building the pipeline

A modern token pipeline looks like: Figma Variables (design source) → DTCG JSON (interchange) → Style Dictionary (build) → CSS variables / Swift / Android XML (platform outputs).

You do not need all of this to start. Begin with hand-written DTCG JSON, build to CSS variables, ship. Add Figma sync later.

Color token naming conventions

Two competing schools:

• "Color role" naming: `color-text-primary`, `color-surface-raised`, `color-border-subtle`. Best for product teams.
• "Color scale" naming: `gray-50` through `gray-950`. Best for design systems shipped as libraries (Radix, Tailwind).

Most production systems use both: scale primitives at the bottom, role semantics on top.