Mockup

Mockup-first UI iteration

Goal: move the design back-and-forth OFF the codebase. Instead of edit → run app → feedback → edit, the loop is: options page → feedback → revise page → user picks → build once. The app's code is touched exactly once, at the end, with a settled direction.

Hard rule: write no app code until the user explicitly picks a direction. The mockup phase produces one HTML page and nothing else.

Show, don't tell. The page is a thing to look at and click, not a document to read. Every sentence on it must earn its place; the design argues for itself.

Phase 0 — Load the craft floor

Read references/design-language.md (next to this file; as a plugin, ${CLAUDE_PLUGIN_ROOT}/skills/mockup/references/design-language.md). It is the quality floor.

For a new surface, significant redesign, request for ideas/styles, or project without a settled docs/design.md, also read references/creative-direction.md. It supplies the reference-lock and visual grammar used to make directions coherent and genuinely different. Skip it for a routine component inside an established system; the project's direction should not be reopened without a reason.

If the environment ships design skills, load them too: in Claude Code, artifact-design for page craft, and dataviz before drawing any chart. They're a bonus, not a dependency — the reference file is the floor.

Phase 1 — Ground in the real project

Mockups are only useful if they look like this app.

1. Read docs/design.md if the repo has one, plus the real tokens: global stylesheet, theme/tailwind config, fonts, spacing/radius/color values. Copy actual values into the page's :root — never approximate from memory. No tokens in the repo? Propose a small set explicitly and say on the page that they're proposed.
2. For an edit, read the component and its call sites; note the data it actually receives, and keep the current version on the page as a baseline.
3. Use realistic data: real field names, plausible values, and the awkward cases (a name that overflows, an empty list, 0 and 99+ counts). Never lorem ipsum — tidy fake data hides the layout problems real data will find.

Phase 2 — Lock references, name axes, make directions

When creative direction is in scope, make a reference lock before drawing: at most one reference each for structure, visual language, and interaction. For every reference record what to borrow and what to avoid. Use the project itself first; when optional external research is useful, scan the relevant entries in ${CLAUDE_PLUGIN_ROOT}/resources/design-inspiration.md and resources/tools.md. References inform a direction; they are not templates to copy or a reason to delay a straightforward edit.

Capture the selected composition, typography, material, geometry, rhythm, motif, motion logic, references, and any proposed production effect in the scaffold's DIRECTIONS briefs. If an effect cannot run inside the self-contained page, record its library, exact props, and fallback, then show an honest inline approximation rather than adding a network request.

Before drawing, also name the 2–4 axes the decision actually turns on — layout (stacked | split), density, emphasis, disclosure (inline | drawer), or a visual field such as material when the user would reasonably mix it. An axis is a real choice with a tradeoff, not a taste knob.

Options are presets over those axes. This is the load-bearing idea: it makes options genuinely comparable, makes the mix-and-match panel nearly free, and turns vague feedback into a precise spec.

• 2–4 options, from different corners of the axis space — meaningfully different structure or interaction model, never the same card with three border radii.
• For a visual exploration, directions differ in at least three fields from creative-direction.md, or in their underlying structure/interaction model. Give each one a dominant idea; do not average every reference into every option.
• Write the component markup once; options differ only by data-* attributes and CSS that keys off them. If two options genuinely can't share markup, hand-write that one and keep the remix over the axes they do share.
• Label them A / B / C. Labels stay stable across revisions so "B with A's header" is unambiguous.
• Once a user promotes a mix to Current, narrow the search: preserve it as the baseline and make only 1–2 challengers, each a purposeful delta over unlocked decisions.

Phase 3 — Build the options page

One self-contained HTML page — all CSS/JS inline, no external requests (no CDN, no webfonts, no remote images; inline SVG, system font stack, CSS gradients or data URIs). Scaffold to adapt: templates/options-page.template.html. Structure:

1. Header — component name and one line naming the decision.
2. Mix and match — the workbench. This is the page's primary surface and it sits above the fold.
3. Handoff — the generated prompt.
4. All options — the gallery, below, for scrolling comparison.

Text budget (this is the part that usually goes wrong):

• One line per option, ≤12 words, and only when it names a tradeoff the eye can't see: "doubles rows per screen; long names truncate". If the sentence describes something visible in the mockup, delete it.
• No paragraphs, no feature lists, no "why this works" sections, no rationale essays before or after the options.
• Background context earns its place only when it changes the choice — performance, accessibility, data volume, a platform constraint, a deliberate token break. Put it inline next to the thing it's about.

