designagent-cli 0.1.0

package/dist/skills/a11y-check/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: a11y-check
+description: Audit color pairs and touch targets against WCAG AA. Use when reviewing a design system, a screen, or before shipping UI for accessibility.
+reads: [DESIGN.md, CLAUDE.md]
+---
+
+# a11y-check
+
+Audit the project's tokens and UI against WCAG AA and platform accessibility minimums. Output specific, actionable fixes.
+
+## When to use
+Reviewing `DESIGN.md` color pairs, auditing a screen/component, or as a gate before shipping.
+
+## Checks
+
+### Contrast (WCAG AA)
+- For every `on-*` / surface or foreground/background pair in `DESIGN.md`, compute the contrast ratio.
+- **Pass:** ≥4.5:1 for normal text, ≥3:1 for large text (≥24px, or ≥18.66px bold) and meaningful UI/graphics.
+- Report each failing pair with its ratio and a suggested adjusted hex that passes while staying close to the intended hue.
+
+### Touch / click targets
+- iOS: ≥44×44pt. Android: ≥48×48dp. Web: ≥24×24px with adequate spacing.
+- Flag interactive elements below the minimum.
+
+### Non-color signals
+- Flag any state conveyed by color alone (error, success, selection) — require an icon, text, or shape pairing.
+
+### Focus & keyboard
+- Every interactive element must have a visible, non-color-only focus indicator and full keyboard operability.
+
+### Semantics
+- Inputs have labels; icon-only controls have accessible names; meaningful images have alt text; motion respects reduced-motion.
+
+## Process
+1. Parse `DESIGN.md` tokens; enumerate all foreground/background pairings (including component `backgroundColor`/`textColor`).
+2. Compute contrast for each; collect failures.
+3. If auditing code, scan for target sizes, focus styles, labels, and color-only signals.
+4. Output a prioritized fix list: each item = location, the problem, the measured value, and the concrete fix.
+
+## Output contract
+- A table of color pairs with ratios and pass/fail.
+- A prioritized list of fixes (highest impact first).
+- No vague advice — every item names a token/element and a specific change.

package/dist/skills/component-audit/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: component-audit
+description: Scan the codebase for hardcoded values and token drift, cross-reference against DESIGN.md, and produce a prioritized fix list. Use when checking design-system adherence or before a cleanup pass.
+reads: [DESIGN.md, CLAUDE.md, .designagent/config.json]
+---
+
+# component-audit
+
+Find where the code has drifted from the design system and rank the fixes. This is James's killer feature: turn invisible drift into a concrete, prioritized list.
+
+## When to use
+Auditing a codebase for design-system adherence, before a refactor, or to quantify drift for the team.
+
+## Inputs
+1. `DESIGN.md` — the source-of-truth tokens to measure against.
+2. `.designagent/config.json` — frameworks in play (so the scan targets the right files).
+3. The codebase itself.
+
+## What to flag
+- **Hardcoded colors** — hex/rgb/hsl/named CSS colors that match (or nearly match) a `DESIGN.md` color token. Suggest the token.
+- **Magic spacing** — px/rem values off the spacing scale. Suggest the nearest on-scale token.
+- **One-off type** — font sizes/weights not in the typography tokens.
+- **Missing token references** — components that re-declare a value a token already covers.
+- **Orphan values** — colors/sizes that appear once or twice with no token and no pattern (candidates either to tokenize or remove).
+
+## Process
+1. Read `DESIGN.md` tokens into a lookup (color hexes, spacing values, radii, type).
+2. Scan source for literal values (prefer the `@designagent/scanner` drift report if available — it already maps file:line → nearest token).
+3. For each finding, attach: file, line, the literal, the nearest token, and a confidence (exact match vs. approximate).
+4. **Prioritize:** exact-match drift first (mechanical fixes), then near-matches, then orphans. Within each, sort by frequency (most-repeated value = biggest win).
+
+## Output contract
+- A prioritized table: file:line · value · suggested token · confidence.
+- A short summary: total drift, % that are exact-match (auto-fixable), top 3 highest-impact values.
+- Never auto-edit unless asked — this skill reports; fixing is a separate, confirmed step.

