Structured token hierarchy diagram showing colour, spacing, and typography tokens flowing from abstract to component level on grid paper

Design Tokens & Theme.json: Managing Styles in 2026

Design tokens are the atomic values of a design system — the colours, spacing units, type sizes, border radii, shadows, and timing functions that define how a UI looks and feels. In 2026, managing these tokens well is the difference between a design system that scales and one that accumulates inconsistencies until a redesign becomes inevitable.

This guide covers practical token architecture for web projects: how to structure tokens at abstract and semantic levels, how WordPress theme.json fits as a token system, how CSS custom properties implement tokens in production, and the naming conventions that keep a token system maintainable as it grows. It is for front-end developers and theme authors who are already using CSS custom properties and want to formalise their approach into something more structured.

Why Tokens Matter More in 2026

Three developments elevated tokens from "nice to have" to essential:

Multi-platform delivery is standard. A design system that serves a Gatsby site, a WordPress theme, a React Native app, and an email template needs platform-agnostic token definitions that compile to each platform's format. CSS custom properties, theme.json settings, and native platform values all originate from the same token source.

AI-generated interfaces need constraints. When AI tools generate layouts and components (as discussed in the agentic websites guide), tokens are the guardrails that keep generated output on-brand. Without tokens, AI-generated interfaces drift into arbitrary values.

WordPress theme.json is now a complete token system. The Full Site Editing guide covers how theme.json v3 defines typography, colour, spacing, and layout constraints. For WordPress projects, theme.json is not just a configuration file — it is the design token layer.

Token Architecture: Three Tiers

A well-structured token system has three levels:

Tier 1: Global Tokens (Raw Values)

The raw palette. No semantic meaning. These are the universe of values available to the system:

:root {
  /* Colour palette */
  --color-warm-50: #faf8f5;
  --color-warm-100: #f5f0e8;
  --color-warm-200: #e8dfd2;
  --color-warm-900: #1a1a1a;

  /* Spacing scale */
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-3: 0.75rem;
  --space-4: 1rem;
  --space-6: 1.5rem;
  --space-8: 2rem;
  --space-10: 2.5rem;
  --space-12: 3rem;

  /* Type scale */
  --text-xs: 0.75rem;
  --text-sm: 0.875rem;
  --text-base: 1rem;
  --text-lg: 1.125rem;
  --text-xl: 1.375rem;
  --text-2xl: 1.75rem;
  --text-3xl: 2.25rem;
}

Tier 2: Semantic Tokens (Intent-Based)

These map global tokens to purposes. They carry meaning:

:root {
  /* Surface colours */
  --color-surface: var(--color-warm-50);
  --color-surface-raised: var(--color-warm-100);

  /* Text colours */
  --color-ink: var(--color-warm-900);
  --color-ink-muted: var(--color-warm-600);

  /* Spacing intent */
  --space-section: var(--space-12);
  --space-component: var(--space-6);
  --space-element: var(--space-3);

  /* Typography intent */
  --text-body: var(--text-base);
  --text-heading-sm: var(--text-xl);
  --text-heading-lg: var(--text-3xl);
}

Semantic tokens are what components reference. A card uses var(--color-surface-raised) for its background, not var(--color-warm-100). If the design system shifts (warm to cool, light to dark), only the semantic token mappings change. Components are untouched.

Tier 3: Component Tokens (Scoped)

For complex design systems, component-level tokens scope values to specific components:

.card {
  --card-bg: var(--color-surface-raised);
  --card-padding: var(--space-component);
  --card-radius: var(--radius-md);
  --card-shadow: var(--shadow-sm);
}

This tier is optional for smaller projects but essential for design systems that serve multiple brands or themes.

WordPress theme.json as a Token System

WordPress theme.json maps directly to the token architecture:

{
  "settings": {
    "color": {
      "palette": [
        { "slug": "surface", "color": "#faf8f5", "name": "Surface" },
        { "slug": "surface-raised", "color": "#f5f0e8", "name": "Surface Raised" },
        { "slug": "ink", "color": "#1a1a1a", "name": "Ink" },
        { "slug": "ink-muted", "color": "#696969", "name": "Ink Muted" },
        { "slug": "accent", "color": "#8b6914", "name": "Accent" }
      ]
    },
    "typography": {
      "fontSizes": [
        { "slug": "small", "size": "0.875rem", "name": "Small" },
        { "slug": "medium", "size": "1rem", "name": "Medium" },
        { "slug": "large", "size": "1.25rem", "name": "Large" }
      ]
    },
    "spacing": {
      "spacingSizes": [
        { "slug": "20", "size": "0.5rem", "name": "XS" },
        { "slug": "40", "size": "1rem", "name": "M" },
        { "slug": "60", "size": "2.5rem", "name": "XL" }
      ]
    }
  }
}

