ux-extract（用户体验提取）

UX Extract

Exhaustively study a reference web app and produce a reusable pattern library. Goes everywhere, captures everything, then organises it into a document another audit or build can reference.

The inverse of ux-audit:

• Audit asks: *does this match a bar?*
• Extract asks: *what is the bar?*

Audits without extracts implicitly compare to "my memory of other apps" — fragile and inconsistent. Extracts turn that memory into a concrete, navigable artifact. An audit can then say: *"Empty state on /app/clients shows no CTA. Reference (claude.ai) shows 3 keyboard shortcuts plus 'New chat' in the same position"* instead of *"feels a bit sparse"*.

When to use

• Before building a new feature — study how best-in-class apps handle it
• Benchmarking a build — extract the reference, then audit against it
• Onboarding designers or engineers — here's what good looks like, concretely
• Competitor research — document the competitor's UX so you can meaningfully differentiate
• Refreshing an old app — extract patterns from modern equivalents to guide the update

Scope and ethics

Before starting, confirm the target is fair game:

1. Use your own account — don't scrape anything that requires credentials you don't legitimately hold
2. Respect robots.txt for unauthenticated crawling
3. Rate-limit — act like a human user, not a crawler. Pause between pages.
4. Check ToS — most SaaS Terms of Service permit individual inspection but prohibit automated scraping
5. Don't redistribute screenshots of a live competitor's app publicly — pattern libraries are internal references

If the target is behind a paywall or requires a trial account, ask the user whether they have legitimate access before proceeding.

Setup

1. Browser tool

See ../ux-audit/references/browser-tools.md for commands.

2. Viewport

Pin 1440×900 as baseline (MacBook standard). Also capture 768 and 375 for responsive patterns. Don't exceed 2000px wide.

2b. Screenshot post-processing

On Retina Macs, Chrome captures at 2× the logical viewport — a 1440-wide window produces a 2880-wide PNG. Post-process after each batch so the library isn't full of oversized files:

img-process batch ./screenshots --action optimise --max-width 1440

Idempotent — no-op on already-small files. Run at the end of each route's capture, or across the whole screenshots/ folder at the end of the extract. Playwright MCP users can set deviceScaleFactor: 1 in the context options and skip this step.

3. Scope

Decide before starting:

• Whole app — traverse everything reachable (can take hours, produces a comprehensive library)
• Feature area — one section ("the settings flow", "the dashboard", "the billing flow")
• Pattern class — just empty states, just error handling, just onboarding

Narrower scope produces tighter, more useful libraries. "Whole app" is only worth it for apps you'll be building a direct analogue of.

4. Focus lens (optional)

Optional bias for capture. Examples:

• *"Focus on patterns for data-heavy lists"* — prioritise table, filter, search, virtualisation screenshots
• *"Focus on onboarding and empty states"* — prioritise first-run flows and zero-data views
• *"Focus on permission boundaries"* — log in as multiple roles, document the differences

If no focus is given, capture broadly.

Discovery

Sitemap crawl

Build the full route inventory:

1. Public sitemap — check /sitemap.xml, /robots.txt for discoverability
2. Nav crawl — click through every section visible in the top nav, sidebar, footer
3. In-app discovery — once inside, note every link that appears (breadcrumbs, tabs, contextual menus)
4. URL inspection — some apps have useful patterns in /settings, /preferences, /admin that aren't in the main nav

Record each route with its purpose: /settings/billing — subscription plan, payment method, invoice history.

Pattern inventory

Before deep-capture, scan the app once and list pattern types you'll document. Typical categories:

• Wayfinding (nav, breadcrumbs, current-location, back)
• Lists & tables (row, hover, action reveal, selection, sort, filter, paginate, empty)
• Forms (label, validation, error, required, inline help)
• Modals & dialogs (trigger, focus, escape, scroll, confirm)
• Feedback (toast, inline, progress, loading, saved)
• Onboarding & empty states (first-run, zero-data CTA, guided tour)
• Permissions & roles (restricted views, denied-access, role indicators)
• Copy & microcopy (buttons, headings, errors, placeholders, tooltips)
• Keyboard (shortcut sheet, focus, tab order, command palette)
• Motion (transition, reveal, loading, gesture)
• Responsive (breakpoints, mobile-specific: bottom sheet, tabs, swipe)

Not every app uses every category. Mark which apply.

Capture Phase

For each route, capture exhaustively. Screenshots are cheap — err toward more.

Screenshot all states

Per meaningful element, capture:

See references/capture-checklist.md for the full per-pattern checklist.

Capture copy verbatim

Copy the text exactly, including punctuation, ellipses, and tone:

