---
name: ui-ux-quality-review
description: Child skill under Build Quality UI/UX for foundational screen and
  flow review across hierarchy, clarity, spacing, type, color, consistency,
  states, charts, and responsive fit. Returns evidence-backed findings with
  severity and concrete fixes; includes an AI-generated-UI smoke test.
---

# UI/UX Quality Review

General-purpose UI review child. The discipline this skill enforces is **sequencing**: do not ask whether the interface is pretty until you have answered whether the user can complete the job, whether the screen has a visible hierarchy, whether components behave consistently, and whether the UI responds to user action.

The deep rules live in reference modules. The skill body holds the sequence, the output contract, and the escalation map; load the references before producing findings.

## When to Use

- Reviewing an app screen, dashboard, mobile flow, product workflow, modal, form, table, or chart.
- Reviewing AI-generated UI from v0, Lovable, Cursor, or Bolt before it ships.
- The user asks for a UI/UX audit without naming accessibility, marketing, design systems, research, calm, or delight as the main lens.
- Diagnosing why a UI feels amateur, cluttered, or hard to trust.
- You need a compact findings list with severity, evidence, and concrete fixes.

## Workflow

1. Preflight. Confirm the user task on this surface in one sentence — if unclear, ask before reviewing. Capture or request: screenshots at mobile (375px), tablet (768px), desktop (1280px); light and dark mode if supported; interactive states (hover, focus, active, disabled, loading, error, empty) for primary controls; the design tokens in play (Inkprint for BuildOS surfaces) so fixes can be expressed in tokens, not arbitrary values. When only markup or code is available, reason directly from it — note unverifiable items (rendered contrast, real breakpoint behavior) instead of stalling on missing screenshots.
2. If the UI is AI-generated or looks generic, read `references/ai-ui-smoke-test.md` and run the fingerprint scan first.
3. read `references/foundation-checks.md` and review areas 1–6 in order: flow & states, visual hierarchy, spacing & layout, typography, color & contrast, component consistency. Flow problems outrank pixel problems — if the user cannot complete the job, lead with that and keep cosmetic findings brief.
4. read `references/polish-and-fit-checks.md` and review areas 7–11 in order: visual noise, icons & affordances, feedback & states, charts & data clarity, responsive fit. Skip chart checks when no data viz is present.
5. For a targeted question (for example "fix my typography"), load only the reference covering that area and run just those checks — but still flag any blocking flow issue you notice.
6. Tag out-of-scope findings for escalation instead of dropping them: conceptual confusion → `information_architecture_review`; works-but-lacks-polish craft fixes → `visual_craft_fundamentals`; semantics, focus, keyboard, or screen-reader behavior → `accessibility_inclusive_ui_review`; landing-page persuasion structure → `marketing_site_design_review`; delight opportunities once foundations are clean → `delightful_product_review`.
7. Assemble the findings report using the Output contract below, ordered by severity then user impact, ending with the top 3 fixes.

## Output

Every finding follows this canonical shape:

```
Area: <flow | hierarchy | spacing | typography | color | consistency | noise | icons | feedback | charts | responsive>
Finding: <named rule violated, e.g. "Closed-scale spacing violated">
Evidence: <specific component, class string, region, or coordinate>
Severity: <high | medium | low>
Fix: <concrete tokens or named technique>
Delegated: <optional sibling skill id if the fix is out of this skill's scope>
```

Severity rubric:

- **high** — blocks task completion, breaks the accessibility floor (body text contrast < 4.5:1), or creates inclusion risk.
- **medium** — significantly degrades polish or readability; consistency drift; off-scale spacing.
- **low** — stylistic preference, minor decorative noise.

Stop conditions before returning: every applicable area has at least one finding or an explicit "no issues"; the top 3 high-severity fixes are ranked by impact; every finding carries Evidence and Severity; out-of-scope concerns are tagged Delegated, not dropped.

## Worked Example

Condensed from a full review of a v0-generated analytics dashboard; the input is in `evals.md` Task 1. Match this shape and rigor.

**Input (summary):** Static Tailwind markup on a saturated `bg-indigo-600` page; every card `rounded-2xl shadow-md border`; three identical gradient "Export" buttons (`h-6`, `hover:opacity-90` only, calling a ~3s API); a "Signups This Week" chart with 16 gradient bars and no y-axis for a 7-day range; an empty `<ul>` for recent signups and a `"Something went wrong"` error div; off-scale values (`p-[13px]`, `text-[22px]`, `space-y-[7px]`). User task: check this week's signup numbers and export a report.

**Preflight:** User task confirmed from the prompt. Markup-only review — no screenshots at 375/768/1280px, no dark mode; responsive and state findings are derived from class strings and flagged for screenshot confirmation before ship. No token system in play, so fixes use Tailwind scale values. Headline: the user cannot complete either half of the job — flow and chart findings lead; cosmetic findings stay brief.

**AI-Generated UI Smoke Test (run first — v0 output):** 5 of 8 fingerprints present, itemized as findings: `rounded-2xl` + `shadow-md` + `border` stacked on all 5 cards; `text-gray-400` on every muted element; the `from-blue-500 to-purple-500` AI gradient on buttons and bars; flat `shadow-md` ladder; default `p-4`/`gap-4` everywhere.

