Don't Make Me Think — Usability Review & Redesign

Evaluate and improve UIs through Steve Krug's "Don't Make Me Think" principles. The report itself must practice what Krug preaches: scannable, visual, zero fluff. A human should skim it in 30 seconds; an AI agent should be able to parse it and start fixing.

When to Use

Trigger this skill when the user asks for a usability audit, UX review, or UI feedback on a screenshot, live URL, or HTML/CSS code. Do not use for visual/brand critique, WCAG accessibility audits, or backend/API review — route those elsewhere.

Dependency Preflight (mandatory)

This skill invokes /browse, and only on the live URL path — screenshot, code, wireframe, and description inputs need nothing installed. Resolve it before navigating anything:

test -d "$HOME/.claude/skills/browse" || asm list -p claude --json | grep -q '"browse"' || {
  echo "Missing required skill: browse" >&2
  echo "Install it:      asm install github:garrytan/gstack:browse -p claude -s global --yes" >&2
  echo "No asm yet:      npm install -g agent-skill-manager" >&2
  echo "Verify:          asm list -p claude --json | grep 'browse'" >&2
}

The install-path test runs first on purpose: /browse ships in gstack and may be present without asm knowing about it, so an asm list check alone would nag on every live-URL review.

-p claude is not decoration: asm install refuses to guess a provider non-interactively and --yes does not cover that choice. Naming the same provider in the verification stops an install under a different tool from reporting success. -s global is what makes the install agree with the detection: scope otherwise defaults to a prompt, and a project-scoped install lands in .claude/skills/, where the $HOME test above will never find it.

A missing /browse is fail-soft, not fatal — take the /browse row in Error Handling below. Never review a URL you could not load.

Repo Sync Before Edits (mandatory)

Steps 1-4 below are read-only and need no sync. Redesign Mode (step 5) writes to UI source files in a git repo — sync the branch with the remote before its first edit, so fixes land on the latest base:

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

If the tree is dirty, git stash, sync, git stash pop. If origin is missing or the pull conflicts, stop and ask the user — never skip or force the sync.

Instructions

Follow this workflow to keep the agent's context budget tight:

1. Check Prerequisites — confirm input type and access (see below).
2. Process Input — handle per the Input Handling table.
3. Evaluate — apply applicable lenses from The Ten Lenses (see references/krug-principles.md for token-efficient deep dives).
4. Generate Report — use the Report Format template verbatim.
5. Redesign (optional) — only if user requests fixes; always confirm before destructive edits.

Prerequisites

• Browser access (live URL input only): /browse, per the Dependency Preflight above
• Input available: one of — live URL, screenshot/image, HTML/CSS code, wireframe, or verbal description
• Code editor access (Redesign Mode only): write permission to the UI source files being modified

Screenshot Pre-processing

When the input is a screenshot, run the pre-processing script before visual analysis, so the review rests on measured data instead of image-processing code written at runtime:

python3 scripts/process_screenshots.py <image_path> [--recursive]

It always produces both outputs: JSON on stdout — metadata, color palette, layout regions, visual density, quality score, warnings — and a human-readable markdown report on stderr. Populate the review from the JSON; read the markdown for a quick sanity check. If the script fails or the image is invalid, fall back to visual analysis and note the failure in the review.

Read references/screenshot-processing.md for the full flag set, every extracted field, and how to map the output onto the scorecard.

Input Handling

The Ten Lenses

Evaluate through whichever lenses apply. Read references/krug-principles.md for deep detail on any principle.

Report Format

The review output must be concise, visual, and skimmable. Think bullet points, tables, and diagrams — not paragraphs. The report serves two audiences simultaneously: a human who wants to skim in 30 seconds, and an AI agent who needs enough context to implement fixes.

Use this exact template:

# Usability Review: [Page/Screen Name]

## Thinking Cost: [LOW | MODERATE | HIGH]

