Mark Learst - Senior Frontend & Design Engineer

The Problem

Design systems teams face a fundamental infrastructure challenge: there is no standard for how design variables should be versioned, governed, and synchronized across tools. This creates:

Tool lock-in: Figma Variables, Adobe, and code-based token systems use incompatible formats
Broken design-code handoff: No standard way to track which variable version is deployed in production
Version control gaps: Design tools lack Git-like versioning for variables
Governance chaos: No defined approval workflows for token changes affecting multiple brands
Sync failures: Manual processes to keep Figma, Style Dictionary, and codebases aligned

After building Aurora at GM and seeing these pain points firsthand, I realized the industry needed an open specification defining how variables should be structured, versioned, and validated across the entire design-to-code pipeline.

The Solution

Variable Contract is an open specification that defines JSON structures, validation rules, versioning strategies, and adapters for design variable governance and cross-tool synchronization.

Contract Structure

Defines a standardized JSON contract format:

Metadata: Contract version, schema version, source of truth, timestamps
Variable definitions: DTCG-compliant token structures with type safety
Modes/themes: Multi-brand or multi-theme variable sets
Dependencies: Track relationships between variables (aliases, references)
Change log: Git-style commit history for variable changes

Semantic Versioning

Applies SemVer to design variables:

MAJOR: Breaking changes (variable renamed or removed)
MINOR: Backward-compatible additions (new variables added)
PATCH: Value updates without structural changes
Enables teams to understand impact before deploying token updates

Validation Schema

JSON Schema for validating contracts:

Validates contract structure before deployment
Ensures DTCG compliance for token definitions
Checks for breaking changes between versions
Prevents accidental variable deletions or renames

Tool Adapters

Reference implementations for cross-tool sync:

Figma Variables Adapter: Export Figma Variables to contract format
Style Dictionary Adapter: Convert contracts to Style Dictionary tokens
Git Adapter: Track contract changes in version control
CI/CD Integration: Validate contracts in pull requests

Governance Model

Defines approval workflows:

Required approvers for MAJOR vs MINOR vs PATCH changes
Multi-brand approval gates (e.g., GM's 4-brand scenario)
Rollback procedures when deployed tokens break production
Audit trail for all variable changes

Technical Implementation

DTCG Compliance

Aligned with W3C Design Tokens Community Group:

Uses DTCG 2025.10 token format as foundation
Extends spec with versioning and governance metadata
Maintains compatibility with existing DTCG tools
Contributed feedback to W3C community discussions

Real-World Testing

Developed from hands-on experience:

Patterns tested during Aurora (GM) implementation
Governance model based on real 4-brand token workflows
Validation rules informed by production token failures
Adapter designs driven by Figma Variables to Style Dictionary pipelines

Documentation & Spec

Comprehensive specification docs:

Contract schema definition with examples
Versioning strategy guidelines
Adapter implementation patterns
Governance workflow templates
Migration guides from existing token systems

Impact & Vision

Variable Contract addresses foundational infrastructure gaps in the design systems ecosystem:

Solves tool lock-in by defining portable variable structures that work across Figma, Adobe, and code-based systems
Enables Git-like versioning for design variables, bringing version control discipline to design tools
Standardizes governance with approval workflows that scale to multi-brand design systems
Prevents breaking changes through SemVer and validation, protecting production applications
DTCG-compliant foundation ensures compatibility with W3C standards and tooling ecosystem
Open specification drives community discussion and potential standardization

The specification is published on GitHub as a living document, with ongoing development informed by design systems practitioners and W3C community feedback. The goal is to establish an industry standard for design variable governance that design systems teams can adopt regardless of their tool stack.