design-review

Skill: design-review

Runs a structured evaluation of a screen, flow, or mockup and returns a prioritized, severity-rated findings list — each issue mapped to the recognized usability principle or aesthetic reference it violates, with one concrete, portable recommendation. The list is the artifact: it turns "this feels off" into something a stakeholder can argue and a builder can act on.

Four modes, always run in this order:

1. Quality-floor pass — mandatory; checks all states, accessibility, and reduced-motion.
2. Heuristic evaluation — walks the surface against recognized usability principles.
3. Marketing clarity pass (when the artifact includes above-fold copy with a persuasion/conversion goal — a landing page, marketing page, or product announcement) — checks the copy against the tweet test, five-second scan, and painkiller-first structure. Does not fire for internal tools, forms, settings screens, or content pages with no conversion goal.
4. Taste critique (when a grounded aesthetic reference is present) — checks the screen against the grounded aesthetic reference and platform fit.

Authoring-time self-review. This skill is an interactive, authoring-time tool — it runs in the session, with the author. It is not a fresh-context pass and not an adversarial reviewer; a same-session critique marks its own homework. The genuine fresh-context UX review is the forked-context experience-reviewer agent — invoke it for an independent pass after the authoring session.

Output rendering

Severity list — Lead each finding with a severity glyph — 🟥 blocker, 🟧 major, 🟨 minor, ⚪ advisory — worst first, one finding per line, file:line anchor aligned.

When to invoke

Confirm all three before drafting; if any fails, resolve it first.

1. There is something concrete to review — a screen, flow, mockup, or described surface. A vibe with no artifact isn't ready; route to creative-direction.
2. You know whose task you're judging — a critique needs a user and a goal. Without them, severity is unanchored guesswork; draw out the primary task first.
3. You're evaluating, not creating — the ask is "is this good," not "make this." If it's deriving values or structuring a layout, hand to design-system or information-architecture.

Procedure

0. Surface inventory (multi-surface platforms only). If the review subject is a multi-surface platform (e.g., marketing site + documentation site, or app + marketing + docs): (a) enumerate every surface and label its genre (marketing / documentation / analytical / etc.); (b) confirm which surface is under review in this pass; (c) note which other surfaces exist — they will need separate passes; (d) flag: cross-surface integration check required (see the marketing genre rubric for copy voice continuity and the information-architecture skill for cross-surface wayfinding). If the review subject is a single surface, skip to step 1.

1. Frame the surface and load design-principles. Name the user, the primary task, and each step under review. This anchors every severity call that follows. Also load the design-principles artefact at docs/design/principles/<slug>.md if one exists for this surface — every finding in this review must be mapped to the principle it was judged against. When a finding cannot be traced to any principle, route it to one of three places: (a) a quality-floor commitment it breaches (these are always valid regardless of whether principles exist — the floor applies unconditionally), (b) a recognized heuristic from the evaluation in step 3, or (c) a new-principle decision — flag it to the team as a gap in the design-principles artefact, not as a finding in this review. Pure aesthetic preferences with no principle backing and no floor/heuristic grounding go in a Director's notes section at the end of the findings list, clearly separated from the severity-rated findings. This is a mandatory procedure step — a design-review that skips design-principles integration does not produce a traceable findings list.

2. Apply the shared floor first. Run the quality-floor checklist at references/quality-floor.md against the surface — handle all states, the accessibility floor, the reduced-motion principle. Each miss is a finding mapped to the floor commitment it breaches; accessibility misses start at major. Then apply the surface-specific mobile checklist for the surface's genre:

   Marketing surface mobile: primary CTA — and secondary CTA if present — is visible above the fold on a small-phone viewport without scrolling; hero top padding does not consume more than one-fifth of a common phone-height viewport before any content appears; navigation drawer items are full-width touch targets — compact inline chips in a vertical list are not acceptable; drawer has an explicit open/close state signal on the toggle icon; stat/feature strip dividers reset correctly when items reflow to multiple rows; tab bars scroll horizontally or wrap without a broken 3+1 layout; grid minimum accounts for the narrowest target viewport usable width minus horizontal padding on both sides; install/code blocks scroll horizontally rather than clipping.

   Documentation surface mobile: code blocks scroll horizontally (not clip); full-bleed sections that extend to the viewport edge must not produce a horizontal scrollbar on systems where scrollbars occupy layout space; sidebar collapses correctly and navigation is accessible without it at narrow-tablet widths and below; single-column reading width stays within a comfortable reading range; search is accessible from the mobile header without opening the sidebar.

3. Run the heuristic evaluation. Walk the surface against the recognized usability principles in references/heuristics.md. For each problem, record what you observed before you judge it.

4. Map and rate. Map each finding to the single best-fit principle (or floor commitment) and assign a 0–4 severity, naming the frequency × impact × persistence factors that set it. See references/heuristics.md.

