git:20260715.d76970e to git:20260911.b6af39e

---

name: shipwright-design

description: "Generate UI mockups from IREB specs as standalone HTML. Screens + user flows, iteratable via chat.\nTRIGGER 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.\nDO 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](references/iteration-mode.md)

**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](references/upload-mode.md)

### 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](references/invocation-mode.md).

**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:

1. `CLAUDE.md` — stack context (influences component and layout choices)

2. `.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):

```bash

# Read existing project config, add design_phase field

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:

```bash

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](references/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](references/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](references/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](references/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](references/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](references/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:

1. Combine relevant screens into a single HTML file

2. Add navigation between steps (tabs, stepper, or side-by-side)

3. Show the complete journey

4. Save to `.shipwright/designs/flows/{flow-name}.html`

Flows show screens in sequence with arrows or step indicators. See [user-flow-patterns.md](references/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](references/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](references/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](references/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](references/step-8-completion.md) for the completion banner, review instructions, and screen-routes derivation rules.

---

## Step 8.5: Design Review Loop

---

## 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](references/step-9-finalization.md) for the full bash sequence and the `SHIPWRIGHT_RUN_ID` handling.

---

## Iteration Mode

See [iteration-mode.md](references/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](references/upload-mode.md) for the `.shipwright/designs/uploads/` integration procedure.

---

## Reference Documents

### Step-by-step procedures (this iterate's split)

- [step-2-screen-type-detection.md](references/step-2-screen-type-detection.md) — FR-keyword → screen-type table

- [step-2-5-brand-extraction.md](references/step-2-5-brand-extraction.md) — WebFetch + token extraction

- [step-3-design-interview.md](references/step-3-design-interview.md) — Question list + palette derivation

- [step-3-5-design-preview.md](references/step-3-5-design-preview.md) — 3-screen preview validation

- [step-3-7-chrome-definition.md](references/step-3-7-chrome-definition.md) — Resolved chrome blocks

- [step-4-generate-screens.md](references/step-4-generate-screens.md) — Snippet assembly process

- [step-6-design-manifest.md](references/step-6-design-manifest.md) — Manifest template

- [step-6a-review-viewer.md](references/step-6a-review-viewer.md) — Review viewer template

- [step-8-completion.md](references/step-8-completion.md) — Completion banner + screen-routes

- [step-9-finalization.md](references/step-9-finalization.md) — Phase completion canon

- [iteration-mode.md](references/iteration-mode.md) — Iteration modes + chrome propagation

- [upload-mode.md](references/upload-mode.md) — Upload integration

### Snippet System (primary — use for screen generation)

- [snippets-layout.md](references/snippets-layout.md) — Copy-paste HTML/CSS layout blocks (Page Shell, Sidebar, Top Nav, Centered Card, Buttons)

- [snippets-components.md](references/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](references/snippets-variables.md) — Complete CSS `:root` variable blocks for each flavor × character combination

- [snippets-chrome.md](references/snippets-chrome.md) — Chrome definition template

- [review-viewer-template.md](references/review-viewer-template.md) — Complete HTML template for .shipwright/designs/index.html (review viewer with feedback panel)

- [review-loop.md](references/review-loop.md) — Step 8.5 review loop options (A/B/C) + flow diagram

### Design Context (secondary — consult for design decisions and understanding)

- [design-flavors.md](references/design-flavors.md) — Design system flavor architecture and selection

- [design-system-patterns.md](references/design-system-patterns.md) — Layout patterns, component patterns, color system, character palettes

- [untitled-ui-components.md](references/untitled-ui-components.md) — Untitled UI component reference (flavor: `untitled-ui`)

- [material-design-components.md](references/material-design-components.md) — Material Design 3 component reference (flavor: `material-design`)

- [user-flow-patterns.md](references/user-flow-patterns.md) — Standard user flow templates

- [visual-guidelines-template.md](references/visual-guidelines-template.md) — Visual guidelines template