• Button labels: "Start chat", "Upgrade plan", "Delete forever"
• Empty states: *"No conversations yet. Start one to see it here."*
• Error messages: *"We couldn't save that change. Try again, or contact support if it keeps happening."*
• Confirmation dialogs: *"Delete this project? All 14 tasks and 3 members will be removed. This cannot be undone."*
• Placeholder text: "e.g. smith@company.com"
• Tooltips: "Pressing Cmd+K opens this from anywhere"

Raw copy is gold for writers and informs your app's voice.

Capture interactions

For each interactive element, note:

• Trigger: click / hover / keyboard / long-press / drag
• Target: what it affects (opens modal, filters list, navigates)
• Feedback: immediate visual response? delayed confirmation?
• Reversibility: undoable? destructive?

Capture keyboard patterns

• Shortcut sheet: is there a ? or Cmd+/ that reveals the shortcut list? Capture it.
• Command palette: Cmd+K or similar? Capture the palette open, searching, a result selected, and an action executed.
• Focus indicators: tab through the page, note the ring style, colour, thickness
• Tab order: is it logical? Any unexpected jumps?

Capture responsive treatments

For each route, screenshot at 1440, 768, 375. Note what changes, not just "it works":

• Navigation moves from sidebar to hamburger at [breakpoint]
• Table collapses to stacked cards at [breakpoint]
• Modal becomes full-screen at [breakpoint]
• Multi-column form becomes single-column at [breakpoint]

Capture motion

Record a GIF (Chrome MCP's gif_creator) of any animation worth documenting:

• Page transitions
• Modal enter/exit
• List item enter/exit
• Loading → loaded
• Success animations (confetti, checkmarks)
• Drag-and-drop feedback

One 3-second GIF is worth a paragraph of description.

Dedup Phase

After capture, many patterns will appear on multiple pages. Deduplicate:

• Same row pattern on 5 list pages → one "list row" entry with a note *"used on: /clients, /projects, /invoices, /reports, /team"*
• Same empty state layout with different copy → one "empty state" entry with copy variants listed
• Same modal chrome → one "modal" entry; specific modals listed as usages

Keep two counts per pattern:

• Occurrences — how many times this pattern appears
• Variants — meaningful differences (icon vs no icon, small vs large, with CTA vs without)

A pattern that appears once is rarely worth documenting unless it's unique and notable.

Output

Write to docs/ux-extracts/<app-name>/ (or .jez/artifacts/ux-extracts/<app-name>/ if that directory exists):

docs/ux-extracts/claude-ai/
├── pattern-library.md      ← main document
├── copy-corpus.md          ← optional, raw copy by page (for writers)
└── screenshots/
    ├── 001-home-default.png
    ├── 002-home-hover-cta.png
    ├── 003-new-chat-empty.png
    └── ...

See references/pattern-library-template.md for the output structure.

The pattern library should be:

• Navigable — table of contents at the top, jump links to every section
• Cross-referenced — "see also: Modal Chrome"
• Screenshot-dense — every claim backed by a referenced screenshot
• Copy-accurate — verbatim text in code blocks or blockquotes, not paraphrased
• Honest — note what's *missing* or *weak* as well as what's good. A reference library isn't gospel.

How ux-audit consumes this

ux-audit checks for pattern libraries at .jez/artifacts/ux-extracts/<ref>/pattern-library.md or docs/ux-extracts/<ref>/pattern-library.md. If found, it uses them as the bar for comparison. Audit findings can then cite specific patterns:

*"Empty state on /app/clients has no explanatory copy and no CTA. Reference library [claude.ai § Empty States] shows CTA + 2 example prompts in the same position."*

No integration is required beyond producing the library in the expected path.

Autonomy

• Just do it: Navigate, screenshot, copy text, inject JavaScript to read computed styles, download static assets (logo, icons) for reference
• Ask first: Any login that requires credentials the user hasn't authorised you to use, any scraping of a site where ToS or rate limiting is ambiguous
• Stop and confirm: If the target has a login wall and you don't have clear authorisation, stop and confirm before proceeding

Reference files

Tips

• Screenshots are cheap — capture generously. Easier to drop a screenshot from the library than to rerun the extract to get one.
• Capture copy the moment you see it — don't plan to come back; come back and it'll be behind a different state.
• Note what's absent — if an app has no keyboard shortcut sheet, that's a pattern decision worth documenting too.
• Separate observation from evaluation — extract records what exists, not whether it's good. Opinions belong in an audit, not an extract.
• Extracts decay — apps change. Timestamp the library, link to the date on archive.org if possible, plan to re-extract every 6–12 months for apps you compare against often.
• Build incrementally — open the library file at the start, append as you go. Don't try to structure it all at the end.