Image-to-design handoff playbook

Web developers already live in running apps, local dev servers, screenshots, and browser proof. This pack turns the taught image-to-design handoff into concrete flows where a selected reference image guides the code diff and the browser proves the result.

Original source pages and recordings require authorized access. The full article text here is public.

Web developers already live in running apps, local dev servers, screenshots, and browser proof. This pack turns the taught image-to-design handoff into concrete flows where a selected reference image guides the code diff and the browser proves the result.

Core principles

Copy-paste workflow

When to use: When you can recognize the look you want but can't spec exact CSS. Generate a sheet of visual variations, pick the direction, and hand that concrete reference image to a coding agent to implement only that direction.

Copy-paste prompt

Help me do an image-to-design handoff for <COMPONENT/SCREEN>. I can recognize the look I want but can't spec the CSS, so we'll let a selected reference image carry my taste.

1. Ask an image model for a SHEET of 5 visual variations of <COMPONENT/SCREEN> in one image (vary layout, color, type, density).

2. Stop and let ME select the direction I like. (My selection expresses taste far better than a vague text prompt.)

3. Take the chosen reference image and implement ONLY that direction in code โ€” match its layout, spacing, color, and type. Do not blend in the other variations.

Guardrails:
- MCP-vs-CLI boundary: don't wrap a CLI in MCP just because MCP exists. Keep deterministic work in scripts/CLIs; reserve agents for judgment calls like this selection.
- Model-by-task-shape: use Codex for the coding follow-through; reserve fast Flash-class models for small, tightly scoped tasks only.

How it works

  • Step 1 asks an image model for a sheet of 5 variations of one component/screen at once.
  • Step 2 puts the human in the loop: selecting a direction expresses taste better than a vague prompt.
  • Step 3 hands the chosen reference image to the coding agent and constrains it to implement only that direction.
  • Taught caution โ€” the MCP-vs-CLI boundary: don't wrap a CLI in MCP just because MCP exists; keep deterministic work in scripts/CLIs and reserve agents for judgment.
  • Model-by-task-shape: Codex for coding follow-through, fast Flash models only for small scoped tasks.
  • Reference: Google Gemini video/image prompting, Codex CLI.

Scenarios

Dashboard card from selected reference

Role: As a frontend engineer maintaining a Next.js product dashboard

A billing or usage card in a real dashboard route works correctly but looks generic and has drifted from the product direction. You have a screenshot of the current component and either a selected reference image already chosen by the human or permission to generate a sheet of variations and pause for selection.

As a frontend engineer, I want Codex to implement one selected visual direction for the dashboard card while preserving existing data and behavior, so that the UI improves without turning a working component into a risky rewrite.

Agent brief

Copy-paste to Codex:

Use the image-to-design handoff workflow for the dashboard card at <ROUTE>, backed by these artifacts: current screenshot <CURRENT_SCREENSHOT_PATH>, selected reference image <SELECTED_REFERENCE_IMAGE_PATH>, and relevant source files <COMPONENT_OR_ROUTE_PATHS>.

1. Inspect package.json and the current component/source before editing. Treat the live code as source of truth for props, data loading, auth, events, and tests.
2. If <SELECTED_REFERENCE_IMAGE_PATH> does not exist yet, ask an image model for one sheet of 5 visual variations of this exact card based on <CURRENT_SCREENSHOT_PATH>, then stop and ask me which direction to use. Do not implement until I pick one.
3. Once the selected reference exists, implement ONLY that direction. Match layout, spacing, color, type, density, border/radius, and visual hierarchy. Do not blend in other variations. Preserve existing copy, links, data-testid values, analytics attributes, and behavior unless a markup change is necessary for accessibility.
4. Run `npm run lint`. Run the nearest existing test command from package.json if one is already present; do not invent a test framework.
5. Run `npm run dev` and prove the result in a browser at `http://127.0.0.1:3000<ROUTE>` or the port printed by the dev server.

Expected output: a focused diff, the commands run, a browser screenshot saved as `artifacts/image-to-design-dashboard-card.png`, and a short review note listing inspected files plus any intentional differences from the reference.

Implementation references

Open reference

Open reference

Open reference

package.json
<COMPONENT_OR_ROUTE_PATHS>
<CURRENT_SCREENSHOT_PATH>
<SELECTED_REFERENCE_IMAGE_PATH>

Browser verification

Use a CMUX browser pane or an agent-browser-style flow: open http://127.0.0.1:3000<ROUTE>, take an accessibility snapshot to confirm the card title, values, and CTA names are still present, then use evaluate to capture bounding boxes and computed styles for the card root, heading, primary value, and CTA. Save a screenshot after the DOM proof; a screenshot alone is not enough.

Definition of done

  • Git diff is limited to the target component/route and supporting style files.
  • npm run lint passes, and any pre-existing nearest test command either passes or the failure is documented with exact output.
  • artifacts/image-to-design-dashboard-card.png shows the local route matching the selected reference direction closely enough for human review.
  • Browser proof includes accessibility snapshot evidence that labels, values, links, and CTA names were not lost.
  • Review note explicitly says which reference image was used and confirms no other variation was blended in.

