Variables Contract

A deterministic protocol for design-to-code variable governance. JSON shape, naming, references, modes, and change control.

This specification is protected under the Variables Contract License. Usage for AI-generated derivative standards, false compatibility claims, or ecosystem fragmentation is prohibited.

Start here

• Why Variables - Why we call them variables, not design tokens
• Variables Contract - JSON shape and structure
• Variables Governance - Governance principles and workflow
• DTCG Alignment - DTCG 2025.10 compliance
• Getting Started - Team adoption guide

Introduction

• Why Variables - Why “variables” not “design tokens”
• Comparison - Variables Contract vs other standards
• Positioning - What Variables Contract is and is not

Contract reference

• Variables Contract - JSON shape and structure
• Groups - Group structure and extension
• References - Reference syntax and resolution
• Modes - Mode structure and resolution
• Types - Type system reference
• Composite Types - Border, Transition, Shadow, Gradient, Typography
• Naming - Naming convention
• Anatomy - Base, alias, and component variables

Adoption

• Getting Started - Team adoption guide and implementation
• Implementation Checklist - Pre/post implementation checklists
• Migration Strategy - Phased migration approaches

Governance

• Governance Overview - Governance principles and workflow
• Getting Started - Checklist for variable changes
• Change Control - Review and release process
• Validation - Validation tools and CI setup
• Versioning - Semantic versioning and breaking changes
• Migration - Migrating from other formats
• Troubleshooting - Common issues and solutions
• Accessibility - Accessibility constraints
• Roles - Role definitions
  • Designer - Creates variables in Figma
  • Design Engineer - Bridges design and development, owns contract
  • Frontend Developer - Consumes variables in code

Scenarios

• Multi-Brand - Multi-brand architecture patterns
• Multi-Theme - Theme composition and mode inheritance
• Large Sets - Performance considerations and optimization
• Component Integration - Component library integration patterns

Tooling

• Ecosystem - Tools that support Variable Contract
• CI/CD - CI/CD integration patterns and examples
• Build Pipelines - Complete build pipeline examples
• Figma - Figma export normalization and workflow
• Tokens Studio - Tokens Studio export normalization and workflow
• Style Dictionary - CSS/TypeScript output generation

Consumption

• CSS - CSS variable consumption patterns
• TypeScript - TypeScript type generation and usage
• Frameworks - React/Vue integration patterns

Design

• Figma Naming - How to name variables in Figma UI
• Figma Workflow - Designer workflow optimization
• Component Variables - Using variables in Figma components

Testing

• Validation - Testing variable changes and reference validation
• Visual Regression - Visual regression testing strategies
• Consumption Tests - Testing generated outputs

Patterns

• Multi-Brand Architecture - Complete multi-brand example
• Theme Composition - Theme composition patterns and examples
• Performance - Performance optimization strategies

Adapters

• Adapters Overview - Adapter pattern and responsibilities
• Figma Adapter - Figma export normalization and workflow
• Tokens Studio Adapter - Tokens Studio export normalization and workflow
• Style Dictionary Adapter - CSS/TypeScript output generation
• Tailwind Adapter - Tailwind theme configuration generation

Examples

• Figma Export JSON - Example Figma export
• DTCG Compliant Example - Complete DTCG 2025.10 example
• Adapter Pipeline - End-to-end transformation example

Reference

• Glossary - Terminology definitions
• Quick Reference - Cheat sheet for common tasks
• Conformance - How to claim compliance

FAQ

• FAQ - Common questions and answers