Variable Design Standard

• Naming confusion: Designers call them one thing, developers another. Handoff breaks because vocabulary is split.

• No governance: Variables change without rules. Breaking changes ship to production without notice.

• Tool lock-in: Figma Variables, Tokens Studio, and code-based systems use incompatible formats and reference syntax.

• Handoff breaks: Design and code don't align. No way to track which variable version is deployed.

• No validation: Invalid variables pass review and cause build failures downstream.

• Layer proliferation: Teams add mapped collections between base and semantic layers to solve brand switching. Each extra layer means extra reference hops, extra naming decisions, and extra surfaces to audit. Variables should be easy to reason about, without requiring a specialist to untangle.

JSON-as-API Architecture

{
  "color": {
    "text": {
      "primary": {
        "$type": "color",
        "$value": "{color.gray.900}",
        "$description": "Primary text color for body content"
      }
    },
    "surface": {
      "brand": {
        "$type": "color",
        "$value": "{color.brand.primary}"
      }
    }
  }
}

Adapter examples

// Before: Figma export (tool-specific)
{
  "@primitives": {
    "$color": {
      "primary": {
        "$type": "color",
        "$value": "{@primitives.$color.blue.500}",
        "$variable_metadata": {
          "figmaId": "VariableID:502:227"
        }
      }
    }
  }
}

// After: VDS contract (normalized)
{
  "primitives": {
    "color": {
      "primary": {
        "$type": "color",
        "$value": "{primitives.color.blue.500}",
        "$extensions": {
          "figma": { "variableId": "VariableID:502:227" }
        }
      }
    }
  }
}

Mapped layer costs

• Second naming decision: Every semantic variable now requires naming the intermediate mapped value too. Double the naming surface. Double the review scope.

• Extra reference hop: Every resolution traverses one more layer. More hops, more failure points, slower builds.

• Extra audit surface: Another collection to review, validate, and keep in sync across brands. Another place for drift.

• Expanded decision surface: Instead of one file selection, you now manage collection modes in cramped tool panels.

• Artificial complexity: Complexity that benefits specialists, not teams. Variables should be easy to reason about.

// Non-conformant: Mapped layer adds overhead
{
  "mapped": {
    "brand": {
      "primary": { "$type": "color", "$value": "{color.blue.500}" }
    }
  },
  "color": {
    "surface": {
      "brand": { "$type": "color", "$value": "{mapped.brand.primary}" }
    }
  }
}

// Build config selects brand by source list
{
  "source": [
    "tokens/base/**/*.json",
    "tokens/brand-a/**/*.json"
  ]
}

/* CSS cascade layers for brand selection at consumption */
@layer base, brand;
@import "variables-base.css" layer(base);
@import "variables-brand-a.css" layer(brand);

Review and resolution

• One alias hop from base is the default. Direct path. No detours.
• No extra collection to review, audit, or explain to new team members.
• The three-layer graph keeps review scope small and traceable.
• CSS @layer and @import handle cascade. Use the platform.
• Decisions live in files and build inputs, not cramped plugin panels.
• Any engineer can read the folder structure and understand the brand switch.

Version control and build inputs

• Files are already versioned. Git tracks every change. History, blame, diff, rollback for free.

• Paths are already structured. tokens/brand-a/color.json is self-documenting. No second naming system required.

• Build tools already select files. Style Dictionary's source array. CSS @import. The selector exists.

• Engineers already know this pattern. Every dev understands folder structure. Not every dev wants to learn design tool panel quirks.

• One source of truth. The JSON in version control is canonical. The design tool panel is a view, not the source.

DTCG 2025.10 types

{
  "border": {
    "default": {
      "$type": "border",
      "$value": {
        "width": { "value": 1, "unit": "px" },
        "color": {
          "colorSpace": "srgb",
          "components": [0.88, 0.88, 0.88],
          "hex": "#e0e0e0"
        },
        "style": "solid"
      }
    }
  },
  "typography": {
    "heading": {
      "$type": "typography",
      "$value": {
        "fontFamily": "{font.family.primary}",
        "fontSize": "{font.size.lg}",
        "fontWeight": "{font.weight.bold}",
        "lineHeight": 1.5
      }
    }
  }
}

Versioning and deprecation

• MAJOR: Variable renamed or removed, type changed

• MINOR: New variables, new modes, non-breaking additions

• PATCH: Value tweaks, documentation updates

{
  "color": {
    "primary": {
      "$type": "color",
      "$value": "#0066cc",
      "$deprecated": true,
      "$description": "Use color.brand.primary instead"
    },
    "brand": {
      "primary": {
        "$type": "color",
        "$value": "#0066cc"
      }
    }
  }
}