agentleFS
mgiovanimgiovani/cc-arsenal/skills/product-design-tokens/SKILL.md

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.

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
  1. Very specific:

    Read the source first: an existing repo (scan for a design system before anything else), a design spec / screen inventory from …

    line 33
  2. Very specific:

    Run the detection inline, sequentially, with Grep/Glob/Read.

    line 42
  3. Very specific:

    Default to a single docs/specs/design/tokens/tokens.dtcg.json.

    line 47
  4. Distinctive:

    If the request implies a large tree (multi-brand × multi-theme × per-component tokens for dozens of components), stop and ask before …

    line 51
  5. Distinctive:

    Only with genuinely no system present do you seed a new core palette.

    line 63
  6. Distinctive:

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

    line 86
  7. Very specific:

    Never invent colour-psychology claims or approve a palette that fails contrast or carries meaning by colour alone.

    line 136

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.