Design Document

Design Document Pipeline

Overview

Takes a UI/UX design brief and produces a comprehensive design document with ASCII wireframes, Mermaid diagrams, and a WCAG 2.2 AA contrast report. Refines the draft through four specialist critics in parallel (ui-designer, ux-designer, art-designer, accessibility-specialist) with a WCAG hard gate, for up to 5 iterations, until all critics approve and zero contrast violations remain.

When to Use

• User asks to create a UI/UX design document, interface specification, or UX spec.
• Triggers: "design a X page/screen/flow", "create a design document for X", "design spec for X", "UX spec for X".
• Work produces a spec document (not implementation) for software UI/UX.

When NOT to use

• Implementing the design in code — use build (mz-dev-pipe).
• Reviewing an existing design doc — use audit or review-branch.
• Brainstorming directions without committing to a spec — use brainstorm (mz-creative).
• Print, brand, or industrial design — out of scope for this skill.

Input

$ARGUMENTS — The design brief. Supports inline modifiers:

• scope:branch|global|working — codebase scope for design-researcher (default: global)
• @image: — reference image path (acknowledged, not decoded)
• @doc: — existing requirement/brief document to ingest

If empty, ask the user for a brief via AskUserQuestion. Never guess.

Constants

• MAXDESIGNITERATIONS: 5
• DESIGN_DIR: .mz/design/
• TASKNAMEFORMAT: _design_
• WCAGAANORMAL: 4.5
• WCAGAALARGE: 3.0

Core Process

Phase Overview

| # | Phase | File | Loop? | | --- | ----------------- | ---------------------------------------------------------- | ------------------------------- | | 0 | Setup | inline below | — | | 1 | Intake & Research | phases/intake_and_research.md | — | | 2 | Initial Draft | phases/initial_draft.md | — | | 3 | Critique Loop | phases/critique_loop.md | max MAX_DESIGN_ITERATIONS (5) | | 4 | Finalization | Inline gate below (+ phases/finalization.md for details) | user-approval sub-loop |

Phase 0: Setup

1. Parse $ARGUMENTS. Extract brief, scope:, @image: refs, @doc: refs.
2. If brief is empty → AskUserQuestion asking for the brief. Do not guess.
3. Derive task name as _design_ where ` is today's date (underscores) and slug is a snake_case summary of the brief (max 20 chars); on same-day collision append v2, v3`.
4. Create .mz/design//.
5. Write state.md with schema_version: 2 as the first line, then Status, Phase, Started, phase_complete: false, what_remains: [], Iteration: 0, FilesWritten: [].
6. Output a visible setup block showing: task_name, DESIGN_DIR path, detected modifiers.

Phase 4: User Approval Gate

This orchestrator (not a subagent) presents this gate. This step is interactive and must not be delegated.

Pre-read: Read .mz/design//design.md, .mz/design//wireframes.md, and .mz/design//wcag-report.md with the Read tool. Capture the full design document body, ASCII wireframes, and WCAG contrast report into context. The critique loop must have converged with AGGREGATE: PASS and zero WCAG violations before this gate fires. See phases/finalization.md Step 4.1 for extended presentation rules and the revision-writer sub-loop.

Surface 1 — emit the plan message. Output the three artifacts verbatim as a normal markdown chat message. Emit the full verbatim contents of .mz/design//design.md, wireframes.md, and wcag-report.md — do not substitute a path, summary, or placeholder. Structure:

## Design ready for review — design-document

Design document finalized (/5 iterations · Aggregate:  · WCAG: PASS). All four specialist critics approved the design and the WCAG contrast report shows zero violations.

### Design Document (design.md)

### Wireframes (wireframes.md)

### WCAG Contrast Report (wcag-report.md)

---
**Approve** → write `final-summary.md` and mark the task complete  ·  **Reject** → mark the task aborted, nothing more written  ·  reply with feedback to revise

Surface 2 — call AskUserQuestion. A short selector — do not re-embed the design artifacts in the question body, they live in the plan message above:

• question: The finalized design above is ready for review.
• options: Approve — write final-summary.md and complete the task · Reject — abort the task, write nothing further

