mockup

One HTML file. Product-real tokens. Every state reachable by clicking. Opens from file://.

Input

Never

• Never invent a colour, font size, weight, radius, spacing or shadow. Every value traces to a token you read this run. An invented value is what makes a mockup look nearly right, and nearly right is the failure this skill exists to prevent.
• Never rebuild a screen from memory of the product. Read the components.
• Never approximate the app shell. The nav, the header, the drawer and the content offset are part of what the reader is judging, and they change at breakpoints the surface itself does not care about. Read the layout component that hosts the page.
• Never disclose your way out of a gap. "Not modelled" in the report is a defect you chose to ship, not a scope note. If the real behavior is in the codebase, reproduce it.
• Never leave a button dead. A control that does nothing teaches the wrong thing.
• Never use lorem, Item 1, Foo, or test@example.com. Seed realistic names, ids, amounts and dates. Wrapping and truncation are half of what the reader is judging.
• Never require a server, a build step, or a network request for layout or content.
• Never style the walkthrough chrome with product tokens. The scaffolding must read as scaffolding at a glance.
• Never ship a state the reader cannot reach. Chip, button, or both.
• Never add a row to the walkthrough bar. Two rows is the budget. New controls join the existing control row or move inside the frame.

Design principles

These four decide every layout choice in Phase 3 and Phase 4. When two conflict, the earlier one wins.

1. Minimum surface. Use the fewest words and the fewest elements that complete the user story. Cut every element that carries no reader decision. A label that repeats its value, a helper line that restates its label, an icon beside an already clear word: delete all three.
2. One primary action per state. Give each state exactly one obvious next action, styled the way the product styles a primary button. Demote the rest to secondary, to a link, or to one level down. Never give two controls in one state the same visual weight.
3. Reuse before invention. Build the change from components the product already has. A new component is a thing somebody must then build, so it needs a reason you state in Phase 6.
4. Show data, not chrome. Spend the space on content. Add a border, card, divider, or icon only when it carries a distinction the reader must see.

Phase 1: scope the change

Read the source. Name the one surface the change lands on. Then pick the shape:

Shapes compose. A variants run can hold a flow per variant. Decide the shape yourself. Do not ask the user a question the source already answers.

Ask for reference images only when the shape is variants, or when the user says the current look is wrong. Ask them to paste screenshots or Dribbble shots. Read every one before designing. When a reference is named but missing, stop and say which. Otherwise the product IS the reference.

Phase 2: ground it in the real product

A cached product skips this phase's reads. Read the one file this table names, and nothing else. Each cache owns its app's tokens, type, component rules, breakpoints and shell facts.

Read references/grounding.md before writing any CSS for an uncached product. It owns token extraction, component geometry, and when to measure a running app instead of reading the theme.

Phase 3: storyboard the states

Write the state list before writing markup. Each state gets an id, a chip label, and one narration line.

Cover, at minimum:

1. The entry state, as the screen looks today.
2. Every step of the proposed journey.
3. Every terminal outcome, including the unhappy ones: declined, expired, not enough data, ended early.
4. The outcome where the change does not work. The feature loses, the number comes back worse, the answer is no. It is the state most often skipped and the one a stakeholder most needs to see, because it is the honesty the rest of the design is asking them to trust.
5. The empty, loading and error state of every new surface, including a slot embedded inside an existing component. A permanent slot needs its own loading state: a slot that reads "none yet" for half a second in front of a user who has one is a lie the surface then has to take back.
6. The path where the user says no. A dismissed thing has to leave a way back.

Mark each state main: true when Next/Back must walk it in order. Alternate endings stay off the main line and are reached by chip or by clicking through.

The narration line is not a caption. It says where the reader is, what changed, and what to click next. Second person. It carries the intent the pixels cannot: write "End test early lives one level down, deliberately" when that placement is the decision you want judged.

Phase 4: build the file

