Mark Learst | Lead Design Engineer (Design Systems, React, Accessibility, DX + AI Tooling)

The Problem

Everyone calls them something different--design tokens, style properties, variables, constants. The terminology split is a symptom of a deeper problem: there is no standard for how design variables should be governed across tools and teams. This creates:

Naming confusion: Designers call them one thing, developers another. Handoff breaks because vocabulary is split.
No governance: Variables change without rules. Breaking changes ship to production without notice.
Tool lock-in: Figma Variables, Tokens Studio, and code-based systems use incompatible formats and reference syntax.
Handoff breaks: Design and code don't align. No way to track which variable version is deployed.
No validation: Invalid variables pass review and cause build failures downstream.
Layer proliferation: Teams add mapped collections between base and semantic layers to solve brand switching. Each extra layer means extra reference hops, extra naming decisions, and extra surfaces to audit. Variables should be easy to reason about--not require a specialist to untangle.

After building Aurora at GM and experiencing these pain points across 4 brands, I realized the industry needed something different--not a new format, but a governance layer on an existing one. One that solves multi-brand without adding complexity.

The Solution

Variable Design Standard (VDS) is a governance layer on the DTCG 2025.10 format. It defines naming rules, validation requirements, versioning strategy, and adapter patterns--so handoff holds as teams and products grow. Three layers. File selection for brands. No extra hops.

JSON-as-API Architecture

The JSON file set is the API surface. File paths and variable names are the contract. A rename is a breaking change.

{
  "color": {
    "text": {
      "primary": {
        "$type": "color",
        "$value": "{color.gray.900}",
        "$description": "Primary text color for body content"
      }
    },
    "surface": {
      "brand": {
        "$type": "color",
        "$value": "{color.brand.primary}"
      }
    }
  }
}

Three-Layer Anatomy

VDS defines three layers only. Base, Alias, Component. Implementations must not add a fourth layer between Alias and Base:

Base variables: Raw scales and palettes. The only place literal values live. color.gray.900, space.4
Alias variables: Semantic intent. Reference base variables. color.text.primary → {color.gray.900}
Component variables: Scoped control when needed. component.button.color.background → {color.surface.brand}

Adapter Pattern

Tool exports are inputs, not the contract. Adapters normalize Figma, Tokens Studio, and other formats into VDS:

// Before: Figma export (tool-specific)
{
  "@primitives": {
    "$color": {
      "primary": {
        "$type": "color",
        "$value": "{@primitives.$color.blue.500}",
        "$variable_metadata": {
          "figmaId": "VariableID:502:227"
        }
      }
    }
  }
}

// After: VDS contract (normalized)
{
  "primitives": {
    "color": {
      "primary": {
        "$type": "color",
        "$value": "{primitives.color.blue.500}",
        "$extensions": {
          "figma": { "variableId": "VariableID:502:227" }
        }
      }
    }
  }
}

Governance Built In

Variable names are treated like an API. Changes are reviewed before merge:

Naming rules validated in CI (dot-separated paths, no hyphens)
References validated for resolution and cycles
Breaking changes require MAJOR version bump
Deprecation strategy with migration paths

Why Three Layers

Some approaches add mapped collections between base and semantic layers to handle brand switching. One mapped collection becomes two. Two becomes three. Before long, your variables panel looks like inception--layers within layers, and you need a specialist to trace which value actually renders.

VDS takes a different position: file selection replaces mapped layers. The primitives already exist. JSON has structure. Folders have hierarchy. CSS has @layer, @import, and cascade. Use them.

The Cost of Mapped Layers

Each additional layer between base and alias creates compounding overhead:

Second naming decision: Every semantic variable now requires naming the intermediate mapped value too. Double the naming surface. Double the review scope.
Extra reference hop: Every resolution traverses one more layer. More hops, more failure points, slower builds.
Extra audit surface: Another collection to review, validate, and keep in sync across brands. Another place for drift.
Expanded decision surface: Instead of one file selection, you now manage collection modes in cramped tool panels.
Artificial complexity: Complexity that benefits specialists, not teams. Variables should be easy to reason about.

// Non-conformant: Mapped layer adds overhead
{
  "mapped": {
    "brand": {
      "primary": { "$type": "color", "$value": "{color.blue.500}" }
    }
  },
  "color": {
    "surface": {
      "brand": { "$type": "color", "$value": "{mapped.brand.primary}" }
    }
  }
}

File Selection Rule (JSON-as-API)

Brand selection happens by file list, not by mapped collections in a design tool panel. Pick one folder. The semantic names stay the same. The values change. The folder structure is the switch.

