visual-review

Visual Review

Browser QA for changed UI. Hooks catch static smells; this catches composed UI bugs that need seeing + interaction. See REFERENCE.md for environment fingerprint, platform risk map, ecosystem wiring.

Run

Standalone trigger OK: /visual-review. Also run before /commit-push-pr when diff touches rendered UI: *.tsx, *.jsx, *.css, *.scss, *.html; src/routes/, src/pages/, src/app/, src/components/, components/ui/; Tailwind/theme/config files that affect visuals. Skip only docs-only, test-only, type-only, backend-only, or explicit skip reason.

Inputs

Accept route/component hints. If omitted: inspect git diff --name-only HEAD; map route files to URLs when obvious; map component edits to nearest affected route/story/test; if route cannot be inferred, ask one concise question.

Review matrix

Minimum:

• Chromium desktop; Chromium mobile viewport; keyboard-only pass: Tab, Shift+Tab, Enter, Space, Escape.
• console/network error scan; loading, empty, error, dense-data state where reachable.
• form submit path when form UI changed; notification/toast path when feedback UI changed.

Prefer when feasible:

• Firefox desktop; WebKit/mobile Safari equivalent.
• reduced motion; dark/light mode; high contrast or forced colors.
• text zoom or larger default font when typography/layout changed.
• RTL or localized-long-text sample when copy/layout changed.
• back/forward navigation when route/search/theme/storage changed.
• slow network/media throttling when images/video/loading changed.

Use project scripts first: scripts/skills-browser.sh, Playwright, bun run dev. Never ask user to verify visual UI manually when tools can.

Inspect

Layout/polish

• horizontal overflow; clipped popovers; sticky/fixed overlap; safe-area issues on mobile bottom/top UI.
• viewport unit bugs: 100vh, virtual keyboard, scrollbars, writing mode.
• layout shift from skeletons, images, lazy video, fonts, accordions, tabs.
• broken dense tables/cards/lists; captions/headers still explain tables.
• dark/light contrast and token consistency; text scaling, zoom, system font and OS default font behaviour.
• CSS shorthand/complex layout edits remain readable and intentional.

A11y/semantics

• accessible names match visible intent; native semantics first; ARIA only when needed.
• aria-label not used on static/generic elements and not hiding visible text.
• labels connect to inputs; password managers/autofill still work.
• disabled vs aria-disabled behaviour clear and keyboard-safe.
• focus order, focus trap, Escape/close paths, no surprise autofocus.
• buttons/links do not nest; links look and behave like links.
• dialogs, popovers, custom selects, tabs, tables, forms.
• forms submit correctly via Enter, buttons, and requestSubmit()-style paths.
• toasts/notifications announced, persistent enough, not sole carrier for critical actions.
• text effects, transforms, uppercase, strikethrough, emoji, generated content do not harm screen-reader output.
• SVG/icons/images have meaningful names or are hidden decoratively.

Browser/platform

• Firefox/Safari differences, not just Chromium; in-app browser/WebView quirks when relevant.
• viewport/virtual-keyboard issues on mobile forms; bfcache/back-forward state for theme/auth/search params.
• smooth scrolling, scroll snapping, scrollIntoView, overscroll, and scrollbar-gutter side effects.
• view-transition/reduced-motion behaviour and interaction blocking.
• popover/dialog/select/native-control behaviour across browsers.
• unsupported Baseline/new platform features have fallback or feature detection.

Perf-sensitive UI

• responsive images dimensions/sizes/lazy/preload rules.
• responsive video/media has controls, captions where needed, and stable aspect ratio.
• important images not hidden as CSS backgrounds when they need priority/alt.
• large data URLs/assets, render-blocking additions, third-party embeds/scripts.
• obvious Core Web Vitals risks: LCP image, CLS, INP/long interaction.
• animation cost: transform/opacity preferred, no motion that ignores reduced-motion.
• font loading: fallback, size-adjust/layout shift, oversized custom fonts.

Heuristics

HTML first. User agents vary. State beats happy path. Motion is interaction. Content stress wins. Accessibility automation is partial. Performance is visual. If seen twice, automate.

Output

Return concise report:

## Visual review
Status: ready | needs fixes | blocked
Changed UI: <routes/components>
Checked: <browser/viewport/state list>
Findings: | Severity | Area | Finding | Evidence | Fix |
Screenshots: | View | Browser | Path | Notes |
PR notes: <rows usable in /commit-push-pr screenshot table>
Automation candidates: <repeatable misses worth hook/eval/docs>

Severity: P0 blocks use/security/data loss. P1 fix before PR. P2 fix if low-risk else note. P3 advisory.

Finish

P0/P1 fixed or user accepted. Screenshot evidence captured for visual changes when app runnable. Skip reasons recorded for unrun matrix items. Recurring deterministic issue suggested as hook/eval follow-up.