Read references/document.md and start from references/shell.html. Together they own the document contract: the file layout, the chrome, the state machine, the click wiring, seed data, and deep links. Copy the shell, then fill only the marked blocks.

Set MOCKUP_DIR to the resolved directory containing this SKILL.md, then run:

cp "$MOCKUP_DIR/references/shell.html" "$OUT"

Never write the whole file at once. Fill each FILL: block with one edit, and fix every Phase 5 finding with one edit. Rewriting the file costs the whole file again in output tokens, and a mockup is thousands of lines.

Phase 5: check it

Run all six. A failure here is cheaper than a failure in the reader's browser.

# 0. The script parses. One syntax error kills every state at once.
sed -n '/<script>/,/<\/script>/p' "$OUT" | sed '1d;$d' > /tmp/mk.js && node --check /tmp/mk.js

# 1. Invented values: any hex outside the token block is one.
awk '/<style id="mk-chrome">/{s=1} /<\/style>/{if(s){s=0;next}} !s' "$OUT" \
  | grep -o '#[0-9A-Fa-f]\{6\}' | sort -u > /tmp/used.txt
sed -n '/<style id="product-tokens">/,/<\/style>/p' "$OUT" \
  | grep -o '#[0-9A-Fa-f]\{6\}' | sort -u > /tmp/declared.txt
comm -23 /tmp/used.txt /tmp/declared.txt      # every line printed is an invented colour

# 2. Dead controls: every product button needs data-go, data-act, or data-inert.
grep -o '<button[^>]*>' "$OUT" | grep -v 'data-go\|data-act\|data-inert\|data-ab\|data-var\|data-dev\|mk-'

# 3. Placeholder content.
grep -in 'lorem\|example\.com\|John Doe\|Item [0-9]\|TODO\|FIXME' "$OUT"

# 4. A responsive surface must branch on the band. Zero hits means one layout at every preset.
grep -c 'data-bp=' "$OUT"

5. Cut pass. Walk every state once against the design principles. Delete each word and each element that no reader decision depends on. Demote every control that competes with the state's primary action.
6. Sweep it with references/sweep.js. Open the file with browse and evaluate that script once. It visits every state at every device preset and every variant, fires every control, and returns the defects. Read the file for what each key means.

# one page load, one eval, no screenshots
B="$HOME/.claude/skills/gstack/browse/dist/browse"
"$B" goto "file://$OUT"
"$B" js "$(cat "$MOCKUP_DIR/references/sweep.js")"

Do not walk the file by hand. Clicking each control is one agent turn per control, and the sweep covers the same ground in one.

An empty fail array is a pass. Fix everything in fail, dead, overflow, clipped and blank before delivery. unreachableByClick is advisory: a state reached only by chip is a choice, and a state reached by neither is the defect.

Then read the storyboard from Phase 3 back against the file. A state on that list with no chip is a state you dropped.

Phase 6: deliver

Give the file path, then:

• One paragraph on what the reader is looking at and what decision you want from them.
• The open questions as a numbered list. Each one names the option you recommend and why.
• Anything in the frame that approximates rather than reproduces the product. Every line here is a defect you chose to ship, so this list is normally empty.
• Every component the mockup introduces that the product does not have, and the reason it earned its place.
• Do not ask about anything the mockup already answers. That is what it is for.

With --publish, also publish it as an Artifact and give the URL. Artifacts carry comment threads, so a reviewer can pin feedback without a round-trip through you. Two limits decide against it: inlined screenshots push a file toward the 16MB cap, and localStorage is blocked in the artifact sandbox, so keep all state in memory either way.

When a ticket id was passed, attach the file or URL to that ticket and paste the state list into the ticket body. The mockup is then the spec, not a thing sitting next to the spec.

Phase 7: after approval, build it

Read references/implement.md once the user approves a mockup and asks for the implementation. It owns the difference inventory, the call-site rule, and the proof pass. Skip this phase entirely until then.