DTCG format

The W3C Design Token Community Group (DTCG) defines a standard interchange format for design tokens, so they can travel between tools (Figma, code, documentation) without loss of meaning.

@uncinq/design-tokens uses DTCG JSON as its source format. Style Dictionary v5 transforms those JSON files into CSS custom properties — see STYLE-DICTIONARY.md for the build pipeline. The DTCG spec informs the architecture (primitive → semantic → component, naming conventions, token types).

The DTCG format

The DTCG spec defines tokens as JSON objects with reserved $-prefixed keys:

{
  "color": {
    "brand": {
      "$value": "oklch(0.530 0.195 22.0)",
      "$type": "color",
      "$description": "Primary brand color — used for CTAs and highlights."
    }
  }
}

Note on OKLCH: The DTCG color type accepts any valid CSS color value, including oklch(…). @uncinq/design-tokens uses OKLCH throughout — perceptually uniform, wide-gamut, and natively supported in modern browsers.

DTCG token types

Scalar types

Composite types

→ Full type list: tr.designtokens.org/format/#types

Note on clamp() values: DTCG has no native fluid type. Fluid tokens (--font-size-fluid-sm, --font-size-fluid-md, --spacing-fluid-*) use $type: "dimension" as the closest match — a documented gap in the spec.

Token groups

Tokens are organized in nested objects. Groups share a $type by inheritance:

{
  "color": {
    "$type": "color",
    "gray": {
      "100": { "$value": "oklch(0.967 0.003 264.542)" },
      "900": { "$value": "oklch(0.208 0.006 264.542)" }
    }
  }
}

→ tr.designtokens.org/format/#groups

Naming conventions

CSS compound properties → camelCase

CSS property names that are two words (kebab-case in CSS) are written as a single camelCase key — not as a nested group. The pathToKebab transform converts them back to kebab-case for the CSS output, so the result is identical either way.

// ✅ correct
"btn": {
  "fontSize": { "$value": "{fontSize.sm}", "$type": "dimension" },
  "fontWeight": { "$value": "{fontWeight.bold}", "$type": "fontWeight" }
}

// ❌ wrong
"btn": {
  "font": {
    "size": { "$value": "{fontSize.sm}", "$type": "dimension" },
    "weight": { "$value": "{fontWeight.bold}", "$type": "fontWeight" }
  }
}

Exception — semantic namespaces: border, color, padding, margin, shadow used to group multiple sub-properties stay nested, because the group key itself is not a CSS property compound word.

// ✅ border as a namespace grouping multiple properties
"border": {
  "radius": { "$value": "{radius.control}", "$type": "dimension" },
  "width":  { "$value": "{border.width.sm}", "$type": "dimension" }
}

// ✅ color as a semantic grouping
"color": {
  "background": { "$value": "{color.background.default}", "$type": "color" },
  "text":       { "$value": "{color.text.default}", "$type": "color" }
}

Logical properties → sub-keys of padding / margin

Sub-axes of padding and margin use CSS logical property names as sub-keys — not physical directions (x, y, top, bottom, left, right).

// ✅ correct
"padding": {
  "inline": { "$value": "{spacing.sm}", "$type": "dimension" },
  "block":  { "$value": "{spacing.xs}", "$type": "dimension" }
}

// ❌ wrong
"padding": {
  "x": { "$value": "{spacing.sm}", "$type": "dimension" },
  "y": { "$value": "{spacing.xs}", "$type": "dimension" }
}

Exception — CSS top/bottom/left/right as positioning values (not margin/padding sub-keys) keep their physical names, since they map to CSS position properties, not logical shorthands.

// ✅ positioning — physical names are correct here
"sticky": {
  "top": { "$value": "4rem", "$type": "dimension" }
}

States → nested sub-keys

Interactive states (default, hover, active, disabled…) are expressed as nested keys under the property they modify. The default key is automatically stripped by the build transform.

"color": {
  "background": {
    "default": { "$value": "{color.brand.default}", "$type": "color" },
    "hover":   { "$value": "{color.brand.hover}",   "$type": "color" }
  }
}

/* output */
--btn-color-background: var(--color-brand);
--btn-color-background-hover: var(--color-brand-hover);

States and camelCase properties compose naturally:

"color": {
  "textDecoration": {
    "default": { "$value": "transparent", "$type": "color" },
    "hover":   { "$value": "{color.link.default}", "$type": "color" }
  }
}

--btn-color-text-decoration: transparent;
--btn-color-text-decoration-hover: var(--color-link);

References (aliases)

Tokens can reference other tokens using {dotted.path} syntax:

{
  "color": {
    "link": {
      "default": {
        "$value": "{color.brand.default}",
        "$type": "color"
      }
    }
  }
}

In CSS, this maps to var():

--color-link: var(--color-brand);

This is the key mechanism behind the primitive → semantic → component hierarchy.

→ tr.designtokens.org/format/#alias

References

• DTCG specification — W3C Community Group draft
• DTCG GitHub — issues, discussion
• Style Dictionary v5 — token build pipeline, see STYLE-DICTIONARY.md