---
name: design-critique
description: >
  Run a structured design critique on any page or component BEFORE building. Trigger on any task
  touching visible UI, or phrases like "improve the UI", "redesign", "polish", "make it look
  better", "visual upgrade", "design review", "layout fix", "UX improvement". Produces a structured
  critique the builder must address before writing code. If you are about to edit a file that
  renders visible UI, use this skill first.
---

# Design Critique

You are a design critic for this project's UI. Evaluate a page or component against the project's
design system and compositional principles, then produce a verdict the builder must address before
writing or modifying code.

## Why This Exists

LLM builders converge on median patterns. They produce locally correct components that are globally
incoherent — every card looks fine alone, but the page has no hierarchy, no reading order, no
dominant element. Over many "improve X" tasks a UI accumulates flat layouts, equal-weight sections,
and decoration that doesn't earn its space. This skill forces a compositional audit before code.

## When to Run

1. **Before building** — read the target page, run the critique, address issues in your plan.
2. **After building** — re-run on your changes to verify you introduced no new violations.

## Step 0: Declare the Dials (before critiquing)

Soft guidance gets ignored; agents converge on median output unless forced to commit. State three
dials up front — they set the bar the critique measures against:

- **Variance** (1–10): symmetric/templated → asymmetric/bespoke.
- **Density** (1–10): airy → cockpit.
- **Motion** (1–10): static → cinematic (motion signals state change, not decoration).

Plus a one-line page read: `kind / audience / the one thing they must see first`.

## Step 1: Gather Context