package/dist/skills/copywriting/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: copywriting
+description: Write UI copy in the product's brand voice, following platform conventions and any voice guidelines in CLAUDE.md. Use when writing or revising microcopy — labels, buttons, empty states, errors, onboarding.
+reads: [CLAUDE.md, DECISIONS.md]
+---
+
+# copywriting
+
+Write interface copy that sounds like the product and respects the platform.
+
+## When to use
+Drafting or revising microcopy: button labels, form labels and helper text, empty states, error and success messages, tooltips, onboarding, confirmations.
+
+## Inputs
+1. `CLAUDE.md` — product identity and any voice/tone guidance.
+2. `DECISIONS.md` — naming and terminology decisions to stay consistent with.
+3. The surface being written (what the user is doing and what just happened).
+
+## Principles
+- **Clarity over cleverness.** The user is mid-task; say what's true and what to do next.
+- **Voice from the product, not a default.** Match the tone established in `CLAUDE.md`; don't impose generic friendly-startup voice.
+- **Action labels are verbs.** Buttons say what happens ("Save changes", not "OK"). One primary action per surface.
+- **Errors are helpful, not blaming.** What went wrong + how to fix it. No "Oops!" for serious failures.
+- **Consistent terminology.** Reuse the product's nouns (check `DECISIONS.md`); don't call the same thing three names.
+- **Platform conventions.** Respect iOS HIG / Android / web norms for casing, punctuation, and standard terms.
+
+## Process
+1. Read the voice guidance and existing terminology first.
+2. For each string: state the user's goal and context, then write the shortest copy that's clear and on-voice.
+3. Provide 1–2 alternatives for key strings (e.g. the primary CTA) when tone could reasonably vary.
+4. Check length against the UI — labels must fit their controls.
+
+## Output contract
+- The copy, mapped to each UI element/state.
+- Terminology consistent with `DECISIONS.md`; flag any new term introduced so it can be recorded.
+- Note platform-specific variants when the copy differs across iOS/Android/web.

package/dist/skills/design-review/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: design-review
+description: Review a screen or component against DESIGN.md tokens and CLAUDE.md craft principles, and return a structured critique with specific fixes. Use when reviewing UI work before it ships.
+reads: [DESIGN.md, CLAUDE.md, DECISIONS.md]
+---
+
+# design-review
+
+Review UI against the project's own standards — not generic taste. Output a structured, fixable critique.
+
+## When to use
+Reviewing a component, screen, or PR for design quality before it merges.
+
+## Inputs
+1. `CLAUDE.md` — the craft principles and "Do not" list to review against.
+2. `DESIGN.md` — exact token values.
+3. `DECISIONS.md` — prior rationale that may justify an apparent "violation".
+4. The component/screen (code, and a screenshot if available).
+
+## Review dimensions (score each, with specific fixes)
+- **Hierarchy** — is the primary action clear? One focal point per view? Size/weight/color used intentionally?
+- **Spacing** — on the scale? Consistent rhythm? Related things grouped, unrelated things separated?
+- **Color** — role tokens used correctly (`primary` for primary action, `on-*` on surfaces)? No raw values?
+- **Typography** — named type tokens only? Sensible scale steps? Readable measure/line-height?
+- **Accessibility** — AA contrast, focus states, target sizes, semantics (defer detail to `a11y-check`).
+- **Consistency** — matches existing components and `DECISIONS.md`? No reinvented primitives?
+
+## Process
+1. Read the standards first (`CLAUDE.md`, `DESIGN.md`), then the work.
+2. Check each dimension; cite the exact token or principle a finding relates to.
+3. Before flagging an inconsistency, check `DECISIONS.md` — it may be deliberate.
+4. Separate **must-fix** (violates a token/principle/AA) from **consider** (subjective polish).
+
+## Output contract
+- Per-dimension findings, each with: what, where, why it matters, and the specific fix (name the token/value).
+- A short verdict: ship / ship-with-fixes / needs-work.
+- No vague advice ("improve spacing") — always name the token or value to change.

