/ux-compare

name: ux-compare
description: "Compare UX patterns across multiple reference apps using pattern libraries produced by ux-extract. Reads 2+ pattern-library.md files, walks them category by category, identifies where apps converge (strong signal), where they diverge (genuine design choice), what's unique to one app, and what's absent across the set. Produces an opinionated comparison document with recommendations for a new build. No browser needed — pure markdown analysis. Trigger with 'compare UX patterns', 'how do top apps handle X', 'ux comparison', 'pattern comparison across reference apps'."
compatibility: claude-code-only

UX Compare

Read N pattern libraries produced by `ux-extract` and synthesise a comparison. Answers questions like:

• *"Across claude.ai, Linear, Notion, Vercel, and Superhuman — how are empty states handled?"*
• *"Which apps use keyboard shortcuts, and what's the shared vocabulary?"*
• *"When we build our billing page, should we follow convention or deliberately break it?"*

A single extract is a reference point. Multiple extracts are a design library. A comparison is a *decision aid* — it turns the library into "here's what to do and why".

When to use

• **Before a build** — comparing 3–5 references for the feature class you're about to build reveals the convention and the tradeoffs
• **During a design review** — "this pattern isn't in any of the 5 references we've extracted — is that deliberate?"
• **For team alignment** — shared reference for a design decision
• **To produce a design brief** — convergent patterns become the baseline; divergent patterns become the discussion

Inputs

Available libraries

First, discover what's available. Pattern libraries live at:

• `docs/ux-extracts/<app-name>/pattern-library.md`
• `.jez/artifacts/ux-extracts/<app-name>/pattern-library.md`

List everything you find. Show the user the inventory with the extraction date for each so they can spot stale ones:

Available pattern libraries:
- claude.ai      (extracted 2026-03-12)
- linear.app     (extracted 2026-02-28)
- notion.so      (extracted 2026-01-15) ← 3 months old
- superhuman     (extracted 2026-03-20)

If only one library exists, stop and suggest running `ux-extract` on more apps first. A one-library "comparison" is just the library.

Scope / focus

Ask the user what to compare — or infer from their request:

• **Whole library** — compare every category across every library (verbose but comprehensive)
• **One category** — just empty states, just keyboard, just modals (tighter, more useful for specific decisions)
• **A feature area** — "how do these apps handle settings", crosses multiple categories but stays focused
• **A specific question** — "which apps support offline?" — searches Notable Absences sections too

Narrower scope produces sharper recommendations. Default to asking: *"What feature or pattern do you want to compare?"*

Libraries to include

By default, include every library the user mentions or all of them if they don't specify. Let them exclude: *"all except notion — their library is too stale"*.

Comparison Process

1. Read every library

For each library in scope, read the full `pattern-library.md`. Note:

• Extraction date
• Scope of the extract (whole app vs partial)
• Any **Notable Absences** section — often the most interesting data for comparison

2. Walk category by category

For the scope requested, walk each pattern category that appears in any library. For each category:

1. **List what each app does** — one bullet per app, concrete and verbatim where possible 2. **Identify convergence** — what's the same across most or all? This is the low-risk default. 3. **Identify divergence** — where do they genuinely differ? This is a design decision. 4. **Flag unique approaches** — only one app does X. Either innovation or weirdness; call it out either way. 5. **Flag coverage gaps** — if an app's library doesn't cover this category, say so (don't silently treat absent-from-library as absent-from-app).

3. Cross-reference absences

After walking categories, collect what's absent across the set. If 4 of 5 apps have no undo on destructive actions, that's a pattern. If 3 of 5 apps have no keyboard shortcut for new-record creation, that's a decision someone keeps making.

4. Synthesise recommendations

Close with opinionated guidance:

• **Safe default** — the convergent pattern. Following it means users feel at home.
• **Deliberate choices** — the divergent patterns, with the tradeoff of each so the user can pick.
• **Avoid** — unique-to-one patterns unless there's a clear reason why that one app does it differently.
• **Gaps worth filling** — absences that are surprising, or that your users would benefit from seeing addressed.

The recommendations section is the reason to run the comparison. Without it, the doc is a pile of bullets. With it, it's a decision.

Output

Write to `docs/ux-comparisons/<topic>-YYYY-MM-DD.md` (or `.jez/artifacts/ux-comparisons/<topic>-YYYY-MM-DD.md` if that path exists).

Topic slug from the scope — e.g. `empty-states`, `keyboard-shortcuts`, `onboarding`, `destructive-actions`.

See [references/comparison-template.md](references/comparison-template.md) for the full output shape.

Short version:

# UX Comparison: Empty States

Compared: claude.ai, linear.app, notion.so, superhuman
Date: 2026-04-19
Scope: How these apps handle empty states across list views, onboarding, and zero-data dashboards.

## At a glance

[2-3 sentences: what converges, what diverges, what's missing across the set]

## Pattern-by-pattern

### Empty list state

- **claude.ai**: illustration + headline + description + primary CTA + 3 shortcut hints
- **linear**: headline only, small text, no CTA
- **notion**: template picker (unique — offers 12 templates)
- **superhuman**: empty state not reached in extract (all-data demo account)

Convergence: most show some form of guidance; none are fully blank.
Dive