Specification Overview

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

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

Abstract

Variable Design Standard (VDS) defines how variables are named, structured, reviewed, and shipped across design and code. It adds governance, validation, and role boundaries to the DTCG 2025.10 format so handoff holds as teams and products grow. JSON-as-API means file paths and names are the interface.

Status of This Document

This specification is Draft. The table above lists the current version, license, and schema.

Conformance

Conformance requires DTCG 2025.10 format compliance, Variable Design Standard (VDS) naming rules, reference syntax, validation, and versioning. See Conformance.

Start here

• Why Variables: Why we call them variables, not design tokens
• Variable Design Standard (VDS): 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: Variable Design Standard vs other standards
• Positioning: What Variable Design Standard is and is not

Contract reference

• Variable Design Standard (VDS): 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 Engineer: Consumes variables in code

Scenarios

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

Tooling

• Ecosystem: Tools that support Variable Design Standard
• 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
• UI Libraries: React/Vue integration patterns

Design

• Figma Naming: How to name variables in Figma UI
• Figma Workflow: Designer workflow tuning
• 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 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: Export-to-contract conversion example

Reference

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

Meta

• Status of this Document: Publication status, editors, acknowledgments
• Specification Status: Status taxonomy and definitions
• Change Log: Version history and release notes
• Contributors: People who have contributed
• References: External standards and specifications

FAQ

• FAQ: Common questions and answers