```
Area: flow
Finding: Async action ≥ 200ms with no loading indicator
Evidence: All three Export buttons call a ~3s API; markup defines only `hover:opacity-90` — no loading, disabled, or success state.
Severity: high
Fix: On click, set a disabled loading state (spinner or "Exporting…", `disabled:opacity-50 disabled:cursor-not-allowed`), then explicit success feedback when the file is ready. One loading pattern per surface.
```

```
Area: spacing
Finding: Closed-scale spacing violated (arbitrary off-scale values)
Evidence: `p-[13px]` on the header, `space-y-[7px]` on the signup list.
Severity: medium
Fix: Snap to the closed scale {4, 8, 12, 16, 24, 32, 48, 64, 96}: `p-3` (12px) or `p-4` (16px) for the header; `space-y-2` (8px) for the list.
```

```
Area: flow
Finding: No focus/keyboard states defined on interactive elements
Evidence: Export buttons define only `hover:opacity-90`; no `focus-visible:` styles anywhere in the markup.
Severity: medium
Fix: Add `focus-visible:ring-2 focus-visible:ring-offset-2` to all buttons.
Delegated: accessibility_inclusive_ui_review (keyboard/focus semantics are that skill's scope; flagged here because the state is entirely absent)
```

```
Area: charts
Finding: One-bar-per-data-point violated — 16 bars rendered for a 7-day range
Evidence: Chart card comment: "16 bars rendered for the 7-day range" inside "Signups This Week"; no y-axis labels, so the screen's core question is unanswerable.
Severity: high
Fix: Render exactly 7 bars, one per day, with day labels on the x-axis; add 3–4 y-axis gridline values starting at zero.
```

_(…12 further findings in the same shape across hierarchy, typography, color, consistency, noise, icons, feedback, and responsive — every applicable area got at least one finding or an explicit "no issues".)_

**Out-of-scope, tagged for escalation (not dropped):** focus/keyboard semantics, button `type` attributes, chart accessible alternative → `accessibility_inclusive_ui_review`; post-fix craft polish (shadow recipe, palette warmth, type pairing) → `visual_craft_fundamentals`.

**Top 3 fixes (ranked by impact on the stated task):**

1. Make the chart readable: 7 bars for 7 days, with a y-axis and day labels; flat tops, solid single-hue fill — this is the entire "check this week's signups" half of the job.
2. Make export real: one clearly primary "Export report" action with a loading state for the 3s call and visible success confirmation; kill or demote the three ambiguous per-card gradient buttons; bring the button to ≥ 44px.
3. Fix the color foundation: neutral page background (60/30/10) and raise all `text-gray-400` text to ≥ 4.5:1 (`text-gray-600`+ on white; same-hue light tint, not grey, on any colored surface).

## Guardrails

- A finding without evidence is not a finding — if it cannot be tied to a specific component, class, region, or coordinate, do not include it.
- Do not assign severity without referencing the rubric.
- Do not over-index on personal taste. Tie each issue to comprehension, task completion, confidence, accessibility, or maintainability.
- Do not recommend decorative gradients, extra cards, or ornamental effects as the first fix — subtraction beats addition.
- Do not make every element the same visual weight, and do not stack contrast levers to make everything important.
- Do not allow off-scale spacing or font-size values, and do not assume desktop spacing works on mobile.
- Do not remove labels from unfamiliar icon-only controls without adding tooltips.
- Do not produce findings for areas 1–11 without loading the matching reference module first.

## Notes

- Reference modules: `ui_ux_quality_review.foundation_checks` (areas 1–6), `ui_ux_quality_review.polish_and_fit_checks` (areas 7–11), `ui_ux_quality_review.ai_ui_smoke_test` (AI-slop fingerprints).
- Primary sources: Kole Jain (beginner mistakes, UI/UX concepts), DesignSpo (visual hierarchy, typography, color theory, 4-pixel golden rule), Nesrine Changuel (delight framework, consumed via `delightful_product_review`).
- Maintainers: the canonical research draft with full lineage lives at `docs/research/youtube-library/skill-drafts/ui-ux-quality-review/` (not available at runtime).

## Portable References

This skill ships with local reference files. Read them only when the current task matches the trigger.

- `references/foundation-checks.md` — Foundation Checks (areas 1–6) (ui_ux_quality_review.foundation_checks): Threshold-bearing rules for flow & states, visual hierarchy, spacing, typography, color & contrast, and component consistency — closed spacing/type scales, contrast-lever ranking, 60/30/10 color proportions, contrast floors.
  - Read when: When executing a full review, before producing findings for areas 1–6.
  - Read when: When the user's concern is hierarchy, spacing, typography, color, or consistency drift.

- `references/polish-and-fit-checks.md` — Polish & Fit Checks (areas 7–11) (ui_ux_quality_review.polish_and_fit_checks): Threshold-bearing rules for visual noise, icons & affordances, feedback states, charts & data clarity, and responsive fit — shadow recipe, icon-library rules, loading thresholds, chart axis rules, breakpoint checklist.
  - Read when: When executing a full review, before producing findings for areas 7–11.
  - Read when: When the user's concern is decorative noise, icons, interaction feedback, charts, or mobile fit.

- `references/ai-ui-smoke-test.md` — AI-Generated UI Smoke Test (ui_ux_quality_review.ai_ui_smoke_test): Fingerprint table for AI-generated UI (v0, Lovable, Cursor, Bolt) — eight named slop patterns with the corrective move for each.
  - Read when: When the screen under review was generated by an AI tool, or the user says the UI looks generic or like AI slop.