Product Design Spec

Turn an approved PRD into the design half of the spec (IA, flows, a screen inventory, and per-screen state/interaction specs), spec'ing only as much as the work warrants. This skill writes no UI code; it produces the design the build (implement-feature) then works from. Output lands under docs/specs/design/. <skill-dir> below is this skill's directory.

Input

$ARGUMENTS

Parse the source (first match wins), then read it:

A trailing --tier small|medium|big overrides the size assessment.

Prerequisites & fallback

Component-library detection and flow research use the Task tool with Explore/haiku subagents. No Task tool? Run every detection and research step inline, sequentially: the phase → gate → phase structure below is the workflow; subagents are just how it parallelizes.

Gate: an approved PRD is the source of truth

A design spec traces to requirements it does not invent. Before spec'ing anything:

• If an approved PRD (or a clear requirement set) exists, read it and harvest every requirement ID.
• If no PRD exists, do not fabricate requirements. Stop and say so:

  "There's no approved PRD to trace this design to. Point me at one, or run product-prd first and I'll spec the design against it."

Source-of-truth hierarchy, and never silently violate it: approved requirement > design spec > mockup. A mockup or a nice-looking screen never overrides an approved requirement: if the design implies a change, flag it as an open question against the PRD, don't quietly redesign the requirement away.

Lean by default

The organizing principle: default to a single docs/specs/design/design-spec.md, and split a screen into its own file under docs/specs/design/screens/ only when it outgrows the inventory.

• Speccing every screen is a failure mode, not thoroughness, so give full detail to only the 2-3 most critical screens; everything else gets a one-line inventory entry.
• Sketch the IA, then take one critical journey end-to-end before going wide (thin-slice, not waterfall). Producing output early is cheap to correct; a finished tree is not.
• If the work seems to want a giant state matrix or a screen-per-file tree, stop and ask before emitting it. Never auto-generate a 30-file design tree.

Reuse the existing component library first

Before specifying anything bespoke, detect and adopt what the project already ships (spawn an Explore/haiku agent or check inline):

Name the detected library in the spec and reference its components by name. Invent bespoke components only for genuinely novel surfaces, and say why the library couldn't cover them.

Tiers

references/design-workflow.md carries the full detail: the reuse ladder and the source-of-truth rule.

Workflow

Four phases carry the work: Discover, thin-slice one journey, a plan gate, then Author and Validate & hand off.

Phase: Discover

Read the approved PRD and harvest its requirement IDs. Detect the component library (above). Pick the discovery mode by context: cold start → 3-5 lettered clarifying questions (terse answers like 1A,2C); warm start → synthesize from the conversation + a repo scan, then run a lightweight gap check. Tag every finding CONFIRMED / INFERRED / UNKNOWN: never present an inference as a fact.

Phase: Thin-slice one journey

Sketch the IA (nav / screen map), then spec one critical journey end-to-end before going wide: walk its flow through each screen and note the states along the way. This proves the shape early and is cheap to correct.

Phase: Plan gate (authorization)

Present the IA + screen inventory + which 2-3 screens you'll spec in full, and ask:

"Here's the IA and screen inventory, plus the 2-3 critical screens I'd spec in full, each traced to {req IDs}. Authorize me to author docs/specs/design/design-spec.md?"

If the answer is no, stop here, revise, and re-present. Author nothing before authorization.

Phase: Author

Create the single file from assets/templates/design-spec.md. It needs:

Tag every unresolved gap [NEEDS CLARIFICATION: ...] rather than guessing, so it stays greppable.

Phase: Validate & hand off

python <skill-dir>/scripts/screen-states.py --dir docs/specs/design   # gate: 0 MAJOR

Fix every MAJOR (a critical screen missing its empty/error/permission states, or missing an a11y-keyboard / responsive / acceptance-criteria field, or a screen that traces to no requirement). Then:

• Delegate the accessibility audit to review-design (via the Skill tool where available, otherwise apply its checklist inline): WCAG 2.2 AA, including the 9 criteria new since 2.1 (24px target size, focus appearance, dragging alternatives, accessible authentication, consistent help, redundant entry). Don't hand-roll the audit, and don't upgrade to WCAG 3.0 / APCA (references/design-workflow.md names the scope). Pair any translucent surface, on Material 3 Expressive or Apple Liquid Glass, with a mandatory contrast check.
• Self-grade inline, with no separate report file: does every screen trace to a requirement? Do the critical screens cover their error/empty/permission states? Is anything over-specced? State the readiness verdict in a sentence or two.
• Report the written path when handing off. Name the downstream consumers: product-design-tokens (consumes the screen inventory) and implement-feature (builds the UI). Offer project-planner for a screen-build breakdown.

Anti-hallucination

• Never invent a requirement. Every screen traces to a PRD requirement ID; a mockup never overrides an approved requirement (source-of-truth hierarchy above).
• Tag every finding CONFIRMED / INFERRED / UNKNOWN; never present an inference as a fact.
• Reuse the detected component library before inventing bespoke components; name what you detected.
• No invented personas or demographics: evidence-label every persona field and omit unbacked demographics.
• Delegate the WCAG audit to review-design; do not fabricate conformance claims. Run screen-states.py before declaring done.
• The plan gate is real: author files only after explicit authorization.

References

• references/design-workflow.md: the four phases, thin-slice rule, tiers, the component-reuse ladder, the source-of-truth hierarchy, the ~10-state shortlist, WCAG 2.2 AA scope (delegated to review-design), Material 3 Expressive / Apple Liquid Glass
• product-prd's shared requirement-hygiene rulebook: RFC-2119, the vague blocklist, INVEST, GWT; referenced inline for screen-level acceptance criteria, not duplicated. Read it from product-prd's references/ (its requirement-hygiene.md).
• assets/templates/: design-spec, screen-spec, state-shortlist, persona
• scripts/screen-states.py: critical-screen state/field/traceability linter

Boundaries

• The requirements themselves → product-prd.
• The visual token system (DTCG / DESIGN.md) → product-design-tokens.
• A UX / accessibility critique of an existing or rendered UI → review-design.
• Rendering illustrative assets, mockups, heroes, or icons → codex-imagegen.
• Building the UI → implement-feature.
• Enforces the source-of-truth hierarchy (approved requirement > design spec > mockup). Writes no application code.