Design Quality v2

A full-cycle skill for creating and evaluating interface design. For existing interfaces, it audits and scores. For new ones, it sets a direction and ensures the craft is there. For broken ones, it applies fixes pass by pass.

This version uses specialized subagents for Review Mode and Fix Mode — parallel where possible, deep-diving automatically when a dimension scores ≤ 5.

Gate 0: Resolve Input Type

Before any analysis or creation, identify what was shared. This changes everything downstream.

What was shared	What to do
Screenshot / image	Analyze visually; note what CSS you can't confirm
HTML / CSS source	Read the styles; full audit possible
Project folder	Glob for main CSS/component files first; read before scoring
URL / live page	Read the DOM; inspect styles via DevTools if browser available
Artifact link	Read the artifact; treat as HTML source
Text description only	Ask for at least one of the above before scoring; describe what's missing

Also detect context type — this affects which heuristics apply:

App screen (tool, dashboard, SaaS product): density governs; header is small; action IS the content
Page (landing page, marketing, editorial): more creative license; hero matters; sections and rhythm

When uncertain, state your assumption and proceed.

Mode Selection

Detect from the request — when in doubt, start with review:

Request type	Mode
"review", "critique", "audit", "does this look AI-generated?"	review
"build", "create", "design this page"	create
"fix", "improve", "unslop", "redesign"	fix (review → apply)
"polish", "feels slightly off", "almost there"	polish

If a PROJECT_DESIGN.md file exists in the project root, read it first. It contains the approved direction, palette, and Signature — don't override it without asking.

Agent Architecture

For Review Mode and Fix Mode, dispatch specialized subagents rather than doing all work serially. This produces deeper analysis in less time.

When to use agents

Review Mode on any real UI input → always dispatch 3 parallel review agents
Any dimension scoring ≤ 5 → auto-dispatch the matching deep-dive agent after the scorecard
Fix Mode → dispatch a dedicated fix agent per pass (passes 3 and 4 in parallel)
Create Mode Gate 1 → optionally dispatch a direction research agent when product URL or category is known

Fork vs fresh

subagent_type: "fork" — for review and fix agents that need the full conversation context (the UI input, screenshots, code)
Default (fresh) — for direction research agents that don't need the conversation history

Agent prompt files

Full prompt templates are in references/agents/. Reference them when dispatching — each file is self-contained with the instructions and output format for that agent.

Review Mode

Audit, score, and prioritize. No code changes without asking first.

Step 0: Dispatch 3 Parallel Review Agents

Before doing any analysis yourself, dispatch all three agents in one message using the Agent tool. All three are forks — they inherit full conversation context including the UI input.

Agent 1 — Slop Auditor Prompt template: references/agents/review-slop.md Task: slop audit, template check, accessibility, mobile/touch, performance quick checks.

Agent 2 — Scorecard Scorer Prompt template: references/agents/review-scorecard.md Task: score all 8 dimensions 1–10 with reasoning per score.

Agent 3 — Emotion Analyst Prompt template: references/agents/review-emotion.md Task: Felt State Check across all key states + Peak-End Rule mapping.

Wait for all 3 to complete, then proceed to Step 1.

Step 1: Synthesize

Merge the three agents' outputs into the standard output format. Deduplicate findings that appear in multiple agents. If agents disagree on a score, use the lower value and note the disagreement.

## Slop Audit
[from Agent 1 — each finding with location and severity]

## Template Check
[from Agent 1]

## Scorecard
Product fit:    X/10   [from Agent 2 — one-line note]
Hierarchy:      X/10
Clarity:        X/10
Taste:          X/10
Restraint:      X/10
Density:        X/10
Craft:          X/10
Responsiveness: X/10
Overall:        X/10

## Emotional Design
[from Agent 3 — Felt State + Peak-End findings]

## Verdict
Best part:
Worst part:
Required fix (P0): [if any — otherwise "none"]
Quick wins (P1): [top 3 at most]

After the output, ask whether to apply any of the fixes.

Step 2: Auto Deep-Dive

After the scorecard is shown, check every dimension. For any that scored ≤ 5, auto-dispatch the matching deep-dive agent without waiting to be asked.

See references/agents/deepdive-dispatch.md for the dispatch table and prompt templates.

Announce before dispatching: "Hierarchy scored 4 — dispatching a focused visual-hierarchy critique."

Deep-dive map:

Dimension / finding	Skill to dispatch
Hierarchy ≤ 5	`critique-visual-hierarchy` skill
Clarity ≤ 5 (affordances)	`critique-affordance` skill
Clarity ≤ 5 (density)	`critique-information-density` skill
Craft ≤ 5 (typography)	`critique-typography` skill
Craft ≤ 5 (color)	`critique-color` skill
Craft ≤ 5 (layout)	`critique-composition` skill
Taste ≤ 5 (feels flat)	`interfaces-that-feel` skill
Density ≤ 5	`critique-information-density` skill
Emotional arc issues	`peak-end-rule` skill

Create Mode

Before writing any UI, follow this sequence. Each step is a gate — stop and confirm before moving on.

Gate 0: Context type

State which applies before proceeding:

App screen — tool, dashboard, data product. Density, actions, and states govern.
Page — landing, editorial, marketing. Composition, rhythm, and sections govern.

Gate 1: Product Research Agent (optional but recommended)

If the product has a URL, name, or belongs to a known category, dispatch a research agent before asking the user for product understanding. This saves a round-trip and surfaces domain-specific conventions the user might not think to mention.

Prompt template: references/agents/direction-research.md

If no URL or category is known, skip this step and ask the user directly.

Check for an existing PROJECT_DESIGN.md in the project root. If it exists, read it — direction is already set; skip to Gate 3 (Build) and apply the recorded direction.