package/dist/skills/design-to-code/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: design-to-code
+description: Turn a design intent, screenshot, or canvas node into production code for this project's framework(s), using DESIGN.md tokens. Use when implementing UI from a design, mockup, or description.
+reads: [DESIGN.md, CLAUDE.md, DECISIONS.md, .designagent/config.json]
+frameworks: [react, vue, svelte, react-native, swiftui, compose]
+---
+
+# design-to-code
+
+Translate design intent into production code that respects the project's token system and conventions.
+
+## When to use
+Implementing a screen/component from a screenshot, a canvas node, a description, or a redline — for any framework configured in this project.
+
+## Inputs to read first
+1. `.designagent/config.json` — the configured framework(s), design system, and canvas.
+2. `DESIGN.md` — exact token values (colors, typography, spacing, rounded, components).
+3. `CLAUDE.md` — framework conventions and the "Do not" list.
+4. `DECISIONS.md` — prior rationale that constrains the implementation.
+
+## Process
+1. **Identify the target framework** from config. If multiple, ask which target (or generate the shared token layer plus the requested platform).
+2. **Decompose** the design into the smallest reusable primitives. Reuse existing components before creating new ones.
+3. **Map every visual value to a token.** Color → color token, spacing → spacing scale, radius → rounded, text → typography token. If a value has no token, add it to `DESIGN.md`, lint, then use it. Never emit a raw hex/size/spacing literal that a token covers.
+4. **Emit framework-idiomatic output:**
+   - **React / Vue / Svelte** → components using Tailwind utilities or CSS variables exported via `npx @google/design.md export --format css-tailwind DESIGN.md`.
+   - **React Native** → `StyleSheet.create` referencing token constants; handle `Platform.OS` differences.
+   - **SwiftUI** → a `DesignTokens.swift` (Color/Font extensions) bridge + `View` code using semantic colors, SF Symbols, Dynamic Type. Modifier order: content → layout → background → overlay → accessibility.
+   - **Jetpack Compose** → a `Theme.kt`/`Tokens.kt` (Material 3 `ColorScheme` + token objects) + composables reading `MaterialTheme.*`, with `modifier` params and slot APIs.
+5. **Accessibility pass:** labels, focus/keyboard, contrast (AA), touch targets (44pt iOS / 48dp Android / 24px web). Run `a11y-check` if available.
+6. **Self-review** against `CLAUDE.md` principles and the "Do not" list. Record any non-obvious decision in `DECISIONS.md`.
+
+## Output contract
+- Tokenized, idiomatic, accessible code for the requested framework.
+- A short note of which tokens were used and any new tokens added to `DESIGN.md`.
+- No hardcoded values that duplicate a token.
+
+## Note on mobile
+There is no automated Swift/Kotlin token exporter in `@google/design.md` yet, so this skill generates the bridge file (`DesignTokens.swift` / `Theme.kt`) directly from `DESIGN.md`. Keep that file as the single source the views read from, and regenerate it when tokens change.

package/dist/skills/redlines/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: redlines
+description: Generate a precise implementation spec (redlines) from a component — dimensions, spacing, colors, type, and states — expressed in token names, framework-aware. Use when handing a component to engineering or documenting it.
+reads: [DESIGN.md, CLAUDE.md, .designagent/config.json]
+---
+
+# redlines
+
+Produce an exact, build-ready spec for a component, expressed in tokens rather than raw values.
+
+## When to use
+Documenting a component for handoff or its own spec sheet — the inverse of `design-to-code`.
+
+## Inputs
+1. The component (code and/or a canvas node).
+2. `DESIGN.md` — to express every measurement as a token, not a literal.
+3. `.designagent/config.json` — framework, so the spec's code references match the target.
+
+## What to specify
+- **Layout** — width/height behavior (fill vs. hug), alignment, internal direction.
+- **Spacing** — padding and gaps as spacing tokens (`spacing.md`), not px.
+- **Color** — background/text/border as color tokens (`colors.surface`, `colors.on-surface`).
+- **Shape** — corner radius as a `rounded.*` token; border width.
+- **Typography** — the named type token per text element.
+- **States** — default / hover / focus / active / disabled / loading, each as token deltas from default.
+- **Accessibility** — target size, focus ring, contrast notes, required labels.
+
+## Process
+1. Inspect the component; resolve every concrete value back to its nearest `DESIGN.md` token (flag any that don't map — that's drift to fix first).
+2. Lay out the spec per element, then per state.
+3. Express measurements in token names; include the resolved value in parentheses for reference.
+4. Match output format to the framework (e.g. SwiftUI modifier names, Tailwind utilities, Compose params).
+
+## Output contract
+- A structured spec: element → property → token (resolved value), then a states table.
+- Accessibility notes inline.
+- Anything that can't be expressed as a token is called out as drift, not silently hardcoded.