tokens/
base/              # Shared scales (all brands)
  color.json
  spacing.json
brand-a/           # Brand A values
  color.json       # color.brand.primary = #0066cc
brand-b/           # Brand B values
  color.json       # color.brand.primary = #ff0066

// Build config selects brand by source list
{
  "source": [
    "tokens/base/**/*.json",
    "tokens/brand-a/**/*.json"
  ]
}

If you can select files, you can switch brands. No extra collection required. One decision point. CSS cascade layers handle consumption.

/* CSS cascade layers for brand selection at consumption */
@layer base, brand;
@import "variables-base.css" layer(base);
@import "variables-brand-a.css" layer(brand);

Why This Is Faster

One alias hop from base is the default. Direct path. No detours.
No extra collection to review, audit, or explain to new team members.
The three-layer graph keeps review scope small and traceable.
CSS @layer and @import handle cascade. Use the platform.
Decisions live in files and build inputs, not cramped plugin panels.
Any engineer can read the folder structure and understand the brand switch.

Why JSON-as-API Works

The primitives already exist. You do not need new abstraction layers:

Files are already versioned. Git tracks every change. History, blame, diff, rollback for free.
Paths are already structured. tokens/brand-a/color.json is self-documenting. No second naming system required.
Build tools already select files. Style Dictionary's source array. CSS @import. The selector exists.
Engineers already know this pattern. Every dev understands folder structure. Not every dev wants to learn design tool panel quirks.
One source of truth. The JSON in version control is canonical. The design tool panel is a view, not the source.

Mapped layers are a workaround for tools that cannot do file selection. We have tools that can.

Technical Implementation

DTCG 2025.10 Compliance

VDS builds on the W3C Design Tokens Community Group specification, adding governance without reinventing the format:

{
  "border": {
    "default": {
      "$type": "border",
      "$value": {
        "width": { "value": 1, "unit": "px" },
        "color": {
          "colorSpace": "srgb",
          "components": [0.88, 0.88, 0.88],
          "hex": "#e0e0e0"
        },
        "style": "solid"
      }
    }
  },
  "typography": {
    "heading": {
      "$type": "typography",
      "$value": {
        "fontFamily": "{font.family.primary}",
        "fontSize": "{font.size.lg}",
        "fontWeight": "{font.weight.bold}",
        "lineHeight": 1.5
      }
    }
  }
}

Semantic Versioning

Breaking changes are explicit. Consumers can plan upgrades:

MAJOR: Variable renamed or removed, type changed
MINOR: New variables, new modes, non-breaking additions
PATCH: Value tweaks, documentation updates

{
  "color": {
    "primary": {
      "$type": "color",
      "$value": "#0066cc",
      "$deprecated": true,
      "$description": "Use color.brand.primary instead"
    },
    "brand": {
      "primary": {
        "$type": "color",
        "$value": "#0066cc"
      }
    }
  }
}

Validation in CI

Every PR runs validation before merge:

JSON schema validation for DTCG compliance
Naming convention checks (dot-separated, lowercase)
Reference resolution and cycle detection
Mode key consistency within collections
Breaking change detection with release notes requirements

What VDS Is and Isn't

VDS Is

A governance layer on DTCG 2025.10 format
Rules for naming, validation, and versioning
Adapter patterns for tool integration
A standard for managing variables in version control
Three layers only: Base, Alias, Component

VDS Is Not

A new format (uses DTCG 2025.10)
A tool (works with existing tools)
A design system (governs variables, not design decisions)
A runtime library (validation is build-time)
A place for extra abstraction layers

VDS succeeds when teams adopt it without confusion, variables are validated automatically, design and code stay aligned, and tools work together via DTCG format and adapters.

Impact & Vision

Variable Design Standard addresses foundational infrastructure gaps:

Solves tool lock-in through adapter patterns that normalize any tool output into a portable contract format
Enables design-code alignment with shared vocabulary ("variables" across CSS, JS, and Figma) and validated handoff
Prevents breaking changes through SemVer, deprecation strategy, and CI validation before merge
Scales to multi-brand with file selection rules that keep one semantic name set across brands--no intermediate layers
Reduces governance overhead by keeping the layer count minimal. Three layers. One decision point for brand selection.
DTCG-compliant foundation ensures compatibility with W3C standards and the broader tooling ecosystem

The specification is published as a living document, informed by real design systems work at scale. The goal is to establish an industry standard for design variable governance that teams can adopt regardless of their tool stack--because the contract should outlive any tool choice.