Variable Design Standard (VDS)

Public specification and governance standard for design variables. DTCG 2025.10 compliant format with naming rules, validation requirements, versioning strategy, and adapter patterns.

Version: 0.4.0 Status: Draft Editor: Mark Learst

Also known as: Variables Contract

Variables are variables. CSS variables, JavaScript variables, Figma variables. Variable Design Standard standardizes how we name, structure, and govern them. No metaphors. No cute names. Just variables.

If variables are managed without a contract, you get silent renames, broken references, inconsistent naming, tool lock-in, and production failures.

What this is

Variable Design Standard defines:

• JSON structure (DTCG 2025.10 format)
• Naming convention (dot-separated paths, lowercase, no platform prefixes)
• Reference syntax (curly brace {path.to.variable} and JSON Pointer #/path/to/variable)
• Validation requirements (structure, naming, references, types, modes)
• Versioning strategy (semantic versioning, breaking change definitions)
• Adapter patterns (Figma, Tokens Studio, Style Dictionary)

Variable Design Standard does NOT define:

• Variable values (your design decisions)
• Tools to use (works with any DTCG-compliant tool)
• Consumption patterns (CSS, TypeScript, whatever works)
• Design system decisions (governs structure, not values)

Why variables, not "design tokens"

Variables are variables. CSS variables, JavaScript variables, Figma variables. They store values, can be referenced, and can be changed.

"Design tokens" creates confusion. Developers know variables. Designers know variables. Variable Design Standard uses the term everyone understands.

See Why Variables for the full argument.

The problem this solves

Naming chaos

Everyone calls them something different: design tokens, style properties, design constants, variables, tokens. This creates confusion and separation between design and code.

Variable Design Standard standardizes on "variables" and provides clear naming rules.

No governance

Variables change without rules. Renames break components. Invalid references ship to production. Breaking changes go unnoticed.

Variable Design Standard provides governance: naming rules, validation requirements, versioning strategy, change control process.

Tool lock-in

Variables are tied to specific tools. Figma exports don't work with Style Dictionary. Tokens Studio format doesn't match DTCG. Migration is painful.

Variable Design Standard is tool-agnostic. Use any tool. Adapters normalize tool outputs to the standard.

Handoff breaks

Design and code don't align. Designers create variables in Figma. Developers consume CSS variables. The connection breaks.

Variable Design Standard bridges the gap. Variables flow from Figma through adapters to version control to generated outputs.

No validation

Invalid variables ship to production. Broken references break components. Type mismatches cause runtime errors.

Variable Design Standard requires validation. CI checks catch errors before they ship.

DTCG 2025.10 compliance

Variable Design Standard is DTCG 2025.10 compliant. Any JSON file that follows Variable Design Standard rules is valid DTCG 2025.10 format.

What DTCG provides:

• JSON structure for variables and groups
• Type system (color, dimension, fontFamily, fontWeight, duration, cubicBezier, number)
• Reference syntax (curly brace {path} and JSON Pointer #/path)
• Composite types (border, transition, shadow, gradient, typography)
• Group extension with $extends
• $extensions for vendor-specific metadata

What Variable Design Standard adds:

• Modes: Contextual variants (light/dark, mobile/desktop) stored in $value objects. DTCG does not define modes. This is a Variable Design Standard extension.
• String shortcuts: Convenience formats like "16px" for dimensions and "200ms" for durations. DTCG requires object format.
• Hex color shorthand: Convenience format like "#0066cc" for colors. DTCG requires object format with colorSpace and components.
• Naming convention rules
• Change control process
• Validation requirements beyond format correctness
• Versioning strategy
• Adapter patterns for tool integration

See DTCG Alignment for details.

Quick start

For teams adopting Variable Design Standard

1. Read Getting Started
2. Set up repository structure (tokens/ directory)
3. Install validation tools
4. Configure CI validation
5. Export variables from Figma
6. Run adapter to normalize
7. Commit normalized JSON
8. Generate outputs (CSS, TypeScript)

See Implementation Checklist for complete setup.

For designers

1. Read Figma Naming
2. Create variables in Figma following naming convention
3. Use semantic variables in components
4. Export variables
5. Follow Figma Workflow

For developers

1. Read CSS Consumption or TypeScript Consumption
2. Use generated CSS variables or TypeScript types
3. Follow Framework Integration for React/Vue
4. Test variable consumption

For Design Engineers

1. Read Variable Design Standard
2. Set up Validation
3. Configure CI/CD
4. Review Change Control
5. Manage Versioning

Documentation structure

Introduction

• Why Variables - Why "variables" not "design tokens"
• Comparison - Variable Design Standard vs DTCG, Style Dictionary, Material, Adobe
• Positioning - What Variable Design Standard is and is not

Contract reference

• Variable Design Standard - 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 tokens

Adoption

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

Governance

• Governance Overview - Governance principles and workflow
• 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

Scenarios

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

Tooling

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

Consumption

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

Design

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

Testing

• Validation - Testing variable changes
• Visual Regression - Visual regression testing
• Consumption Tests - Testing generated outputs

Patterns

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

Requirements

Variable Design Standard JSON files MUST:

• Use DTCG 2025.10 format
• Follow naming convention (dot-separated paths, lowercase, no platform prefixes)
• Use canonical reference syntax ({path.to.variable})
• Include $type and $value on all variables
• Resolve all references (no broken references)
• Avoid circular references
• Use consistent mode keys within collections

Variable Design Standard JSON files SHOULD:

• Include $description when intent is not obvious
• Use semantic aliases for UI consumption
• Keep modes limited (light, dark)
• Organize by category (base, semantic, component)

See Validation Checklist for complete requirements.

Validation

Variables Design Standard requires validation at multiple points:

1. After adapter normalization (check structure, naming, references)
2. In CI on every PR (block invalid changes)
3. Before build (verify contract compliance)
4. After build (test generated outputs)

Validation checks:

• JSON syntax (valid JSON structure)
• Variable structure ($type and $value present)
• Naming convention (dot-separated paths, lowercase)
• Reference resolution (all references resolve)
• Circular reference detection (no reference cycles)
• Type correctness ($value matches $type)
• Mode consistency (mode keys shared within collections)

See Validation for validation tools and CI setup.

Versioning

Variable Design Standard uses semantic versioning (MAJOR.MINOR.PATCH):

• MAJOR: breaking changes (renames, removals, type changes)
• MINOR: new variables, new modes, non-breaking additions
• PATCH: bug fixes, documentation updates

Breaking changes:

• Variable renames
• Variable removals
• Type changes
• Reference changes that break intent

Non-breaking changes:

• New variables
• New modes
• Value changes (if documented and intentional)

See Versioning for complete versioning strategy.

Adapters

Adapters normalize tool outputs into Variable Design Standard format.

Figma adapter

Normalizes Figma Variables export JSON:

• Extracts $collection_metadata to $extensions
• Extracts $variable_metadata to $extensions
• Removes @ prefix from collection names
• Converts reference syntax {@collection.token} to {collection.token}
• Moves mode values from metadata to $value object

See Figma Adapter for details.

Tokens Studio adapter

Normalizes Tokens Studio export JSON:

• Validates DTCG format compliance
• Checks naming convention
• Verifies reference syntax
• Preserves Tokens Studio metadata in $extensions

See Tokens Studio Adapter for details.

Style Dictionary adapter

Generates platform outputs from Variable Design Standard (VDS) JSON:

• CSS variables
• TypeScript types
• Tailwind CSS v4 (CSS custom properties)
• SCSS variables
• Other platform formats

See Style Dictionary Adapter for details.

Examples

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

UDS Framework

Variable Design Standard is part of UDS (UI Design Standard), a comprehensive framework for design-to-code governance.

UDS components:

• Variable Design Standard (VDS) - this spec
• Integrity Design Standard (IDS) - tooling layer (future)
• Component Design Standard (future) - component mapping
• Pattern Design Standard (future) - pattern mapping
• Design-Dev Mapping (future) - artifact relationships

Variable Design Standard is the first standard in UDS, focusing on variables.

Status

Variable Design Standard is:

• DTCG 2025.10 compliant
• Production-ready
• Tool-agnostic
• Validated in CI
• Used by teams

Variable Design Standard (VDS) is NOT:

• A W3C standard (uses DTCG format)
• A tool (works with existing tools)
• A design system (governs structure, not values)
• Complete UMP system (focuses on variables)

See Status of this Document for publication status, editors, and acknowledgments.

Failure modes

If Variable Design Standard is not used:

• Silent renames break components
• Broken references cause production failures
• Inconsistent naming creates confusion
• Tool lock-in prevents migration
• No validation allows invalid variables to ship
• Versioning chaos makes upgrades risky

If Variable Design Standard is used incorrectly:

• Skipping validation allows invalid variables to ship
• Not following naming convention breaks code generation
• Ignoring versioning causes breaking changes without notice
• Skipping adapters leaks tool metadata into contract
• Not testing consumption breaks component styling

Contributing

Variable Design Standard is a public specification. Contributions welcome.

Before contributing:

1. Read WRITING_GUIDE.md
2. Follow writing guide rules (no slop words, testable requirements)
3. Include examples for new concepts
4. Document failure modes
5. Add validation checklists

Local development

Documentation is built with docmd.

Setup

pnpm install

Development

pnpm run docs:dev

Starts local development server at http://localhost:3000.

Build

pnpm run docs:build

Generates static site in site/.

Contributors

Editor: Mark Learst

Variable Design Standard is maintained by the editor. Contributions welcome.

Acknowledgments

Variable Design Standard builds on:

• DTCG 2025.10 Format - Base format specification
• Style Dictionary - Output generation tool
• Figma Variables - Design tool integration
• Tokens Studio - Design tool integration

JSON Schema

Variable Design Standard provides a JSON Schema for validation:

• Schema URL: /assets/schema/v1.json
• Usage: Add "$schema": "https://variable-design-standard.vercel.app/assets/schema/v1.json" to your JSON files
• Documentation: See Schema Documentation for complete reference

The schema validates:

• Variable structure ($type, $value requirements)
• Type correctness
• Reference syntax
• Group structure
• Mode objects

See Schema for validation tools and IDE integration.

References

• DTCG 2025.10 Specification - Design Tokens Community Group format
• Variable Design Standard Documentation - Complete specification and governance
• DTCG Alignment - Compliance details
• JSON Schema - Validation schema and tools

Conformance

To claim Variable Design Standard compliance:

1. Use DTCG 2025.10 format for variable JSON
2. Follow naming convention (dot-separated paths, lowercase, no platform prefixes)
3. Use canonical reference syntax ({path.to.variable})
4. Validate variables (structure, naming, references, types, modes)
5. Use semantic versioning for variable releases
6. Document breaking changes

See Conformance for complete conformance requirements and test suite.

License

This work is licensed under the Creative Commons Attribution 4.0 International License.

See LICENSE for full license text.

Links

• Documentation
• DTCG 2025.10 Specification
• Style Dictionary
• Figma Variables