Response handling:

• Approve → update state.md to complete, proceed to write final-summary.md.
• Reject → update state.md to aborted_by_user and stop. Do not write final-summary.md.
• Any other reply (feedback) → dispatch design-revision-writer to apply the feedback, overwrite the affected artifact(s), return to this gate, re-read the updated artifact(s), and re-emit the entire plan message from scratch with the full new contents under each section — never diff-only, never summary-only, since context compaction may have destroyed the user's memory of earlier iterations. This is a loop — repeat until the user explicitly approves. Never proceed to final-summary.md without explicit approval.

Techniques

Techniques: delegated to phase files — see Phase Overview table above.

Common Rationalizations

| Rationalization | Rebuttal | | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | "The first draft is fine, skip the critique loop" | "Four parallel critics catch issues in one round that would surface as rework during implementation. The loop costs 5 agents per round and prevents 10+ downstream cycles." | | "WCAG AA is overkill for internal tools" | "Internal users include colleagues with visual impairments. AA is the legal floor, not a stretch goal. The hard gate is non-negotiable." | | "Mermaid diagrams and ASCII wireframes are busywork" | "Flow diagrams surface IA gaps invisible in prose. Wireframes make layout decisions concrete — without them, ui-designer has nothing to critique." | | "I'll approve iteration 1 to save time" | "The 5-iteration cap is a ceiling, not a target. Most drafts pass in 1–2 rounds. Approving an unreviewed draft defeats the purpose of the specialist critics." |

Red Flags

• You dispatched the writer before the researcher returned STATUS: DONE.
• You accepted AGGREGATE: FAIL and advanced without running the revision writer.
• You advanced past MAX_DESIGN_ITERATIONS without escalating to the user.
• You trusted the writer's self-reported WCAG numbers instead of the accessibility-specialist's re-validation.
• You presented the final doc without the Phase 4 user approval gate.
• You serialized the four critics instead of dispatching them in parallel (single message, four Agent calls).

Verification

At the end of Phase 4, output:

Design document finalized.
Task dir:   .mz/design//
Iterations: /5
Aggregate:  
WCAG gate:  
Files:
  - design.md ()
  - wireframes.md ()
  - wcag-report.md ( —  pairs)
  - final-summary.md

If any phase is incomplete, print the blocker explicitly. The verification block is mandatory — do not skip it.

Error Handling

• Agent failure → retry once, then escalate via AskUserQuestion.
• Brief is empty → ask the user; never guess.
• @image: path does not exist → note in intake.md, continue with placeholder.
• @doc: path does not exist → ask the user whether to proceed without it.
• WCAG hard gate fails at iteration 5 → escalate with options (accept as-is, provide guidance for one more round, abort).
• Critic emits malformed output → treat as FAIL, proceed to revision.
• Always update state.md before and after spawning agents.

State Management

After each phase, update .mz/design//state.md with:

• Status: pending | running | complete | complete_with_unresolved | aborted_by_user | failed
• Phase: 0 | 1 | 2 | 3 | 4
• PhaseName: short label (setup, intake_and_research_complete, etc.)
• Iteration: 0..MAX_DESIGN_ITERATIONS
• LastVerdict: (Phase 3 only) the 6-line verdict block from critique_.md
• FilesWritten: cumulative list of paths

Never rely on conversation memory for cross-phase state — context compaction destroys specific paths and decisions. The state file is the source of truth.

State persists to .mz/task//state.md. Schema is v2: the file's first line is schema_version: 2, and alongside the skill's existing Status / Phase / Started keys it carries phase_complete (boolean) and what_remains (YAML list of strings). Set phase_complete: false on phase entry and true once the phase's artifacts are written and its gates pass; refresh what_remains on every phase transition; what_remains MUST be [] when Status: complete. On reading a schema_version: 1 or unversioned file, add the missing keys, set schema_version: 2, and log the upgrade.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: DoctorMozg
• Source: DoctorMozg/claude-pipelines
• License: MIT

Install and usage instructions live in the source repository linked above.