Design tokens — DTCG format

Contract

When you output a design-tokens file (a tokens.json / design-system token set for a Figma-to-code or Style-Dictionary pipeline), emit the W3C Design Tokens Community Group (DTCG) Format Module exactly. This means $-prefixed reserved properties, the fixed $type vocabulary, per-type value objects (not CSS strings), and curly-brace {alias} references. Apply whenever the requested artifact is a machine-readable token file.

Rules

1. A token is a JSON object; $value is the only required property. Optional reserved

properties: $type, $description, $extensions, $deprecated. Every reserved property begins with $. A group is a plain object whose non-$ keys are nested tokens or groups.

1. Never use the bare keys value, type, description, extensions, deprecated.

Always the $-prefixed form ($value, $type, …). This is the single most common miss.

1. $type comes from a closed vocabulary. Atomic: color dimension fontFamily

fontWeight duration cubicBezier number. Composite: strokeStyle border transition shadow gradient typography. Use these exact tokens — never size, spacing, space, px, font, text, string, or boolean.

1. Set $type once on a group; children omit it. A token with no $type inherits the

$type of its nearest ancestor group; if its value is an alias, the type resolves from the referenced token. Do not repeat $type on every leaf when a group covers them.

1. Reference another token with a curly-brace dot path: "$value": "{group.subgroup.token}".

Never put a $ref, a var(--x), an @token, or a copied hex literal in a $value to mean "same as". (A property-level $ref JSON Pointer exists for document access, but the token-value alias is the curly form.)

1. Naming: a token or group name MUST NOT begin with $ and MUST NOT contain

., {, or } — those are reserved for the alias path syntax. Use nesting or hyphens instead of dots (color.brand.primary → nested color → brand → primary).

1. Per-type $value shapes:

• color → object { "colorSpace": "srgb", "components": [r, g, b] } with 0–1 channel

numbers; optional "alpha" (0–1) and optional "hex" fallback. Not a bare "#2563eb" string.

• dimension → object { "value": <number>, "unit": "px" | "rem" }. Not "16px".
• duration → object { "value": <number>, "unit": "ms" | "s" }. Not "200ms".
• number → a plain JSON number (opacity, z-index, unitless line-height, multipliers).
• fontFamily → a single string, or an array of strings for a fallback stack.
• fontWeight → an integer 1–1000, or a lowercase hyphenated keyword alias:

thin hairline extra-light ultra-light light normal regular book medium semi-bold demi-bold bold extra-bold ultra-bold black heavy extra-black ultra-black. Not "Bold", not CSS "bolder"/"lighter".

• cubicBezier → an array of exactly four numbers [x1, y1, x2, y2] (x in [0,1]).

Not "ease-in-out", not "cubic-bezier(0.4,0,0.2,1)".

• strokeStyle → a keyword string from { solid dashed dotted double groove ridge

outset inset }, or an object { "dashArray": <dimension>…], "lineCap": "round"|"butt"|"square" }.

• border → object { "color", "width", "style" } (each a value or {alias}).
• transition → object { "duration", "delay", "timingFunction" }.
• shadow → object { "color", "offsetX", "offsetY", "blur", "spread" } (or an array

of these for layered shadows). Not a "0 1px 2px rgba(...)" string.

• gradient → an array of stops, each { "color", "position" } with position in [0,1].
• typography → object { "fontFamily", "fontSize", "fontWeight", "lineHeight" }.

1. Tool/vendor data lives under $extensions keyed by reverse-domain names

("com.figma.tokens": {…}), never as extra top-level keys on the token.

1. Deprecate with "$deprecated": true (or a string reason) — never a bare deprecated

key and never a // comment.

Worked examples

Color — before (bare keys + hex string) → after:

json
// before
{ "color": { "primary": { "value": "#2563eb", "type": "color" } } }
// after
{ "color": { "$type": "color",
  "primary": { "$value": { "colorSpace": "srgb", "components": [0.145, 0.388, 0.922] } } } }

Dimension — before → after:

json
// before  { "spacing": { "md": { "value": "16px", "type": "size" } } }
// after   { "spacing": { "$type": "dimension",
//            "md": { "$value": { "value": 16, "unit": "px" } } } }

Alias — before (copy / $ref / var) → after (curly path):

json
// before  { "button": { "bg": { "$value": "#2563eb" } } }        // copied literal
// before  { "button": { "bg": { "$ref": "#/color/primary" } } }  // wrong: $ref in value
// after   { "button": { "bg": { "$value": "{color.primary}" } } }

Typography composite — before (flat CSS-ish) → after:

json
// before  { "heading": { "value": "700 24px/1.2 Inter", "type": "font" } }
// after
{ "heading": { "$type": "typography", "$value": {
    "fontFamily": "Inter", "fontSize": { "value": 24, "unit": "px" },
    "fontWeight": "bold", "lineHeight": 1.2 } } }

Shadow — before (CSS string) → after (object):

json
// before  { "elevation": { "1": { "$value": "0 1px 2px rgba(0,0,0,0.1)" } } }
// after
{ "elevation": { "1": { "$type": "shadow", "$value": {
    "color": { "colorSpace": "srgb", "components": [0,0,0], "alpha": 0.1 },
    "offsetX": { "value": 0, "unit": "px" }, "offsetY": { "value": 1, "unit": "px" },
    "blur": { "value": 2, "unit": "px" }, "spread": { "value": 0, "unit": "px" } } } } }

Edge cases & exceptions

• Aliased token has no $type → its type resolves from the token it points at; do not

invent one. { "$value": "{color.primary}" } is a color because color.primary is.

• A hex may accompany a color as an optional convenience property inside the color

object, but colorSpace + components remain the authoritative value.

• Layered shadows use an array of shadow objects; a single shadow is one object.
• Property-level $ref (JSON Pointer, "#/…") is allowed for cross-document reuse of a

property, but the ordinary "same value as another token" case uses the {curly} alias.

• Unitless numbers (opacity 0.5, line-height multiplier 1.5, z-index 10) are

$type: "number", a plain JSON number — not a dimension, not a string.

Do / Don't

• Do prefix every reserved property with $. Don't write value/type.
• Do make color/dimension/duration values objects. Don't use "#hex", "16px", "200ms".
• Do reference with "{group.token}". Don't use $ref, var(--x), @, or a copied literal in $value.
• Do hoist $type to the group. Don't contradict it on children.
• Do keep names free of ./{/}/leading $. Don't name a token "brand.primary".
• Do put tool data in $extensions (reverse-domain key). Don't add ad-hoc top-level keys.

Common mistakes

• "value" / "type" without the $ — the #1 non-conformance.
• $type: "size" or "spacing" instead of "dimension"; "font"/"text" instead of "typography".
• Color as "#2563eb", dimension as "16px", duration as "200ms" (CSS strings, not objects).
• cubicBezier as "ease-in-out" instead of [0.4, 0, 0.2, 1].
• Repeating $type on every leaf instead of once on the group.
• Using $ref/var() inside $value for a simple alias.

Quick checklist

• ] Every reserved property is $-prefixed ($value required).
• ] $type drawn from the closed atomic/composite vocabulary; hoisted to groups.
• ] color/dimension/duration are objects; number is a plain number; cubicBezier is [4 numbers].
• ] Aliases use "{group.token}", never $ref/var()/copied literals.
• ] Names contain no ./{/} and never start with $.
• ] Composite $values carry their exact sub-keys; tool data under $extensions.