Claude Skill

design-planner

Establishes visual design language and screen contracts between project scope docs and phase-planner. Produces docs/design/DESIGN.md (Google design.md spec), screen specs, HTML mockups (screens/*.html + index hub), and design-system.md for phase-builder. Use when the user wants t

LLM Mart · 0 points · 1 views 99 listing impressions 0 install-command copies
Download ayejk-phase-runner-plugin_skills_design-planner-bdf60f6.zip · 28 KB

Install

skills CLI npx skills add https://github.com/AyeJK/phase-runner/tree/main/plugin/skills/design-planner
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install ayejk-phase-runner@llmmart
Git git clone https://github.com/AyeJK/phase-runner.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole ayejk/phase-runner collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Design Planner

Establishes visual language and screen contracts after a scope/rebuild plan and before phase-planner. Output feeds phase-planner (screen references in sprints) and phase-builder (design-system.md for UI implementation and wave-test asserts).

Pipeline position:

product-planner plan or scope doc (what/why/architecture)
    → design-planner (this skill)
    → phase-planner (sprints)
    → phase-builder (build)

Not this skill: Architecture, API design, sprint breakdown, or implementation. Use scope docs + phase-planner + phase-builder for those. product-planner plans the product, and its wireframes fix layout and flow only. It is not a substitute for this step: a plan with UI Mockups comes here next, and phase-planner stops on one that has no design pass.

For file templates, token schema, and screen-spec format, see reference.md.

The build reads the files. Everything this skill decides lives under docs/design/, and that is all phase-planner and phase-builder ever read. In a session whose Artifact tool lists a Design System type, Step 7 also publishes the design system as a Design System artifact. Where it lists a Design type, Step 6 also publishes the screen mockups as artboards on one Design canvas. A published design can then be changed in two places: on its page, or in the files by asking in chat. Design sync copies each change to the other side without asking, so there is one design, not two: a screen's file on disk is its artboard on the canvas, and design-system.md is the design system's README. It runs at the start of every run of this skill, after every change this skill makes, before phase-planner creates a phase and before phase-builder starts a build. In a session without that tool the skill writes the same files and skips every artifact step. Mechanics are in artifacts.md and design-sync.md.


Step 1 — Resolve project layout

Run once at the start. Same rules as phase-builder's project-layout.md — read that file if this project also uses phase-builder, otherwise resolve directly:

Path Role
workspace_root Folder containing docs/ — design artifacts live here
app_root Folder with the stack manifest and src/ (often a subfolder like {name}-app/)

Design output paths (all under workspace_root):

File Purpose
docs/design/DESIGN.md Canonical agent contract — Google design.md spec
docs/design/design-system.md Expanded patterns — phase-builder reads this path
docs/design/screens/*.md Per-surface screen specs (acceptance criteria for phase-planner)
docs/design/screens/*.html Reviewable HTML mockups — one per screen + index.html hub
docs/design/screens/_theme.css Shared styles for the mockups — this project's own visual direction, established in Step 4

Report layout before writing:

Design pass layout:
  workspace_root: {path}
  app_root:       {path}
  scope input:    {path to scope doc or "conversation"}

If docs/design/ doesn't exist, create it and docs/design/screens/ under workspace_root. No setup script is needed first.

If docs/design/DESIGN.md records a published artifact, run Design sync (design-sync.md) first, before reading or changing anything else, so a change made on the page is in the files.

If docs/design/ already exists, read all files before editing. Preserve locked decisions unless the user asks to revise.


Step 2 — Read inputs

Read in order:

  1. Scope doc — user path or pasted plan (e.g. a rebuild plan or product spec under docs/). Extract product name, audience, UI surfaces mentioned, hard UX rules, stack (web framework, desktop shell, etc.). With no path given, use the newest docs/Plan-*.html from product-planner if there is one, and say which file you picked. Its UI Mockups section lists the screens; take layout and flow from the wireframes, never visual style.
  2. Project convention docs — CLAUDE.md / README.md / equivalent, for terminology and conventions the project already uses (many products have their own vocabulary for core concepts — use whatever the scope doc or existing docs establish, don't invent new terms).
  3. Existing design — docs/design/*, root DESIGN.md, prior prototypes.
  4. App context — skim app_root's manifest file, existing routes/components if UI already exists. Note what to extend vs. replace.

Do not re-interview on facts already in the scope doc. Ask only for gaps that block design decisions.


Step 3 — Surface inventory

Produce a table before any visual work. Save it inside docs/design/DESIGN.md under ## Surfaces (extension section — allowed by design.md spec) or as a standalone docs/design/surface-inventory.md when the list is long.

Surface Route / shell Phase Priority Notes
{e.g. Settings — Profile editor} /settings/profile 2 P0
Modal / full-screen 1 P0

Scope rule: Spec surfaces for near-term phases only (typically Phase 1–3). Defer Phase 4+ to a later design pass unless the user explicitly asks.

Present the inventory to the user. Confirm missing surfaces or wrong priorities before locking direction.


Step 4 — Design direction

Commit one aesthetic direction before writing tokens. If a frontend/visual-direction skill is available in this environment, read its design-thinking guidance for the direction workshop and apply its purpose/tone/constraints/differentiation framing to this product, not generic SaaS. If no such skill is available, run the workshop yourself using the same framing: what's the product's purpose, tone, and what should differentiate it visually from competitors.

Present 2–3 directions

Each direction is a short card:

  • Name — a short evocative label for this direction
  • One-line mood
  • Type + color posture — fonts, light/dark, accent strategy
  • Fit — why it matches the product thesis
  • Risk — what it makes harder

Ask the user to pick one, blend two, or describe a reference (site, app, image). Do not lock tokens until they confirm.

Multi-surface products

When surfaces have different jobs (e.g. a control-panel shell vs. a public-facing web app), either:

  • One system, two modes — shared tokens + mode overrides in YAML (e.g. colors.panel-* vs colors.public-*), or
  • Split design passes — one pass per surface family (run skill twice)

State the choice in DESIGN.md Overview.

Optional prototypes

If direction is ambiguous, write one static HTML file to docs/design/prototypes/{name}.html using the chosen direction. Inline CSS only. Present it to the user for review. Prototypes are throwaway — tokens in DESIGN.md are the contract once approved.


Step 5 — Write DESIGN.md

Write docs/design/DESIGN.md following the Google design.md spec. See reference.md for the full template.

Requirements:

  1. YAML front matter — name, version: alpha, token groups: colors, typography, spacing, rounded, components (minimum: primary button + one input), in the shapes reference.md gives under "The token shapes the linter reads"
  2. Body sections in spec order: Overview → Colors → Typography → Layout → Elevation & Depth → Shapes → Components → Do's and Don'ts
  3. Prose matches tokens — every accent color in prose exists in YAML; tokens are normative
  4. Product-specific Do's and Don'ts — translate scope UX rules (e.g. "never show blocking error dialogs" → explicit component behavior)
  5. Terminology — use whatever project-specific terms the scope doc or existing docs already established; don't introduce new ones here
  6. Keep the artifact lines — if the existing DESIGN.md has a Design system artifact: {url} line (written by Step 7) or a Design canvas: {url} line (written by Step 6) under its title, every rewrite keeps them as they are

After writing, run lint when available:

npx -p @google/design.md designmd lint docs/design/DESIGN.md

Use the designmd command as written. The package's other command is named design.md, and on Windows npx @google/design.md lint opens that file in a text editor and hangs instead of running.

If lint reports errors, fix them before proceeding. Read the warnings: fix the ones that point at a real gap, and leave the two reference.md lists as expected. If the CLI is unavailable or doesn't answer within a minute or so, stop waiting and self-check against the reference.md checklist.

Optional: Copy or symlink to {workspace_root}/DESIGN.md when the user wants root-level discovery — note both paths in the handoff.


Step 6 — Write screen specs + HTML mockups

For each P0/P1 surface, create both:

  1. Markdown spec — docs/design/screens/{kebab-name}.md (acceptance criteria for phase-builder)
  2. HTML mockup — docs/design/screens/{kebab-name}.html (visual review for the user)

Use the templates in reference.md. Shared styles live in docs/design/screens/_theme.css (tokens, panels, buttons — reuse from an existing repo if this is a rebuild).

Also write docs/design/screens/index.html — hub linking all mockups.

Each markdown spec must include:

  • Route or shell type
  • Purpose (one sentence)
  • Layout wireframe (ASCII or structured blocks)
  • Component list (names matching DESIGN.md)
  • States matrix — empty, loading, error, success, edge cases from scope doc
  • Copy rules — labels, empty states, forbidden phrases
  • Acceptance bullets — observable checks for phase-builder Verification.assert
  • Preview: link to sibling .html mockup

Each HTML mockup must:

  • Render real tokens from DESIGN.md (not generic wireframe gray boxes)
  • Label interactive regions
  • Take its shared look from _theme.css, with screen-specific styles only when needed

Which form a mockup takes. It depends on whether the project has, or is about to get, a Design canvas:

Session Form
The Artifact tool lists a Design type, or DESIGN.md already records a canvas The canvas's own form (artifacts.md, Screen file form): the file on disk is the artboard, sent as it is. It carries a copy of _theme.css's rules and has no review bar
Anything else The plain form in reference.md: links _theme.css, with a fixed review bar (screen name, phase, link back to index.html). A later session that can publish converts it once, in place

Link each spec from DESIGN.md ## Surfaces table (Spec + Preview columns).

Do not duplicate token tables in screen specs — reference DESIGN.md sections instead.

Publish the Design canvas

Do this after the mockups and index.html are written, and only if the session's Artifact tool lists a Design type. If it doesn't — no Artifact tool, or no such type — skip this section: Step 6 ends at the files above, as it always has, and nothing later depends on the canvas. If DESIGN.md records a canvas from an earlier session, leave the line alone: the next sync in a session that can publish sends this run's changes.

The canvas shows every mockup as an artboard, laid out in rows, using the project's Design System artifact so its Theme menu shows the project's tokens by name. Each artboard is the mockup's own file, uploaded as it is: nothing is converted on the way up, and a screen edited on the canvas comes back down into the same file (Design sync). The files still open from disk.

  1. Look for a recorded canvas. DESIGN.md's header (the lines directly under its title) records one as Design canvas: {url}.
  2. Wait for the design system if it isn't published yet. The canvas installs the project's Design System artifact, which Step 7 publishes. If DESIGN.md's header has no Design system artifact: line and this session can publish one, go on to Step 7 now and come back to this section when its publish is done, before Step 8. If the header already has the line, publish the canvas here.
  3. No canvas line: first run. Create one Design canvas named {Product Name} — Screens, and write its URL into DESIGN.md's header (Design canvas: {url}) and into screens/index.html before filling it. A mockup still in the plain form is converted in place first.
  4. Line present: later run. Revise the canvas at that URL. Never create a second one. Design sync already ran in Step 1, so a screen changed on the canvas is in its file. Send only the screen files this run changed (all of them when _theme.css changed), add an artboard for a new one, and remove the artboard of a deleted one. If the URL can't be opened or edited, tell the user and ask what to do.
  5. Fill it per artifacts.md: exactly one artboard per HTML mockup, each titled with its screen spec's name; app and web screens as fluid pages, phone screens at 390×844; rows by phase or surface family with a title note per row; the first P0 screen as the entry; and the project's Design System artifact installed.
  6. Run the canvas checks in artifacts.md before publishing.
  7. Write the sync record (design-sync.md).
  8. Give the user the link.

If there is no Design System artifact to install (its publish failed, or the session lists no Design System type), publish the canvas without it, tell the user its Theme menu will show plain values for now, and install the system on the first later run that finds it recorded.

A publish that fails doesn't fail the design pass. The mockups on disk are the review fallback: report what happened and carry on.


Step 7 — Seed design-system.md

Write or update docs/design/design-system.md. This is the operational doc phase-builder injects into UI implementation and wave-test.

Structure:

  1. Header — last updated, links to DESIGN.md, optional HTML gallery path
  2. Design intent — condensed from Overview (table of principles)
  3. Design tokens — CSS custom properties derived from YAML (copy-paste ready :root block)
  4. Typography scale — table mapping elements → tokens
  5. Core component patterns — ASCII + class/CSS conventions for buttons, inputs, cards, modals used in screen specs
  6. UI copy — voice rules for visible strings
  7. Screen index — table linking surface → spec file → route

Source-of-truth rule:

File Role
DESIGN.md Locked tokens + rationale — edit in design pass
design-system.md Expanded patterns — grows during early UI sprints; token changes must trace back to DESIGN.md
Design System artifact (when published) The same two files on a page: its README is design-system.md, its tokens are DESIGN.md's. A change on either side is copied to the other by Design sync

When both files exist and conflict on token values, DESIGN.md wins — update design-system.md to match. When the artifact and the files differ, Design sync settles it: the side that changed since the last sync is copied to the other, and the user is asked only when the same thing changed on both.

Publish the Design System artifact

Do this after both files are written, and only if the session's Artifact tool lists a Design System type. If it doesn't — no Artifact tool, or no such type — skip this section: Step 7 ends at the two files, as it always has, and nothing later depends on the artifact. If DESIGN.md records a system from an earlier session, leave the line alone: the next sync in a session that can publish sends this run's changes.

  1. Look for a recorded system. DESIGN.md's header is the lines directly under its # {Product Name} — Design System title, one per published artifact. A published system is recorded there as Design system artifact: {url}.
  2. No line: first run. Create one Design System artifact named after the product, and write Design system artifact: {url} into DESIGN.md's header before filling it.
  3. Line present: later run. Revise the system at that URL. Never create a second one. Design sync already ran in Step 1, so an edit made on the page is in the files. If the URL can't be opened or edited, tell the user and ask what to do.
  4. Fill it per artifacts.md: DESIGN.md's tokens, each with the same value it has in the YAML; design-system.md as its README; a cover; and its index, written last. No components.
  5. Run the artifact checks in artifacts.md before publishing.
  6. Write the sync record (design-sync.md).
  7. Give the user the link.

A publish that fails doesn't fail the design pass. The files are complete; report what happened and go on.

Then the canvas. If Step 6 left the Design canvas waiting for this system, publish it now (Step 6, "Publish the Design canvas"), whether or not the system's publish succeeded. If a canvas is already recorded and this step republished the system with changed tokens, revise the canvas so its installed copy of the tokens matches. Then go on to Step 8.


Step 8 — Handoff

Present saved paths and the review hub:

Design pass complete.

Review mockups (open in browser):
  docs/design/screens/index.html

Artifacts:
  docs/design/DESIGN.md
  docs/design/design-system.md
  docs/design/screens/*.md + *.html

Next steps:

1. **Generate phase plans** — hand off to phase-planner:
   "Use docs/design/ and {scope doc path}. Generate phase plans.
    UI sprints must reference screen spec paths in the Reference column.
    Verification assert lines should come from screen spec acceptance bullets."

2. **Iterate** — revise direction, add a screen, or update tokens in DESIGN.md

With a Design canvas. When DESIGN.md's header records a canvas, give its link alongside the hub, as a second line under "Review mockups":

Review mockups (open in browser):
  docs/design/screens/index.html
  Design canvas: {url}

Tell the user they can change the design on the canvas and the design system page, or by asking in chat, and that either way the files follow: the change is picked up before the next design change, before a phase is planned and before a build starts. With no canvas recorded, the handoff is the block above, unchanged. The phase-planner handoff still names docs/design/ paths, never an artifact link.

If the user asks to proceed immediately, read the phase-planner skill and generate phase plans using design artifacts as constraints.

Phase-planner constraints (include in handoff)

When invoking phase-planner, require:

  • UI task Reference column → docs/design/screens/{file}.md
  • Sprint Verification assert: lines → from screen spec acceptance bullets
  • No visual invention in task descriptions — "implement per screen spec"
  • Data-only sprints → skip-ui: true; no design references needed

Operations (iteration)

User says Action
"revise direction" / "new aesthetic" Re-run Step 4 → rewrite DESIGN.md tokens + design-system.md; flag screen specs that need layout updates
"add screen for X" New screens/*.md; update screen index in design-system.md
"update tokens" / "change accent" Edit DESIGN.md YAML + prose → sync design-system.md CSS block
"sync design-system from DESIGN" Regenerate token/CSS sections from DESIGN.md; preserve component patterns
"design pass report" List surfaces specced vs. deferred; lint status; files changed
"sync the design" / "I changed it on the canvas" Design sync (below)

Use targeted edits. One write pass per operation when possible.

Sync before and after a change. When DESIGN.md's header records an artifact, every operation in this table starts with Design sync, so it edits files that already hold what was changed on the page. After the operation, send what it changed: DESIGN.md or design-system.md to the Design System artifact (Step 7, later run), a screen file or _theme.css to the canvas (Step 6, later run). In a session that can't publish, finish the operation and say nothing more: the next sync in a session that can publish sends the change.

Design sync

Copies what changed on a published page into the files, and what changed in the files onto the page, since the last time they matched. The whole procedure is in design-sync.md: what counts as the same on both sides, the sync record that tells which side changed, and what to do with each change.

  • It doesn't ask. A change on one side is copied to the other. The user is asked only when the same screen or token was changed on both sides, or when a screen was removed from the canvas.
  • It says what it copied, in one short block, and nothing when there was nothing to copy.
  • A screen changed on the canvas updates its spec too. The screen file is replaced by the canvas's version and the lines of its spec the change touches are brought up to date, so phase-planner and phase-builder read a spec that matches the mockup.
  • When it runs: at the start of every run of this skill (Step 1), before and after any operation above, before phase-planner creates a phase, before phase-builder starts a build, and when the user asks for it.

Integration map

Skill / tool When
Scope doc Input — product/architecture only
design-planner This skill — visual language + screens
phase-planner Sprints — references screen specs
phase-builder Build — reads design-system.md; wave-test asserts against it
A frontend-design-style skill, if available Direction workshop + optional prototypes only — not production UI
A ui-pattern skill, if available Implementation patterns during phase-builder — loses to project design docs
product-planner The step before this one — product plan and wireframes, no visual design. Its plan is a valid scope doc
Artifact tool with a Design System type, if the session has one Step 7 publishes the design system; Design sync keeps its page and the files the same. No skill builds from the artifact
Artifact tool with a Design type, if the session has one Step 6 publishes the mockups as artboards on one canvas; Design sync keeps each artboard and its screen file the same. No skill builds from the canvas

Quality checks before finishing

  • User confirmed design direction (Step 4)

  • DESIGN.md has valid YAML + all required body sections (or omitted with reason)

  • Lint passes or manual checklist complete

  • Every P0/P1 surface has a screen spec and HTML mockup with link from spec

  • docs/design/screens/index.html hub links all mockups

  • design-system.md exists with CSS tokens aligned to DESIGN.md

  • Scope UX hard rules appear in Do's and Don'ts

  • No sprint/task breakdown in design artifacts (that's phase-planner's job)

  • Artifacts saved under workspace_root/docs/design/, not inside app_root unless user explicitly uses single-folder layout

  • If a Design System artifact was published: its URL is in DESIGN.md's header, every DESIGN.md token is in it with the same value, and it passes the type's own checks — every token has a usage note, and text contrast is at least 4.5:1 in every theme (full list in artifacts.md)

  • If a Design canvas was published: its URL is in DESIGN.md's header and in screens/index.html, it has exactly one artboard per HTML mockup, each titled with its screen spec's name, the project's design system is installed on it, and each artboard is its screen file under docs/design/screens/, byte for byte (full list in artifacts.md)

  • If either was published or revised: docs/design/.sync.json records it as it is now

The last three checks apply only when this session published or revised that artifact. With no Artifact tool, or without the type listed, they are skipped, not failed.


Anti-patterns

  • Skipping direction confirmation — locking tokens without user pick → rework in every UI sprint
  • Specifying all future phases — over-design before validation
  • HTML monolith plan — that's product-planner; use markdown screen specs instead
  • Tokens only in design-system.md — DESIGN.md must exist as the portable agent contract
  • Generic AI aesthetics — a default sans-serif + purple gradient unless the product explicitly calls for it
  • Implementing production components in this skill — prototypes are static HTML only; code ships in phase-builder
  • Pointing the build at an artifact — handing phase-planner or phase-builder an artifact link. They read docs/design/; Design sync is what puts a page edit there
  • Two versions of a screen — keeping a plain mockup beside its artboard, or converting on the way up. Once a project has a canvas, the screen file on disk is the artboard
  • Asking which side wins — the sync record says which side changed. Ask only when both did
Files (phase-runner)
  • artifacts.md 38.3 KB
    Loading…
  • design-sync.md 9.3 KB
    Loading…
  • reference.md 6.7 KB
    Loading…
  • SKILL.md 25.5 KB
    ---
    name: design-planner
    description: "Establishes visual design language and screen contracts between project scope docs and phase-planner. Produces docs/design/DESIGN.md (Google design.md spec), screen specs, HTML mockups (screens/*.html + index hub), and design-system.md for phase-builder. Use when the user wants to design UI before phase planning, lock a design system, write screen specs, review HTML mockups, or run the design pass after a scope/rebuild plan. Trigger phrases: design pass, design-planner, design the UI, design system, DESIGN.md, screen specs, visual direction, before phase planner."
    ---
    
    # Design Planner
    
    Establishes **visual language and screen contracts** after a scope/rebuild plan and **before** phase-planner. Output feeds phase-planner (screen references in sprints) and phase-builder (`design-system.md` for UI implementation and wave-test asserts).
    
    **Pipeline position:**
    
    ```
    product-planner plan or scope doc (what/why/architecture)
        → design-planner (this skill)
        → phase-planner (sprints)
        → phase-builder (build)
    ```
    
    **Not this skill:** Architecture, API design, sprint breakdown, or implementation. Use scope docs + phase-planner + phase-builder for those. `product-planner` plans the product, and its wireframes fix layout and flow only. It is not a substitute for this step: a plan with UI Mockups comes here next, and phase-planner stops on one that has no design pass.
    
    For file templates, token schema, and screen-spec format, see [reference.md](reference.md).
    
    **The build reads the files.** Everything this skill decides lives under `docs/design/`, and that is all phase-planner and phase-builder ever read. In a session whose Artifact tool lists a Design System type, Step 7 also publishes the design system as a Design System artifact. Where it lists a Design type, Step 6 also publishes the screen mockups as artboards on one Design canvas. A published design can then be changed in two places: on its page, or in the files by asking in chat. **Design sync** copies each change to the other side without asking, so there is one design, not two: a screen's file on disk is its artboard on the canvas, and `design-system.md` is the design system's README. It runs at the start of every run of this skill, after every change this skill makes, before phase-planner creates a phase and before phase-builder starts a build. In a session without that tool the skill writes the same files and skips every artifact step. Mechanics are in [artifacts.md](artifacts.md) and [design-sync.md](design-sync.md).
    
    ---
    
    ## Step 1 — Resolve project layout
    
    Run once at the start. Same rules as phase-builder's `project-layout.md` — read that file if this project also uses phase-builder, otherwise resolve directly:
    
    | Path | Role |
    |------|------|
    | **workspace_root** | Folder containing `docs/` — design artifacts live here |
    | **app_root** | Folder with the stack manifest and `src/` (often a subfolder like `{name}-app/`) |
    
    **Design output paths (all under workspace_root):**
    
    | File | Purpose |
    |------|---------|
    | `docs/design/DESIGN.md` | Canonical agent contract — Google [design.md](https://github.com/google-labs-code/design.md) spec |
    | `docs/design/design-system.md` | Expanded patterns — **phase-builder reads this path** |
    | `docs/design/screens/*.md` | Per-surface screen specs (acceptance criteria for phase-planner) |
    | `docs/design/screens/*.html` | **Reviewable HTML mockups** — one per screen + `index.html` hub |
    | `docs/design/screens/_theme.css` | Shared styles for the mockups — this project's own visual direction, established in Step 4 |
    
    Report layout before writing:
    
    ```
    Design pass layout:
      workspace_root: {path}
      app_root:       {path}
      scope input:    {path to scope doc or "conversation"}
    ```
    
    If `docs/design/` doesn't exist, create it and `docs/design/screens/` under `workspace_root`. No setup script is needed first.
    
    If `docs/design/DESIGN.md` records a published artifact, run **Design sync** ([design-sync.md](design-sync.md)) first, before reading or changing anything else, so a change made on the page is in the files.
    
    If `docs/design/` already exists, read all files before editing. Preserve locked decisions unless the user asks to revise.
    
    ---
    
    ## Step 2 — Read inputs
    
    Read in order:
    
    1. **Scope doc** — user path or pasted plan (e.g. a rebuild plan or product spec under `docs/`). Extract product name, audience, UI surfaces mentioned, hard UX rules, stack (web framework, desktop shell, etc.). With no path given, use the newest `docs/Plan-*.html` from product-planner if there is one, and say which file you picked. Its UI Mockups section lists the screens; take layout and flow from the wireframes, never visual style.
    2. **Project convention docs** — `CLAUDE.md` / `README.md` / equivalent, for terminology and conventions the project already uses (many products have their own vocabulary for core concepts — use whatever the scope doc or existing docs establish, don't invent new terms).
    3. **Existing design** — `docs/design/*`, root `DESIGN.md`, prior prototypes.
    4. **App context** — skim `app_root`'s manifest file, existing routes/components if UI already exists. Note what to extend vs. replace.
    
    Do not re-interview on facts already in the scope doc. Ask only for gaps that block design decisions.
    
    ---
    
    ## Step 3 — Surface inventory
    
    Produce a table before any visual work. Save it inside `docs/design/DESIGN.md` under `## Surfaces` (extension section — allowed by design.md spec) or as a standalone `docs/design/surface-inventory.md` when the list is long.
    
    | Surface | Route / shell | Phase | Priority | Notes |
    |---------|---------------|-------|----------|-------|
    | {e.g. Settings — Profile editor} | `/settings/profile` | 2 | P0 | {any notable constraint} |
    | {e.g. Onboarding overlay} | Modal / full-screen | 1 | P0 | {any notable constraint} |
    
    **Scope rule:** Spec surfaces for **near-term phases only** (typically Phase 1–3). Defer Phase 4+ to a later design pass unless the user explicitly asks.
    
    Present the inventory to the user. Confirm missing surfaces or wrong priorities before locking direction.
    
    ---
    
    ## Step 4 — Design direction
    
    Commit one aesthetic direction before writing tokens. If a frontend/visual-direction skill is available in this environment, read its design-thinking guidance for the direction workshop and apply its purpose/tone/constraints/differentiation framing to **this product**, not generic SaaS. If no such skill is available, run the workshop yourself using the same framing: what's the product's purpose, tone, and what should differentiate it visually from competitors.
    
    ### Present 2–3 directions
    
    Each direction is a short card:
    
    - **Name** — a short evocative label for this direction
    - **One-line mood**
    - **Type + color posture** — fonts, light/dark, accent strategy
    - **Fit** — why it matches the product thesis
    - **Risk** — what it makes harder
    
    Ask the user to pick one, blend two, or describe a reference (site, app, image). **Do not lock tokens until they confirm.**
    
    ### Multi-surface products
    
    When surfaces have different jobs (e.g. a control-panel shell vs. a public-facing web app), either:
    
    - **One system, two modes** — shared tokens + mode overrides in YAML (e.g. `colors.panel-*` vs `colors.public-*`), or
    - **Split design passes** — one pass per surface family (run skill twice)
    
    State the choice in `DESIGN.md` Overview.
    
    ### Optional prototypes
    
    If direction is ambiguous, write **one** static HTML file to `docs/design/prototypes/{name}.html` using the chosen direction. Inline CSS only. Present it to the user for review. Prototypes are throwaway — tokens in `DESIGN.md` are the contract once approved.
    
    ---
    
    ## Step 5 — Write DESIGN.md
    
    Write `docs/design/DESIGN.md` following the Google design.md spec. See [reference.md](reference.md) for the full template.
    
    **Requirements:**
    
    1. **YAML front matter** — `name`, `version: alpha`, token groups: `colors`, `typography`, `spacing`, `rounded`, `components` (minimum: primary button + one input), in the shapes [reference.md](reference.md) gives under "The token shapes the linter reads"
    2. **Body sections** in spec order: Overview → Colors → Typography → Layout → Elevation & Depth → Shapes → Components → Do's and Don'ts
    3. **Prose matches tokens** — every accent color in prose exists in YAML; tokens are normative
    4. **Product-specific Do's and Don'ts** — translate scope UX rules (e.g. "never show blocking error dialogs" → explicit component behavior)
    5. **Terminology** — use whatever project-specific terms the scope doc or existing docs already established; don't introduce new ones here
    6. **Keep the artifact lines** — if the existing DESIGN.md has a `Design system artifact: {url}` line (written by Step 7) or a `Design canvas: {url}` line (written by Step 6) under its title, every rewrite keeps them as they are
    
    After writing, run lint when available:
    
    ```bash
    npx -p @google/design.md designmd lint docs/design/DESIGN.md
    ```
    
    Use the `designmd` command as written. The package's other command is named `design.md`, and on Windows `npx @google/design.md lint` opens that file in a text editor and hangs instead of running.
    
    If lint reports errors, fix them before proceeding. Read the warnings: fix the ones that point at a real gap, and leave the two [reference.md](reference.md) lists as expected. If the CLI is unavailable or doesn't answer within a minute or so, stop waiting and self-check against the [reference.md](reference.md) checklist.
    
    **Optional:** Copy or symlink to `{workspace_root}/DESIGN.md` when the user wants root-level discovery — note both paths in the handoff.
    
    ---
    
    ## Step 6 — Write screen specs + HTML mockups
    
    For each P0/P1 surface, create **both**:
    
    1. **Markdown spec** — `docs/design/screens/{kebab-name}.md` (acceptance criteria for phase-builder)
    2. **HTML mockup** — `docs/design/screens/{kebab-name}.html` (visual review for the user)
    
    Use the templates in [reference.md](reference.md). Shared styles live in `docs/design/screens/_theme.css` (tokens, panels, buttons — reuse from an existing repo if this is a rebuild).
    
    Also write **`docs/design/screens/index.html`** — hub linking all mockups.
    
    Each markdown spec must include:
    
    - Route or shell type
    - Purpose (one sentence)
    - Layout wireframe (ASCII or structured blocks)
    - Component list (names matching DESIGN.md)
    - **States matrix** — empty, loading, error, success, edge cases from scope doc
    - Copy rules — labels, empty states, forbidden phrases
    - **Acceptance bullets** — observable checks for phase-builder `Verification.assert`
    - **Preview:** link to sibling `.html` mockup
    
    Each HTML mockup must:
    
    - Render real tokens from DESIGN.md (not generic wireframe gray boxes)
    - Label interactive regions
    - Take its shared look from `_theme.css`, with screen-specific styles only when needed
    
    **Which form a mockup takes.** It depends on whether the project has, or is about to get, a Design canvas:
    
    | Session | Form |
    |---------|------|
    | The Artifact tool lists a Design type, or DESIGN.md already records a canvas | The canvas's own form ([artifacts.md](artifacts.md), Screen file form): the file on disk is the artboard, sent as it is. It carries a copy of `_theme.css`'s rules and has no review bar |
    | Anything else | The plain form in [reference.md](reference.md): links `_theme.css`, with a fixed review bar (screen name, phase, link back to `index.html`). A later session that can publish converts it once, in place |
    
    Link each spec from DESIGN.md `## Surfaces` table (Spec + Preview columns).
    
    Do not duplicate token tables in screen specs — reference `DESIGN.md` sections instead.
    
    ### Publish the Design canvas
    
    Do this after the mockups and `index.html` are written, and only if the session's Artifact tool lists a **Design** type. If it doesn't — no Artifact tool, or no such type — skip this section: Step 6 ends at the files above, as it always has, and nothing later depends on the canvas. If DESIGN.md records a canvas from an earlier session, leave the line alone: the next sync in a session that can publish sends this run's changes.
    
    The canvas shows every mockup as an artboard, laid out in rows, using the project's Design System artifact so its Theme menu shows the project's tokens by name. Each artboard is the mockup's own file, uploaded as it is: nothing is converted on the way up, and a screen edited on the canvas comes back down into the same file (Design sync). The files still open from disk.
    
    1. **Look for a recorded canvas.** DESIGN.md's header (the lines directly under its title) records one as `Design canvas: {url}`.
    2. **Wait for the design system if it isn't published yet.** The canvas installs the project's Design System artifact, which Step 7 publishes. If DESIGN.md's header has no `Design system artifact:` line and this session can publish one, go on to Step 7 now and come back to this section when its publish is done, before Step 8. If the header already has the line, publish the canvas here.
    3. **No canvas line: first run.** Create one Design canvas named `{Product Name} — Screens`, and write its URL into DESIGN.md's header (`Design canvas: {url}`) and into `screens/index.html` before filling it. A mockup still in the plain form is converted in place first.
    4. **Line present: later run.** Revise the canvas at that URL. Never create a second one. Design sync already ran in Step 1, so a screen changed on the canvas is in its file. Send only the screen files this run changed (all of them when `_theme.css` changed), add an artboard for a new one, and remove the artboard of a deleted one. If the URL can't be opened or edited, tell the user and ask what to do.
    5. **Fill it per [artifacts.md](artifacts.md):** exactly one artboard per HTML mockup, each titled with its screen spec's name; app and web screens as fluid pages, phone screens at 390×844; rows by phase or surface family with a title note per row; the first P0 screen as the entry; and the project's Design System artifact installed.
    6. **Run the canvas checks** in [artifacts.md](artifacts.md) before publishing.
    7. **Write the sync record** ([design-sync.md](design-sync.md)).
    8. **Give the user the link.**
    
    If there is no Design System artifact to install (its publish failed, or the session lists no Design System type), publish the canvas without it, tell the user its Theme menu will show plain values for now, and install the system on the first later run that finds it recorded.
    
    A publish that fails doesn't fail the design pass. The mockups on disk are the review fallback: report what happened and carry on.
    
    ---
    
    ## Step 7 — Seed design-system.md
    
    Write or update `docs/design/design-system.md`. This is the **operational doc phase-builder injects** into UI implementation and wave-test.
    
    Structure:
    
    1. Header — last updated, links to `DESIGN.md`, optional HTML gallery path
    2. **Design intent** — condensed from Overview (table of principles)
    3. **Design tokens** — CSS custom properties derived from YAML (copy-paste ready `:root` block)
    4. **Typography scale** — table mapping elements → tokens
    5. **Core component patterns** — ASCII + class/CSS conventions for buttons, inputs, cards, modals used in screen specs
    6. **UI copy** — voice rules for visible strings
    7. **Screen index** — table linking surface → spec file → route
    
    **Source-of-truth rule:**
    
    | File | Role |
    |------|------|
    | `DESIGN.md` | Locked tokens + rationale — edit in design pass |
    | `design-system.md` | Expanded patterns — grows during early UI sprints; token changes must trace back to `DESIGN.md` |
    | Design System artifact (when published) | The same two files on a page: its README is `design-system.md`, its tokens are DESIGN.md's. A change on either side is copied to the other by Design sync |
    
    When both files exist and conflict on token values, **DESIGN.md wins** — update design-system.md to match. When the artifact and the files differ, **Design sync settles it**: the side that changed since the last sync is copied to the other, and the user is asked only when the same thing changed on both.
    
    ### Publish the Design System artifact
    
    Do this after both files are written, and only if the session's Artifact tool lists a **Design System** type. If it doesn't — no Artifact tool, or no such type — skip this section: Step 7 ends at the two files, as it always has, and nothing later depends on the artifact. If DESIGN.md records a system from an earlier session, leave the line alone: the next sync in a session that can publish sends this run's changes.
    
    1. **Look for a recorded system.** DESIGN.md's header is the lines directly under its `# {Product Name} — Design System` title, one per published artifact. A published system is recorded there as `Design system artifact: {url}`.
    2. **No line: first run.** Create one Design System artifact named after the product, and write `Design system artifact: {url}` into DESIGN.md's header before filling it.
    3. **Line present: later run.** Revise the system at that URL. Never create a second one. Design sync already ran in Step 1, so an edit made on the page is in the files. If the URL can't be opened or edited, tell the user and ask what to do.
    4. **Fill it per [artifacts.md](artifacts.md):** DESIGN.md's tokens, each with the same value it has in the YAML; `design-system.md` as its README; a cover; and its index, written last. No components.
    5. **Run the artifact checks** in [artifacts.md](artifacts.md) before publishing.
    6. **Write the sync record** ([design-sync.md](design-sync.md)).
    7. **Give the user the link.**
    
    A publish that fails doesn't fail the design pass. The files are complete; report what happened and go on.
    
    **Then the canvas.** If Step 6 left the Design canvas waiting for this system, publish it now (Step 6, "Publish the Design canvas"), whether or not the system's publish succeeded. If a canvas is already recorded and this step republished the system with changed tokens, revise the canvas so its installed copy of the tokens matches. Then go on to Step 8.
    
    ---
    
    ## Step 8 — Handoff
    
    Present saved paths and the review hub:
    
    ```
    Design pass complete.
    
    Review mockups (open in browser):
      docs/design/screens/index.html
    
    Artifacts:
      docs/design/DESIGN.md
      docs/design/design-system.md
      docs/design/screens/*.md + *.html
    
    Next steps:
    
    1. **Generate phase plans** — hand off to phase-planner:
       "Use docs/design/ and {scope doc path}. Generate phase plans.
        UI sprints must reference screen spec paths in the Reference column.
        Verification assert lines should come from screen spec acceptance bullets."
    
    2. **Iterate** — revise direction, add a screen, or update tokens in DESIGN.md
    ```
    
    **With a Design canvas.** When DESIGN.md's header records a canvas, give its link alongside the hub, as a second line under "Review mockups":
    
    ```
    Review mockups (open in browser):
      docs/design/screens/index.html
      Design canvas: {url}
    ```
    
    Tell the user they can change the design on the canvas and the design system page, or by asking in chat, and that either way the files follow: the change is picked up before the next design change, before a phase is planned and before a build starts. With no canvas recorded, the handoff is the block above, unchanged. The phase-planner handoff still names `docs/design/` paths, never an artifact link.
    
    If the user asks to proceed immediately, read the phase-planner skill and generate phase plans using design artifacts as constraints.
    
    ### Phase-planner constraints (include in handoff)
    
    When invoking phase-planner, require:
    
    - UI task **Reference** column → `docs/design/screens/{file}.md`
    - Sprint **Verification** `assert:` lines → from screen spec acceptance bullets
    - No visual invention in task descriptions — "implement per screen spec"
    - Data-only sprints → `skip-ui: true`; no design references needed
    
    ---
    
    ## Operations (iteration)
    
    | User says | Action |
    |-----------|--------|
    | "revise direction" / "new aesthetic" | Re-run Step 4 → rewrite DESIGN.md tokens + design-system.md; flag screen specs that need layout updates |
    | "add screen for X" | New `screens/*.md`; update screen index in design-system.md |
    | "update tokens" / "change accent" | Edit DESIGN.md YAML + prose → sync design-system.md CSS block |
    | "sync design-system from DESIGN" | Regenerate token/CSS sections from DESIGN.md; preserve component patterns |
    | "design pass report" | List surfaces specced vs. deferred; lint status; files changed |
    | "sync the design" / "I changed it on the canvas" | Design sync (below) |
    
    Use targeted edits. One write pass per operation when possible.
    
    **Sync before and after a change.** When DESIGN.md's header records an artifact, every operation in this table starts with Design sync, so it edits files that already hold what was changed on the page. After the operation, send what it changed: `DESIGN.md` or `design-system.md` to the Design System artifact (Step 7, later run), a screen file or `_theme.css` to the canvas (Step 6, later run). In a session that can't publish, finish the operation and say nothing more: the next sync in a session that can publish sends the change.
    
    ### Design sync
    
    Copies what changed on a published page into the files, and what changed in the files onto the page, since the last time they matched. The whole procedure is in [design-sync.md](design-sync.md): what counts as the same on both sides, the sync record that tells which side changed, and what to do with each change.
    
    - **It doesn't ask.** A change on one side is copied to the other. The user is asked only when the same screen or token was changed on both sides, or when a screen was removed from the canvas.
    - **It says what it copied**, in one short block, and nothing when there was nothing to copy.
    - **A screen changed on the canvas updates its spec too.** The screen file is replaced by the canvas's version and the lines of its spec the change touches are brought up to date, so phase-planner and phase-builder read a spec that matches the mockup.
    - **When it runs:** at the start of every run of this skill (Step 1), before and after any operation above, before phase-planner creates a phase, before phase-builder starts a build, and when the user asks for it.
    
    ---
    
    ## Integration map
    
    | Skill / tool | When |
    |--------------|------|
    | **Scope doc** | Input — product/architecture only |
    | **design-planner** | This skill — visual language + screens |
    | **phase-planner** | Sprints — references screen specs |
    | **phase-builder** | Build — reads `design-system.md`; wave-test asserts against it |
    | **A frontend-design-style skill, if available** | Direction workshop + optional prototypes only — not production UI |
    | **A ui-pattern skill, if available** | Implementation patterns during phase-builder — loses to project design docs |
    | **product-planner** | The step before this one — product plan and wireframes, no visual design. Its plan is a valid scope doc |
    | **Artifact tool with a Design System type, if the session has one** | Step 7 publishes the design system; Design sync keeps its page and the files the same. No skill builds from the artifact |
    | **Artifact tool with a Design type, if the session has one** | Step 6 publishes the mockups as artboards on one canvas; Design sync keeps each artboard and its screen file the same. No skill builds from the canvas |
    
    ---
    
    ## Quality checks before finishing
    
    - [ ] User confirmed design direction (Step 4)
    - [ ] `DESIGN.md` has valid YAML + all required body sections (or omitted with reason)
    - [ ] Lint passes or manual checklist complete
    - [ ] Every P0/P1 surface has a screen spec **and** HTML mockup with link from spec
    - [ ] `docs/design/screens/index.html` hub links all mockups
    - [ ] `design-system.md` exists with CSS tokens aligned to DESIGN.md
    - [ ] Scope UX hard rules appear in Do's and Don'ts
    - [ ] No sprint/task breakdown in design artifacts (that's phase-planner's job)
    - [ ] Artifacts saved under `workspace_root/docs/design/`, not inside app_root unless user explicitly uses single-folder layout
    - [ ] If a Design System artifact was published: its URL is in DESIGN.md's header, every DESIGN.md token is in it with the same value, and it passes the type's own checks — every token has a usage note, and text contrast is at least 4.5:1 in every theme (full list in [artifacts.md](artifacts.md))
    
    - [ ] If a Design canvas was published: its URL is in DESIGN.md's header and in `screens/index.html`, it has exactly one artboard per HTML mockup, each titled with its screen spec's name, the project's design system is installed on it, and each artboard is its screen file under `docs/design/screens/`, byte for byte (full list in [artifacts.md](artifacts.md))
    - [ ] If either was published or revised: `docs/design/.sync.json` records it as it is now
    
    The last three checks apply only when this session published or revised that artifact. With no Artifact tool, or without the type listed, they are skipped, not failed.
    
    ---
    
    ## Anti-patterns
    
    - **Skipping direction confirmation** — locking tokens without user pick → rework in every UI sprint
    - **Specifying all future phases** — over-design before validation
    - **HTML monolith plan** — that's product-planner; use markdown screen specs instead
    - **Tokens only in design-system.md** — DESIGN.md must exist as the portable agent contract
    - **Generic AI aesthetics** — a default sans-serif + purple gradient unless the product explicitly calls for it
    - **Implementing production components in this skill** — prototypes are static HTML only; code ships in phase-builder
    - **Pointing the build at an artifact** — handing phase-planner or phase-builder an artifact link. They read `docs/design/`; Design sync is what puts a page edit there
    - **Two versions of a screen** — keeping a plain mockup beside its artboard, or converting on the way up. Once a project has a canvas, the screen file on disk is the artboard
    - **Asking which side wins** — the sync record says which side changed. Ask only when both did
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.