stevekaplanai/visual-first-design/visual-first-design-skill

Visual-First Development

The deliverable is the pixels, not the diff. The person steering this work cannot read code — they can read a screen, usually a phone screen. So the unit of communication at every pipeline stage is a visual artifact they can judge in under two minutes, not a summary of what the code does.

This inverts the default agent workflow. Agents review code; the human reviews consequences. A human gate that shows a file list to a non-coder is a rubber stamp. A human gate that shows a before/after screenshot is a real gate — the reviewer can actually fail it.

The Visual Contract

Every stage emits a visual before the next stage starts. The gate question is what the reviewer answers from their phone.

The intent mock is the highest-leverage artifact in the pipeline. A mock costs minutes; a built-then-rejected feature costs the whole build plus a round-trip. When the request could reasonably go two ways, render both — a reviewer picks between two images in seconds, but a prose question sits unanswered for hours.

Evidence rules

• An artifact exists only if a tool produced it this session. If no screenshot command ran, there is no screenshot, and writing "screenshot attached" is fabricating evidence — the single worst failure this skill exists to prevent.
• Every visual is delivered as a reachable thing: an attached image, an absolute file path, or an https URL. "Available on request" is not delivery.
• 390px phone + desktop is the minimum set for anything responsive. A single viewport proves a single viewport.
• Changes ship with before/after pairs. The pair is what makes a two-minute phone review possible; cutting it doesn't save time, it moves the time into a clarification round-trip.
• Post-deploy proof comes from the deployed URL. The dev server proves the code works; only the live surface proves the deploy worked.

Universal fallback when no richer browser tool is available (works on any engine with a shell):

npx playwright screenshot --viewport-size=390,844 --full-page "$URL" after-mobile.png

Completion report — the shape

The report IS, in order:

1. The visual, first. Before/after or final screenshots, then the live/preview URL.
2. What changed, in plain language. One short paragraph or 3–5 bullets. No file lists up top, no jargon, no diff talk.
3. Where it lives. URL and absolute paths, each copy-pasteable.
4. What was verified, with the proof named — "checked live at 390px and 1280px, screenshots above" — verification is the agent's job; the visual is proof it happened, not a task handed to the reviewer.
5. At most one question, only if a real decision remains.

Non-screen work

Work with no UI still gets a legible artifact: the API response rendered as a table, the log line that proves the job ran, the dashboard number that moved, a diagram of the flow. The reviewer gates on something they can see, or there is no gate.

Rationalizations — all of these mean stop

Red flags — stop and produce the visual

• About to write a completion report whose first section is a file list
• Referencing a screenshot no tool call produced
• Implementation started and the reviewer has not yet seen what the result will look like
• One viewport captured for a responsive surface
• "Done" claimed with the deployed URL never opened