SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsproduct-design-tokens

product-design-tokens

Design & creation

View repository

Updated 10-16 00:29

About this skill

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/. <skill-dir> below is this skill's directory.

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.

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 or extend it by expressing the existing values as DTCG tokens (alias into them; add only what the change needs), rather than replacing 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 carry the work: 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 <skill-dir>/assets/templates/tokens.dtcg.json docs/specs/design/tokens/tokens.dtcg.json
  • DTCG 2025.10 shape, full detail in 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 as 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 never rely on 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 follow suit: motion uses Material 3 Expressive spring (stiffness/damping), not fixed duration+easing; translucency uses Apple Liquid Glass with a mandatory contrast check. See references/standards.md.

Phase: Validate

python <skill-dir>/scripts/dtcg_validate.py --tokens docs/specs/design/tokens/tokens.dtcg.json
python <skill-dir>/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, and 0 failing pairs is the gate: a pair below its AA threshold is a blocker, so darken/lighten the token and re-run rather than approving a failing or 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, the reuse-vs-greenfield path, and whether a DESIGN.md/alpha layer was produced. Report the written path(s), and recommend the live pipeline (Figma Code Connect → Dev Mode MCP → AI editor → human polish) reconciled against the versioned tokens.dtcg.json, rather than 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, and 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.
  • Building the themed UI → implement-feature.
  • This skill only authors and validates the token contract. Writes no application code.