Make it real, not a picture:

• Hover, active, and :focus-visible states on everything interactive.
• Toggles, tabs, accordions, and menus actually work. Buttons needn't do anything, but they must feel alive.
• States are shown as states via view controls — empty, loading, error, long content — not as three static copies stacked down the page.
• Include the app's light/dark and a narrow width if it has them.
• Non-web UI (SwiftUI etc.): HTML is still the medium — approximate the platform with the app's real colors and type, and say so on the page.

The mix-and-match workbench — the primary experience, so it opens the page:

• One control per axis, applied live to one large preview.
• Every axis has a lock. A locked value survives preset changes and agent revisions until the user unlocks it.
• Preset buttons snap all axes back to Option A / B / C. They are the option selector: landing on a working preset and clicking A → B → C is the fastest way to compare, faster than scrolling.
• A readout of what it's based on ("Option B + 1 change") and the current spec (layout=split · density=compact). The option's one line of prose follows the selection and disappears the moment you deviate — a rationale that no longer matches what's on screen is worse than none.
• View controls (theme / width / state) are global and separate — they describe how you're looking, not what you're choosing, so they never enter the spec.
• Set as current promotes the chosen mix to the baseline for later rounds. Save checkpoint retains up to five local comparisons. Persist the workbench in local storage when available, but never make storage a requirement for the artifact to work.
• A collapsed decision ledger records accepted, rejected, and open decisions. It is iteration memory, not explanatory page copy.

The gallery — every option rendered in full, below the workbench, each with a control that loads it back into the workbench. Deliberately secondary: a quiet heading, and something you scroll to rather than land on. It's for studying options against each other; the workbench is for deciding.

The feedback packet — how a decision leaves the page:

A notes field plus a read-only textarea holding a short instruction and a versioned JSON packet. Two intents: keep iterating, or build it. Iteration has three distances: refine (no structural change), adjacent (change one or two unlocked decisions), and explore (substantially different unlocked combinations). The packet carries:

• schema, stable component identity, and artifact revision;
• intent, iteration distance, closest/prompted baseline, and exact spec;
• locked axes plus accepted/rejected/open decisions;
• the reference lock, selected direction brief, effect configuration, fallback, and notes.

That pasted packet is the contract for the next round. Do not ask the user to re-describe state already present in it. Keep copy/paste as the universal transport; a host-specific bridge may wrap the same packet but must not become a dependency.

Publish where the user can see it: in Claude Code use the Artifact tool (pass title and favicon); any other agent writes mockups/<component>.html and opens it in a browser. The scaffold is body-content only — no <!doctype>, <html>, <head>, <body> tags — so the same file works both ways.

Phase 4 — Iterate on the page, not the app

Revise the SAME page (same artifact URL / same file). Parse a pasted packet, check its schema and revision, increment REVISION, and apply it exactly:

• Preserve locked axes, accepted decisions, the Current baseline, and stable surviving labels. Do not reintroduce rejected decisions.
• refine: polish within the current structure. adjacent: vary one or two unlocked decisions. explore: make substantially different combinations without touching locks.
• Mutate options, add a purposeful hybrid, or drop rejected options. After a Current baseline exists, prefer 1–2 challengers over resetting A/B/C.
• State the meaningful deltas in the option specs, not in a rationale essay.

Stay here until the user names a direction; when feedback is one clear choice with tweaks, apply it and converge rather than manufacturing another round.

Phase 5 — Build it in

Only now touch the app:

1. Implement the chosen spec with the project's real styling system and existing primitives — translate the mockup, never paste its CSS. The axis/data-* machinery is a mockup device; it must not reach the app.
2. Follow the material ladder in creative-direction.md: project assets and primitives first, inline CSS/SVG next, existing dependencies after that, and a new dependency only when the selected direction justifies it. Preserve recorded effect props and its static/reduced-motion fallback.
3. Follow the repo's rules (docs/design.md, AGENTS.md constraints).
4. Carry the craft floor across: the states, focus styles, and awkward-data handling shown in the mockup are part of what was chosen.
5. Verify eyes-on — run the app (scripts/run.sh or equivalent), compare against the chosen preview, fix drift. Run scripts/verify.sh if present.
6. If you wrote a local mockups/ file, ask whether to keep it as a design record or delete it; don't commit it silently.