ui-visual-review

UI Visual Review

A coding agent can't fix what it can't see. Qt layout reads fine in source and still renders with dead space, clipped labels, full-width inputs, or buttons shoved off-screen. The only reliable way to catch that is to render the screen to an image and look at it. This skill is that loop.

The loop

1. Locate the target widget / dialog / panel in the codebase. If the user handed you a screenshot instead, view it and jump to step 4.
2. Render it to PNG(s) with the offscreen harness (scripts/snap.py). No running app and no display are required — see references/pyside.md.
3. Render the states that actually break:
   • the real on-screen size (not the default sizeHint);
   • maximized / large — tables and content sprawl edge-to-edge here (L5/L6);
   • empty / typical / overflowing data;
   • for dock/settings panels, a narrow width (~280–320 px).
4. View every PNG.
5. Critique against ui-design-standards. Name each violation as rule-ID + widget + concrete fix.
6. Fix the source — smallest change that satisfies the rule.
7. Re-render and re-view. Confirm the fix landed and nothing regressed. Loop 4–7 until the screen passes the checklist.
8. Report before/after with the rule IDs you resolved.

Never declare a UI "fixed" without a fresh screenshot proving it.

The whole trick (offscreen rendering)

import os
os.environ["QT_QPA_PLATFORM"] = "offscreen"   # MUST be set before importing Qt
# ... build the widget, apply the real theme ...
widget.grab().save("shot.png")                # render to an image, no window

widget.grab() paints the widget into a pixmap with no visible window and no GPU. It works in CI and in a headless agent run. Standard widgets and QGraphicsView render fully offscreen; QOpenGLWidget / live matplotlib GL content needs a real display (use qt-mcp live mode for those — see below).

Two modes

• Offscreen (default). Use scripts/snap.py. Best for iterating on layout: deterministic, scriptable, needs no running app. This is what you'll use 90% of the time. Details + recipes: references/pyside.md.
• Live / interactive. If the app is running and instrumented with the qt-mcp probe, use the qt_* MCP tools to screenshot real windows, walk the widget tree, run qt_layout_check, and click/type through real states. Details: references/qt-mcp.md.

Using the harness

scripts/snap.py is a ~40-line, dependency-free template. Copy it into the project (or run it in place), replace main() with your real screens, point it at the project's apply_theme, and call shoot(widget, name, size) per state. It writes PNGs into a shots/ folder for you to view.

Always render with the project's real theme applied — an unthemed snapshot hides spacing/contrast problems and invents others.

Common Qt gotchas this loop catches

• Stray addStretch() between fields → floating content / dead space (S1).
• Inputs with Expanding size policy and no max width → full-width boxes (L1).
• Missing minimumWidth → panel clips instead of wrapping when narrowed (R1).
• Back/Next on opposite ends of a tall layout → Next off-screen when narrow (R2/A1).
• QFormLayout.setLabelAlignment(0x0002) and similar raw-int enum calls → TypeError on modern PySide6; pass Qt.AlignmentFlag (e.g. Qt.AlignRight). The harness surfaces these because it actually instantiates the widget.

Interaction & state testing (not just static shots)

A screenshot can't reveal "I clicked Assign and nothing happened" or "the button is dead when only one row is checked." Those are interaction bugs (rulebook section I). To catch them you must drive the UI, not just photograph it:

• Enumerate selection states — empty / one / some / all / max — and for each, check button enablement (I1/I3) and run the action.
• Verify feedback (I2). After the action, confirm something visible changed: status cells update, a log line appears, the model actually mutated. Screenshot before and after and compare.
• How to drive it:
  • Live (best): qt-mcp — qt_click the checkbox, qt_click "Assign", qt_screenshot before/after, qt_widget_details to confirm new state.
  • Headless: in snap.py, set the selection in code (check items / set the model), call the same slot the button invokes, re-render, and assert the status changed. Pair with the desktop-gui-testing skill for signal/slot and geometry assertions.
• Reason about it first. Write down what should happen in each state before testing — that's the "be intelligent" step that turns a happy-path screen into a correct one.

Beyond review: agent-in-the-app (Phase 2)

To let the running app itself host an agent that inspects and rewrites its own UI (a toggleable "Design Mode"), see references/in-app-agent-sdk.md — the Claude Agent SDK + the qt-mcp probe + these skills.