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

| Target | Tool | Notes | |--------|------|-------| | Authenticated reference (you have an account) | Chrome MCP | Uses your logged-in session | | Public reference (marketing pages, docs, public demos) | Playwright MCP | No login needed |

See [../ux-audit/references/browser-tools.md](../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:

| State | Trigger | |-------|---------| | Default | page loaded, nothing interacted with | | Hover | mouse over a button, row, nav item | | Focus | keyboard-focused via Tab | | Active | button mid-click, input being typed into | | Open | dropdown open, menu expanded | | Closed | dropdown closed, menu collapsed | | Expanded | accordion open, detail panel expanded | | Collapsed | accordion closed | | Selected | checkbox ticked, row selected, tab active | | Loading | skeleton, spinner, pending state | | Empty | list with no items | | Populated | list with many items | | Error | inline, toast, or full-page error | | Success | post-action confirmation |

See [references/capture-checklist.md](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 paragra