Product Design Tokens

Product Design Tokens

Produce the token contract a themed UI is built from: a valid, WCAG-checked DTCG 2025.10 JSON file that stays the single source of truth. This skill writes no application code and never draws assets; it authors and validates the tokens. Output lands under docs/specs/design/tokens/.

Input

$ARGUMENTS

Read the source first: an existing repo (scan for a design system before anything else), a design spec / screen inventory from product-design-spec, a brand brief, or a plain idea. --with-design-md also emits the optional alpha DESIGN.md prose layer.

Prerequisites & fallback

Sibling skills are invoked via the Skill tool where available; with no Skill tool, apply the named sibling's documented rules inline (each delegation below states the fallback in-sentence). Design-system detection uses the Task tool with an Explore/haiku subagent; no Task tool? Run the detection inline, sequentially, with Grep/Glob/Read. The optional @google/design.md CLI is probed at runtime, never assumed: the DTCG JSON is emitted whether or not it runs.

Lean by default

Default to a single docs/specs/design/tokens/tokens.dtcg.json. Split a layer (semantic, component) into its own file only when it outgrows the single file. contrast-report.md sits alongside it; DESIGN.md only when asked.

• Cost stop-condition: if the request implies a large tree (multi-brand × multi-theme × per-component tokens for dozens of components), stop and ask before emitting it: scope it down or confirm the tree first. Never auto-generate a 30-file token set.

Reuse first (top of the ladder)

Inventing a brand from scratch is the last resort, greenfield-only. Before writing any token:

1. Detect an existing design system: scan for tailwind.config.*, shadcn (components.json, @/components/ui), MUI theme, CSS custom properties, or a native platform system.
2. Adopt / extend it: express the existing values as DTCG tokens (alias into them; add only what the change needs). Do not replace a working system with a new invented palette.
3. Only with genuinely no system present do you seed a new core palette.

State which path you took in one line.

Workflow

Four phases: Detect → Draft → Validate → Hand off.

Phase: Detect

Scan the repo for an existing design system (spawn an Explore/haiku agent, or do it inline):

Task (Explore, haiku): "Find this repo's design system: tailwind.config.*, components.json / shadcn
ui dir, MUI theme, CSS custom properties (:root { --... }), or a native platform system. Return the
tool, the token values found (colour/spacing/radius/type), and the file paths, invent nothing."

Decide reuse vs. greenfield from what you find. If a spec from product-design-spec is present, read its screen inventory so the semantic tokens cover what the screens actually render.

Phase: Draft

Create the single canonical file from the skeleton and fill it:

cp skills/product-design-tokens/assets/templates/tokens.dtcg.json docs/specs/design/tokens/tokens.dtcg.json

• DTCG 2025.10 shape (full detail: references/standards.md): a token is any object with a $value; groups carry an inheritable $type; aliases are {group.token.path}. Pin to https://www.designtokens.org/tr/2025.10/: never /tr/drafts/.
• Layer the colours: a primitive base palette, then a semantic layer that aliases it (UI consumes semantic). OKLCH is fine for exploration, but export an sRGB/hex-compatible value.
• Status colours are never colour-alone (WCAG 1.4.1): annotate each to pair with an icon/label.
• Brand art that informs the palette goes to codex-imagegen (produce the prompt; don't draw the asset here: via the Skill tool where available, else write the prompt for the user to run).
• DESIGN.md is optional and derived. Only with --with-design-md: probe the CLI at runtime, pin the alpha version in its frontmatter, add the ALPHA banner, and always keep tokens.dtcg.json alongside as canonical (template: assets/templates/DESIGN.md).
• Platform tokens: motion → Material 3 Expressive spring (stiffness/damping), not fixed duration+easing; translucency → Apple Liquid Glass with a mandatory contrast check. See references/standards.md.

Phase: Validate

python skills/product-design-tokens/scripts/dtcg_validate.py --tokens docs/specs/design/tokens/tokens.dtcg.json
python skills/product-design-tokens/scripts/contrast.py       --tokens docs/specs/design/tokens/tokens.dtcg.json

• dtcg_validate.py must print VALID (every token has a resolvable $type, every alias resolves, no cycles). Fix any error before proceeding.
• contrast.py writes the contrast table: 0 failing pairs is the gate. A pair below its AA threshold is a blocker: darken/lighten a token and re-run; never approve a failing or a colour-alone palette. Save its output to docs/specs/design/tokens/contrast-report.md.
• In-context accessibility sign-off (the palette rendered in real screens) goes to review-design for the WCAG 2.2 AA audit (via the Skill tool where available, otherwise apply its WCAG 2.2 AA checklist, the 9 criteria new since 2.1 in references/standards.md, inline).

Phase: Hand off

• State the single readiness verdict: DTCG VALID, contrast 0 failures, reuse-vs-greenfield path, and whether a DESIGN.md/alpha layer was produced.
• Report the written path(s). Recommend the live pipeline (Figma Code Connect → Dev Mode MCP → AI editor → human polish) reconciled against the versioned tokens.dtcg.json, not a one-shot handoff export. Name the downstream consumer: implement-feature builds the themed UI from these.

Anti-hallucination

• Reuse before invent: scan for an existing design system before proposing any new brand token.
• Pin DTCG to /tr/2025.10/, never /tr/drafts/; the DTCG JSON is always the canonical source: DESIGN.md is never the sole record.
• Never invent colour-psychology claims or approve a palette that fails contrast or carries meaning by colour alone. Run contrast.py before declaring done.
• Target WCAG 2.2 AA explicitly; do not introduce WCAG 3.0 / APCA.
• The @google/design.md CLI and its subcommands are probed at runtime, never assumed; pin the version you generated against.

References

• references/standards.md: DTCG 2025.10 (stable URL), WCAG 2.2 AA + the 9 new-since-2.1 criteria (3.0/APCA excluded), Material 3 Expressive, Apple Liquid Glass, DSDS (emerging/unendorsed), the live handoff pipeline.
• assets/templates/: tokens.dtcg.json (canonical skeleton), DESIGN.md (optional alpha), contrast-report.md.
• scripts/dtcg_validate.py · scripts/contrast.py

Boundaries

• Screen structure, flows, and states → product-design-spec.
• The requirements themselves → product-prd.
• Auditing an existing/rendered design's UX or accessibility → review-design.
• Rendering the actual logo / hero / mascot art → codex-imagegen (or nanobanana).
• Building the themed UI → implement-feature.
• This skill only authors and validates the token contract. Writes no application code.