Frequently Asked Questions

Common questions about Variable Design Standard (VDS).

What is Variable Design Standard (VDS)?

Variable Design Standard (VDS) is a governance standard for design variables. It defines JSON structure, naming rules, validation requirements, and versioning strategy. Built on DTCG 2025.10 format.

Why “variables” not “design tokens”?

Variables are variables. CSS variables, JavaScript variables, Figma variables. Everyone understands “variables.” “Design tokens” creates confusion and separation between design and code.

Is Variable Design Standard (VDS) a new format?

No. Variable Design Standard (VDS) uses DTCG 2025.10 format. It adds governance (naming rules, validation, versioning) on top of the format.

Is Variable Design Standard (VDS) a spec or governance?

Both. The spec defines JSON shape, naming, references, and modes. Governance defines review and validation gates. The contract is the JSON in version control.

Do I need to change my existing variables?

Not immediately. Variable Design Standard (VDS) provides migration paths from existing formats (Style Dictionary, custom formats, older DTCG). See Migration Strategy.

What tools do I need?

Any DTCG-compliant tool works. Variable Design Standard (VDS) is tool-agnostic. Common tools:

  • Figma (authoring)
  • Style Dictionary (output generation)
  • DTCG validators (validation)

Who owns variables?

Designer creates variables in Figma. Design Engineer owns the Variable Design Standard (VDS) (maintains naming rules, reviews changes). Frontend Engineer consumes variables in code.

What’s the difference between Designer and Design Engineer?

Designer creates variables in Figma. Design Engineer bridges design and development, owns the contract, understands both Figma and React component libraries.

Do I need all three roles?

In smaller teams, one person (Design Engineer) may fill multiple roles. But responsibilities remain distinct: authoring (Designer), contract ownership (Design Engineer), consumption (Frontend Engineer).

How do I handle breaking changes?

  1. Mark old variable as deprecated
  2. Create new variable with new name
  3. Update all references
  4. Bump MAJOR version
  5. Document migration path
  6. Remove deprecated variable in next major version

See Versioning for details.

Can I use platform names in variable names?

No. Variable names MUST NOT include platform names (ios, android, web, etc.). Platform mapping belongs in translation layers (adapters, build tools).

What if my tool uses different reference syntax?

Use an adapter to normalize tool-specific syntax to Variable Design Standard (VDS) format. See Adapters for examples.

How do I validate variables?

Run validation in CI:

  1. Validate JSON structure
  2. Validate naming convention
  3. Validate reference resolution
  4. Detect circular references
  5. Validate types

See Validation for tools and setup.

Can I use modes?

Yes. Modes are supported. Mode keys must match within collections (validation enforces this). Common modes: light/dark, mobile/desktop.

See Modes for details.

Do I need a mapped layer or mapped collection?

No. Variable Design Standard (VDS) uses three layers only: base, alias, component. Brand selection happens by file selection or alias modes. CSS cascade layers handle consumption. See Anatomy, Multi-Brand Architecture, and CSS Consumption.

What’s the difference between base, alias, and component variables?

  • Base variables: Raw values (color.gray.900)
  • Alias variables: Semantic names that reference base variables (color.text.primary)
  • Component variables: Component-scoped aliases (component.button.color.background.default)

See Anatomy for details.

How do I get started?

  1. Read Getting Started
  2. Set up repository structure
  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

Can I contribute?

Yes. Contributions welcome. See Contributors for details.

See License for usage terms.

Is Variable Design Standard (VDS) production-ready?

Yes. Version 0.5.0 is in Draft status but production-ready. Used by teams in production. See Specification Status for status definitions.

How do I claim conformance?

See Conformance for conformance requirements and report template.

What if I find a bug?

Report issues via GitHub issues. Include:

  • Variable Design Standard (VDS) version
  • Steps to reproduce
  • Expected behavior
  • Actual behavior

Can I use Variable Design Standard (VDS) with my design system?

Yes. Variable Design Standard (VDS) is design-system agnostic. It governs variable structure and governance, not design decisions (values, colors, spacing).

PreviousReferences NextLicense