--- name: jezweb/ux-compare source: https://app.decimal.ai/s/jezweb-ux-compare@1/SKILL.md source_sha256: 6eacfa494ba6 --- # 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//pattern-library.md` - `.jez/artifacts/ux-extracts//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/-YYYY-MM-DD.md` (or `.jez/artifacts/ux-comparisons/-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. 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 | When | Read | |------|------| | Writing the comparison document | [references/comparison-template.md](references/comparison-template.md) | ## 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.