package/dist/skills/token-namer/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: token-namer
+description: Rename heuristic/auto-generated color tokens (e.g. accent-4, color-1) to semantic, role-based names in DESIGN.md — done by Claude Code itself, no API key needed. Use right after `designagent init` or whenever DESIGN.md has non-semantic color names.
+reads: [DESIGN.md, DECISIONS.md, .designagent/config.json]
+---
+
+# token-namer
+
+Give a reverse-engineered design system **good names** — the "taste" step. The scanner extracts real colors but can only guess names heuristically (`primary`, `secondary`, or fallbacks like `accent-4`). You — the Claude Code already running in this project — assign semantic, role-based names. This needs **no external API and no API key**: it's your judgment, applied to the user's own session.
+
+## When to use
+- Immediately after `designagent init` generated `DESIGN.md`.
+- Whenever `DESIGN.md` contains non-semantic color names (`accent-N`, `color-N`, `neutral-N`) or names that don't match how the color is actually used.
+
+## What "good" looks like
+Role-based, lowercase, kebab-case, matching `/^[a-z][a-z0-9-]*$/` (never start with a digit — required for Tailwind v4 export). Prefer these roles where they fit:
+`primary`, `secondary`, `tertiary`, `neutral`, `surface`, `on-surface`, `on-primary`, `outline`, `muted`, `accent`, `error`, `success`, `warning`, `info`.
+
+## Process
+1. Read `DESIGN.md` colors. For each, note its hex, usage count (if present), and how it's actually used in the codebase (grep the source: backgrounds → `surface`, body text → `on-surface`, the most-used saturated brand color → `primary`, destructive/error states → `error`, borders → `outline`).
+2. Propose a semantic name per token. Resolve collisions (two colors both "primary" → `primary` + `secondary`/`accent`). Keep already-good names.
+3. **Rewrite `DESIGN.md`**: rename the color keys AND update every `{colors.<old>}` reference (components, etc.) to the new name. Don't orphan a reference.
+4. **Lint:** `npx @google/design.md lint DESIGN.md` — must be 0 errors. Fix any digit-leading or duplicate names.
+5. **Export-check:** `npx @google/design.md export --format css-tailwind DESIGN.md` must succeed (catches invalid token names).
+6. Record the rename map (old → new) in `DECISIONS.md` with today's date, so the rationale is preserved.
+
+## Output contract
+- `DESIGN.md` with semantic color names, all references updated, lints + exports clean.
+- A `DECISIONS.md` entry listing the renames and the reasoning.
+- Never invent colors or change hex values — this is naming only.
+
+## Note
+For non-interactive/CI use where there's no Claude Code session, `designagent <cmd> --ai` does the same naming via a direct Anthropic API call (needs `ANTHROPIC_API_KEY`). In normal interactive use this skill is preferred — it's free and uses the session you already have open.

package/dist/skills/token-sync/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: token-sync
+description: Pull design tokens from the canvas (Figma / Pencil / OpenPencil) into DESIGN.md and record the diff. Use when the canvas changed and DESIGN.md needs to catch up.
+reads: [DESIGN.md, .designagent/config.json]
+requires: [figma-mcp OR pencil-mcp OR .pen file]
+---
+
+# token-sync
+
+Keep `DESIGN.md` in sync with the design canvas, then lint and record what changed.
+
+## When to use
+The canvas (Figma variables, a Pencil/OpenPencil file) changed and `DESIGN.md` should reflect it — or you want to seed `DESIGN.md` from an existing canvas.
+
+## Source by canvas (read from `.designagent/config.json`)
+- **Figma** → read variables/styles via the Figma Dev Mode MCP. Map collections to `colors`, `typography`, `spacing`, `rounded`.
+- **Pencil / OpenPencil** → parse the `.pen` JSON; extract token definitions.
+
+## Process
+1. Read the configured canvas from `.designagent/config.json`.
+2. Pull tokens from the canvas source.
+3. **Map to DESIGN.md schema** — preserve existing token names where they match; map canvas naming to role tokens (`primary`, `on-surface`, …). Don't rename tokens that already exist unless the canvas clearly supersedes them.
+4. **Write the merge** into `DESIGN.md`, keeping markdown prose sections intact.
+5. **Lint:** `npx @google/design.md lint DESIGN.md` — fix any errors before finishing.
+6. **Diff:** `npx @google/design.md diff <old> DESIGN.md` to capture token-level changes and regressions.
+7. **Record:** append a dated entry to `DECISIONS.md` summarizing what changed (added/removed/changed tokens) and why, if known.
+
+## Output contract
+- Updated `DESIGN.md` that lints clean.
+- A diff summary of token changes.
+- A timestamped `DECISIONS.md` entry.
+- Never overwrite prose sections or silently drop tokens — report removals.