WordPress generates CSS custom properties from these definitions: --wp--preset--color--surface, --wp--preset--font-size--medium, --wp--preset--spacing--40. These are effectively Tier 2 semantic tokens that the block editor and front end both use.

The typography and readability guide covers the type scale decisions that feed into these token definitions. The human-centric design trends guide covers the colour temperature choices that define your palette tokens.

Naming Conventions That Scale

Token naming is the hardest part. A bad naming convention creates confusion and duplication as the system grows.

Rules That Work

  1. Name by purpose, not by value. --color-accent not --color-gold. When the accent colour changes, the name still makes sense.
  2. Use a consistent hierarchy. --category-property-variant: --color-surface-raised, --text-heading-lg, --space-section.
  3. Number scales for ordered values. --space-1 through --space-12 for spacing. --color-warm-50 through --color-warm-900 for shades.
  4. Avoid abbreviations that require explanation. --space-component is clearer than --sp-cmp.

Anti-Patterns

  • --blue-500 in semantic layer (what if the brand colour changes?)
  • --margin-top-large (too specific — use --space-section for the intent)
  • --header-bg-color (component token used as a semantic token)

Token Tooling in 2026

Style Dictionary

The most established token build tool. Define tokens in JSON, compile to CSS custom properties, theme.json, iOS/Android values, or any custom format. For projects that need multi-platform output, Style Dictionary is the canonical tool.

Design Tool Integration

Figma's variable system maps directly to design tokens. Designers define variables in Figma → export as token JSON → compile to CSS and theme.json. This closes the designer-developer handoff gap for token values.

CSS Custom Properties: The Implementation Layer

For web-only projects, CSS custom properties are sufficient as both the definition and implementation layer. No build tool needed. Define tokens in :root, reference them in components, and override them in theme variants:

/* Default (light) theme */
:root {
  --color-surface: #faf8f5;
  --color-ink: #1a1a1a;
}

/* Dark theme override */
[data-theme="dark"] {
  --color-surface: #1a1a1a;
  --color-ink: #f5f0e8;
}

Components use var(--color-surface) and the correct value applies based on the active theme. No component CSS changes needed for theming.

When Tokens Are Overkill

For a single-purpose site with no theme variants and no multi-platform delivery, formal design tokens add process overhead without proportional benefit. CSS custom properties in a single file with clear names are sufficient. Formalise into tokens when:

  • Multiple themes or brands use the same component library
  • Multiple platforms consume the same design system
  • The team is large enough that naming consistency requires governance
  • WordPress theme.json is the design system layer (it is already token-based)

Checklist

  • [ ] Token architecture defined with global, semantic, and (optionally) component tiers
  • [ ] Naming convention documented and consistent across all tokens
  • [ ] Colour tokens named by purpose, not by hue
  • [ ] Spacing scale defined with consistent increments
  • [ ] Typography tokens cover size, weight, line-height, and font-family
  • [ ] WordPress theme.json generated from (or aligned with) token definitions
  • [ ] Dark mode / theme variants implemented via semantic token overrides
  • [ ] Component CSS references semantic tokens, not global tokens or raw values
  • [ ] Token values checked for accessibility (contrast ratios, minimum sizes)
  • [ ] Token documentation maintained for the design team

FAQ

Should I use CSS custom properties or a token build tool? For web-only projects, CSS custom properties are sufficient. For multi-platform projects (web + native + email), use Style Dictionary or a similar build tool to generate platform-specific output from a single token source.

How do tokens interact with container queries? Container queries can override tokens at the component level. A card in a narrow container might use tighter spacing tokens than the same card in a wide container. The container queries guide covers this pattern.

Is theme.json the right place for all design decisions? For block themes, yes — it is the canonical location for design tokens. For hybrid themes or custom front-end projects, CSS custom properties in a dedicated token file are more flexible.

Next Steps

Design SystemsCSSWordPress

Continue Reading