Skip to content

dvy1987/agent-loom / .agents/skills/design-review

design-review

Verified

Review a built frontend against its chosen direction, catch drift back to generic AI defaults, enforce state coverage, ethical patterns, UX heuristics, and polish, and check contrast with APCA (not the legacy WCAG ratio). Produces specific, prioritized fixes — never vibes-based feedback. Works with pasted screenshots or Playwright MCP automated capture. Load when the user asks to review a UI, audit a design, check if a frontend looks generic or vibecoded, evaluate visual quality or polish, says "review this UI", "is this design good", "audit my frontend", "does this feel like [product]", "design QA", or when frontend-design routes here. Sub-skill of frontend-design.

references/review-rubric.md

View on GitHub
# Review Rubric

Scoring 0–3 per dimension. Anchors below.

## Direction fidelity

- **0** — does not feel like the chosen direction's "feels like X" at all; reads as a different direction
- **1** — partial fit; some right moves, but key signature elements missing
- **2** — recognizable as the direction; most signature moves present
- **3** — feels indistinguishable in spirit from the reference; signature moves all present and intentional

## Anti-vibecoded gates

- **0** — multiple banned defaults present (Inter-only + Tailwind grays + purple gradient + Lucide drop-in)
- **1** — 1–2 banned defaults present without justification
- **2** — no banned defaults; at least one distinctive move present
- **3** — no banned defaults; multiple distinctive moves present (typography + color + layout)

## Typography

- **0** — single font for everything OR mismatched pairing OR Tailwind defaults left untouched
- **1** — pairing exists but hierarchy is unclear, or tracking / line-height not archetype-correct
- **2** — pairing executed correctly, hierarchy clear, tracking and line-height archetype-correct
- **3** — typography is the strongest element of the build; pairing and rhythm carry the brand voice

## Color

- **0** — hex literals in components, banned palettes present, dark mode is inverted lightness
- **1** — tokens used inconsistently, OR dark mode partially executed
- **2** — all colors via tokens, dark mode is a separate hand-set story
- **3** — color story is distinctive, used as content where appropriate, contrast quietly excellent (APCA, see below)

## State coverage

Includes **micro-copy** quality — empty, error, loading, and CTA text are part of the score.

- **0** — only the populated/happy path exists; no empty/loading/error
- **1** — some states present but inconsistent (e.g. spinners not skeletons, generic "No data", "Error occurred")
- **2** — every data surface has loading + empty + error + populated; interactive els have hover/active/focus-visible/disabled; copy is functional
- **3** — states designed with equal care: skeletons match layout; empty states offer a specific next action; errors name what failed + how to recover; CTAs state the real outcome (no vague "Continue" / "Submit")

### Micro-copy signals (use when scoring State coverage)

| Signal | Weak (caps at 1) | Strong (supports 2–3) |
|---|---|---|
| Empty state | "No data" / "Nothing here" | "No projects yet — create one to get started" |
| Error state | "Something went wrong" | "Couldn't save — check your connection and retry" |
| CTA | "Continue" / "OK" / "Learn more" | "Create project" / "Start 14-day trial" / "Download CSV" |
| Loading | Silent or generic spinner only | Skeleton matches layout; label where wait is long |

## Iconography

- **0** — Lucide drop-in default OR mixed icon libraries OR icons don't match type weight
- **1** — single library used but not tuned to type weight, sizes inconsistent
- **2** — coherent set, matched to type, consistent sizes; bespoke or properly-tuned
- **3** — icons are a signature element; clearly bespoke or perfectly tuned; carries brand identity

## Layout & rhythm

- **0** — generic 3-col feature grid + centered hero + cards-everywhere
- **1** — some structure present but rhythm is uneven, density doesn't match archetype
- **2** — grid logic clear, spacing log-spaced, density matches archetype
- **3** — layout has a signature move (asymmetry, recurring marginalia, archetype-specific)

## Motion

Includes **delight** — transitions that confirm causality; not decoration-only animation.

- **0** — `transition-all duration-300` everywhere, no easing variation, no reduced-motion support
- **1** — motion exists but doesn't follow archetype budget; reduced-motion present but partial
- **2** — duration budget matches archetype; easing curve is archetype-specific; reduced-motion fully honored
- **3** — motion expresses state and confirms causality; one signature delight moment per primary flow

## Accessibility (HARD GATE — pass/fail)

PASS requires ALL of:
- APCA contrast in BOTH modes: body Lc≥75, large/bold ≥45, non-text UI ≥30 (run `scripts/apca.mjs`, see `apca-contrast.md`)
- Keyboard reachable for every interactive element
- Visible `:focus-visible` state on every interactive element
- Heading hierarchy sequential
- Form fields have associated `<label>`
- Icons that convey meaning have `aria-label`
- `prefers-reduced-motion` shrinks durations to ≤0.01ms

FAIL on any of the above. No partial credit.

## Ethical patterns (HARD GATE — pass/fail)

PASS requires NONE of the patterns in `ethical-patterns.md`:
confirm shaming, mislabeled actions, hidden costs, forced continuity, fake urgency,
privacy zuckering, roach motel.

FAIL on any hit. No partial credit. Ethical fails outrank polish — fix before iterating typography.

## Responsive

- **0** — broken at 375px width; horizontal scroll; content cut
- **1** — works at 375px but layout is awkward; some sections need work
- **2** — clean at 375px, 768px, 1024px, 1280px; container queries where appropriate
- **3** — responsive design carries information density appropriate to viewport (not just shrunk)

## Distinctive moves

- **0** — zero distinctive moves; UI is generic
- **1** — one distinctive move present
- **2** — distinctive moves in two of {typography, color, layout}
- **3** — distinctive moves in three+ areas; the UI has identifiable character

---

## Verdict thresholds

- **SHIP** requires:
  - Accessibility = PASS (APCA targets met in both modes)
  - Ethical patterns = PASS (no deceptive UI per `ethical-patterns.md`)
  - Direction fidelity ≥ 2
  - Anti-vibecoded ≥ 2
  - State coverage ≥ 2
  - All other dimensions ≥ 2
  - Distinctive moves ≥ 2

- **REVISE** = anything below the SHIP bar.

If REVISE: top 8 findings drive the next build loop.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall