# UI Review Standard Use this standard whenever a chunk changes visible frontend UI, including components, themes, navigation, forms, layouts, dialogs, app shell behavior, admin UX, or frontend visual states. UI review is mandatory for visible frontend changes. Keep it proportional, but do not skip it because unit tests pass. ## Review Order Run UI review in this order: 1. Structural / DOM / component review. 2. Heuristic layout and accessibility review. 3. Browser smoke. 4. Screenshot capture and review after structure and heuristics look reasonable. 5. Optional human/reference comparison for major UX, theme, app-shell, admin, or design-direction work. Cheap structural checks come first. Screenshot review is higher value after the DOM, routing, role visibility, and basic component states are plausible. ## Developer Responsibilities For visible frontend changes, Developer must: - identify affected screens, routes, components, and states. - inspect component and DOM structure. - inspect role visibility and navigation behavior when relevant. - inspect forms, validation, focus, disabled, loading, empty, and error states when relevant. - inspect mobile responsiveness basics. - run browser smoke when a browser runner or runtime smoke path exists. - capture screenshots after structural and heuristic checks pass when screenshot requirements apply. - summarize UI review findings and gaps in `## Test Impact` or `## Execution Notes`. If Playwright/browser smoke or screenshot tooling is unavailable, state that explicitly and explain whether the gap is acceptable for the chunk or needs a follow-up tooling chunk. ## QA Responsibilities For visible frontend changes, QA must: - review DOM/component structure and role/navigation behavior. - review browser smoke and screenshots when applicable. - inspect layout consistency, spacing, hierarchy, and visual coherence. - inspect navigation, dropdowns, forms, dialogs, and theme distinctions. - inspect mobile usability basics. - compare against stated design direction or references when the chunk changes UX direction. - block when the UI is incoherent, inaccessible, not human-verifiable, or materially contradicts the stated design direction. ## Heuristic Checklist Apply these checks pragmatically: - spacing rhythm is consistent. - alignment is deliberate and stable across breakpoints. - typography has clear scale, weight, and rhythm. - visual hierarchy makes the primary task obvious. - navigation labels and destinations are clear. - forms are readable, labeled, keyboard usable, and have visible focus/error states. - dropdowns and menus are discoverable, usable, and role-aware where applicable. - hover, focus, loading, empty, disabled, and error states are coherent. - mobile layouts stack predictably without cramped or overlapping content. - themes are visibly distinct when theme identity is in scope. - component-library defaults do not leak as raw, unpolished UI. - card, button, input, badge, table/list, and alert language is consistent. - layouts are not giant crowded panels without grouping or hierarchy. - empty/loading/error states are not broken, misleading, or absent where expected. ## Screenshot Requirements Screenshot or browser visual review is required when a chunk changes: - themes. - app shell or navigation. - dropdowns, dialogs, forms, or menus. - admin UX. - page layout or visual hierarchy. - UI foundation components. - mobile layout behavior. - major user/operator workflows. For major UI work such as Lumen theme, navigation redesign, Remote Dev Operator Console, admin UX, or design-system foundation, include screenshot review and a short comparison against stated references or direction such as Laravel, WorkOS, Railway, PrimeNG, or the active requirements. ## Browser Smoke Browser smoke should verify the changed UI in the most realistic available path: - app loads without page errors. - affected route/view renders. - relevant interaction works, such as theme switching, dropdown open/close, form input, or role-gated navigation. - relevant desktop and mobile viewport basics are checked. Use Playwright or another approved browser runner when available. If no browser runner exists, use the closest available runtime/manual path and document the gap. Passing component tests alone is not enough for significant visual changes. ## Managed Dev Server And Screenshot Path For local/dev browser smoke and screenshots, follow `ai/standards/local-dev-runtime.md` and use the canonical dev-server helpers in `ai/tools/dev-server/` before falling back to ad hoc terminals: ```sh ai/tools/dev-server/status.sh frontend ai/tools/dev-server/start.sh frontend ai/tools/dev-server/restart.sh frontend ai/tools/dev-server/wait-url.sh http://127.0.0.1:4220/ ``` If Codex cannot see the trusted runtime tmux sessions or localhost servers from its sandbox, those failures are advisory only. Request trusted status or screenshot capture through `ai/tools/operator-daemon` and use the daemon result as the source of truth. The helpers use named tmux-managed sessions when tmux is available, write logs under `/tmp`, avoid duplicate managed servers, and report unmanaged port conflicts without killing unrelated processes. Lifecycle guidance: - Small CSS-only changes may reuse a verified running managed server. - Routing, auth/session, GraphQL/codegen, backend, environment/config, Dev Console, or major UI changes should restart the managed server cleanly. - Before screenshots, ensure the managed server is running, verify the URL from the same command context used for screenshot capture, then capture screenshots. Known-good Runtime-owned browser proof path: ```sh node ai/runtime/dist/cli.js testing runtime-action-panel-browser-smoke --json ``` Do not rely only on `command -v playwright`, `command -v chromium`, or `command -v google-chrome`; these checks can be misleading when Playwright is available through the pinned repo dependency and browser cache. Future UI chunks must use a Runtime-owned browser proof method when one exists. Ad hoc `npx playwright` commands are diagnostics only and are not canonical proof. For Angular, PrimeNG, RxJS, Apollo Angular, and browser-proof selector work, consult `ai/references/frontend-frameworks/` and `ai/references/framework-reference-policy.md` before inventing local patterns. Screenshots, temporary Playwright specs, route mocks, storage-state files, and logs must be written to `/tmp` or another ignored runtime location and must not be staged. For authenticated pages, temporary `/tmp` Playwright specs, storage state, or route mocks are acceptable when they avoid leaking secrets and keep repo state clean. When screenshot/browser validation fails, record the exact command and exact error. Do not summarize the blocker as "browser tooling absent" unless the Runtime-owned browser proof path and managed dev-server path were both tried or shown to be inapplicable. ## DRY Ownership This file owns UI-review policy. Roles, templates, and other standards should reference this standard instead of restating the full pipeline or heuristic checklist.