Governance: Troubleshooting
Troubleshooting
Common issues when working with Variable Design Standard (VDS) and how to fix them.
Workflow
- Reproduce the error in CI or local validation.
- Identify the file and variable path from the error output.
- Fix the cause (type, reference, or mode key set).
- Re-run validation before merge.
Circular references
Problem
Circular reference detected: color.a → color.b → color.a
Cause
Variable A references variable B, which references variable A (directly or indirectly).
Solution
Break the cycle by making one variable reference a literal value:
Before:
{
"color": {
"a": {
"$type": "color",
"$value": "{color.b}"
},
"b": {
"$type": "color",
"$value": "{color.a}"
}
}
}
After:
{
"color": {
"a": {
"$type": "color",
"$value": "#0066cc"
},
"b": {
"$type": "color",
"$value": "{color.a}"
}
}
}
Detection
Validation should detect circular references. Check validation output for cycle warnings.
Invalid types
Problem
Variable spacing.base has $type: "color" but $value: "16px"
Cause
$type does not match $value format.
Solution
Fix the type or value:
Option 1: Fix type
{
"spacing": {
"base": {
"$type": "dimension",
"$value": "16px"
}
}
}
Option 2: Fix value
{
"spacing": {
"base": {
"$type": "color",
"$value": "#0066cc"
}
}
}
Prevention
Run validation before committing. Check type matches value format.
Review checklist
- Error reproduced with validation output
- Variable path and file identified
- Fix applied and validation passes
Reference resolution failures
Problem
Reference {color.primary} points to non-existent variable
Cause
Referenced variable does not exist or path is incorrect.
Solution
Create the referenced variable or fix the reference path:
Before:
{
"color": {
"text": {
"primary": {
"$type": "color",
"$value": "{color.primary}"
}
}
}
}
After:
{
"color": {
"primary": {
"$type": "color",
"$value": "#0066cc"
},
"text": {
"primary": {
"$type": "color",
"$value": "{color.primary}"
}
}
}
}
Prevention
Validate references resolve before committing. Use validation tools.
Mode mismatches
Problem
Variable color.surface has mode light but collection expects light and dark
Cause
Mode keys do not match within a collection.
Solution
Add missing modes or remove mismatched modes:
Before:
{
"color": {
"surface": {
"$type": "color",
"$value": {
"light": "#ffffff"
}
},
"text": {
"$type": "color",
"$value": {
"light": "#000000",
"dark": "#ffffff"
}
}
}
}
After:
{
"color": {
"surface": {
"$type": "color",
"$value": {
"light": "#ffffff",
"dark": "#000000"
}
},
"text": {
"$type": "color",
"$value": {
"light": "#000000",
"dark": "#ffffff"
}
}
}
}
Prevention
Define mode strategy upfront. Validate mode key sets in CI.
Naming violations
Problem
Variable name color/web-primary includes platform prefix
Cause
Variable name violates naming convention (no platform prefixes).
Solution
Remove platform prefix:
Before:
{
"color": {
"web-primary": {
"$type": "color",
"$value": "#0066cc"
}
}
}
After:
{
"color": {
"primary": {
"$type": "color",
"$value": "#0066cc"
}
}
}
Prevention
Validate naming convention in CI. Use naming linter.
Missing $type
Problem
Variable color.primary missing $type
Cause
Variable object does not have $type property.
Solution
Add $type property:
Before:
{
"color": {
"primary": {
"$value": "#0066cc"
}
}
}
After:
{
"color": {
"primary": {
"$type": "color",
"$value": "#0066cc"
}
}
}
Prevention
Validate structure in CI. Check all variables have $type.
Invalid reference syntax
Problem
Reference uses non-canonical format: color.primary instead of {color.primary}
Cause
Reference syntax does not match Variable Design Standard (VDS) format.
Solution
Convert to canonical format:
Before:
{
"color": {
"text": {
"primary": {
"$type": "color",
"$value": "color.primary"
}
}
}
}
After:
{
"color": {
"text": {
"primary": {
"$type": "color",
"$value": "{color.primary}"
}
}
}
}
Prevention
Run adapter normalization. Validate reference syntax in CI.
Group extension failures
Problem
Group color.brand references non-existent group {color.base}
Cause
Group $extends target does not exist.
Solution
Create the referenced group or fix the reference path:
Before:
{
"color": {
"brand": {
"$extends": "{color.base}"
}
}
}
After:
{
"color": {
"base": {
"primary": {
"$type": "color",
"$value": {
"colorSpace": "srgb",
"components": [0, 0.4, 0.8],
"hex": "#0066cc"
}
}
},
"brand": {
"$extends": "{color.base}"
}
}
}
Prevention
Validate group references resolve. Check $extends targets exist.
Property-level reference errors
Problem
Property-level reference {color.primary.r} targets non-color type
Cause
Property-level reference used on wrong type.
Solution
Use property-level references only on compatible types:
Before:
{
"spacing": {
"base": {
"$type": "dimension",
"$value": "16px"
},
"base-r": {
"$type": "number",
"$value": "{spacing.base.r}"
}
}
}
After:
{
"color": {
"primary": {
"$type": "color",
"$value": {
"r": 0,
"g": 102,
"b": 204,
"alpha": 1
}
},
"primary-r": {
"$type": "number",
"$value": "{color.primary.r}"
}
}
}
Prevention
Validate property-level references target compatible types.
Getting help
If issues persist:
- Check validation output for specific errors
- Review Validation guide
- Check Change Control for review process
- Consult Design Engineer role
Out of scope
- Tool-specific issues (see adapter documentation)
- Build pipeline issues (see Style Dictionary documentation)
- Runtime consumption issues (see platform-specific docs)