Failure modes and mitigations

  • The agent averages several generated directions into a mushy UI; mitigate by removing non-selected references from context and repeating: implement ONLY <SELECTED_REFERENCE_IMAGE_PATH>.
  • The agent rewrites data loading or auth while chasing the visual target; mitigate by requiring source inspection first and rejecting diffs outside the target UI/styling surface.
  • The agent claims visual success from code only; mitigate by requiring browser screenshot plus accessibility snapshot/evaluate evidence from the running dev server.

Auth-gated onboarding visual refresh

Role: As a full-stack product engineer responsible for a SaaS onboarding flow

The onboarding flow behind login is functional, but the organization setup step needs to match a selected generated reference image. The proof has to run through the real browser flow because the page depends on auth state, form validation, redirects, and route guards.

As a product engineer, I want the agent to apply the selected image direction to the onboarding step and verify it through login and form interaction, so that the visual refresh does not break the first-run user path.

Agent brief

Copy-paste to Codex:

Apply image-to-design handoff to the onboarding screen at <ONBOARDING_ROUTE>. Artifacts: selected reference image <SELECTED_REFERENCE_IMAGE_PATH>, current screenshot <CURRENT_SCREENSHOT_PATH>, explicit login or seed instructions <AUTH_INSTRUCTIONS>, and source hints <AUTH_FILES_AND_ONBOARDING_FILES>.

1. Inspect the route, auth guard, form component, validation messages, and existing tests before editing. Do not assume browser cookies are shared with the automation environment.
2. Implement ONLY the visual direction in <SELECTED_REFERENCE_IMAGE_PATH>. Preserve the onboarding state machine, validation behavior, submit handlers, redirects, copy, and analytics/data attributes.
3. If a selected reference is missing, generate one sheet of 5 visual variations for this onboarding step, then stop for human selection before editing code.
4. Run `npm run lint`. If package.json already defines a relevant test, run that exact script. Do not add a new browser framework just to prove this change.
5. Run `npm run dev`. Verify in a browser from login through <ONBOARDING_ROUTE> using <AUTH_INSTRUCTIONS>.

Expected output: focused UI diff, command logs, `artifacts/onboarding-before-or-current.png` if available, `artifacts/onboarding-after-selected-reference.png`, and a short proof note covering login, validation, successful submit or expected blocked submit, and any console/dev-server errors.

Implementation references

Open reference

Open reference

Open reference

package.json
<AUTH_FILES_AND_ONBOARDING_FILES>
<AUTH_INSTRUCTIONS>
<CURRENT_SCREENSHOT_PATH>
<SELECTED_REFERENCE_IMAGE_PATH>

Browser verification

Use agent-browser-style actions: snapshot the login screen, fill the explicit test email/password or complete the provided seed-login path, click through to <ONBOARDING_ROUTE>, snapshot the form, fill a realistic organization name, click Continue, and evaluate that validation text, focus state, and redirect/blocked-submit behavior still match the original flow. This is the right proof because auth, route guards, and form behavior cannot be trusted from a static screenshot.

Definition of done

  • Browser path starts from an unauthenticated state and reaches the onboarding screen through the documented login or seed flow.
  • The refreshed onboarding screen visually follows the selected reference image while preserving form labels, validation, focus states, and submit behavior.
  • npm run lint passes and relevant existing tests pass or exact failure output is included.
  • Screenshot and browser snapshot artifacts are saved under artifacts/ with names tied to the route.
  • The final note calls out that cookies were not assumed and names the auth path used.

Failure modes and mitigations

  • The browser agent gets stuck because it expects the human's normal cookies; mitigate by giving explicit auth/seed instructions and starting proof from a clean browser state.
  • The visual refresh hides validation or keyboard focus states; mitigate by tabbing through the form and evaluating visible focus/validation output before declaring done.
  • The agent changes redirects or submit logic while editing the screen; mitigate by diff-reviewing handlers and requiring the browser path to prove submit or expected blocked submit.

Responsive marketing hero handoff

Role: As a growth-focused web developer shipping a marketing route

A landing page hero needs to move from vague direction like 'more premium' to a concrete selected image. The desktop composition is the design target, but the implementation also needs mobile proof because the route is public and responsive.

As a growth developer, I want the agent to translate one selected hero reference into the actual landing page while preserving CTA behavior and responsive layout, so that the shipped page has a clear visual direction and does not break conversion paths.

Agent brief

Copy-paste to Codex:

Implement the selected image-to-design direction for the marketing hero at <MARKETING_ROUTE>. Artifacts: selected reference image <SELECTED_REFERENCE_IMAGE_PATH>, current route screenshot <CURRENT_SCREENSHOT_PATH>, and relevant source files <HERO_ROUTE_AND_COMPONENT_FILES>.

