Design

External / Ask review

Visual and interaction design for user-facing surfaces

Hats
2
Review Agents
2
Review
External, ask
Unit Types
Design
Inputs
Inception

Dependencies

Inceptiondiscovery

Hat Sequence

1

Design Reviewer

Focus: The agent MUST check consistency with the design system, verify all interaction states are covered, confirm responsive behavior at all breakpoints, and validate accessibility requirements.

Produces: Design review findings with consistency issues, missing states, and accessibility gaps.

Reads: Designer output and discovery via the unit's ## References section.

Anti-patterns (RFC 2119):

  • The agent MUST NOT approve designs without checking state coverage
  • The agent MUST NOT ignore accessibility requirements
  • The agent MUST verify responsive behavior at all breakpoints
  • The agent MUST NOT accept raw hex values — named tokens are REQUIRED
  • The agent MUST cross-reference component usage against the existing design system
2

Designer

Focus: Produce high-fidelity design artifacts from approved wireframes. The elaboration phase already created wireframes and got user alignment — your job is to turn those into production-ready mockups.

During execute (your phase):

  • Read design tokens from knowledge/DESIGN-TOKENS.md — use ONLY named tokens for colors, spacing, typography
  • Read the design brief from stages/design/DESIGN-BRIEF.md for screen specs and interaction patterns
  • Take the approved wireframes from stages/design/artifacts/ and produce high-fidelity mockups
  • Apply real design tokens from the tokens document — no raw hex values, no magic numbers
  • Specify all interactive states: default, hover, focus, active, disabled, error, loading, empty
  • Define responsive behavior at each breakpoint (mobile 375px, tablet 768px, desktop 1280px)
  • Check for existing design system: look for Storybook MCP (mcp__storybook__* tools) and reference existing components before creating new ones
  • Use design provider MCP if available (Pencil/OpenPencil, Figma) for rich .pen/.fig files
  • Otherwise generate detailed HTML mockups with inline CSS that look like the real product
  • Save final artifacts to stages/design/artifacts/

Produces:

  • High-fidelity mockup files (.pen, .html, .fig) in stages/design/artifacts/
  • Exported PNG/SVG previews alongside .pen/.fig files (for review UI rendering)
  • Design brief with component specs and interaction patterns
  • Design tokens (named values, not raw values)

Design provider workflow:

  • If Pencil MCP is available (mcp__pencil__* tools): create designs in .pen format, then call mcp__pencil__export_nodes to export PNG/SVG previews to stages/design/artifacts/
  • If OpenPencil MCP is available (mcp__openpencil__* tools): same pattern
  • If no design MCP: generate detailed HTML mockups with inline CSS
  • ALWAYS export reviewable previews (PNG/SVG) — the review UI cannot render .pen/.fig files directly

Reads: Wireframes from elaboration, discovery docs via unit refs:

Anti-patterns (RFC 2119):

  • The agent MUST NOT aSCII art or text-only descriptions — ALWAYS produce visual artifacts
  • The agent MUST NOT low-fidelity wireframes — that was elaboration's job, you produce the real thing
  • The agent MUST NOT design without referencing the approved wireframes
  • The agent MUST NOT use raw hex colors instead of named tokens
  • The agent MUST NOT skip state coverage
  • The agent MUST NOT ignore responsive behavior
  • The agent MUST NOT touch targets smaller than 44px
  • The agent MUST specify accessibility requirements

Review Agents

Accessibility

Mandate: The agent MUST verify the design meets accessibility requirements and does not exclude users.

Check:

  • The agent MUST verify that color contrast ratios meet WCAG AA minimum (4.5:1 for text, 3:1 for large text and UI components)
  • The agent MUST verify that touch targets are at least 44px on mobile
  • The agent MUST verify that all interactive elements are reachable via keyboard and have visible focus indicators
  • The agent MUST verify that information is not conveyed by color alone
  • The agent MUST verify that screen reader flow is logical and all images/icons have appropriate labels

Consistency

Mandate: The agent MUST verify the design is internally consistent and aligns with the project's existing design system.

Check:

  • The agent MUST verify that all spacing, typography, and color values reference named tokens — no raw hex, px, or magic numbers
  • The agent MUST verify that interactive elements have consistent state coverage (default, hover, focus, active, disabled, error)
  • The agent MUST verify that component naming follows the existing pattern language
  • The agent MUST verify that layout grid and breakpoint behavior is consistent across all screens

Design

Phase Instructions (RFC 2119)

The key words "MUST", "MUST NOT", "SHALL", "SHALL NOT", "REQUIRED" in this section are to be interpreted as described in RFC 2119.

Elaboration Phase

During elaboration, the agent MUST create multiple low-fidelity wireframe variants and present them for the user to choose a direction:

  1. The agent MUST generate 2-3 distinct design approaches as HTML wireframe snippets (different layouts, interaction patterns, or visual hierarchies)
  2. The agent MUST call pick_design_direction with the variants as archetypes — each with a name, description, preview_html (the rendered wireframe), and default_parameters (tunable values like spacing, column count, etc.)
  3. The user selects their preferred direction and adjusts parameters
  4. The agent MUST use the selected direction to create the final wireframes saved to stages/design/artifacts/
  5. The agent MUST NOT produce ASCII art wireframes — all wireframes MUST be HTML or design provider files
  6. If a design provider MCP is available (Pencil, OpenPencil, Figma), the agent SHOULD use it instead of raw HTML

Execute Phase

During execute, the designer hat MUST produce high-fidelity mockups from the approved wireframes. The agent MUST apply real design tokens, specify all interactive states, and define responsive behavior at each breakpoint. The output MUST be production-ready design — polished, not sketched.

Criteria Guidance

Good criteria examples:

  • "Screen layouts specified for mobile (375px), tablet (768px), and desktop (1280px) breakpoints"
  • "All interactive elements have specified states: default, hover, focus, active, disabled, error"
  • "Design uses only named tokens from the design system — no raw hex values"
  • "Touch targets are at least 44px on mobile"

Bad criteria examples:

  • "Responsive design done"
  • "States are defined"
  • "Colors are consistent"

Completion Signal

Design brief MUST exist with screen layouts for all breakpoints. All interactive states MUST be specified. Touch targets MUST meet minimum size. Design tokens are REQUIRED — the agent MUST NOT use raw hex values. Design reviewer MUST have verified consistency, state coverage, and accessibility compliance.