Skip to content

Worked example: explanation

Generated by skills/document-author with type=explanation. Demonstrates the canonical Diátaxis explanation format — discursive, motivation-driven, justifies design decisions.

---
title: Why design-ai uses W3C DTCG token format (and not Tokens Studio's native format)
description: The decision behind design-ai's choice of W3C DTCG (Style Dictionary–compatible) for token serialization, the alternatives we considered, and the tradeoffs accepted.
type: explanation
audience: Engineers and designers extending design-ai or integrating it with another token system
last_updated: 2026.05.08
---

# Why design-ai uses W3C DTCG token format

## The problem

A design token is a key-value pair: `color.primary.600 = #7C3AED`. The data model is trivial. The hard part is **the format**: how do you serialize this so that it's:

1. Readable by humans
2. Convertible across platforms (CSS, iOS, Android, Figma)
3. Compatible with existing tooling
4. Stable as the token system evolves

Several formats exist. design-ai picks one — W3C DTCG (Design Tokens Community Group format). This doc explains why.

## What we considered

### Option A: Tokens Studio's native JSON

```json
{
  "global": {
    "color": {
      "primary": {
        "600": {
          "value": "#7C3AED",
          "type": "color",
          "description": "Brand primary"
        }
      }
    }
  }
}

Pros: well-supported by the Tokens Studio Figma plugin. Has 5+ years of evolution. Many consumers.

Cons: vendor-specific. Tokens Studio has been promising migration to W3C DTCG. Format isn't a standard.

Option B: Style Dictionary's traditional format

{
  "color": {
    "primary": {
      "600": {
        "value": "#7C3AED",
        "type": "color"
      }
    }
  }
}

Pros: enormous tooling ecosystem. Style Dictionary is from 2018, widely adopted at Amazon/Salesforce/etc. Battle-tested transformations.

Cons: pre-dates the W3C effort. Not technically a standard. type is sometimes attributes.category.

Option C: W3C DTCG format (the chosen one)

{
  "color": {
    "primary": {
      "600": {
        "$value": "#7C3AED",
        "$type": "color"
      }
    }
  }
}

Note the $value / $type (with $ prefix) — that's the W3C distinction.

Pros: emerging W3C standard. Tokens Studio is migrating to it. Style Dictionary v4 supports it natively. Future-proof.

Cons: less mature than Style Dictionary's traditional format. Some tools still in transition.

Option D: Vendor formats (Material Tokens, Primer, etc.)

Each large design system (Material 3, Primer, Polaris, Carbon) has its own token format. For consumers of those systems, native is fine. For a generic system like design-ai? Wrong choice — locks consumers into the parent vendor.

What we chose

W3C DTCG format (Option C).

{
  "color": {
    "brand": {
      "primary": {
        "50":  { "$value": "#F5F3FF", "$type": "color" },
        "600": { "$value": "#7C3AED", "$type": "color" }
      }
    },
    "semantic": {
      "primary": { "$value": "{color.brand.primary.600}", "$type": "color" }
    }
  }
}

The reasoning:

  1. Standard track. The W3C DTCG group includes Adobe, Figma, Atlassian, GitHub, and others. The format will likely become a real standard within 2 years.

  2. Tools converge here. Style Dictionary v4 reads it. Tokens Studio is migrating to it. Custom tooling we write today will keep working.

  3. Distinguishable from JSON-data. The $value prefix prevents collision with regular JSON keys. { "value": ... } was ambiguous.

  4. Already widely supported. The major upstream design systems are publishing tokens in this format.

Tradeoffs accepted

Tradeoff 1 — early-adopter ecosystem

Some Figma plugins haven't migrated yet. Specifically: older Tokens Studio versions still use the non-$ format. Workaround: convert at the boundary using tokens-studio-format npm package.

Impact: minor. The Tokens Studio team has signaled migration.

Tradeoff 2 — slightly more verbose

$value + $type adds 4 chars per entry over the bare value + type. For a 200-token system that's ~800 chars of bytes. Negligible.

Impact: nil.

Tradeoff 3 — older docs reference the non-$ format

Some older Style Dictionary tutorials say "value": .... New users may copy-paste and get the old format. Workaround: design-ai's docs explicitly use $value everywhere, with a "if you see value, that's the old format" note.

Impact: minor — primarily a docs / onboarding cost.

What this means in practice

  • design-ai's tokens/source.json examples use $value / $type.
  • The Figma plugin (tools/figma-plugin/) reads $value directly.
  • The figma-token-sync skill outputs $value format.
  • Tokens Studio plugin: "When importing the JSON to Tokens Studio, use the W3C DTCG import option."

What might change

If the W3C DTCG format diverges significantly from current expectations (e.g., dramatic schema changes), we'll re-evaluate. The transformation is mechanical — switching is a one-time change to the extractor scripts.

If Tokens Studio decides not to support W3C DTCG (unlikely as of mid-2025), we may need to bridge formats per consumer.

For now: W3C DTCG is the bet.

  • Why nested vs flat: nested matches the way tokens are reasoned about (hierarchy). Flat (color.brand.primary.600 = #7C3AED) loses that semantic.
  • Why JSON not YAML: JSON has stronger machine-tooling. YAML's whitespace sensitivity bites here.
  • Why allow references: {color.brand.primary.600} aliases let semantic tokens cleanly point to primitives without duplicating values.

See also

Why this is a good explanation example

  • Problem stated up front — frames the decision space.
  • Options enumerated — A through D, each with pros + cons.
  • Choice declared, with reasoning — not just "we chose C", but why.
  • Tradeoffs accepted — what we gave up; honest.
  • What might change — when this decision should be revisited.
  • Related decisions — links the broader rationale.
  • Discursive but rigorous — not preachy, not academic. Conversational with structure.

Cite knowledge/patterns/technical-writing.md — explanation voice is more discursive than tutorial / how-to.

Cross-reference