> [One sentence: what's the single biggest usability problem on this page]

## Scorecard

Rate each applicable lens 0-10. Use a mermaid chart to visualize.

xychart-beta title "Usability Scores" x-axis ["Self-evident", "Scanning", "Hierarchy", "Words", "Navigation", "Trunk test", "Landing", "Affordances", "Mobile", "Goodwill"] y-axis "Score" 0 --> 10 bar [8, 6, 5, 4, 7, 8, 9, 6, 7, 5]

| Lens | Score | Why |
|---|---|---|
| Self-evidence | 8/10 | Labels are clear, one ambiguous nav item |
| ... | ... | ... |

## Issues

Use severity icons: 🔴 Critical, 🟡 Moderate, 🟢 Minor

### 🔴 [Short issue title]
- **Problem:** [one line — what the user experiences]
- **Impact:** [one line — what happens because of this]
- **Fix:** [one line — specific, actionable, concrete]
- **Where:** [element/section/selector if applicable]

### 🟡 [Short issue title]
...

### 🟢 [Short issue title]
...

## Issue Map

Show where issues cluster on the page using a mermaid diagram.

graph TD subgraph Header/Nav I1["🔴 Duplicate 'macOS' label"] end subgraph Hero OK1["✅ Clear tagline"] end subgraph Mid-page I2["🟡 Tab selector too subtle"] I3["🟡 23 carousel images"] end subgraph Bottom I4["🔴 Disabled buttons, no explanation"] I5["🟡 No pricing shown"] end style I1 fill:#ff4444,color:#fff style I4 fill:#ff4444,color:#fff style I2 fill:#ffbb33,color:#000 style I3 fill:#ffbb33,color:#000 style I5 fill:#ffbb33,color:#000 style OK1 fill:#00C851,color:#fff

## Page Flow Analysis

When relevant, show the user's journey and where friction occurs.

graph LR A["Land on page"] --> B["Read hero ✅"] B --> C["Scroll features ✅"] C --> D["See carousel 🟡"] D --> E["Reach CTA"] E --> F["Button disabled 🔴"] F --> G["Abandon ❌"] style F fill:#ff4444,color:#fff style G fill:#ff4444,color:#fff style B fill:#00C851,color:#fff style C fill:#00C851,color:#fff

## What Works

Bullet list — protect these during redesign:
- ✅ [Good thing 1]
- ✅ [Good thing 2]

## Fix Priority

| Priority | Issue | Effort | Impact |
|---|---|---|---|
| 1 | [issue] | Low | High |
| 2 | [issue] | Medium | High |
| 3 | [issue] | Low | Medium |

Report Rules

• No paragraphs. Use bullet points, tables, and mermaid diagrams.
• One line per finding. Problem, impact, fix — each one line max.
• Be specific. "Move price next to download button" not "improve transparency."
• Include selectors/locations. An AI agent reading this should know exactly where to look.
• Diagrams over descriptions. If you can show it in a mermaid chart or flowchart, do that instead of writing about it.
• Severity is visual. 🔴🟡🟢 — no walls of text explaining severity levels.
• Scores are honest. A 10/10 means flawless. Most things are 5-8. Don't grade inflate.

Redesign Mode

When the user wants fixes applied (not just reported), every destructive edit requires an explicit dry-run preview and user confirmation before writing:

1. Produce the review first (same format above).
2. Dry-run first — show the planned diff (file path, selector, before/after) and wait for explicit user confirmation. Treat unconfirmed edits as a backup safety check; never write without an approval.
3. Fix critical (🔴) issues first, then moderate (🟡).
4. Change the minimum necessary — surgical, not a rewrite.
5. Preserve brand/aesthetic — make it more intuitive, not different.
6. After each fix, show before/after; if a write fails, rollback by reverting the file from git.

If working with code, edit files directly only after confirmation. For screenshots, provide specs an AI agent or developer can implement without guessing.

Error Handling

Expected Output

A completed usability review delivers a structured Usability Review markdown report containing:

• Thinking Cost rating (LOW / MODERATE / HIGH)
• Scorecard table with 0-10 scores per applicable lens
• Issues list with 🔴🟡🟢 severity icons, one-line problem/impact/fix per item
• Issue Map mermaid diagram showing where problems cluster
• Fix Priority table ordered by effort/impact

Example summary line:

Thinking Cost: HIGH — 3 critical issues found (disabled button, missing nav labels, no landing clarity)

Edge Cases

Acceptance Criteria

• Review covers all applicable lenses from The Ten Lenses table
• Every issue entry includes Problem, Impact, Fix, and Where fields (one line each)
• Mermaid Issue Map diagram is included showing issue locations on the page
• Fix Priority table is sorted by impact (highest first)
• Redesign Mode shows a before/after for each fix applied
• Report is skimmable in 30 seconds — no long paragraphs, tables and bullets only

Step Completion Reports

After each major phase, emit a status report. See references/step-completion-reports.md for the template and per-phase check names.

Working With Live Sites

1. Navigate to the page, take screenshots
2. Interact with key elements (buttons, nav, forms)
3. Check responsive behavior
4. Produce the review based on real interaction