UI Review

Codex compatibility note:

• Invoke repository skills with $skill-name in Codex; this mirrored copy rewrites legacy Claude /skill-name references.
• Task tracker mandate: BEFORE executing any workflow or skill step, create/update task tracking for all steps and keep it synchronized as progress changes.
• User-question prompts mean to ask the user directly in Codex.
• Ignore Claude-specific mode-switch instructions when they appear.
• Strict execution contract: when a user explicitly invokes a skill, execute that skill protocol as written.
• Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required spawn_agent subagent(s) for that task.
• Do not skip, reorder, or merge protocol steps unless the user explicitly approves the deviation first.
• For workflow skills, execute each listed child-skill step explicitly and report step-by-step evidence.
• If a required step/tool cannot run in this environment, stop and ask the user before adapting.

Codex Project-Reference Loading (No Hooks)

Codex uses static project-reference loading instead of runtime-injected project docs. When coding, planning, debugging, testing, or reviewing, open project docs explicitly using this routing.

Always read:

• docs/project-config.json (project-specific paths, commands, modules, and workflow/test settings)
• docs/project-reference/docs-index-reference.md (routes to the full docs/project-reference/* catalog)
• docs/project-reference/lessons.md (always-on guardrails and anti-patterns)

Missing/stale context route: If docs/project-config.json, the docs index, lessons.md, CLAUDE.md, AGENTS.md, or any task-required reference doc is missing or stale, auto-run $project-init or the narrow setup route ($project-config, $docs-init, $scan-all, $scan --target=<key>, $claude-md-init) before ordinary project-specific work. If Codex mirrors or AGENTS.md are missing/stale, ask the user to run $sync-codex; do not auto-run it.

Situation-based docs:

• Project structure/architecture/tech-stack/deployment/setup (any layer — backend, frontend, or infra): project-structure-reference.md
• Backend/CQRS/API/domain/entity changes: backend-patterns-reference.md, domain-entities-reference.md
• Frontend/UI/styling/design-system: frontend-patterns-reference.md, scss-styling-guide.md, design-system/README.md
• Spec authoring, docs/specs/ pathing, or TC format: feature-spec-reference.md, spec-system-reference.md, spec-principles.md
• Behavior/public-contract changes or spec-test-code sync: workflow-spec-test-code-cycle-reference.md plus the spec docs above
• Derived spec indexes/ERDs/reimplementation guides: spec-system-reference.md and source Feature Specs under docs/specs/
• Integration test implementation/review: integration-test-reference.md
• E2E test implementation/review: e2e-test-reference.md
• Code review/audit work: code-review-rules.md plus domain docs above based on changed files

Do not read all docs blindly. Start from docs-index-reference.md, then open only relevant files for the task.

[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. [BLOCKING] Before each step or sub-skill call, update task tracking: set in_progress when step starts, set completed when step ends. [BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason. [BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.

Quick Summary

Goal: Validate UI/frontend changes for the six visual-quality dimensions that break in production but slip past correctness review — long-content overflow & truncation, responsive multi-screen layout (flex-wrap / row-to-column so it stays usable on small devices), flex-grow vs fixed sizing, z-index scale discipline, SCSS/CSS/BEM styling quality, and async UI states & feedback (loading indicator, user-visible error surface, empty state, in-flight disable) — so frontend/UI changes survive real content, responsive layouts, layering, styling conventions, and the loading/error/empty branches before handoff.

Default scope: All uncommitted frontend changes (staged + unstaged) matching the frontend path and file-extension patterns declared by the project configuration/docs index. Override: specify files, directories, components, or full frontend codebase.

CONDITIONAL — SKIP when no frontend files in scope. In workflow context this skill is SKIPPED when the diff has no files matching the project frontend path/extension patterns. If invoked standalone with no frontend changes → announce "No frontend changes detected — ui-review skipped" and report clean.

ROUTING BOUNDARY (read before starting):

• ui-review (this skill) — the project UI review gate. Purpose: find issues, assign severity, give project-specific fix guidance citing real reuse targets (sourced from the project reference docs). It complements architecture-review. In workflow-review-changes it runs in TWO places by design (keep both): (a) INTERNALLY as changes-review's UI dimension (step 1), AND (b) as a DEDICATED conditional parallel-batch member (step 9, ui-ux-designer sub-agent). Both fire only when frontend files are in scope.
• web-design-guidelines — a generic, standalone accessibility / UX checklist. Cross-read it for a11y depth (WCAG, focus order, ARIA, contrast); do NOT duplicate its content here.
• ui-ux-designer — specialized UI/UX, accessibility, responsive layout, and design-token review/authoring sub-agent when the local agent catalog provides it.

MANDATORY MUST ATTENTION Plan tasks to READ UI rules BEFORE reviewing:

1. Project styling rules doc — BEM convention, mixins, variables, responsive patterns (READ FIRST — primary styling rules source; resolve via project config/docs index)
2. Project design-system/token doc — design tokens, especially the Z-Index & Layering section
3. Project frontend architecture/patterns doc — base component classes, state/store, API service, lifecycle teardown rules shared with architecture-review
4. Project code-review rules doc — anti-patterns and conventions

Not found → search: "scss styling", "design tokens", "frontend patterns". Rules come from docs — NOT general knowledge.

Workflow:

1. Phase 0: Load UI Rules — Resolve and read the four project UI/styling rule docs above
2. Phase 1: Determine Scope — Changed frontend files (default) or user-specified scope
3. Phase 2: Blast Radius — Run graph trace if graph.db exists
4. Phase 3: UI Category Review — Check each file against all 6 applicable categories
5. Phase 4: Finalize — Generate compliance report with PASS/BLOCKED/WARN verdicts
6. Fix Loop: Validate → Fix → Full UI Re-Review — validate findings first; after validated fixes, rerun the full UI review using the local sub-agent selection guide only when that protocol calls for agents

Key Rules:

• Write findings to plans/reports/ui-review-{date}-{slug}.md
• BLOCKED = must fix before merge | WARN = review and decide | PASS = compliant
• Every violation needs file:line proof + grep 3+ counterexamples before flagging
• Review is read-only until $why-review --validate-findings confirms findings; fixes may happen only in the validated fix loop or downstream plan/feature-implement, and every fix restarts a full UI review from Phase 0 with brand-new tasks.

Your Mission

First Principle — Easy to Change

The success metric of every coding decision is future change cost. DRY, SRP, abstraction, design patterns, naming, layering, tests — every technique exists to serve one goal: making the next change cheaper.

When evaluating styling, a layout, a token, or a component, ask: does this make the next change cheaper or more expensive?

• Reject "best practices" that raise change cost (hardcoded values forcing per-file edits, hand-rolled overflow handling, raw breakpoints, copy-pasted truncation CSS).
• Name the real enemies in findings: magic values, duplicated styling knowledge, fixed sizing that fights the viewport, cross-system token mixing, z-index escalation wars.
• A simpler layout that survives 320px and a 200-char value beats a pixel-perfect fixed layout that breaks on either.

Apply this lens before invoking any specific rule, pattern, or checklist below — if a downstream rule would raise change cost, this principle wins.

Review Mindset (NON-NEGOTIABLE)

Skeptical. Every claim needs traced proof, confidence >80%.

• NEVER flag a styling violation without reading the actual SCSS/template + tracing the rendered element
• Every finding MUST include file:line evidence
• Before flagging a pattern violation: grep 3+ existing examples — codebase convention wins
• Question: "Is this actually a violation, or an established exception (icon dimensions, fixed brand assets, genuinely fixed UI)?"

Phase 0: Load UI Rules (MANDATORY FIRST) (MUST ATTENTION)

MUST ATTENTION: Read project UI docs BEFORE reviewing. Rules come from docs, not general knowledge.

• read the project styling rules doc — extract BEM convention, mixin names, variable names, responsive breakpoint mixins, nesting limits
• read the project design-system/token doc — extract design tokens and the Z-Index & Layering section
• read the project frontend architecture/patterns doc — extract base component classes, store/effect patterns, API service base, lifecycle teardown pattern
• read the project code-review rules doc — extract frontend anti-patterns and review rules directly

CROSS-SYSTEM WARNING (carry through every category): Do NOT mix token systems with incompatible root-size, namespace, or layer assumptions in one file. When flagging a fix, recommend whichever token system the file already imports/uses; never introduce another system unless the project docs explicitly require migration.

Phase 1: Determine Scope

Default (no override): Review all uncommitted frontend changes.

git status          # List changed files
git diff            # Staged + unstaged changes
git diff --cached   # Staged only

• Collect file list to review
• Filter to files matching the project frontend path/extension patterns resolved from project config/docs
• If ZERO frontend files match → announce "No frontend changes detected — ui-review skipped" and report clean (honor the CONDITIONAL skip)

Phase 2: Blast Radius (if graph.db exists)

• If .code-graph/graph.db exists: run graph trace on key changed component files
• Record: impacted file count, shared-component fan-out (a changed shared-library component affects every consumer app), risk level
• Prioritize review by highest-impact files first (shared library components > app-local components)
• Graph unavailable: note "Graph not available — skipping blast radius" and proceed

For each changed component/style file with downstream impact:

python .claude/scripts/code_graph trace <changed-file> --direction both --json

Use --node-mode file first (10-30x less noise), then --node-mode function for detail. Flag shared-component consumers impacted by a styling or layout change.

Phase 3: UI Category Review

Create report: plans/reports/ui-review-{date}-{slug}.md

For EACH file in scope, evaluate against ALL applicable categories. Skip categories not applicable to the file type (e.g., a pure .ts store file skips overflow/sizing/z-index but still hits Category 5's architecture checks and Category 6's loading/error/empty-state wiring).

Apply the Think: reasoning prompt before each category — derive violations, do NOT recite checklists.

Category 1: Long-Content Overflow & Truncation — Severity: WARN (HIGH when a flex child truncates with no min-width: 0)

Think: Does every text container survive a 200-char value? Single-line or multi-line? Can the user still read the full value when it is truncated?

Detection signals:

• Hand-rolled text-overflow: ellipsis (with white-space: nowrap / overflow: hidden re-declared by hand) instead of the project mixin/directive
• A flex child that truncates but has NO min-width: 0 — the flex-overflow trap: a flex item's default min-width: auto refuses to shrink below content width, so ellipsis never triggers
• Truncated text with NO tooltip / title to reveal the full value

DECISION RULE the reviewer enforces:

• Single-line labels / table cells / chips → ellipsis + tooltip-on-overflow
• Multi-line prose / descriptions → wrap or -webkit-line-clamp

Project fix guidance (cite real reuse targets from the resolved styling rules doc):

• Prefer the project's documented overflow/ellipsis directive, component, or utility. It must expose the full value only when the element actually overflows and must handle the flex min-width trap.
• OR the project's documented truncate/text-ellipsis mixins or utility classes from the styling rules doc.
• Multi-line: use the project-documented clamp pattern.

GOOD vs BAD: a utility/token-driven truncation that exposes the full value on overflow (tooltip/title) is correct; a hand-rolled substring / width-math truncation, or truncated text with no tooltip, is the anti-pattern. Cite the styling rules doc for the project's reuse targets.

Category 2: Responsive Multi-Screen via Flex — Severity: WARN (BLOCKED only when content is broken on a small screen — clipped, cut off, or unreachable)

Think: Is this usable at 320 / 768 / 1024 / 1440? Does the layout flex, wrap, and reflow from row to column on small screens? If it genuinely cannot reflow, does it at least stay usable via a fixed min-width/min-height + overflow: auto scroll — or does content get clipped, cut off, or pushed out of reach?

Small-screen usability — the minimum bar (canonical):

• Preferred: reflow — flex-wrap: wrap, a flex-direction: row → column switch at the breakpoint, or a responsive grid that collapses to a single column.
• Acceptable fallback: when a layout genuinely can't reflow (dense tables, canvases, diagrams, wide data grids), a fixed min-width/min-height with overflow: auto is fine — scrolling is OK, not a defect. Do NOT flag a component BLOCKED merely because it scrolls.
• Hard minimum (BLOCKED if violated): on a small screen the UI is usable and nothing is broken — no clipped, cut-off, or unreachable content/controls (e.g. a submit button pushed off-screen with no scroll path, text overlapping, a fixed row that overflows AND hides content instead of scrolling).
• Escalation: if making a surface small-screen-usable would need a refactor too large for the current change, STOP and confirm scope with the user before proceeding — note it as a finding, do not silently rewrite the layout.

Detection signals:

• Raw @media (max-width: NNNpx) / (min-width: NNNpx) in component SCSS that bypasses the breakpoint mixins
• A multi-child flex row with NO flex-wrap, NO flex-direction: column override, AND no overflow: auto escape → content is trapped and clips on a phone (BLOCKED); the same row WITH a scroll escape is at most WARN (prefer reflow)
• Multi-column CSS grid with fixed column counts / fixed track widths and no single-column collapse and no scroll container at small breakpoints
• Non-flex fixed layouts (absolute positioning, fixed px widths on containers) that cannot reflow AND cannot scroll → content lost off-screen
• Content clipped, overlapping, or a control pushed out of reach below ~360px with no scroll path (BLOCKED). Horizontal scroll by itself, with all content still reachable, is the acceptable fallback — not a finding.

Project fix guidance:

• Preferred: the project documented responsive-flex mixins/utilities; add flex-wrap: wrap and/or the documented row → column breakpoint switch so the layout stacks vertically on small screens
• Fallback (when reflow isn't feasible): give the container a sensible min-width/min-height and overflow: auto so everything stays reachable by scroll
• Breakpoints from the project breakpoint tokens — NEVER inline pixel breakpoints
• Large layout refactor required → surface it as a finding and confirm with the user; don't bundle a big responsive rewrite into an unrelated change

Anti-patterns: raw @media pixel breakpoints that bypass the project's breakpoint mixins; a flex-direction: row with no wrap, no column fallback, AND no scroll escape so content clips; and non-flex fixed grids that neither reflow nor scroll. Cite the styling rules doc for documented offenders; grep the changeset for the same patterns.

Category 3: Flex-Grow vs Fixed Width/Height (prefer min/max) — Severity: WARN

Think: Must this size be fixed, or can it grow/shrink with content + viewport?

Detection signals:

• Fixed width: / height: in px (≥ ~3 digits) on containers / cards / forms / dialogs

Project fix guidance:

• Prefer flex: 1 / flex-grow + max-width / min-width caps, and min-width: 0 on truncating flex children
• The project flex-container mixin/utility documented in the styling rules doc
• Reserve fixed px for icons / borders / genuinely fixed UI

Anti-patterns: large fixed width: / height: in px on containers / cards / forms / dialogs (e.g. width: 964px, height: 772px) that should flex with content + viewport. Cite the styling rules doc for documented offenders.

Category 4: Z-Index Scale Discipline — Severity: BLOCKED (HARD GATE)

Think: Which layer does this surface belong to (base / raised / dropdown / sticky / modal / toast)?

Detection signals:

• Raw numeric z-index (literal value instead of a token)
• ANY z-index with !important → BLOCKED (an escalation war that the next dev will only beat with a bigger literal)

Project fix guidance — use tokens:

• The project documented z-index layer tokens
• Existing legacy/framework token systems only when the current file already uses that system
• The semantic layer variables declared canonical by the project design-system doc

Cross-reference the project design-system Z-Index & Layering map. The chosen token MUST match the surface's semantic layer.

GOOD vs BAD: a z-index set from a semantic token / layer scale is correct; a raw literal (e.g. z-index: 99999, z-index: 10000) or z-index: N !important is the anti-pattern. Cite the design-system and styling docs for the project's token scale and documented offenders.

Category 5: SCSS/CSS Best Practices & BEM — Severity: WARN (BLOCKED on !important, chained BEM modifiers)

Think: Does this stylesheet read cleanly, follow BEM, and use tokens — or does it hardcode, over-nest, and chain modifiers?

SCSS/BEM rules (canonical): BEM classes on ALL template elements (block__element--modifier). No magic numbers — use variables / design tokens. Max 3 nesting levels.

Detection signals:

• Nesting > 3 levels
• Hardcoded hex colors (should use CSS vars / design tokens)
• px where rem is expected
• Chained BEM modifiers (.block__element.--modifier) — .--mod MUST be a separate class, NEVER chained → BLOCKED
• Template elements missing BEM classes
• !important → BLOCKED

Apply fixes per the resolved project styling rules doc.

Frontend architecture checks (OWNED JOINTLY WITH architecture-review Category 8 — reference, do not drift):

These checks are lifted from architecture-review Category 8 so the two skills stay synchronized. They are owned jointly; when one changes, update both. They apply to the .ts files in scope:

• Components MUST extend the project-documented base component/form/store component classes (BLOCKED)
• State MUST use the project-documented store/effect pattern — NEVER ad hoc local state when the project provides a canonical store pattern (BLOCKED)
• API services MUST extend the project-documented API service base — NEVER raw HTTP clients when the project provides a service abstraction (BLOCKED)
• All subscriptions MUST use the project's auto-teardown operator — NEVER manual unsubscribe (BLOCKED)
• All template elements MUST have BEM classes (WARN)
• Logic in lowest layer: Model > Service > Component (WARN)

Category 6: Async UI States & Feedback — Loading / Error / Empty / Disabled — Severity: BLOCKED (HARD GATE when an async fetch or mutation renders NO loading indicator OR NO user-visible error surface)

This is the fundamental UI-resilience gate. A screen whose happy path renders perfectly but shows a frozen blank while loading, fails silently on error, or shows nothing when empty is a broken user experience. Every async or interactive surface MUST answer three questions for the user: what do I see while it's working, when it fails, and when there's nothing?

Think: For EACH async operation the file performs (data fetch, form submit, mutation, navigation-triggered load, subscription), trace what the user actually sees in the in-flight, failure, and zero-result branches — not just the success branch. If any of those three branches renders a blank/frozen screen or nothing at all, that is the finding.

The essential states every async/interactive surface MUST handle (canonical vocabulary — shared verbatim with design-spec "Component States Checklist": Default / Loading / Disabled / Error / Empty / Success):

• Loading — every in-flight async request MUST render a loading indicator (spinner / skeleton / progress bar), NEVER a frozen or blank screen. Lists/tables → skeleton rows; buttons → in-button spinner + disabled.
• Error — every operation that can fail (network, validation, server error) MUST surface a human-readable error to the user WITH a recovery/retry path where sensible. NEVER a silent failure, a swallowed catch, or a raw stack trace / raw error object rendered to the user.
• Empty — every collection / list / table view MUST render a meaningful empty state (message + optional CTA) when it has zero items, NOT a blank area.
• Disabled / in-flight guard — submit/action controls MUST disable (or show busy) while their request is in-flight, to prevent double-submission.
• Success — a completed mutation SHOULD give confirmation feedback (toast / inline / visibly updated data).

Detection signals:

• An async call (fetch / HTTP / subscribe / awaited mutation) whose template binds NO loading flag (isLoading / pending / loading$ / skeleton) → BLOCKED
• A .catch / try-catch / error callback that logs or swallows the error but renders NO user-visible error surface → BLOCKED
• A raw error shown to the user (stack trace, raw JSON, unmapped exception) → WARN
• A list/table rendered from a collection with NO empty-state branch (@empty, *ngIf="!items.length", items.length === 0 ? …) → WARN (BLOCKED when the collection is the screen's primary content)
• A submit handler that does NOT disable its trigger while in-flight (double-submit risk) → WARN (BLOCKED for payment / create / irreversible actions)

Check for centralized handling BEFORE flagging BLOCKED (avoid false positives): many apps satisfy loading/error at the app level — a route-level progress bar, an HTTP interceptor that shows a global spinner/toast, an error boundary, or a base component that renders loading/error for all its children. If such a mechanism demonstrably covers this surface, the local component is compliant — grep for the shared mechanism (per this skill's "grep 3+ counterexamples / established exception" rule) and downgrade or drop the finding. Flag BLOCKED only when NO layer — local or global — gives the user a loading indicator / error surface.

Project fix guidance (cite real reuse targets from the resolved frontend/patterns + design-system docs):

• Prefer the project's documented loading component / skeleton / spinner and the documented error-banner / empty-state components or patterns — NEVER hand-roll one-off state UI when a canonical one exists.
• Bind loading / error / empty off the store / view-model / API-service state per the project's documented state pattern — state belongs in the lowest layer (Model > Service > Component), not improvised in the template.

GOOD vs BAD: a fetch bound to isLoading → skeleton, error → inline retry banner, and empty → placeholder is correct; a fetch that renders ONLY the populated happy path (blank while loading, nothing on error, blank when empty) is the anti-pattern. Cite the frontend-patterns and design-system docs for the project's reuse targets.

Note vs Category 5's Bug-Detection "Error Handling": the shared Bug Detection protocol checks that catch scope is correct and exceptions are not swallowed at the code level; Category 6 checks that the failure/loading/empty branch produces a user-visible state at the UI level. Both must pass — a correctly-caught error that renders nothing still fails Category 6.

Phase 3B: UI/UX Design Principles Pass (9 dimensions)

The 40 clauses of SYNC:ui-ux-design-principles (full body inlined below in this skill) bind this skill in the REVIEW role: every clause is a fail-condition, not a suggestion. Run them as NINE focused passes over the whole scope — one dimension at a time, in order. A single simultaneous sweep of all nine is what degrades clause review into tick-boxing; serial attention is the mechanism, not a formatting preference.

Per pass: answer the Think: prompt from first principles FIRST — what would make this dimension fail on THIS surface? — then hunt the violation that reasoning predicts. A pass that produced no reasoning produced no review: record the reasoning, never a tick.

Every finding: UI-<clause> + file:line + severity from the Phase 4 rubric already in force (BLOCKED must fix before merge · WARN review and decide · PASS compliant; a WARN escalates to BLOCKED under the escalation rule stated there). This pass introduces NO new severity scale.

Precedence (MUST ATTENTION): the project styling / design-system / frontend-pattern docs loaded in Phase 0 OUTRANK these clauses; the clauses outrank generic taste. Where a project doc states its own value (type scale, spacing unit, breakpoints, token contrast pairs), the PROJECT value is the rule and the clause is satisfied by following it. A genuine conflict is SURFACED to the user by asking the user directly with both sides — NEVER resolved silently.

No double-counting. Several clauses overlap Categories 1-6 (UI-1.5/UI-5.2/UI-9.1 overlap Category 6's async-state gate; UI-2.3 overlaps Category 1's content handling; UI-4.1 overlaps Category 5's magic-number rule; UI-4.4 overlaps Category 2's responsive bar). Where they meet, emit ONE finding carrying BOTH citations (e.g. Category 6 + UI-5.2) at the HIGHER of the two severities — never two findings for one defect, and never a downgrade because "the other category already covers it".

Skip rule. This pass runs whenever any frontend file is in scope. Skip an individual dimension ONLY when the scope contains no surface it can apply to (UI-8.* with no touch surface, UI-7.* with no input) — name the skipped dimensions and the reason, so a skip is auditable rather than an omission.

Phase 4: Finalize — UI Compliance Report

Update report with final sections:

Verdict Scoring

Severity vocabulary (single source of truth). Category headers and this verdict table use BLOCKED / WARN / PASS. The fresh sub-agent (Phase 5 and Round 2) emits Critical / High / Medium / Low + PASS / FAIL from the shared review-protocol template. Reconcile the two with this mapping — do NOT treat them as separate scales:

This skill	Sub-agent (Round 2)	Merge gate
BLOCKED	Critical / High → FAIL	Must fix before merge
WARN	Medium / Low → WARN/INFO	Review and decide
PASS	(no findings) → PASS	Merge-clear

A category's "(HIGH when …)" note is NOT a separate tier — it means that WARN escalates to BLOCKED when the stated condition holds (i.e., the finding is a real rendered bug, not a latent risk).

Report Structure

# UI Review Report — {date}

## Scope

- Files reviewed: {count}
- Components / apps affected: {list}
- Blast radius: {summary from Phase 2}

## Verdict: {PASS | WARN | BLOCKED}

## BLOCKED Findings (Must Fix)

### {Category}: {description}

- **File:** {path}:{line}
- **Rule:** {rule from project UI doc}
- **Evidence:** {what was found}
- **Fix:** {reuse target to use — directive / mixin / token}

## WARN Findings (Review)

### {Category}: {description}

- **File:** {path}:{line}
- **Rule:** {rule from project UI doc}
- **Evidence:** {what was found}
- **Recommendation:** {suggested action}

## PASS Categories

- {list of categories that passed with no findings}

## UI Health Summary

- Long-content Overflow & Truncation: {PASS/WARN/BLOCKED}
- Responsive Multi-Screen (flex-wrap / row→column, usable on small devices): {PASS/WARN/BLOCKED}
- Flex-Grow vs Fixed Sizing: {PASS/WARN/BLOCKED}
- Z-Index Scale Discipline: {PASS/WARN/BLOCKED}
- SCSS/CSS Best Practices & BEM: {PASS/WARN/BLOCKED}
- Async UI States & Feedback (loading / error / empty / disabled): {PASS/WARN/BLOCKED}
- Frontend Architecture (joint w/ architecture-review): {PASS/WARN/BLOCKED/N/A}

Systematic Review Protocol (10+ changed frontend files)

1. Categorize — Group files by app / shared-library / component concern
2. Parallel Sub-Agents — Launch one UI/UX-specialized sub-agent per group with the UI-category checklist
3. Synchronize — Collect findings, cross-reference shared-component consumers and cross-system token mixing
4. Consolidate — Single holistic report with per-category verdicts

Phase 5: Why-Review Findings Validation Gate (MANDATORY when findings exist)

Purpose: Adversarial validation of own findings BEFORE handoff. Catches over-flagged Highs, false positives, and severity inflation at the source rather than letting them propagate downstream.

Trigger: Any finding produced (Critical, High, Medium, OR Low). Skip ONLY when the report's verdict is unconditional PASS with literally zero findings.

Protocol:

1. Read own finalized report from plans/reports/ui-review-{date}-{slug}.md (the exact path written in Phase 3 — NOT {skill}-…)
2. Invoke $why-review --validate-findings plans/reports/ui-review-{date}-{slug}.md
3. Read the validation verdict path returned by why-review, expected as plans/reports/why-review-validate-{date}.md
4. If why-review demotes/removes any finding: UPDATE own finalized report with revised severities, remove false positives, and add a ## Why-Review Validation Notes section citing what changed and why
5. If why-review confirms all findings: Append ## Why-Review Validation line to own report stating "All N findings re-validated against actual code; no severity changes."
6. If the report changed after validation: re-run this validation gate, maximum 2 validation passes, until the report's remaining findings are validated or zero findings remain.

Skip conditions (record explicit reason if skipping):

• Verdict is unconditional PASS with zero findings → log "Skipped — no findings to validate"
• Why-review skill itself is the active context (avoid recursion)

Why this exists: AI sub-agent reports inherit confirmation bias — the orchestrator absorbs severity claims as ground truth. The 2026-05-09 review incident produced 5 Highs; adversarial validation demoted 3 of them. Codify this as standard practice.

Phase 6: Validated Fix + Full UI Re-Review Loop (MANDATORY when validated findings remain)

Trigger: Phase 5 returns CLEAN/validated and the UI review report still has one or more findings that must be fixed.

Protocol:

1. Create a fresh fix-cycle task list before editing. Do not reuse the review tasks.
2. Fix only findings that survived $why-review --validate-findings; route broader or cross-cutting fixes through the parent $plan + $feature-implement flow when this skill is running inside a workflow.
3. Run targeted verification for the fixed UI files and any affected consumers.
4. Re-invoke $ui-review from Phase 0 over the full current UI scope, not only the fixed files.
5. The re-run MUST create brand-new review tasks, reload the UI docs, determine scope again, rerun blast radius where applicable, and review every changed UI file from the start.
6. Repeat validate → fix → full UI re-review until a complete pass has zero findings.
7. If the same validated blocker repeats across 2 full invocations with no progress, stop and ask the user for a decision.

Non-negotiable rules:

• Never fix a finding before $why-review --validate-findings validates it.
• Never mark UI review clean after a targeted fix check only; the clean verdict must come from a full Phase 0 restart.
• Never review only fixed files during the recursive pass; analyze all UI files in scope again.
• Never reuse old todo/task items for the recursive review pass.

Workflow Recommendation

MANDATORY — NO EXCEPTIONS: If NOT already in a workflow, MUST use ask the user directly to ask user. Do NOT judge task complexity or decide "simple enough to skip" — user decides, not you:

1. Activate workflow-review-changes workflow (Recommended) — run the canonical workflow from .claude/workflows.json; it runs UI review in TWO places by design (keep both) — internally as $changes-review's UI dimension AND as a dedicated conditional parallel-batch reviewer (step 9) — alongside findings validation, the other parallel reviewers, code-simplifier self-review, fix-plan cycle, full re-review restart, docs, and handoff.
2. Execute $ui-review directly — run this skill standalone

Next Steps

MANDATORY — NO EXCEPTIONS: After completing, use ask the user directly to present:

• "$code-simplifier" (Recommended) — Simplify and refine the styling/component code
• "$web-design-guidelines" — Generic accessibility / UX checklist for a11y depth
• "Skip, continue manually" — user decides

AI Agent Integrity Gate (NON-NEGOTIABLE)

Before reporting ANY work done:

1. Grep every removed name. Extraction/rename/delete → grep confirms 0 dangling refs across ALL file types (SCSS @use, template class refs, TS imports)
2. Ask WHY before changing. Existing values intentional until proven otherwise — a fixed width may be a genuinely fixed UI element; no "fix" without traced rationale
3. **Verify ALL outputs

…(truncated)