Design tokens and the W3C spec, in practice

Two layers: primitives and semantics

Design tokens split into primitives and semantic tokens. Primitives are the raw material — a brand scale, a type-size ramp, a radius set — named after what they are (brand.500, font-size.base). Semantic tokens are the decisions components consume — background, foreground, primary, border-muted — named after the job. Components reference semantics; semantics reference primitives; only the semantic layer changes when you retheme.

This layering is what the W3C Design Tokens (DTCG) format encodes. The spec is a community standard for describing tokens as JSON so tools can interchange them: Tokens Studio, Style Dictionary, container queries and hand-rolled pipelines all read the same $type/$value shape.

The JSON shape you'll actually see

The core of the format is a nested JSON object where each leaf token carries a $type and a $value, with an optional $description. A color primitive looks like {"$type": "color", "$value": "#6d28d9"}; a dimension like {"$type": "dimension", "$value": "0.5rem"}. Composite types like typography and shadow bundle sub-properties under one token.

ChromaBrew's design token generator emits exactly this shape — DTCG-style JSON with $type, $value and $description on every token — covering colors, typography, spacing, radius and shadows for both light and dark, so the file is a complete quiet description of the system with no CSS attached.

{
  "$description": "Aurora design tokens — generated by ChromaBrew",
  "primitive": {
    "color": {
      "brand": {
        "500": { "$type": "color", "$value": "#6d28d9" }
      }
    }
  },
  "semantic": {
    "light": {
      "primary": { "$type": "color", "$value": "#6d28d9" },
      "background": { "$type": "color", "$value": "#fdfcff" }
    }
  }
}

Aliasing is where the power lives

The DTCG format's killer feature is aliasing: a semantic token can $value-refer a primitive instead of repeating its hex. Then changing the brand scale updates every consumer through one indirection. The format supports it cleanly, though in practice generated files often write literal values so the JSON is readable without a reference resolver.

If your pipeline consumes tokens with a reference engine (Style Dictionary, Tokens Studio), alias-aware files are the goal. If you export for humans with a text editor, literal values are the safer default. What matters is the schema staying spec-shaped so either pipeline can ingest it.

The W3C export in the design system

The full design system generator carries a dedicated W3C Design Tokens export alongside its CSS, Tailwind and shadcn ones. It flattens the whole generated system — semantic tokens for light and dark, typography, spacing, radius — into a design-tokens-w3c.json that matches the interchange shape, and a bundle export packages it with a README for handoff across tools.

The pattern is: CSS variables for the running site, DTCG JSON for the token pipeline, and both generated from the same system so they can never drift.