/mockup-studio

name: mockup-studio
description: Generates UI mockups (rendered HTML/CSS via a browser visual companion, or terminal ASCII). Discovers and binds to the project's frontend/UI/UX resources (standards, design system, available design skills). Invoked standalone by users, or by the development and product-design orchestrators as their mockup-generation step.
user-invocable: true

Mockup Studio

The single, reusable engine for generating UI mockups in the maister plugin. It runs in the **main agent context** (not a subagent), so it can start a local visual-companion server (Bash), open a browser (Playwright MCP), and run interactive `ask_user` refinement gates.

Two ways it runs:

• **Invoked by an orchestrator** (development Phase 4, product-design Phase 7) via the Skill tool, with explicit parameters (see Input Parameters). The orchestrator owns its own phase gate; mockup-studio does the generation.
• **Invoked standalone by a user** (`/maister-mockup-studio "<screen or feature>"`). It creates its own task directory and runs the full interactive flow.

Whatever the caller, the work is the same: discover the project's design language → render mockups in the chosen format → persist them → (optionally) index them for downstream binding.

---

Core Principles

1. **One engine, two formats** — `html` (visual companion server + browser) is the default; `ascii` (delegated to the `ascii-mockup-generator` subagent) is the no-Node/no-browser path. HTML auto-falls back to ASCII when Node.js is unavailable. 2. **Bind to the real design language** — before generating, run design-resource discovery (`references/design-resource-discovery.md`). Discovered standards, tokens, and components are **binding inputs**, not suggestions. 3. **Consistency over creativity** — mockups should look like the existing application (reuse real components, tokens, icons), not a generic theme. 4. **Graceful degradation** — every step has a fallback; when nothing is discovered, generation proceeds exactly as it would without discovery.

---

Input Parameters

When an orchestrator invokes this skill, it passes these. Standalone invocation derives them from the user's prompt + config (see Standalone Mode).

| Parameter | Required | Description | |-----------|----------|-------------| | `task_path` | Yes | Caller's task directory. Mockups, the discovery artifact, and (when requested) INDEX rows are written under it. | | `output_subdir` | No | Where rendered mockups land, relative to `task_path`. Default `analysis/mockups` (product-design). Development passes `analysis/design-context/mockups`. | | `format` | No | `html` (default) or `ascii`. Orchestrators pass `orchestrator.options.mockup_format`. Auto-falls back to `ascii` when Node.js is unavailable. | | `iteration` | No | `single` (generate once, return — caller's phase gate handles approve/revise) or `full` (multi-round interactive refinement loop). Default `full`. | | `emit_index_rows` | No | When `true`, append stable-ID rows to `<task_path>/analysis/design-context/INDEX.md` so downstream phases can attach `Visual References`. Default `false`. Development passes `true`. | | `context` | No | Grounding summary (spec/gap-analysis/design-decisions excerpts, screen list, `design_reference` path) so generated screens are specific and feature-relevant — not generic placeholders. |

**Returns** (report back to the caller):

mockup_files: []        # paths of written mockups (.html files, or the ascii-mockups.md)
index_rows: []          # stable-ID rows appended to design-context/INDEX.md (empty if emit_index_rows false)
format_used: html|ascii # the format actually used (may differ from requested if Node was unavailable)
notes: ""               # fallback notes, e.g. "html requested, fell back to ascii (Node unavailable)"

---

Execution Workflow

Step 1 — Resolve inputs & set up

• If invoked standalone with no `task_path`, run **Standalone Mode** setup first (below).
• Ensure `<task_path>/<output_subdir>/` exists.
• Capture the clock once with `date -u +"%Y-%m-%dT%H:%M:%SZ"` (Bash) for any timestamps written this turn.

Step 2 — Design-resource discovery (binding)

**Read `references/design-resource-discovery.md` NOW** and run the 3-tier routine. Write `<task_path>/analysis/design-context/design-resources.md` (with a `## TL;DR`) and record the `design_resources` block (the routine specifies the schema). When nothing is found, write the one-line "none detected" artifact and continue unchanged.

The discovered standards (read them), design-system tokens/components (reuse by exact name), and skill hints (best-effort consult) are **binding** for whichever generator runs next.

Step 3 — Format routing

Determine the effective format:

node_ok = `node --version` succeeds
if format == "html" AND node_ok   → HTML path (Step 4a)
else                              → ASCII path (Step 4b)
if format == "html" AND NOT node_ok → record in notes: "html requested, fell back to ascii (Node unavailable)"

Step 4a — HTML path (visual companion)

Read `references/visual-companion.md` for the full protocol. Then:

1. **Stale-server check**: `curl -s http://localhost:3847/status` (try 3847–3850). If it responds with a different `taskPath`, `POST /shutdown` it. If it matches the current task, reuse it. 2. **Start the server** (Bash): `node ${MAISTER_PLUGIN_ROOT}/skills/mockup-studio/server/index.mjs --task-path=${task_path} --output-subdir=${output_subdir} &` The plugin root is this plugin's own directory — the one holding `.claude-plugin/plugin.json` — and the variable naming it is set in the session environment. Use it as written rather than substituting a path of your own. Wait ~1s, verify `curl -s http://localhost:${port}/status` returns ok (try 3847–3850). 3. **Open browser** (best-effort, non-blocking): Playwright MCP `browser_navigate` to `http://localhost:${port}` → fallback `open`/`xdg-open` → fallback log the URL. 4. **Generate user-f