frontend-impl-design-tokens

name	frontend-impl-design-tokens
description	Use when structuring a design-token system for a web app or component library, authoring the JSON interchange file per the W3C Design Tokens Community Group format, emitting tokens as CSS custom properties, deciding whether a value belongs at the primitive / semantic / component tier, registering an animatable token via `@property`, wiring up runtime theme switching via `data-theme` attribute or `color-scheme`, or migrating a codebase off hardcoded hex / rgb / oklch literals. Prevents the most common token-system regressions in 2026 : hardcoded color literals scattered across components so a brand refresh requires a twelve-file PR, single-tier flat tokens that map `--color-blue-500` directly to a button background and break the moment the brand picks a new blue, tokens declared in the default cascade layer that get overridden by random component CSS, a transitioned custom property that does not animate because it was never registered via `@property`, raw token names like `--my-bg` that leak into application styles, JSON files that invent their own shape and require rewriting when migrating to a real DTCG-aware tool, and shipping the experimental DTCG draft without disclosing its not-production-ready status. Covers the DTCG Design Tokens Format Module 2025.10 draft (JSON shape, required `$value`, required `$type`, optional `$description`, optional `$extensions` vendor metadata under reverse-DNS keys), the seven base types (`color`, `dimension`, `fontFamily`, `fontWeight`, `duration`, `cubicBezier`, `number`) plus the six composite types (`border`, `shadow`, `transition`, `strokeStyle`, `gradient`, `typography`), the alias syntax `{group.subgroup.token}` that resolves to target `$value`, the three-tier chain (raw brand to primitive to semantic to component), the CSS emission rules (custom properties under `@layer tokens`, `@property` registration for typed and animatable tokens, `light-dark()` for theme-aware swaps, `data-theme` attribute for explicit user override), and the rule that production today MUST transform DTCG JSON via a build pipeline (Style Dictionary, Tokens Studio, or equivalent) because the spec is explicitly NOT production-ready. Keywords: design tokens, DTCG, design tokens community group, W3C, designtokens org, $value, $type, $description, $extensions, alias, primitive token, semantic token, component token, three-tier tokens, CSS custom properties, custom property, var, @property, color, dimension, fontFamily, fontWeight, duration, cubicBezier, number, border, shadow, transition, strokeStyle, gradient, typography, light-dark, color-scheme, data-theme, @layer tokens, Style Dictionary, Tokens Studio, hardcoded hex everywhere, brand change painful, design system fragmented, no single source of truth for colors, theme broken at runtime, magic numbers everywhere, tokens drift, theme switch flashes, what are design tokens, how do I structure design tokens, three-tier token chain, DTCG W3C draft, design tokens to CSS, how to organize CSS variables, how to theme an app
license	MIT
compatibility	Designed for Claude Code. Requires Frontend Design evergreen-2026.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

Frontend Impl : Design Tokens

This skill is the operational reference for designing a token system that follows the W3C Design Tokens Community Group Format Module 2025.10 draft and emits CSS custom properties under cascade layers. It covers the DTCG JSON shape, the seven base types and six composite types, the alias resolution rule, the three-tier brand-to-component chain, the @property registration for animatable tokens, and runtime theme switching. The skill does NOT cover OKLCH palette generation (see [[frontend-theming-color-palette-oklch]]), dark / light mode implementation details (see [[frontend-theming-dark-light-mode]]), or specific tooling deep-dives.

CRITICAL : DTCG draft status (2025.10)

The DTCG Format Module is a W3C Community Group draft preview dated 7 May 2026 and is explicitly NOT production-implementation-ready per the spec preamble. Source : designtokens.org : Format Module draft (verified 2026-05-19).

Implications for production work today :

1. ALWAYS author tokens in the DTCG JSON shape so future migrations are mechanical, not destructive.
2. ALWAYS transform DTCG JSON to CSS custom properties via a build pipeline (Style Dictionary, Tokens Studio export, or a thin custom transformer). Do NOT consume the raw JSON at runtime.
3. ALWAYS pin to the 2025.10 draft revision in your tooling. NEVER expect the format to be stable across draft versions until the spec reaches Candidate Recommendation.
4. Disclose the draft status in any internal documentation that mentions DTCG conformance.

Quick Reference

Floor rules

• ALWAYS tier every token : primitive (raw brand atoms) -> semantic (intent like "action", "feedback success") -> component (button-specific override). NEVER skip the semantic tier and map primitive directly to component.
• ALWAYS emit tokens as CSS custom properties under @layer tokens (or a similar dedicated layer). NEVER declare tokens in the default layer where any component rule can override them.
• ALWAYS register a custom property via @property when it is transitioned, animated, or interpolated. NEVER transition a plain --var ; the property is <custom-ident> by default and only swaps discretely.
• ALWAYS namespace token names with category and intent : --color-fg-action, --space-inline-md, --radius-control-sm. NEVER ship raw names like --my-bg, --blue, .