5. Run the marketing clarity pass (when the artifact includes above-fold copy with a persuasion/conversion goal). For each of the three criteria, record what you observed, then map and rate: a. Tweet test — can the headline or tagline stand alone as a conviction statement? If you shared just that line with no surrounding context, would it communicate what this is and why it matters to the target reader? Failure: the line only describes the product, names a category without a reader benefit, or requires the page for meaning. b. Five-second scan — after 5 seconds on the above-fold, can a first-time visitor answer: what is this / who is it for / should I care? All three must be answerable from the visible content alone, not inferred. Failure: one or more answers are absent, ambiguous, or below the fold. c. Painkiller-first structure — does the copy lead with the reader's problem, pain, or desired outcome before naming the product's features? A painkiller solves a known hurt; a vitamin is a nice-to-have. Failure: copy leads with the author's feature list or product identity rather than the reader's recognized need.

   Map each finding to the criterion it violates and assign a 0–4 severity using the frequency × impact × persistence rubric, where impact means conversion/persuasion cost — how badly the miss hurts the reader's ability to determine fit and take the intended action. (This is a deliberate application of the same rubric to a persuasion-cost dimension; it is not a separate scale.) Label source mode marketing. A settings screen or internal tool that is out of scope for this pass produces no findings with this label.

6. Run the taste critique (when a grounded aesthetic reference from creative-direction is available). See references/taste-critique.md for the full method. In brief: a. Check aesthetic alignment — for each named goal in the grounded reference, ask whether the screen advances, is neutral to, or contradicts it. Ground each verdict in the recorded referent (persona + precedent + standards), never in a fresh opinion. b. Check platform fit — verify the screen respects the platform surface's (responsive-web / iOS / Android / cross-platform) conventions; point to the platform standard as the warrant, never reprint its values. c. Map and rate taste findings — each taste finding maps to the aesthetic goal it contradicts or the platform convention it violates; rate 0–4 by the same severity rubric (frequency × impact × persistence), with 0 reserved for genuine disagreement where the referent does not clearly resolve the call.

7. Prioritize and recommend. Merge all findings from all modes. Sort worst-first across modes, lead with a count-by-severity headline, and give each finding one concrete, portable recommendation expressed as design intent — never a stack-specific implementation. Label the source mode (floor / heuristic / marketing / taste) so the reader knows which lens each finding came from.

Genre-specific rubrics

After the quality-floor and heuristic passes, route to the genre-specific rubric that matches the surface's surface-genre: declaration (from the per-screen brief). If no genre is declared, elicit it — genre rubrics are not optional for genre-bearing surfaces; they surface issues the generic passes miss.

Each rubric is a numbered checklist. Work through it in order; a "no" is a finding, mapped to the genre rubric item that failed it. Rate each finding with the standard 0–4 severity (frequency × impact × persistence). Label source mode genre-rubric.

Multi-surface routing: When the subject includes both a marketing surface and a documentation surface, the marketing genre rubric and the documentation genre rubric must each be run as separate passes. Do not collapse them into a single pass. Each pass gets its own findings list; the cross-surface integration check (copy voice continuity, cross-surface wayfinding) runs after both surface passes are complete.

Documentation genre rubric

1. Navigation tier match — does the navigation strategy match the page count tier? (≤30 pages: flat nav; 30–200: hub-and-spoke; >200: search-first.) A flat-nav structure on a 400-page docs site fails this item.
2. Content typing — is every piece of content typed (tutorial / how-to / reference / explanation)? Does the page structure match its declared type? (A tutorial that contains a full API reference mid-step is typed incorrectly.)
3. Landing page orientation and hub structure — does the docs landing page serve orientation rather than marketing copy? Verify all three hub jobs are present: (1) "Start Here" entry point — one link, one promise, above the fold; (2) content-type entry points — one section per Diátaxis type (tutorial / how-to / reference / explanation), named by what the reader accomplishes, not by content-type label; (3) search above the fold with a placeholder naming a real example query. A landing page that leads with product benefits rather than reader navigation fails this item. For >200-page sites (see item 1, navigation tier match), search must be persistent and prominent — a top-right corner widget does not meet the search-first requirement.
4. TTFV reachability — is the first-value moment achievable from the tutorial entry point? (Tutorial is scoped to ≤20 minutes of active work; prerequisites are stated before the reader starts; code samples work as pasted.)
5. Machine-readability by design — are machine-readability requirements built into the IA? (Code blocks typed with language identifiers; API tables with consistent column structure; heading hierarchy that reflects content type.) These should be design decisions, not implementation afterthoughts.

Marketing genre rubric