1. Inspect package.json, the hero route/component files, and any shared button/link components before editing. Preserve copy, hrefs, tracking attributes, data-testid values, and form/newsletter behavior.
2. If there is no selected reference image, ask an image model for a sheet of 5 hero variations from the current screenshot and product constraints, then stop for human selection.
3. Implement only the selected direction. Match composition, rhythm, spacing, type scale, contrast, image/illustration treatment, and CTA prominence. Do not introduce a maintained design system or broad route-variant workflow for this task.
4. Run `npm run lint` and any existing route/component test script listed in package.json.
5. Run `npm run dev` and prove desktop and mobile in the browser.

Expected output: a focused diff, desktop screenshot `artifacts/hero-desktop-selected-reference.png`, mobile screenshot `artifacts/hero-mobile-selected-reference.png`, command output, and a concise implementation note describing how the selected image was translated into code.

Implementation references

Open reference

Open reference

Open reference

package.json
<HERO_ROUTE_AND_COMPONENT_FILES>
<CURRENT_SCREENSHOT_PATH>
<SELECTED_REFERENCE_IMAGE_PATH>

Browser verification

Use a local browser, CMUX browser pane, or Playwright if already present. Open http://127.0.0.1:3000<MARKETING_ROUTE> at 1440x900 and 390x844. Take screenshots at both sizes. Use evaluate to assert document.documentElement.scrollWidth <= document.documentElement.clientWidth, the primary CTA is visible without horizontal scroll, and the CTA href/data attributes are unchanged.

Definition of done

  • Desktop and mobile screenshots are both saved and reviewable.
  • No horizontal overflow at the mobile viewport.
  • Primary CTA remains visible, clickable, and wired to the original href or handler.
  • npm run lint and any relevant existing test script pass or include exact failure logs.
  • Final review note maps the selected image's visible traits to concrete implementation choices: spacing, type, color, layout, and CTA treatment.

Failure modes and mitigations

  • The agent overfits the desktop reference and breaks mobile; mitigate by making mobile viewport proof part of done, not a later nice-to-have.
  • The agent replaces tracked links/buttons while restyling; mitigate by preserving hrefs, handlers, data-testid values, and analytics attributes and checking them with browser evaluate.
  • The agent turns a one-screen handoff into a broad design-system rewrite; mitigate by limiting scope to <HERO_ROUTE_AND_COMPONENT_FILES> and the selected image direction.

Implementation notes

  • Keep the technique narrow: image sheet, human selection, implement only the selected reference, browser proof.
  • For web apps, the selected image is not enough. The agent must inspect current source first so it preserves data loading, auth, handlers, copy, tests, and route behavior.
  • Use Codex or a persistent coding agent for the implementation pass. Fast Flash-style models are a poor fit for a multi-step UI implementation that may require self-correction.
  • Use deterministic scripts and browser checks for proof. Do not wrap a direct CLI or test command in MCP just because MCP is available.
  • Do not claim pixel perfection. Ask for concrete evidence: screenshots, accessibility snapshots, computed style or bounding-box checks, command logs, and a short diff review note.
  • When auth is involved, do not assume cookies are available. Provide explicit login, seed, or test-account instructions and prove the flow from a clean browser state.
  • Generated reference images can express taste, but the human selection is the decision point. The agent should stop before implementation when no selected reference exists.

Boundaries and caveats

  • Do not turn this into an Impeccable or Google Stitch tutorial. Impeccable was only lightly highlighted, and the lesson did not teach a full npx impeccable workflow.
  • Do not introduce Google Stitch, Executor, Clicklight, pi.dev, or broad tool comparisons as required implementation steps for this topic.
  • Do not use a maintained Storybook/design-system expansion as the default answer; that is beyond this one toolkit technique.
  • Do not let the agent blend several generated variations. The handoff depends on one selected reference image.
  • Do not change business logic, auth, analytics, or data fetching unless the requested visual handoff explicitly requires it.
  • Do not hide behind an MCP wrapper when a direct repo-local command, browser check, or script is clearer and easier to verify.
  • Do not treat browser screenshots as the only proof for interactive web flows; include snapshot/click/fill/evaluate evidence where interaction matters.

Agent reference map

Image-to-design handoff prompt

Use as the base copy-paste workflow: generate a sheet, pause for human selection, then implement only the chosen reference image.

Open reference

Lesson 06 validated references

Grounds the scenarios in the taught concepts: CMUX orchestration, model choice by task shape, generated images as design references, video context, and MCP-vs-CLI boundaries.

Open reference

Lesson 06 validation notes

Use this to avoid reintroducing items that were only mentioned or softened, especially around Impeccable, Google Stitch, Executor, Clicklight, and pi.dev.

Open reference

Packed source bundle

Use as the local bundle snapshot when an agent needs the prompt, references, catalog context, and Gemini analysis in one place.

/mnt/data/scenario-image-design.txt

CMUX browser or pane state

Use when the agent needs to identify the current pane or coordinate browser proof from a CMUX workspace.

cmux --json tree

Browser verification primitive shape

Use for web proof after implementation: snapshot for accessible structure, click/fill for flows, evaluate for DOM/style assertions, and screenshot for human visual review.

agent-browser-style workflow: snapshot -> click/fill -> evaluate -> screenshot

Source references