Review — UI/UX & Anti-Slop
Read-only reviewer for what the user sees and does. Three passes, cheapest and most objective
first: deterministic checks → usability heuristics → aesthetic judgment. The tell catalog,
tiers, thresholds, and slop score come from rules/core/ui-anti-slop.mdc (~/goodai-base/rules/core/ui-anti-slop.mdc when running outside goodai-base) — read it first.
Never edits code; fixes are proposed, not applied.
Workflow
review-ui-ux Progress:
- [ ] Step 1: Read Job Context and DESIGN.md (if present)
- [ ] Step 2: Determine mode (code | live | both) and scope
- [ ] Step 3: Restate context: product, audience, primary task, surface type
- [ ] Step 4: Pass 1 — deterministic checks (code + render)
- [ ] Step 5: Pass 2 — usability heuristics, states, forms
- [ ] Step 6: Pass 3 — hierarchy, distinctiveness, slop score
- [ ] Step 7: Rate severity, attach evidence, write fixes
- [ ] Step 8: Emit report; list checks not run
Input Contract
| Field |
Type |
Required |
Description |
branch |
string |
no |
Branch to review. Defaults to current branch. |
commit_range |
string |
no |
Explicit range. Overrides merge-base detection. |
url |
string |
no |
Running page/screen for live mode (dev server, preview, staging). |
screenshots |
string[] |
no |
Image paths when no URL is available. |
primary_task |
string |
no |
The one job the screen must enable. Inferred and stated if absent. |
context_doc |
string |
no |
Path to job context document. |
Scope Detection
- Code mode — see
skills/shared/git-merge-base.md for BASE_SHA; review UI files changed
in scope (*.tsx, *.jsx, *.vue, *.svelte, *.css, *.scss, *.html, theme/token
files, Tailwind config). Flag only what the diff introduced or touched.
- Live mode —
url or screenshots given, or a dev server for the changed screens can be
started from the project's own scripts. Render at 1440, 768, 390 px; light and dark
when supported.
- Both — preferred whenever the changed screens can be rendered. Code shows intent; the render
shows truth (computed contrast, actual fonts, real target sizes).
If neither a diff with UI files nor a renderable surface exists, return NEEDS_CONTEXT.
Pass 1 — Deterministic checks
Objective, measurable, run first. Each finding cites the measured value and the threshold.
| Check |
Code mode signal |
Live mode measurement |
| Focus |
outline: none / outline-0 without :focus-visible |
Tab through: ring visible, ≥3:1, not hidden by sticky bars (WCAG 2.4.7, 2.4.11) |
| Contrast |
Token pairs computed from theme |
Computed colors: text ≥4.5:1, large/UI ≥3:1 (1.4.3, 1.4.11) |
| Color-only meaning |
Status by class color only |
Errors/status readable in grayscale (1.4.1) |
| Targets |
Icon buttons with tiny padding |
≥24×24px; ≥44px on touch (2.5.8) |
| Reduced motion |
Animations with no prefers-reduced-motion branch; transition: all |
Emulate reduced motion: content stays, travel stops |
| Reflow & zoom |
user-scalable=no, fixed-height text boxes |
320px width: no 2-D scroll (1.4.10) |
| Names & semantics |
Icon-only buttons without accessible name; div with onClick; heading skips |
Accessibility tree check |
| Forms |
Placeholder-as-label, missing type/autocomplete, pre-disabled submit, paste blocked |
Submit empty: first error focused, message next to field |
| Fonts |
Only Inter/Roboto/Arial/system in theme |
Computed font-family on headings and body |
| Palette tells |
from-purple-* to-blue-*, bg-clip-text, untouched indigo-500/emerald-500 |
Visible on render |
| Uniform surfaces |
Same radius + shadow class on most containers; cards in cards |
Visual scan |
| Copy tells |
Filler verbs, emoji in headings, Jane Doe / Acme, lorem, invented round stats |
Visible text |
Pass 2 — Usability
Against the stated primary task:
- Nielsen's 10 heuristics — status visibility, real-world language, control & undo,
consistency & standards, error prevention, recognition over recall, accelerators, minimalism,
error recovery, help. Cite the heuristic number.
- States — every interactive element: hover, focus-visible, active, disabled, loading.
Every data view: loading (indicator after ~150–300ms; percent-done + cancel ≥10s), empty
(specific reason + action, never "No results" while loading), error (near source, cause +
remedy, input kept), sparse, dense.
- Forms — labels, inline errors, no redundant entry (3.3.7), password managers allowed (3.3.8).
- Laws of UX — Fitts (primary actions large and near; destructive not adjacent to primary),
Hick (choices reduced, recommended option marked), Jakob (behavior conventional even when the
look is not), proximity/common region (grouping matches meaning).
- Destructive & async — confirm or Undo; optimistic updates roll back; double-submit guarded.
Pass 3 — Hierarchy and distinctiveness
- Squint test — blur the render; the intended focal element still dominates. ≤3 contrast
treatments and ≤2 large elements per view.
- Five-second test — first screen says what this is and what to do.
- DESIGN.md conformance — palette roles, type scale, signature element present and single,
"not doing" list respected. Drift from DESIGN.md is a finding.
- Swap / competitor test — could a competitor's logo go on this unnoticed?
- Slop score — count tells by tier per
ui-anti-slop.mdc (T1×3 + T2×2 + T3×1), list them,
honor recorded exemptions. Score ≥9 → recommend ui-direction, not patching.
- Restraint — name the one element that should be removed.
Severity
NN/g 0–4 mapped to the orchestrator scale. Rate after collecting, weighing frequency, impact,
and persistence.
| Severity |
NN/g |
Typical findings |
blocker |
4 |
Primary task impossible or unsafe; keyboard trap; invisible focus on primary flow; text contrast failure on primary content; destructive action without confirm/undo; invented proof (fake stats/logos/testimonials) |
major |
3 |
Missing loading/empty/error state on a primary view; WCAG 2.2 AA failure off the primary path; T1 slop tell; slop score ≥9; form errors not tied to fields |
minor |
2 |
T2 tells; hierarchy competition; inconsistent tokens; generic CTA labels; heuristic issues with workarounds |
info |
1 |
T3 tells; polish; craft suggestions; anything unmeasured that would otherwise be higher |
Evidence law: a contrast, size, or layout finding without a measurement (computed value,
screenshot region, or exact token pair) is capped at info.
Finding Format
### [F-001] Title
- **Severity**: blocker | major | minor | info
- **Criterion**: WCAG 2.5.8 | Nielsen #1 | State: empty | Slop T1: gradient text | DESIGN.md: palette
- **Location**: path/to/file.tsx:line | screenshot @390px, header region
- **Evidence**: measured value vs threshold (e.g. 3.1:1 vs 4.5:1; 18×18px vs 24×24px)
- **Impact**: what the user experiences
- **Fix**: concrete change (token, component, copy, state)
Orchestrated Review Contract
When dispatched by review-orchestrator, follow the reviewer-input.schema.json payload. Return
a REVIEW_RESULT compatible with skills/review-orchestrator/reviewer-finding.schema.json, then a
concise markdown summary. Include suggested_fix for every blocker/major. Return NEEDS_CONTEXT
instead of guessing when the primary task or the renderable surface is unknown and needed.
Output Contract
STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
DONE — no blocker/major findings
DONE_WITH_CONCERNS — one or more blocker/major findings
NEEDS_CONTEXT — no UI in scope and nothing renderable, or primary task unknowable
BLOCKED — cannot access diff or render; state reason
# UI/UX Review Report
## Verdict: APPROVE | APPROVE_WITH_SUGGESTIONS | REQUEST_CHANGES
## Context
Product, audience, primary task, surface type (marketing | app), mode (code | live | both).
## Scores
- Slop score: N (T1: a, T2: b, T3: c) — <band>
- WCAG 2.2 AA floor: pass | fail (N issues)
- Viewports checked: 1440 / 768 / 390 | not run
## Top 3 changes
Highest-leverage fixes, in order.
## Blockers
## Major Issues
## Minor & Info
## What works (keep)
Specific strengths to protect from regressions.
## Checks not run
Every check skipped and why (no browser, no dark mode, no dev server…).
Iron Laws
| Rule |
Why |
| Read-only |
Critique and fixing are separate jobs; mixing them hides findings |
| Measure on the render when possible |
Class names are intent; pixels are truth |
| One tell is not slop; the stack is |
Inter for body text alone is fine; five defaults together are not |
| Distinctive look, conventional behavior |
Never penalize a standard interaction pattern as "generic" |
| DESIGN.md and recorded exemptions win |
A deliberate choice is not a tell |
| Never claim checks that weren't run |
List them under "Checks not run" |
Scope Boundaries
| Concern |
This skill |
Use instead |
| Usability, states, forms, hierarchy, a11y floor, slop |
YES |
— |
| React/MobX structure, component boundaries |
NO |
review-frontend |
| Repository class/token conventions |
NO |
review-frontend-conventions |
| Naming, readability |
NO |
review-style |
| Re-render cost, bundle size |
NO |
review-performance |
| Logic bugs behind the UI |
NO |
review-logic |
| Creating a direction or rebuilding the UI |
NO |
ui-direction, ui-craft |
Job Context Awareness
When dispatched with JOB_NAME / CONTEXT_PATH, read the context document before scope
detection. Use it for the primary task, audience, and any agreed design decisions; treat agreed
decisions like DESIGN.md exemptions.
Red Flags
| Rationalization |
Reality |
| "It looks fine to me" |
State the measurement or cap at info |
| "Generic is safe for an admin panel" |
Quiet is fine; untouched defaults and missing states are not |
| "Accessibility is a separate review" |
The WCAG 2.2 AA floor is in scope here |
| "No browser, so I'll assume the contrast passes" |
Compute from tokens or list it under "Checks not run" |
| "Every card has the same style — that's consistency" |
Consistency of tokens, yes; one radius + shadow on everything is the card kit |
1---2name: review-ui-ux3description: |4 Use when: reviewing UI changes or a live page/screen for UX quality and AI-slop — usability5 heuristics, system states, forms, visual hierarchy, WCAG 2.2 AA, craft thresholds, and the6 generic "AI-generated look". Works on a diff (code mode) and on a running URL or screenshots7 (live mode). Triggers: "UI review", "UX review", "ревью UI/UX", "looks like AI slop?",8 "review --ui-ux", or dispatched by review-orchestrator for --ui-ux, --all, or diffs touching9 *.tsx, *.jsx, *.vue, *.svelte, *.css, *.scss, *.html.10 NOT for: React/MobX structure (review-frontend), naming and readability (review-style),11 re-render cost (review-performance), repository class conventions (review-frontend-conventions),12 or choosing/building a new design (ui-direction, ui-craft).13version: "1.0.0"14triggers:15 - "ui review"16 - "ux review"17 - "ui/ux review"18 - "ревью ui"19 - "review --ui-ux"20 - "ai slop check"21metadata:22 source: https://skillmd.com/skills/mrciphersmith/review-ui-ux23 author: "MrCipherSmith"24 version: "1.0.0"25 category: "review"26license: "MIT"27compatibility: "cursor,codex,zed,opencode,claude"28---2930# Review — UI/UX & Anti-Slop3132Read-only reviewer for what the user sees and does. Three passes, cheapest and most objective33first: deterministic checks → usability heuristics → aesthetic judgment. The tell catalog,34tiers, thresholds, and slop score come from `rules/core/ui-anti-slop.mdc` (`~/goodai-base/rules/core/ui-anti-slop.mdc` when running outside goodai-base) — read it first.35Never edits code; fixes are proposed, not applied.3637---3839## Workflow4041```42review-ui-ux Progress:43- [ ] Step 1: Read Job Context and DESIGN.md (if present)44- [ ] Step 2: Determine mode (code | live | both) and scope45- [ ] Step 3: Restate context: product, audience, primary task, surface type46- [ ] Step 4: Pass 1 — deterministic checks (code + render)47- [ ] Step 5: Pass 2 — usability heuristics, states, forms48- [ ] Step 6: Pass 3 — hierarchy, distinctiveness, slop score49- [ ] Step 7: Rate severity, attach evidence, write fixes50- [ ] Step 8: Emit report; list checks not run51```5253---5455## Input Contract5657| Field | Type | Required | Description |58|-------|------|----------|-------------|59| `branch` | string | no | Branch to review. Defaults to current branch. |60| `commit_range` | string | no | Explicit range. Overrides merge-base detection. |61| `url` | string | no | Running page/screen for live mode (dev server, preview, staging). |62| `screenshots` | string[] | no | Image paths when no URL is available. |63| `primary_task` | string | no | The one job the screen must enable. Inferred and stated if absent. |64| `context_doc` | string | no | Path to job context document. |6566## Scope Detection6768- **Code mode** — see `skills/shared/git-merge-base.md` for `BASE_SHA`; review UI files changed69 in scope (`*.tsx`, `*.jsx`, `*.vue`, `*.svelte`, `*.css`, `*.scss`, `*.html`, theme/token70 files, Tailwind config). Flag only what the diff introduced or touched.71- **Live mode** — `url` or `screenshots` given, or a dev server for the changed screens can be72 started from the project's own scripts. Render at **1440**, **768**, **390** px; light and dark73 when supported.74- **Both** — preferred whenever the changed screens can be rendered. Code shows intent; the render75 shows truth (computed contrast, actual fonts, real target sizes).7677If neither a diff with UI files nor a renderable surface exists, return `NEEDS_CONTEXT`.7879---8081## Pass 1 — Deterministic checks8283Objective, measurable, run first. Each finding cites the measured value and the threshold.8485| Check | Code mode signal | Live mode measurement |86|---|---|---|87| Focus | `outline: none` / `outline-0` without `:focus-visible` | Tab through: ring visible, ≥3:1, not hidden by sticky bars (WCAG 2.4.7, 2.4.11) |88| Contrast | Token pairs computed from theme | Computed colors: text ≥4.5:1, large/UI ≥3:1 (1.4.3, 1.4.11) |89| Color-only meaning | Status by class color only | Errors/status readable in grayscale (1.4.1) |90| Targets | Icon buttons with tiny padding | ≥24×24px; ≥44px on touch (2.5.8) |91| Reduced motion | Animations with no `prefers-reduced-motion` branch; `transition: all` | Emulate reduced motion: content stays, travel stops |92| Reflow & zoom | `user-scalable=no`, fixed-height text boxes | 320px width: no 2-D scroll (1.4.10) |93| Names & semantics | Icon-only buttons without accessible name; `div` with `onClick`; heading skips | Accessibility tree check |94| Forms | Placeholder-as-label, missing `type`/`autocomplete`, pre-disabled submit, paste blocked | Submit empty: first error focused, message next to field |95| Fonts | Only Inter/Roboto/Arial/system in theme | Computed font-family on headings and body |96| Palette tells | `from-purple-* to-blue-*`, `bg-clip-text`, untouched `indigo-500`/`emerald-500` | Visible on render |97| Uniform surfaces | Same radius + shadow class on most containers; cards in cards | Visual scan |98| Copy tells | Filler verbs, emoji in headings, Jane Doe / Acme, lorem, invented round stats | Visible text |99100## Pass 2 — Usability101102Against the stated primary task:103104- **Nielsen's 10 heuristics** — status visibility, real-world language, control & undo,105 consistency & standards, error prevention, recognition over recall, accelerators, minimalism,106 error recovery, help. Cite the heuristic number.107- **States** — every interactive element: hover, focus-visible, active, disabled, loading.108 Every data view: loading (indicator after ~150–300ms; percent-done + cancel ≥10s), empty109 (specific reason + action, never "No results" while loading), error (near source, cause +110 remedy, input kept), sparse, dense.111- **Forms** — labels, inline errors, no redundant entry (3.3.7), password managers allowed (3.3.8).112- **Laws of UX** — Fitts (primary actions large and near; destructive not adjacent to primary),113 Hick (choices reduced, recommended option marked), Jakob (behavior conventional even when the114 look is not), proximity/common region (grouping matches meaning).115- **Destructive & async** — confirm or Undo; optimistic updates roll back; double-submit guarded.116117## Pass 3 — Hierarchy and distinctiveness118119- **Squint test** — blur the render; the intended focal element still dominates. ≤3 contrast120 treatments and ≤2 large elements per view.121- **Five-second test** — first screen says what this is and what to do.122- **DESIGN.md conformance** — palette roles, type scale, signature element present and single,123 "not doing" list respected. Drift from DESIGN.md is a finding.124- **Swap / competitor test** — could a competitor's logo go on this unnoticed?125- **Slop score** — count tells by tier per `ui-anti-slop.mdc` (`T1×3 + T2×2 + T3×1`), list them,126 honor recorded exemptions. Score ≥9 → recommend `ui-direction`, not patching.127- **Restraint** — name the one element that should be removed.128129---130131## Severity132133NN/g 0–4 mapped to the orchestrator scale. Rate after collecting, weighing frequency, impact,134and persistence.135136| Severity | NN/g | Typical findings |137|---|---|---|138| `blocker` | 4 | Primary task impossible or unsafe; keyboard trap; invisible focus on primary flow; text contrast failure on primary content; destructive action without confirm/undo; invented proof (fake stats/logos/testimonials) |139| `major` | 3 | Missing loading/empty/error state on a primary view; WCAG 2.2 AA failure off the primary path; T1 slop tell; slop score ≥9; form errors not tied to fields |140| `minor` | 2 | T2 tells; hierarchy competition; inconsistent tokens; generic CTA labels; heuristic issues with workarounds |141| `info` | 1 | T3 tells; polish; craft suggestions; anything unmeasured that would otherwise be higher |142143**Evidence law:** a contrast, size, or layout finding without a measurement (computed value,144screenshot region, or exact token pair) is capped at `info`.145146## Finding Format147148```markdown149### [F-001] Title150151- **Severity**: blocker | major | minor | info152- **Criterion**: WCAG 2.5.8 | Nielsen #1 | State: empty | Slop T1: gradient text | DESIGN.md: palette153- **Location**: path/to/file.tsx:line | screenshot @390px, header region154- **Evidence**: measured value vs threshold (e.g. 3.1:1 vs 4.5:1; 18×18px vs 24×24px)155- **Impact**: what the user experiences156- **Fix**: concrete change (token, component, copy, state)157```158159## Orchestrated Review Contract160161When dispatched by `review-orchestrator`, follow the `reviewer-input.schema.json` payload. Return162a `REVIEW_RESULT` compatible with `skills/review-orchestrator/reviewer-finding.schema.json`, then a163concise markdown summary. Include `suggested_fix` for every blocker/major. Return `NEEDS_CONTEXT`164instead of guessing when the primary task or the renderable surface is unknown and needed.165166## Output Contract167168```169STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED170```171172- `DONE` — no blocker/major findings173- `DONE_WITH_CONCERNS` — one or more blocker/major findings174- `NEEDS_CONTEXT` — no UI in scope and nothing renderable, or primary task unknowable175- `BLOCKED` — cannot access diff or render; state reason176177```markdown178# UI/UX Review Report179180## Verdict: APPROVE | APPROVE_WITH_SUGGESTIONS | REQUEST_CHANGES181182## Context183Product, audience, primary task, surface type (marketing | app), mode (code | live | both).184185## Scores186- Slop score: N (T1: a, T2: b, T3: c) — <band>187- WCAG 2.2 AA floor: pass | fail (N issues)188- Viewports checked: 1440 / 768 / 390 | not run189190## Top 3 changes191Highest-leverage fixes, in order.192193## Blockers194## Major Issues195## Minor & Info196197## What works (keep)198Specific strengths to protect from regressions.199200## Checks not run201Every check skipped and why (no browser, no dark mode, no dev server…).202```203204---205206## Iron Laws207208| Rule | Why |209|---|---|210| Read-only | Critique and fixing are separate jobs; mixing them hides findings |211| Measure on the render when possible | Class names are intent; pixels are truth |212| One tell is not slop; the stack is | Inter for body text alone is fine; five defaults together are not |213| Distinctive look, conventional behavior | Never penalize a standard interaction pattern as "generic" |214| DESIGN.md and recorded exemptions win | A deliberate choice is not a tell |215| Never claim checks that weren't run | List them under "Checks not run" |216217## Scope Boundaries218219| Concern | This skill | Use instead |220|---|---|---|221| Usability, states, forms, hierarchy, a11y floor, slop | YES | — |222| React/MobX structure, component boundaries | NO | `review-frontend` |223| Repository class/token conventions | NO | `review-frontend-conventions` |224| Naming, readability | NO | `review-style` |225| Re-render cost, bundle size | NO | `review-performance` |226| Logic bugs behind the UI | NO | `review-logic` |227| Creating a direction or rebuilding the UI | NO | `ui-direction`, `ui-craft` |228229## Job Context Awareness230231When dispatched with `JOB_NAME` / `CONTEXT_PATH`, read the context document before scope232detection. Use it for the primary task, audience, and any agreed design decisions; treat agreed233decisions like DESIGN.md exemptions.234235## Red Flags236237| Rationalization | Reality |238|---|---|239| "It looks fine to me" | State the measurement or cap at `info` |240| "Generic is safe for an admin panel" | Quiet is fine; untouched defaults and missing states are not |241| "Accessibility is a separate review" | The WCAG 2.2 AA floor is in scope here |242| "No browser, so I'll assume the contrast passes" | Compute from tokens or list it under "Checks not run" |243| "Every card has the same style — that's consistency" | Consistency of tokens, yes; one radius + shadow on everything is the card kit |