21.1 Image inputs for debugging UI issues

Goal: use screenshots to shorten the debugging loop

UI bugs are often hard to describe precisely in text. A screenshot removes ambiguity. The model’s best contribution here is:

turning a screenshot into a small set of testable hypotheses and a minimal change plan.

Do not ask for “the fix” first. Ask for a diagnosis you can verify in DevTools, then apply a minimal diff.

What the model can and can’t infer from a screenshot

A screenshot is a snapshot of pixels. From that, the model can often infer:

• layout symptoms (overflow, misalignment, clipping, stacking issues),
• visual hierarchy issues (contrast, spacing, density),
• common responsive problems (breakpoints, fixed widths, long strings).

But it cannot reliably infer:

• your actual HTML structure and CSS specificity,
• computed styles, layout constraints, or JS-driven measurements,
• which CSS framework utilities are active,
• dynamic states (hover, focus, loading) unless you show them.

Build a UI screenshot pack

Before you prompt, build a small pack so the model can be specific:

• Screenshot(s): include the broken state; include the correct state if possible.
• Viewport info: width/height, device, browser.
• Expected behavior: one sentence.
• Component name/path: where this exists in your app.
• Constraints: “Tailwind only,” “no markup changes,” “must support Safari,” etc.

If you can add one extra artifact, make it a DevTools “computed styles” excerpt for the problem element (or the CSS for the component). That turns guesses into targeted suggestions.

Prompt for diagnosis (not fixes)

Force the model to produce a diagnosis you can verify. Good diagnosis outputs include:

• 3–5 likely causes, ranked by likelihood,
• what in the screenshot suggests each cause,
• the cheapest DevTools check to confirm/deny each cause,
• the single best next inspection step.

This keeps you in control and prevents random changes.

Translate diagnosis into a minimal diff

Once you’ve confirmed a cause, ask for a minimal diff with guardrails:

• Scope: “Change only component styles; do not refactor layout globally.”
• Budget: “At most 10 lines changed.”
• Compatibility: list browsers/devices that must be supported.
• Regression: ask for one quick regression check (manual or automated).

Verification steps (don’t skip)

For most UI bugs, the fastest reliable verification set is:

• Reproduce on the target viewport (same width/zoom).
• Confirm the cause in DevTools (computed style / layout panel).
• Apply the minimal diff and re-check the screenshot scenario.
• Check one adjacent viewport (slightly smaller/larger) to avoid breakpoint regressions.
• Check one “long content” case (long labels, large numbers, localization).
• Capture a ship point: a “before/after” screenshot in the PR or changelog.

Copy-paste prompts

Prompt: screenshot → ranked hypotheses + DevTools checks

You are helping me debug a UI issue. Do NOT propose a full rewrite.

I will provide:
- A screenshot of the broken UI
- Environment details (viewport/browser)
- The expected behavior
- Constraints (framework, what I can/can’t change)

Task:
1) Provide 3–5 ranked hypotheses for what’s causing the issue.
2) For each hypothesis:
   - what in the screenshot supports it
   - the cheapest DevTools check to confirm or deny it
3) Recommend the single best next inspection step.

If you cannot be confident from the screenshot, ask for exactly what extra info you need (specific element CSS, DOM snippet, computed styles).

Prompt: confirmed cause → minimal diff

We confirmed the root cause is: [describe confirmed cause].

Constraints:
- Framework: [e.g., Tailwind/CSS Modules/etc]
- Allowed changes: [CSS only / markup allowed / no new deps]
- Change budget: [e.g., <= 10 lines changed]
- Must support: [browsers/devices]

Task:
1) Propose the smallest change that fixes the issue.
2) Explain why the change works (in terms of layout rules).
3) List 3 quick regression checks I should run (viewports/states).
Return only the patch plan (no extra suggestions).

Optional: force a structured diagnosis

Return your diagnosis as JSON with this schema:
{
  "observations": string[],
  "hypotheses": [{
    "rank": number,
    "cause": string,
    "evidence_from_screenshot": string,
    "confirm_in_devtools": string,
    "deny_in_devtools": string
  }],
  "best_next_step": string,
  "missing_info_needed": string[]
}

Anti-patterns

• “Fix this” with no constraints (you’ll get a rewrite).
• Single screenshot, no environment (mobile vs desktop bugs look similar).
• No expected behavior (the model guesses what “correct” means).
• Skipping verification (“looks fine” is not a test).

Where to go next

• 21.4 Visual test case generation (turn fixes into test coverage)
• Reference: debugging loop fundamentals