If not, read or ask for: what the product does, who it's for, what the primary task is, what content exists, the tech stack, existing brand colors, fonts, components.

Ask: "Is my understanding correct before I set the design direction?" Stop. Wait.

Gate 2: Direction + Design Dials

Derive five lines from the product — never from trends, portfolios, or what looks cool:

Product: What it does and for whom, one plain sentence.
Character: 2–3 concrete words. calm, exact, a little warm or fast, technical, playful. "Clean, modern, sleek, minimal, premium" are banned — they describe every template.
World: The material or place the product belongs to naturally. A note app: paper and ink. A monitoring tool: instruments and night shifts. A travel app: maps and window light. This tints the neutrals, the accent, and the visual moments.
Moments: 1–2 places on the screen where the design gets rich and specific. Everything else stays quiet so these read instantly.
Signature: One small detail only this product would have, repeated consistently.

Present 1–3 directions. For each, show three Design Dials:

Variance  ░░░░░░░░░░  1–10   (1 = minimal/centered, 10 = bold/asymmetric)
Motion    ░░░░░░░░░░  1–10   (1 = static, 10 = animated)
Density   ░░░░░░░░░░  1–10   (1 = spacious/editorial, 10 = dashboard/dense)

Ask: "Which direction? And are the dials right, or should I adjust any?" Stop. Wait.

After direction is confirmed, suggest creating a PROJECT_DESIGN.md in the project root:

# PROJECT_DESIGN.md

## Direction: [Name]
Product: [one sentence]
Character: [2–3 words]
World: [material / place]
Moments: [1–2 specific places]
Signature: [one detail]

## Dials
Variance: X/10
Motion: X/10
Density: X/10

## Palette
Canvas: [token + hex]
Accent: [token + hex]
Text primary: [token + hex]
Text muted: [token + hex]

## Typography
Display: [font name + weight]
Body: [font name + weight]
Mono: [font name] (if applicable)

## Border radius: [value]px

Design Principles

With direction confirmed, apply in this order (earlier passes affect later ones):

Spacing — establish first

8px grid. All margins, paddings, gaps: multiples of 4 or 8. (mt-[13px] → fix it.)
Same element = same size. All list rows share one height and one gap.
Space shows grouping: inner < outer. A section label sits closer to its own items than to the one above.
Navigation is densest: rows 32–36px, 2–4px between them.

Color

One neutral ramp, tinted toward the World. Backgrounds, surfaces, borders, text all from that ramp.
One accent, used rarely: primary action, selection, or the one number that matters.
Three text roles: primary, secondary, muted. Never ten slightly different grays.
Banned: hue gradients on surfaces, gradient text, colored glows, colored shadows, radial blobs, neon borders.
Accent with text on it: ≥ 4.5:1 contrast.
Prefer OKLCH for new color tokens: oklch(L% C H).

Typography

Pair a distinctive display font with a clean body font. Maximize weight contrast.
text-wrap: balance on all headings (h1–h3). text-wrap: pretty on body and list text.
-webkit-font-smoothing: antialiased on :root or html.
Minimum 14px body text (prefer 16px). One h1 per page.

Components

Buttons: verb-first labels. One primary per section.
No emoji as icons. One icon library, one stroke weight, currentColor only.
Cards: shadow OR border, not both.
Empty states: illustration + headline + CTA. Never just empty.
Loading: skeleton screens (not spinners) after 300ms delay.
Modals: X, Cancel, and Escape. Trap focus. Return focus on close.
overscroll-behavior: contain on all modals, drawers, and dropdowns.
All icon buttons need aria-label. All form inputs need an associated <label>.

One Bright Element Rule

Each screen gets one polished, rich element. Everything around it stays quiet.

Anti-Generic Guardrail

If the design would look impressive in a portfolio screenshot but make the product less clear, reject it.

After Building

Run Review Mode (with agents). Done when: no P0 findings, overall ≥ 7/10, product fit ≥ 7/10.

Fix Mode

Run Review Mode first to get the scorecard. Then dispatch fix agents in pass order.

Execution order:

Passes 1, 2 → sequential (spacing first, then color)
Pass 3 + Pass 4 → parallel (icons and copy are independent)
Passes 5–10 → sequential

See references/agents/fix-passes.md for each pass's agent prompt template.

For each pass, announce what the agent is doing and report per pass: what changed and what still needs attention.

Pass order:

Spacing — 8px grid alignment, rhythm, grouping
Color — remove slop, build from neutral ramp
Icons — one set, one size, one stroke, currentColor (parallel with Copy)
Copy — remove emoji labels, calm the shouting, make it product-specific (parallel with Icons)
Typography — hierarchy, weights, text-wrap: balance, text-wrap: pretty, antialiasing, tabular-nums
Layout — alignment, density
Details — concentric radii, shadows, borders
Accessibility & Touch — focus states, aria-label, touch-action: manipulation, 44px targets, overscroll-behavior
Visuals — empty state illustrations, icon consistency, image aspect ratios. See references/passes-visuals.md
Motion — last pass, only where it adds meaning. See references/passes-motion.md

After all passes: run Review Mode agents again to verify. Report delta from original scorecard.

Polish Mode

For interfaces that are mostly well-designed but feel slightly off.

Technique: slow the interface to 10% speed in browser DevTools (Animations panel) and walk every state: hover, focus, active, loading, empty. What feels off at 10% is what's subtly wrong at full speed.

See references/micro-polish.md for specific values.

Quick checklist:

Pre-Delivery Checklist

Before marking any UI done:

RomuloRogerio/design-quality-v2

What is design-quality-v2?

Ask in your favorite AI

Documentation