1. **Read `DESIGN.md` and `PRODUCT.md`** at the project root. `DESIGN.md` owns the visual system
   (palette, typography, spacing, elevation, components, and the named anti-patterns / "do's and
   don'ts"). `PRODUCT.md` owns audience, voice, and strategic design principles. If they don't
   exist, that's the first gap — a critique without a design system is just opinion.
2. **Read any brand book** (e.g. under `docs/branding/`). When it and DESIGN.md agree you're on
   canon; when they disagree on palette / typography / voice / anti-patterns, surface the conflict.
3. **Read the target page in full** — not just the component you're editing. You need full page
   context to judge compositional hierarchy.
4. **List all sibling components** on the page. You'll weigh each one's visual weight against the others.
5. **Check both states:** populated and empty/zero-data. Both need clear hierarchy (a hero only where one is warranted — see Check 1).

## Step 2: The Seven Checks

For each, give ✅ Pass / ⚠️ Weak / ❌ Fail plus a one-line reason.

### Check 1: Hero Element (conditional — NOT every page needs one)
> Give the page one dominant element WHEN it has one thing that must lead. A hero is not mandatory.
Does this page have a single thing that must lead? If yes: name it; missing/weak = ⚠️/❌. If no (a
dense tool / list / board / settings surface): a calm, even hierarchy is ✅ — do NOT manufacture a
hero to pass this check. Two elements *competing* for dominance is ALWAYS ❌ (the real failure).

### Check 2: Reading Order
> hero → primary action → supporting content → tertiary.
Trace it explicitly. Interchangeable sections = ⚠️. Nowhere for the eye to land first = ❌.

### Check 3: Information Density
> No more than ~3 visible sections before the user must scroll or click.
Count sections above the fold. Ask: does each earn its above-fold spot, or could it be collapsed?

### Check 4: Earned Elements
> Every visible element answers a question the user has when they open this page.
State the question each section/card/metric answers. Can't articulate it → it doesn't earn its space.
Decorative elements with no data or action purpose are ❌.

### Check 5: Typography Hierarchy
> Display > Heading > Subheading > Body > Caption — each visually distinct.
Metric values larger/bolder than labels. Use the DESIGN.md type scale and font roles. Monospace ONLY
for IDs and code — never labels, status, timestamps. Two levels at the same weight/size = ❌.

### Check 6: Anti-Pattern Scan
> Cross-reference the named anti-patterns in DESIGN.md ("do's and don'ts").
Run through every named anti-pattern and flag matches. Common universal ones:
- Equal visual weight across the page (no primary element)
- Components built for unpopulated/zero data
- Monospace on non-ID content
- Decorative gradients / glows (the generic-AI look)
- Cards inside cards (three surface levels)
- Pages without a hero
- Auth/gate before any value is shown
- Hostile zero states ("No items" / "Nothing here")

### Check 7: Colour Compliance
> Every colour has a job. Check the DESIGN.md palette is used correctly.
- Accent/brand colours: actions and emphasis, not random decoration.
- Signal/status colours: only on elements that represent that status.
- Neutrals tinted per the brand, not cold grey.
- Hardcoded hex instead of tokens: ❌.

### Check 8: Hard-Fail Blocklist (falsifiable AI tells)
> Soft principles converge on slop. These are pass/fail. ANY hit = ❌ for the page.

- Gradient text or gradient fill used decoratively.
- Brand accent as a glow / dark-only sheen instead of solid intentional colour.
- A "signal" colour used as a plain decorative fill.
- Two elements competing for dominance (both fight for the eye). NOT a fail: a page with no hero
  when nothing must lead (see Check 1) — only *competing* dominance fails here.
- Guidance, state, or a next action carried by a sentence of helper text where a visual cue
  (position, size, colour, an icon, a signpost, motion-on-change) would do — prose as a crutch for
  missing visual steering. Prefer showing over telling.
- A label, its value, and its explanation each taking their own line ("The Stacked Caption") —
  anywhere the three exist, they share ONE line.
- A new datum added as a sibling row beside a row it could extend ("The Siblinged Row") — extend
  the existing row (inline suffix, extra cell, chip on the same baseline), never stack a twin row.
- An eyebrow label or explanatory subtitle above/below a heading ("The Eyebrow Crutch") — labels
  carry themselves; a heading that needs a subtitle to be understood is the wrong heading.
- Identical-sized cards in a uniform row (flat hierarchy).
- Monospace on labels / status / timestamps / nav.
- Header, label, and value at the same size+weight.
- Cards nested in cards (three surface levels).
- Cold/untinted grey where the brand neutrals are tinted.
- An em-dash in any UI string, button, alt text, or eyebrow.
- Duplicate CTA intent on one view.
- A detail/side panel showing an empty placeholder when nothing is selected (it should be absent).
- Hostile/jargon empty state.
- A decorative element you can't tie to a user question.
- Motion that breaks above ~100ms load, animates layout props, or lacks a reduced-motion fallback.

## Step 3: The Verdict

```
## Design Critique: [Page Name]

### Score: X/7 passing

| Check | Verdict | Issue |
|-------|---------|-------|
| Hero Element | ✅/⚠️/❌ | ... |
| Reading Order | ✅/⚠️/❌ | ... |
| Information Density | ✅/⚠️/❌ | ... |
| Earned Elements | ✅/⚠️/❌ | ... |
| Typography Hierarchy | ✅/⚠️/❌ | ... |
| Anti-Pattern Scan | ✅/⚠️/❌ | ... |
| Colour Compliance | ✅/⚠️/❌ | ... |

### Must-fix before building:
1. [specific, actionable fix]

### Recommendations (non-blocking):
1. [improvement that would elevate the design]
```

## Step 4: Addressing the Critique

The builder MUST address every ❌ before completing the task. ⚠️ items if scope allows. Document
which items were addressed. If a critique item conflicts with the handoff (e.g. "add a section" but
density is already too high), flag the conflict — don't silently make the page worse.

## Post-Build: Pre-Delivery Checklist

The pre-build critique catches composition; this catches what's only visible in a real browser:

- [ ] Verified in-browser at three states: populated, 0-data/empty, mobile (≤640px).
- [ ] Contrast checked in every theme the project ships (don't assume light values carry to dark).
- [ ] `reduced-motion` honoured — every animation has a fallback.
- [ ] No hardcoded hex; tokens regenerated if the project has a token build step.
- [ ] `tabular-nums` on data tables and stat values.
- [ ] Mobile body floors at 16px (no iOS zoom-on-focus); breakpoints via CSS, never JS viewport detection.
- [ ] Re-ran the Seven Checks + Blocklist on the finished surface — no new violations.

## The Core Principle

**Composition > Decoration, and show > tell.** A page with perfect tokens and flat hierarchy is
worse than one with slightly-off tokens and clear hierarchy. Two things generalist agents keep
getting wrong: (1) **steer with visuals, not text** — reach for position, size, colour, an icon, a
signpost, or motion-on-change before a sentence of helper text; over-explaining in prose is the
default AI failure mode. (2) **A hero is conditional** — give a page one dominant element only when
it has one thing that must lead; dense list / tool / settings surfaces carry a calm, even hierarchy,
so do not manufacture a hero. Clear reading order, everything earns its space, show before you tell.