package/dist/templates/claude-md/base.md

@@ -0,0 +1,95 @@
+# {{PROJECT_NAME}} — Design Agent Briefing
+
+> Generated by [designagent](https://designagent.dev). This file is Claude Code's design brain for this project.
+> Edit it freely — it is yours now. Re-run `designagent update` to pull in template improvements.
+
+## Project
+
+- **Name:** {{PROJECT_NAME}}
+- **Canvas:** {{CANVAS}}
+- **Design system:** {{DESIGN_SYSTEM}}
+- **Framework(s):** {{FRAMEWORKS}}
+- **Tokens:** `DESIGN.md` (machine-readable, linted via `@google/design.md`)
+- **Decisions:** `DECISIONS.md` (the why behind the what)
+
+When you start work, read `DESIGN.md` for exact token values and `DECISIONS.md` for prior rationale. Treat both as the source of truth over anything you infer from existing code.
+
+## How to use the three files
+
+| File | Question it answers | Authority |
+|---|---|---|
+| `DESIGN.md` | *What* are the exact values? | Tokens — colors, type, spacing, components |
+| `CLAUDE.md` (this file) | *How* do we build? | Craft, conventions, agent behavior |
+| `DECISIONS.md` | *Why* is it this way? | History and rationale |
+
+If `DESIGN.md` and code disagree, `DESIGN.md` wins — flag the drift. If a request conflicts with `DECISIONS.md`, surface the prior decision before overriding it.
+
+## Design principles
+
+- **Tokens over literals.** Never hardcode a hex value, font size, or spacing number that exists in `DESIGN.md`. Reference the token. If a needed value is missing, add it to `DESIGN.md` first, then use it.
+- **Hierarchy is deliberate.** Size, weight, and color carry meaning. One primary action per view. Secondary actions recede. Don't make everything bold.
+- **Spacing is a system, not a guess.** Use the spacing scale (`xs`…`xxl`). Multiples of the base unit only — no `13px`, no `7px`.
+- **Type scale is closed.** Use the named typography tokens (`headline-*`, `body-*`, `label-*`). Don't invent one-off sizes.
+- **Color carries semantics.** `primary` for primary action, `error` for destructive/error, `on-*` for content that sits on a surface. Never pick a raw color when a role token fits.
+- **Restraint reads as quality.** Fewer borders, fewer shadows, fewer competing accents. Whitespace is a feature.
+
+## Token reference
+
+Exact values live in `DESIGN.md`. Resolve token references (e.g. `{colors.primary}`) against that file. To see resolved output for this stack, run:
+
+```
+npx @google/design.md export --format css-tailwind DESIGN.md   # Tailwind v4 @theme
+npx @google/design.md export --format dtcg DESIGN.md           # W3C Design Tokens
+```
+
+Before relying on `DESIGN.md`, confirm it lints clean:
+
+```
+npx @google/design.md lint DESIGN.md
+```
+
+## Canvas
+
+{{CANVAS_BLOCK}}
+
+## Accessibility
+
+- **Contrast:** WCAG AA minimum — 4.5:1 for body text, 3:1 for large text (≥24px or ≥18.66px bold) and meaningful UI/graphics. Verify every `on-*` token against its surface.
+- **Focus:** Every interactive element has a visible, non-color-only focus state.
+- **Targets:** Touch targets ≥44×44pt (iOS) / 48×48dp (Android); ≥24×24px clickable on web with adequate spacing.
+- **Semantics:** Real semantic elements/roles, labels for inputs, alt text for meaningful images, respects reduced-motion.
+- **Don't rely on color alone** to convey state — pair with icon, text, or shape.
+
+## Agent instructions
+
+When given a design task:
+
+1. **Read first.** `DESIGN.md` (values) → `DECISIONS.md` (rationale) → the relevant existing component.
+2. **Reuse before creating.** Search for an existing component/token that fits. Extend it before adding a new one.
+3. **Work in tokens.** Express every color/space/type choice as a token reference. If you must introduce a value, add the token to `DESIGN.md`, lint, then use it.
+4. **State your design reasoning briefly** when making a non-obvious choice — then record meaningful decisions in `DECISIONS.md`.
+5. **Self-review against this file** before declaring done: hierarchy, spacing system, token usage, accessibility, and the "Do not" list below.
+6. **Lint after touching tokens.** Run `npx @google/design.md lint DESIGN.md` and fix any errors.
+
+## Skills
+
+Installed under `~/.designagent/skills/`. Invoke when relevant:
+
+- **token-namer** — rename heuristic color tokens (e.g. `accent-4`) to semantic, role-based names. No API key — you do this with your own judgment.
+- **design-to-code** — turn a design intent, screenshot, or canvas node into production code for this project's framework(s), using `DESIGN.md` tokens.
+- **a11y-check** — audit color pairs and touch targets against WCAG AA.
+- **token-sync** — pull tokens from the canvas into `DESIGN.md` and record the diff.
+
+## First run
+
+If `DESIGN.md` was reverse-engineered by `designagent init`, its color names may be heuristic (`accent-4`, `neutral-2`). On your first session in this project, run the **token-namer** skill to give them semantic, role-based names — then everything downstream (components, drift suggestions, docs) reads cleanly. This is free: it's your judgment on the session already open, no API key required.
+
+## Do not
+
+- Do not hardcode hex colors, rgb/hsl literals, or named CSS colors — use color tokens.
+- Do not use magic spacing numbers — use the spacing scale.
+- Do not invent font sizes — use the typography tokens.
+- Do not add a new component when an existing one can be composed or extended.
+- Do not ship contrast below WCAG AA.
+- Do not edit `DESIGN.md` to a state that fails lint.
+- Do not silently override a recorded decision — reference and update `DECISIONS.md`.

package/dist/templates/claude-md/compose.md

@@ -0,0 +1,21 @@
+## Jetpack Compose conventions
+
+Target: **Jetpack Compose (Android)**. There is no automated Kotlin exporter yet — the `design-to-code` skill reads `DESIGN.md` and generates a `Theme.kt` / `Tokens.kt` (a Material 3 `MaterialTheme` wiring + token objects) plus composables. Keep that as the single bridge between tokens and UI.
+
+### Tokens in Kotlin
+- Map `DESIGN.md` colors into a Material 3 `ColorScheme` (`primary`, `onPrimary`, `surface`, `onSurface`, `error`, …) and read them via `MaterialTheme.colorScheme.*` in composables — never inline `Color(0xFF...)`.
+- Typography → `MaterialTheme.typography.*` built from the `DESIGN.md` type tokens. Spacing → a `Dimens`/`Spacing` object of `Dp` constants. No magic `.dp` literals.
+- Provide light and dark `ColorScheme`s; support dynamic color (Android 12+) only if it doesn't break brand tokens.
+
+### Composables
+- `@Composable` functions are `PascalCase`, UI-only, side-effect-free in the composition path. Hoist state — pass values down, events up.
+- Every composable takes a `modifier: Modifier = Modifier` as its first optional param and applies it to the root. **Modifier order matters** (it's applied outside-in): size/padding → background → clip → clickable → semantics.
+- Prefer **slot APIs** (`content: @Composable () -> Unit`) over many boolean flags for layout flexibility.
+
+### Material 3
+- Use M3 components (`Button`, `Card`, `Scaffold`, `TopAppBar`) and tokens rather than rebuilding them. Follow M3 elevation/state-layer conventions.
+- Touch targets ≥48×48dp. Respect `LocalAccessibilityManager` and reduced-motion preferences.
+- Content descriptions on every meaningful `Icon`/`Image`; decorative ones get `contentDescription = null`.
+
+### Previews
+- `@Preview` for light + dark (`uiMode`) and a font-scale variant for the key composables.

package/dist/templates/claude-md/monorepo.md

@@ -0,0 +1,9 @@
+## Cross-platform strategy
+
+This project targets multiple frameworks ({{FRAMEWORKS}}). `DESIGN.md` is the **single source of truth** for all of them — one token set, many outputs.
+
+- **One token layer.** All targets derive from the same `DESIGN.md`. Web reads exported CSS variables; React Native reads `StyleSheet` constants; SwiftUI/Compose read generated token files. Never let a platform fork its own values.
+- **Shared semantics, platform-idiomatic output.** A token named `primary` stays `primary` everywhere; only its rendered form differs (CSS var vs. `Color.primary` vs. `MaterialTheme.colorScheme.primary`).
+- **Naming parity.** Keep token names identical across platforms so a change in `DESIGN.md` maps 1:1 to every target.
+- **When a value must diverge per platform** (e.g. elevation, motion), record why in `DECISIONS.md` and keep both under the same token name with platform notes.
+- **Regenerate, don't hand-edit** exported/generated token files — change `DESIGN.md` and re-export so platforms never drift.

package/dist/templates/claude-md/react.md

@@ -0,0 +1,25 @@
+## React conventions
+
+Target: **React** ({{DESIGN_SYSTEM}}). Design tokens reach components as Tailwind v4 CSS variables — generate them with `npx @google/design.md export --format css-tailwind DESIGN.md` into your global stylesheet's `@theme`.
+
+### Components
+- Function components only. Named exports, one component per file, `PascalCase.tsx`.
+- Props are a typed `interface` named `<Component>Props`. No `any`. Prefer discriminated unions over boolean prop soup.
+- Compose, don't configure: small primitives (`Button`, `Card`, `Stack`) combined over one mega-component with 15 props.
+- Co-locate: component, its variants, and its types in one file unless shared.
+
+### Styling
+- Use Tailwind utilities mapped to tokens — `bg-primary`, `text-on-surface`, `rounded-md`, `p-md`. Never arbitrary values (`p-[13px]`, `bg-[#1A1C1E]`) when a token utility exists.
+- Class order: layout → box model → typography → visual → state/variants. Keep it consistent; let Prettier/tailwind plugin sort if present.
+- Conditional classes via `clsx`/`cn` — no string concatenation.
+- No inline `style={{}}` for anything that maps to a token.
+
+### State & data
+- Local state with `useState`/`useReducer`. Lift only when shared. Reach for context/store only when prop-drilling genuinely hurts.
+- Side effects belong in `useEffect`/event handlers, not render. Keep render pure.
+- Derive, don't duplicate: compute from props/state instead of mirroring into more state.
+
+### Accessibility in JSX
+- Semantic elements first (`button`, `a`, `nav`, `label`). Reach for ARIA only to fill gaps.
+- Every input has an associated `label`. Icon-only buttons get `aria-label`.
+- Keyboard: interactive custom elements handle Enter/Space and show a focus ring.

package/dist/templates/claude-md/swiftui.md

@@ -0,0 +1,22 @@
+## SwiftUI conventions
+
+Target: **SwiftUI (iOS)**. There is no automated Swift exporter yet — the `design-to-code` skill reads `DESIGN.md` and generates a `DesignTokens.swift` (Color/Font extensions) plus view code. Keep that generated file as the single bridge between tokens and views.
+
+### Tokens in Swift
+- Map `DESIGN.md` colors to `Color` extension statics (`Color.primary`, `Color.onSurface`) and typography to `Font` helpers or a `Text` modifier set. Views reference those — never inline `Color(hex:)` or `.font(.system(size: 17))`.
+- Spacing → a `Spacing` enum/struct of `CGFloat` constants from the scale. No magic padding numbers.
+- Asset catalog colors should mirror the token names so Dynamic Color (light/dark) works.
+
+### Views
+- Small composable views; extract subviews once a `body` grows past a screen. Computed `var`s or `@ViewBuilder` funcs for repeated chunks.
+- **Modifier order matters** and is conventional: content → layout (`frame`, `padding`) → background/clip → overlay → accessibility → gesture. Apply `.padding` before `.background` so the background includes the padding.
+- Prefer SF Symbols (`Image(systemName:)`) over bundled icons; size with `.imageScale`/`.font`, never hardcoded frames where a symbol scale fits.
+
+### iOS HIG
+- Respect Dynamic Type: use semantic text styles or scalable fonts; don't pin to fixed point sizes. Test the largest accessibility size.
+- Support light and dark via asset-catalog/semantic colors — no hardcoded light-only hex.
+- Honor safe areas, standard navigation patterns, and `@Environment(\.accessibilityReduceMotion)` for animations.
+- Touch targets ≥44×44pt.
+
+### Previews
+- Every view ships a `#Preview` covering light + dark and at least one large Dynamic Type size.

package/dist/templates/design-md/custom.md

@@ -0,0 +1,138 @@
+---
+name: {{PROJECT_NAME}}
+version: alpha
+description: Design tokens for {{PROJECT_NAME}}. Opinionated neutral scaffold — replace every value with your own.
+colors:
+  primary: "#111827"
+  on-primary: "#FFFFFF"
+  secondary: "#374151"
+  on-secondary: "#FFFFFF"
+  tertiary: "#4B5563"
+  on-tertiary: "#FFFFFF"
+  neutral: "#6B7280"
+  surface: "#FFFFFF"
+  on-surface: "#111827"
+  error: "#B91C1C"
+  on-error: "#FFFFFF"
+  outline: "#D1D5DB"
+typography:
+  headline-display:
+    fontFamily: system-ui
+    fontSize: 3rem
+    fontWeight: 700
+    lineHeight: 1.1
+  headline-lg:
+    fontFamily: system-ui
+    fontSize: 2.25rem
+    fontWeight: 700
+    lineHeight: 1.15
+  headline-md:
+    fontFamily: system-ui
+    fontSize: 1.5rem
+    fontWeight: 600
+    lineHeight: 1.25
+  body-lg:
+    fontFamily: system-ui
+    fontSize: 1.125rem
+    fontWeight: 400
+    lineHeight: 1.6
+  body-md:
+    fontFamily: system-ui
+    fontSize: 1rem
+    fontWeight: 400
+    lineHeight: 1.6
+  body-sm:
+    fontFamily: system-ui
+    fontSize: 0.875rem
+    fontWeight: 400
+    lineHeight: 1.5
+  label-lg:
+    fontFamily: system-ui
+    fontSize: 0.875rem
+    fontWeight: 500
+    lineHeight: 1.4
+  label-md:
+    fontFamily: system-ui
+    fontSize: 0.75rem
+    fontWeight: 500
+    lineHeight: 1.4
+  label-sm:
+    fontFamily: system-ui
+    fontSize: 0.6875rem
+    fontWeight: 500
+    lineHeight: 1.3
+spacing:
+  xs: 4px
+  sm: 8px
+  md: 16px
+  lg: 24px
+  xl: 32px
+  xxl: 48px
+rounded:
+  none: 0px
+  sm: 4px
+  md: 8px
+  lg: 12px
+  xl: 16px
+  full: 9999px
+components:
+  button-primary:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.on-primary}"
+    rounded: "{rounded.md}"
+    padding: 12px
+  button-secondary:
+    backgroundColor: "{colors.secondary}"
+    textColor: "{colors.on-secondary}"
+    rounded: "{rounded.md}"
+    padding: 12px
+  card:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.on-surface}"
+    rounded: "{rounded.lg}"
+    padding: 16px
+  input:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.on-surface}"
+    rounded: "{rounded.sm}"
+    padding: 8px
+---
+
+## Overview
+
+A neutral, opinionated starting point for **{{PROJECT_NAME}}**. Every value here is a placeholder with a sensible default — replace the palette, type, and component tokens with your own, then run:
+
+```
+npx @google/design.md lint DESIGN.md
+```
+
+## Colors
+
+Role-based tokens with `on-*` foregrounds. Start by setting `primary` to your brand color and checking `on-primary` contrast.
+
+## Typography
+
+`system-ui` so it renders everywhere with no font loading. Swap in your typeface across the scale when ready.
+
+## Layout
+
+4px-based spacing scale. Keep all spacing on-scale.
+
+## Elevation & Depth
+
+Define your shadow language here. Start flat; add elevation only where it communicates layering.
+
+## Shapes
+
+Corner radii from `none` to `full`. Pick a default radius for your brand and apply it consistently.
+
+## Components
+
+Token-composed primitives to extend. Add components as your system grows — always referencing tokens, never raw values.
+
+## Do's and Don'ts
+
+- **Do** replace these defaults with real brand values.
+- **Do** keep contrast at WCAG AA.
+- **Don't** leave placeholder values in production.
+- **Don't** hardcode values that belong in a token.