Ux Compare

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 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.
Divergence: claude.ai guides toward keyboard workflow; notion guides toward templates.
Unique: notion's template-first empty state.
Coverage gap: superhuman not assessed.

### Empty search results
[...]

## Recommendations

- **Safe default**: illustration + one-line description + primary CTA. All convergent apps do this.
- **Consider**: shortcut hints (like claude.ai) if your power-user persona is strong. Tradeoff: adds visual noise that doesn't help first-time users.
- **Skip**: notion's template picker unless you have a templates feature.
- **Fill a gap**: none of the 4 apps explain *why* the list is empty. A one-liner ("No clients yet — add your first to get started") is convergent practice and worth preserving.

## Source libraries

- claude.ai — 2026-03-12
- linear.app — 2026-02-28
- notion.so — 2026-01-15 (stale, re-extract recommended)
- superhuman — 2026-03-20

Autonomy

• Just do it: Discover available libraries, read them, write the comparison document, cite specific screenshots or copy from the source libraries
• Ask first: If the user didn't specify scope — one focused question is cheaper than a sprawling comparison
• Stop and confirm: If fewer than 2 usable libraries exist — comparing is impossible with 1 library, suggest ux-extract first

Reference files

Tips

• Don't re-list everything from every library. The comparison is value-add synthesis. If you're just copying bullets from 5 libraries, you're not comparing.
• Convergence is usually the safest choice, but not always the most interesting one. Call out where convergence might be copy-paste rather than good design.
• Cite screenshots from the source libraries — don't copy them. "See claude.ai pattern library § Empty States, screenshot 502" keeps extracts as the single source of truth.
• Stale libraries are still useful — just note the date. A 12-month-old library is a snapshot of that moment, not nothing.
• Recommendations must be opinionated. "It depends" is the weakest possible output. State a position. The user can disagree.
• Comparisons age too. Re-run when underlying extracts get refreshed, or when a new reference enters the set.

Future: more than 5 apps

Comparisons scale non-linearly. 3 apps is comfortable; 5 is the upper bound of readability; 10 becomes a matrix that's impossible to synthesise in prose. If comparing more than 5 libraries, bucket them:

• Tier 1 (closest to your app) — detailed bullets
• Tier 2 (reference-class) — summary bullets
• Tier 3 (outliers, novel approaches) — mention by exception

Or do several narrower comparisons rather than one mega-comparison.

Comparison Output Template

Structure for the document produced by ux-compare. Write to docs/ux-comparisons/<topic>-YYYY-MM-DD.md.

Topic slug matches the scope: empty-states, onboarding, keyboard, destructive-actions, modals, whole-app, etc.

# UX Comparison: [Topic]

**Date**: YYYY-MM-DD
**Scope**: [What this comparison covers — specific feature, category, or whole-library]
**Compared**:
- [app-1]  (extracted YYYY-MM-DD)
- [app-2]  (extracted YYYY-MM-DD)
- [app-3]  (extracted YYYY-MM-DD — ⚠ stale, re-extract recommended)
**Source libraries**: `docs/ux-extracts/[app-1]/`, `docs/ux-extracts/[app-2]/`, etc.

## At a glance

[2–3 sentences: the headline findings. What converges? What diverges? What's surprisingly absent?]

## Convergence (strong signal)

Where most or all of the compared apps agree. These are defensible defaults — following them means users won't feel lost.

- **[Pattern]**: [how it's handled across the set, one sentence]
- **[Pattern]**: [...]

## Divergence (design decisions)

Where apps genuinely differ. Each divergence is a tradeoff — pick based on your context.

### [Pattern with divergence]

- **[App A]**: [what they do]
- **[App B]**: [what they do]
- **[App C]**: [what they do]

**Tradeoff**: [one sentence explaining when you'd pick each approach]

### [Another pattern]
[...]

## Unique approaches

Patterns only one app in the set uses. Call them out — either innovation worth borrowing, or weirdness worth avoiding.

- **[App]** — [pattern]. [Why they probably do it; whether it's borrowable]

## Absent across the set

What none or few of these apps do. Notable because it surfaces design *decisions by omission*.

- **[Absence]**: [X of N apps skip this]. [Interpretation — deliberate, convention, or overlooked?]

## Pattern-by-pattern detail

For each pattern category in scope, one section. Use this structure:

### [Pattern category, e.g. Empty list state]

**What each app does:**

- **[app-1]**: [concrete description — verbatim copy, layout, CTA behaviour]
  - *Source*: [path or anchor to the library entry, e.g. `ux-extracts/claude-ai/pattern-library.md#empty-states`]
- **[app-2]**: [...]
- **[app-3]**: [not covered in the extract — coverage gap]

**Convergent**: [what's shared across the set]

**Divergent**: [where the apps split]

**Unique**: [if any]

**Missing**: [if any app's library doesn't cover this]

### [Next pattern]
[...]

## Recommendations

This is the reason to have run the comparison. State positions. If you hedge here, the document is just a pile of bullets.

### For a new build in this space

1. **Safe default**: [the convergent choice — use this unless you have reason not to]
2. **Consider**: [divergent option A] — trades [benefit] for [cost]
3. **Consider**: [divergent option B] — trades [benefit] for [cost]
4. **Skip**: [unique approaches you'd avoid, with the reason]
5. **Fill a gap**: [absences worth addressing because your users would benefit]

### For an existing build in this space

- **Convergence you're missing**: [patterns common across references but not in your app]
- **Divergence worth reviewing**: [places your app does something unusual — is the reason still valid?]
- **Unique strengths**: [if your app already does something no reference does well, note it]

## Source library health

| Library | Extracted | Coverage for this comparison | Staleness risk |
|---------|-----------|----------------------------|----------------|
| [app-1] | YYYY-MM-DD | Full / Partial / Missing | Fresh |
| [app-2] | YYYY-MM-DD | Full | ⚠ 4 months — re-extract |

## What this comparison doesn't tell you

Be explicit about the limits:

- [e.g. "Performance was not captured in any extract — if speed is a key criterion, test directly."]
- [e.g. "Mobile patterns less thoroughly extracted for [app-3] — findings there may be partial."]
- [e.g. "All extracts used paid-tier accounts; free-tier UX may differ."]

Guidelines for writing the comparison

• Synthesise, don't list. If you're just copying bullets from 5 libraries, you're not comparing — you're collating. The value is the convergent / divergent / unique / absent framing.
• Be opinionated in recommendations. "It depends" is the weakest possible output. State a position.
• Cite sources. Link to the specific section of the pattern library file. ux-extracts/claude-ai/pattern-library.md#empty-states is enough. Don't re-embed screenshots — the extract is the single source of truth.
• Flag coverage gaps honestly. "Not covered in app-3's extract" is not the same as "app-3 doesn't do this". One is a library gap, one is an app decision.
• Date everything. Both the comparison itself and each source library. Comparisons decay as fast as the libraries they're built on.
• When app extracts are stale, note it prominently — don't just mention it in the source table. Recommendations based on 6-month-old extracts should come with a qualifier.
• Limit scope for sharpness. A focused "empty states across 4 apps" is more useful than "whole-library comparison across 7 apps". Narrow wins.