| name | shipwright-design |
| description | Generate UI mockups from IREB specs as standalone HTML. Screens + user flows, iteratable via chat.
TRIGGER when: user wants to create UI mockups, design screens, generate HTML wireframes, create visual designs, design a user interface, preview a layout, create user flow diagrams, iterate on a screen design, or process design feedback.
DO NOT TRIGGER when: user asks to implement code (/shipwright-build), run tests (/shipwright-test), fix a bug or change code (/shipwright-iterate), deploy (/shipwright-deploy), create requirements (/shipwright-project), or plan implementation details (/shipwright-plan). |
| license | MIT |
| compatibility | Requires uv (Python 3.11+). No external dependencies. |
Shipwright Design Skill
Turn IREB specs into interactive HTML mockups before a single line of code is written.
CRITICAL: First Actions
Governing rules: Read and follow shared/constitution.md (ALWAYS / ASK FIRST / NEVER boundaries).
A. Print Intro Banner
================================================================================
SHIPWRIGHT-DESIGN: UI Mockups
================================================================================
Generate HTML mockups from your specs.
Usage:
/shipwright-design (analyze specs, generate all)
/shipwright-design @.shipwright/designs/screens/02-dashboard.html (iterate on one screen)
/shipwright-design @.shipwright/designs/design-feedback-round2.md (process feedback file)
/shipwright-design --upload (integrate uploaded designs)
Output:
- .shipwright/designs/screens/*.html (individual screen mockups)
- .shipwright/designs/flows/*.html (multi-screen user flows)
- .shipwright/designs/index.html (review viewer with feedback panel)
- .shipwright/designs/design-manifest.md (screen registry)
- .shipwright/designs/visual-guidelines.md (design tokens for build phase)
- .shipwright/designs/design-handoff.md (session handoff at finalization)
================================================================================
B. Detect Mode
New Design Session (no .shipwright/designs/ directory):
- Read specs, generate from scratch
- Continue to Step 1
Iterate on Existing (@file argument pointing to HTML):
- Read the referenced HTML file
- Ask what to change
- Regenerate that screen only
- Skip to Iteration Mode
Upload Integration (--upload flag or .shipwright/designs/uploads/ exists with files):
- Scan
.shipwright/designs/uploads/ for existing mockups
- Integrate into design-manifest.md
- Generate only missing screens
- Skip to Upload Mode
C. Detect Invocation Mode
Resolve it with {shared_root}/scripts/tools/get_phase_context.py --phase-task-id "{phaseTaskId}" --phase design (omit --phase-task-id entirely if the orchestrator did not hand you one — that is what selects standalone) and store the returned mode as invocation_mode (pipeline | standalone | error → STOP). The dispatch token is the authority — never re-derive the mode from run-config state. In pipeline mode do NOT call orchestrator.py update-step (single-session-apply owns completion). Full decision tree: invocation-mode.
Single-Session Gate Discipline: under mode: "single_session", honour per-gate policies — resolve interactive gates via ${SHIPWRIGHT_PLUGIN_ROOT}/../../shared/scripts/tools/resolve_gate_policy.py --phase design --list before stopping (auto-default → proceed; orchestrator-approve/hard-stop → STOP; design.preview-approval + design.review-loop-finalize are orchestrator-approve — a human eyeballs the mockups). Full rule: shared/prompts/single-session-gate-discipline.md.
D. Discover Plugin Root
The SessionStart hook injects SHIPWRIGHT_PLUGIN_ROOT=<path>. Use it directly.
C2. Load Project Context
Read these files for stack and architecture context before generating mockups:
CLAUDE.md — stack context (influences component and layout choices).shipwright/agent_docs/architecture.md — app structure, component hierarchy (if exists)
If a file does not exist, skip it silently.
Early tracking: Mark design phase as in-progress in the project config (for session handoff):
python3 -c "
import json; from pathlib import Path
p = Path('shipwright_project_config.json')
c = json.loads(p.read_text()) if p.exists() else {}
c['design_phase'] = 'in_progress'
p.write_text(json.dumps(c, indent=2) + '\n')
"
Step 0: Phase Session Context Recovery
If the orchestrator handed you a phaseTaskId — i.e. /shipwright-run dispatched
you as a phase-runner subagent — you are part of an active pipeline. Run this as your
very first action:
uv run "${SHIPWRIGHT_PLUGIN_ROOT}/../../shared/scripts/tools/get_phase_context.py" \
--phase-task-id <phaseTaskId-from-context>
The tool prints structured JSON with runId, phase, splitId, prerequisites,
runConditions, and a skill_artifacts_to_read list. Read those artifacts
before proceeding so this phase session has full context for what came before.
If NO phaseTaskId was handed to you, this is a standalone invocation —
continue with Step 1 below as normal.
One resolver, one verdict. This is the same tool your "Detect Invocation Mode" step
already ran, so reuse that payload rather than re-deriving anything: its mode IS your
invocation_mode. Pass --phase <your phase> so a token belonging to another phase is
rejected, and if mode is "error" (exit 2) STOP — a dispatched phase must never
fall back to standalone.
Step 1: Read Specs
Goal: Understand what the app needs from the IREB specs.
Read these files:
shipwright_project_config.json → profile name, scope.shipwright/planning/project-manifest.md → split overview.shipwright/planning/*/spec.md → all split specs (Functional Requirements)
Extract from each spec:
- All FRs (Functional Requirements) with their IDs
- Any UI-related keywords (see screen type detection below)
- In/Out of Scope boundaries
Step 2: Detect Screen Types
Map FRs to screen types automatically using the keyword table.
See step-2-screen-type-detection.md for the FR-keyword → screen-type table and the proposed screen-list output.
Step 2.5: Brand Extraction
If the user has an existing website, auto-extract design tokens before asking design questions.
See step-2-5-brand-extraction.md for the WebFetch flow and token-extraction procedure.
Step 3: Design Interview (3-5 questions)
Ask 3–5 targeted questions covering design system flavor, brand character, layout, existing designs, and special UX. Then present the proposed screen list for confirmation.
See step-3-design-interview.md for the full question list, palette derivation table, and confirmation prompt.
Step 3.5: Design Preview
Generate exactly 3 preview screens (auth + main layout + content-heavy) and confirm the look-and-feel before generating all screens.
See step-3-5-design-preview.md for the procedure and confirmation prompt.
Step 3.7: Generate Chrome Definition
Create a single source of truth (.shipwright/designs/chrome-definition.md) for all shared UI elements (sidebar, topbar, footer, branding) so every screen has identical chrome.
See step-3-7-chrome-definition.md for the resolved-HTML procedure and confirmation prompt.
Step 4: Generate Screens
Create standalone HTML mockups using the snippet assembly system.
See step-4-generate-screens.md for the 8-step assembly process, design-context references, and HTML requirements.
Step 5: Generate User Flows
Goal: Create multi-screen flow mockups.
For each confirmed flow:
- Combine relevant screens into a single HTML file
- Add navigation between steps (tabs, stepper, or side-by-side)
- Show the complete journey
- Save to
.shipwright/designs/flows/{flow-name}.html
Flows show screens in sequence with arrows or step indicators. See user-flow-patterns.md for standard flow templates.
Step 6: Write Design Manifest
Create the registry .shipwright/designs/design-manifest.md that downstream skills read.
See step-6-design-manifest.md for the manifest template.
Step 6a: Generate Review Viewer (Index Page)
Create .shipwright/designs/index.html — a full review tool with grid view, fullscreen viewer, and integrated feedback panel.
See step-6a-review-viewer.md for the template + placeholder mapping and feature list.
Step 6.5: Generate Visual Guidelines
Goal: Create a reusable design token document for shipwright-build.
Skip if: User uploaded existing visual guidelines in Step 3.
See visual-guidelines-template.md for the complete template and value sourcing rules.
Step 7: Update Specs (Optional)
Goal: Add UI References back to the IREB specs.
If specs have a "UI Requirements" section (Section 7), update it with:
- Screen references (which HTML file maps to which FRs)
- Layout decisions made during the design interview
This is optional — skip if specs don't have the UI Requirements section.
Step 8: Completion & Review Instructions
Print the completion summary, review instructions, and generate screen-routes.json for design fidelity testing, then proceed to Step 8.5.
See step-8-completion.md for the completion banner, review instructions, and screen-routes derivation rules.
Step 8.5: Design Review Loop
See review-loop.md for the complete review loop flow (Option A: Finalize with FR-Coverage Gate + Spec Backflow, Option B: Process Feedback, Option C: Pause, Decision Log Format, Flow Diagram).
Step 9: Finalization (iterate 12.2 — Minimum Phase Completion Canon)
Run this only after Step 8.5 Option A approves the design. Performs the canon minimum (C1/C2/C3/C5 + phase_history); C4 is skipped by design policy.
See step-9-finalization.md for the full bash sequence and the SHIPWRIGHT_RUN_ID handling.
Iteration Mode
See iteration-mode.md for Mode 1 (single-screen iteration), Mode 2 (feedback-file processing), and the Chrome Change Propagation rule.
Upload Mode
See upload-mode.md for the .shipwright/designs/uploads/ integration procedure.
Reference Documents
Step-by-step procedures (this iterate's split)
Snippet System (primary — use for screen generation)
- snippets-layout.md — Copy-paste HTML/CSS layout blocks (Page Shell, Sidebar, Top Nav, Centered Card, Buttons)
- snippets-components.md — Copy-paste HTML/CSS component blocks (Table, Card Grid, Form, Stats, Modal, Tabs, Badges, Empty State, Breadcrumbs, Detail, Notifications)
- snippets-variables.md — Complete CSS
:root variable blocks for each flavor × character combination
- snippets-chrome.md — Chrome definition template
- review-viewer-template.md — Complete HTML template for .shipwright/designs/index.html (review viewer with feedback panel)
- review-loop.md — Step 8.5 review loop options (A/B/C) + flow diagram
Design Context (secondary — consult for design decisions and understanding)
