Authoring design tokens in the DTCG format (2025.10 stable)

What. The Design Tokens Community Group (DTCG) format is the vendor-neutral JSON format for design tokens. Its Format Module reached a first stable version (2025.10) on 28 October 2025 (verified 2026-09-24). Authoring tokens in this shape keeps them portable across Figma plugins, Style Dictionary and platform outputs.

Why. Tokens exist so that a design decision is authored once and referenced everywhere; a standard file format is what lets tools rely on the same definitions at scale. Writing tokens in an ad-hoc JSON shape ties you to one build tool and blocks design-tool sync.

Use when: any new token set; migrating hand-written CSS variables into a build pipeline; exchanging tokens between design and code.

Do not use when: you have three colours and one spacing scale in a throwaway prototype — plain CSS custom properties are fine until a second theme or platform appears.

1. Tokens vs groups. A token is any JSON object with $value; a group is any object without one. Optional $type, $description, $deprecated, $extensions.
2. Type inheritance. Set $type once on a group; children inherit unless they declare their own.
3. Aliases. Reference another token with {path.to.token}; tools resolve chains to a final value and must reject circular references.
4. Typed values (2025.10):

   {
     "color": { "$type": "color",
       "blue": { "600": { "$value": { "colorSpace": "oklch", "components": [0.45, 0.20, 260], "hex": "#2451c9" } } } },
     "space": { "$type": "dimension", "4": { "$value": { "value": 16, "unit": "px" } } },
     "radius": { "$type": "dimension", "md": { "$value": { "value": 6, "unit": "px" } } },
     "motion": { "duration": { "$type": "duration", "base": { "$value": { "value": 200, "unit": "ms" } } } }
   }

   Semantic tier: { "color": { "action": { "primary": { "$value": "{color.blue.600}", "$description": "Primary button background" } } } }.

5. Colour spaces. oklch is one of the natively supported spaces; author new palettes in OKLCH so perceptual lightness is consistent and output to shadcn/Tailwind needs no conversion. Include hex as a fallback for tools that cannot read the object form.
6. Files. Use .tokens.json; split by tier (primitive/, semantic/, component/) and by theme when the semantic tier varies.
7. Deprecation. Mark with "$deprecated": "Use color.action.primary" rather than deleting; remove only after a warn → wait → remove cycle (see sys-versioning-and-deprecation-sequence).
8. Tool status (verified 2026-09-24): Style Dictionary v4 has first-class DTCG support; full 2025.10 support is described as work in progress for v5. Validate your file against the spec version your build tool understands.

• Every token has $value; every group lacks it; a JSON-schema or linter check passes.
• No component file references a primitive token path directly; all references resolve through semantic aliases.
• Colour tokens include colorSpace and components (and hex fallback); dimension tokens use {value, unit}.
• Alias resolution has no cycles (build passes with reference resolution enabled).
• Deprecated tokens carry $deprecated and still build for at least one release.
• The build tool's DTCG version support is recorded in the repo README.

Sources:

• https://www.designtokens.org/tr/drafts/format/
• https://www.w3.org/community/design-tokens/2025/10/28/design-tokens-specification-reaches-first-stable-version/
• https://styledictionary.com/info/dtcg/

• The DTCG spec is a W3C Community Group report, not a W3C Recommendation; tool support for the newest typed values still varies.
• Figma has no confirmed native DTCG import/export in the sources reviewed; the bridge is a plugin (commonly Tokens Studio) or a script.
• Native platforms consume tokens through generated Swift/Kotlin outputs; dynamic type and platform theming still need hand mapping.