1. Hero approach fit — does the hero approach match the product's position and reader's awareness level? (Vision for underfunded markets; social-proof for mature markets; job-to-be-done for buyers who know the pain but not the product.) An approach mismatch is a conversion-strategy finding, not a cosmetic one.
2. Above-fold spec — verify all six elements are present and correctly placed: (1) Headline: ≤10 words, IC-first (reader pain/goal before product name); (2) Subheadline: conviction-building (outcome or benefit), not a second problem statement; (3) Primary CTA: outcome language, not system action ("Install the core loop" not "Submit"); (4) Secondary CTA: only if primary asks meaningful commitment — absent is valid; (5) Proof signal: specific number, recognizable logo, or third-party rating, positioned adjacent to the CTAs; (6) Friction microcopy: one line removing the dominant objection to clicking the primary CTA ("No credit card", "Reversible", "1 command to try, 1 to remove") — absence is a blocker if the primary CTA implies commitment. Tone collision check: if the headline is a Statement, the subheadline must stay conviction-building — not pivot to problem-agitation (that belongs in a separate section below the fold).
3. Scroll-story zone integrity — does each zone in the scroll story have a single job? A zone that simultaneously introduces a feature, shows a testimonial, and prompts a second CTA has no job — it has three, and does none of them well.
4. Cross-surface copy voice continuity (only when a documentation surface is in scope for the same platform) — does the marketing copy voice carry through to the docs surface? Flag as minor: marketing uses precision/technical register but docs uses casual/tutorial register without explanation. Flag as major: marketing makes product claims the docs surface contradicts or doesn't support. This check requires reading at minimum the docs landing page and one how-to page alongside the marketing surface.
5. Social proof tier calibration — is the social proof at the right tier for the product's maturity stage? (Early: named customer quotes; Growth: logos + metrics; Scaled: independent validation.) A startup listing analyst rankings it hasn't earned fails this item.

Analytical genre rubric

1. Business-question traceability — does every widget trace to at least one of the 3–5 named business questions? A widget that answers no named question is a candidate for removal; flag it.
2. Tier 1 KPI ceiling — are Tier 1 KPIs ≤9 and above the fold without scrolling? Does each KPI have a visible comparison baseline (not just a primary value)? "1,247 active users" with no comparison baseline fails this item.
3. Filter adjacency — do filter controls live adjacent to the data they filter? A date range filter in a sidebar while the charts it controls are in the center creates a spatial mismatch; fails Shneiderman's zoom-and-filter principle.
4. Widget state completeness — does every widget have a designed loading state, empty state, error state, and stale-data state? A widget designed only in its "populated" state fails this item.

Informational genre rubric

1. Line-length constraint — is the reading column width constrained to produce 45–75 characters per line at the chosen type scale? A full-width text block on a wide viewport fails this item.
2. Reading-pattern consistency — does the chosen pattern (F for dense/reference-heavy, Z for conversational/single-topic) apply consistently to heading placement, first-sentence construction, and layout decisions across the page?
3. "What's next" intent clarity — does the post-article zone serve a defined reader intent (related topic / deeper dive / action / discovery) at a clear visual priority? A zone with four equal-weight "what's next" categories at identical visual weight serves no intent.

Marketplace genre rubric

1. Card hierarchy decision weight — is the card hierarchy ordered by decision weight (primary identifier → key attribute → social proof signal → secondary attributes → CTA)? An attribute that drives the match decision (price, availability, compatibility) buried below secondary details fails this item.
2. Filter architecture + buyer behavior match — is the filter architecture appropriate to the declared buyer behavior? (Browse-first: chip-based filters, immediately visible; Search-first: sidebar filters, complex taxonomy.) A browse-first surface with a sidebar-only filter fails this item.
3. Transaction bridge context — does the transaction flow (cart, checkout, booking) keep marketplace context visible throughout? A checkout screen that shows only the cart line items, with no reference to the listing the buyer selected, fails this item.

Workspace genre rubric

1. Last-location landing — does the surface land returning users at their last working context? A workspace that greets returning users with a generic dashboard instead of their last location fails this item.
2. Interrupt escalation respect — is the interrupt escalation ladder respected? (Ambient for non-urgent; focal — modal, sound, motion overlay — only for time-sensitive + action-required.) A workspace that uses focal interrupts for non-urgent notifications fails this item.
3. Agentic output review surface — for any agentic output (generated content, proposed code change, automated action), is there a review surface between the output and its application? An agent that applies output without a review step fails this item.

Anti-patterns to refuse

• Claiming to be a fresh-context reviewer. This skill is authoring-time self-review. The genuine fresh-context UX review is the forked-context experience-reviewer agent — it runs independently, between sessions, and does not mark its own homework.
• Reprinting the aesthetic reference values. The taste critique points to the grounded referent; it never reprints palette entries, type scales, spacing values, or any literal from the reference. See references/taste-critique.md.
• Unrated opinions. A finding without a severity and a violated principle or aesthetic goal is taste, not a critique. Map it or drop it.
• Skipping the floor. The quality-floor pass is mandatory, not optional polish. A surface can clear all ten heuristics and still fail the floor.
• Prescribing the stack. Recommendations name the what and why as design intent. The moment you reach for a framework, value, or property, you've left the method.
• Burying the catastrophe. A flat or alphabetized list hides the blocker. Worst-first, always, with the headline up top.