product-design-tokens v1.0.0A

Immutable. This exact content never changes and is served at /api/v1/blob/9acb92950147a63f.

---
name: product-design-tokens
description: >-
  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.
metadata:
  summary: "A durable W3C DTCG design-token contract, reusing your design system and enforcing WCAG 2.2 AA contrast"
  author: mgiovani
  version: 1.0.0
disable-model-invocation: true
argument-hint: "<idea | repo path | existing tokens/config> [--with-design-md]"
context: fork
agent: general-purpose
allowed-tools: Read, Write, Edit, Grep, Glob, Bash(git *), Bash(gh *), Bash(python *), Bash(uv run *), Bash(npx *), Task, WebSearch, WebFetch, 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/`.

## 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:

```bash
cp skills/product-design-tokens/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

```bash
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, 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.