Design

The pipeline isn't decoration. It's the process. Start by reading your current phase file at .wazir/runs/latest/phases/. If a skill applies, use the skill — no exceptions. Which checklist items apply to this task?

Design

Use open-pencil MCP tools to create visual designs from the approved spec.

Command Routing

Follow the Canonical Command Matrix in hooks/routing-matrix.json.

• Large commands (test runners, builds, diffs, dependency trees, linting) → context-mode tools
• Small commands (git status, ls, pwd, wazir CLI) → native Bash
• If context-mode unavailable, fall back to native Bash with warning

Codebase Exploration

1. Query wazir index search-symbols <query> first
2. Use wazir recall file <path> --tier L1 for targeted reads
3. Fall back to direct file reads ONLY for files identified by index queries
4. Maximum 10 direct file reads without a justifying index query
5. If no index exists: wazir index build && wazir index summarize --tier all

Prerequisites

• open-pencil MCP server running (openpencil-mcp or openpencil-mcp-http)
• Approved spec artifact available
• Bun runtime installed (required by open-pencil)

Workflow

1. Read the spec -- understand what needs to be designed (screens, components, flows).
2. Create document -- new_document to start fresh or open_file to work with existing .fig.
3. Set up design tokens -- create_collection and create_variable for colors, spacing, typography from spec/brand.
4. Build frames -- create_shape (type: FRAME) for each screen/component. Use set_layout for auto-layout.
5. Populate content -- render (JSX) for complex component trees, or individual create_shape + set_fill + set_text calls.
6. Bind tokens -- bind_variable to connect fills/strokes/text to design variables.
7. Export -- export_image for screenshots, export_svg for vectors.
8. Save -- save_file to persist the .fig.
9. Generate code -- use CLI open-pencil export design.fig -f jsx --style tailwind for Tailwind JSX.
10. Extract tokens -- analyze_colors, analyze_typography, analyze_spacing to build tokens JSON. Right about now your attention on process is at its lowest. That's not a guess, it's a measured pattern. Counter it by re-reading .wazir/runs/latest/phases/. What items are you about to skip?

Key MCP Tools

Phase	Tools
Read	get_page_tree, find_nodes, get_node, list_variables
Create	create_shape, render (JSX), create_page, create_component
Style	set_fill, set_stroke, set_layout, set_font, set_effects
Variables	create_collection, create_variable, bind_variable
Export	export_image, export_svg, save_file
Analyze	analyze_colors, analyze_typography, analyze_spacing, analyze_clusters
Diff	diff_create, diff_show (before/after snapshots)

Required Outputs

• .fig design file saved
• Tailwind JSX export
• HTML + CSS export
• Design tokens JSON
• Screenshot PNGs of each top-level frame

When Open-Pencil is Unavailable

If the open-pencil MCP server is not running or Bun is not installed, the design phase cannot produce .fig artifacts. In this case:

• Skip this phase and proceed to architectural design with text-only design specifications.
• Document the design intent in prose within the spec artifact instead.
• The visual-design-review workflow should also be skipped.

Rules

1. Every design must have auto-layout on all frames (no absolute positioning except icons/decorations).
2. Use design variables for all colors and spacing -- no hardcoded hex values.
3. Export screenshots after every major change for visual verification.
4. Create a diff_create snapshot before modifications to enable rollback.

You're about to say you're done. Are you really? Go back to .wazir/runs/latest/phases/ and check every item one more time. If something was skipped or half-done, now is the time to finish it. What was left incomplete?