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:

```bash
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.