Migration Guide

Scope: migration rules for converting existing variable formats to Variable Design Standard (VDS).

Failure if ignored: references fail, type validation breaks, and maintenance cost grows.

Workflow

Migration converts existing variable formats to Variable Design Standard (VDS) (DTCG 2025.10) format with governance rules applied.

Migration steps:

1. Audit existing variables (identify format, structure, naming)
2. Map to Variable Design Standard (VDS) structure (groups, types, references)
3. Normalize naming (apply naming convention)
4. Convert references (update reference syntax)
5. Validate output (run validation checklist)
6. Test consumption (verify generated outputs work)

Review checklist

• Reference syntax converted to curly brace format
• All variables include $type
• Tool metadata moved to $extensions
• Validation checklist passes
• Outputs match previous behavior

From older DTCG formats

If you have variables in DTCG formats before 2025.10:

Step 1: Update reference syntax

Older formats may use different reference syntax. Convert to curly brace format:

Before:

{
  "color": {
    "text": {
      "primary": {
        "$type": "color",
        "$value": "color.primary"
      }
    }
  }
}
                    

After:

{
  "color": {
    "text": {
      "primary": {
        "$type": "color",
        "$value": "{color.primary}"
      }
    }
  }
}
                    

Step 2: Add missing $type

Older formats may omit $type. Add it:

Before:

{
  "spacing": {
    "base": {
      "value": "16px"
    }
  }
}
                    

After:

{
  "spacing": {
    "base": {
      "$type": "dimension",
      "$value": "16px"
    }
  }
}
                    

Step 3: Move tool metadata

Move tool-specific metadata to $extensions:

Before:

{
  "color": {
    "primary": {
      "$type": "color",
      "$value": "#0066cc",
      "toolId": "123:456"
    }
  }
}
                    

After:

{
  "color": {
    "primary": {
      "$type": "color",
      "$value": "#0066cc",
      "$extensions": {
        "tool": {
          "id": "123:456"
        }
      }
    }
  }
}
                    

From Style Dictionary format

Style Dictionary uses value and type instead of $value and $type.

Step 1: Rename properties

Convert value → $value and type → $type:

Before:

{
  "color": {
    "primary": {
      "value": "#0066cc",
      "type": "color"
    }
  }
}
                    

After:

{
  "color": {
    "primary": {
      "$type": "color",
      "$value": "#0066cc"
    }
  }
}
                    

Step 2: Update reference syntax

Style Dictionary may use different reference syntax. Convert to curly braces:

Before:

{
  "color": {
    "text": {
      "primary": {
        "value": "{color.primary}",
        "type": "color"
      }
    }
  }
}
                    

After:

{
  "color": {
    "text": {
      "primary": {
        "$type": "color",
        "$value": "{color.primary}"
      }
    }
  }
}
                    

Step 3: Normalize naming

Style Dictionary naming may not follow Variable Design Standard (VDS) convention. Apply naming rules:

Before:

{
  "colorPrimary": {
    "$type": "color",
    "$value": "#0066cc"
  }
}
                    

After:

{
  "color": {
    "primary": {
      "$type": "color",
      "$value": "#0066cc"
    }
  }
}
                    

From custom formats

If you have variables in custom formats:

Step 1: Map structure

Identify:

• Variable names and paths
• Variable types
• Variable values
• References between variables
• Modes or variants

Step 2: Convert to Variable Design Standard (VDS) structure

Create groups and variables following Variable Design Standard (VDS) structure:

• Base tokens: raw scales and palettes
• Semantic aliases: reference base tokens
• Component tokens: reference semantic aliases

Step 3: Normalize types

Map custom types to Variable Design Standard (VDS) types:

• Custom color formats → color
• Custom spacing formats → dimension
• Custom font formats → fontFamily, fontWeight, dimension

Step 4: Convert references

Map custom reference syntax to curly brace format:

• Custom syntax → {path.to.token}

Migration checklist

After migration, verify:

• All variables have $type and $value
• All references use canonical format ({path})
• Names follow naming convention
• No circular references
• Types match values
• Mode keys match within a collection
• Validation passes

Testing migration

Test migration by:

1. Running validation on migrated JSON
2. Generating outputs (CSS, TypeScript) from migrated JSON
3. Comparing outputs with original outputs
4. Testing component consumption
5. Verifying mode switching works

Rollback plan

If migration causes issues:

1. Keep original format files in version control
2. Create migration branch
3. Test migration thoroughly
4. Rollback if validation fails or outputs break

Failure modes

If migration is incomplete:

• Missing $type breaks type validation
• Invalid references break resolution
• Naming violations break code generation
• Type mismatches cause runtime errors
• Lost metadata breaks round-trip workflows

Out of scope

• Automated migration tools (build custom scripts as needed)
• Cross-format conversion libraries
• Migration UI tools

Ownership

• Design Engineer: plans and reviews migration steps
• Frontend Engineer: validates outputs after migration

Links

• Adapters
• Validation
• Conformance