product-design-tokens
Skill8 starsChanged 52 days agoMITView on GitHub
Authors a durable design-token contract: a W3C DTCG 2025.10 JSON file ($value/$type, {group.token.path} aliases) as the canonical source, adopting the project's existing design system first and enforcing WCAG 2.2 AA contrast (never meaning by colour alone). An optional Google-Labs DESIGN.md alpha layer is version-pinned, runtime-probed, and always paired with the DTCG JSON. Use for "define our design tokens", "create a DTCG token file", or "set up our colour palette with contrast checks". Not for the screen structure (use product-design-spec), a UX/accessibility critique (use review-design), or generating logo/hero art (use codex-imagegen). Writes no application code.
In this repository53 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- agent-browserSkill
- anything-to-skillSkill
- ci-generateSkill
- ci-localSkill
- clotho-researchSkill
- codex-imagegenSkill
- create-ruleSkill
- create-skillSkill
- db-migrateSkill
- docker-initSkill
- docs-adrSkill
- docs-checkSkill
- docs-diagramSkill
- docs-initSkill
- docs-rfcSkill
- docs-updateSkill
- env-setupSkill
- find-skillsSkill
- fix-bugSkill
- git-commitSkill
- git-create-prSkill
- gitflowSkill
- git-releaseSkill
- git-syncSkill
- i18n-checkSkill
- implement-featureSkill
- improve-skillSkill
- inject-docsSkill
- jira-cliSkill
- motion-studioSkill
- optimize-ai-setupSkill
- orchestrateSkill
- oss-launchSkill
- prd-to-issuesSkill
- product-design-specSkill
- product-prdSkill
- project-illustratorSkill
- project-plannerSkill
- refactorSkill
- renderSkill
- review-codeSkill
- review-depsSkill
- review-designSkill
- review-perfSkill
- review-planSkill
- review-securitySkill
- shipSkill
- stopslopSkill
- test-suiteSkill
- vrt-checkSkill
- wtfSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 3 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 33
Read the source first: an existing repo (scan for a design system before anything else), a design spec / screen inventory from …
- Very specific: line 42
Run the detection inline, sequentially, with Grep/Glob/Read.
- Very specific: line 47
Default to a single docs/specs/design/tokens/tokens.dtcg.json.
- Distinctive: line 51
If the request implies a large tree (multi-brand × multi-theme × per-component tokens for dozens of components), stop and ask before …
- Distinctive: line 63
Only with genuinely no system present do you seed a new core palette.
- Distinctive: line 86
Create the single canonical file from the skeleton and fill it:
- Very specific: line 136
Never invent colour-psychology claims or approve a palette that fails contrast or carries meaning by colour alone.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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:
- Detect an existing design system: scan for
tailwind.config.*, shadcn (components.json,@/components/ui), MUI theme, CSS custom properties, or a native platform system. - 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.
- 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
basepalette, then asemanticlayer 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 theSkilltool 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 keeptokens.dtcg.jsonalongside 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.jsondtcg_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.pybefore declaring done. - Target WCAG 2.2 AA explicitly; do not introduce WCAG 3.0 / APCA.
- The
@google/design.mdCLI 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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

