# UI Inspection Workflow

This repo needs two equal review paths:

- design review for hierarchy, spacing, and intended component behavior
- runtime review for what users actually see in the browser

## Primary tools

### 1. Chrome DevTools MCP

Use Chrome DevTools MCP as the default runtime inspection tool.

Use it for:
- spacing or overflow bugs
- drag and drop hit-area issues
- console or network-backed UI failures
- click latency and rerender debugging
- desktop and mobile screenshots of the live app

Suggested Codex install:

```bash
codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
```

### 2. Playwright MCP

Use Playwright MCP for repeatable end-to-end interaction flows and stateful browser automation.

Use it for:
- stable scripted walkthroughs
- screenshot capture with deterministic setup
- auth-preserving regression checks
- before and after UI comparisons

Suggested Codex install:

```bash
codex mcp add playwright -- npx @playwright/mcp@latest
```

### 3. Figma Dev Mode

Use Figma Dev Mode as the design inspection layer.

Use it for:
- spacing and hierarchy review
- component intent and visual structure
- token or style handoff
- comparing intended layout against the running browser UI

### 4. Figma Make

Use Figma Make only for concept exploration or redesign spikes.
Do not treat Figma Make output as proof that the shipped app behaves correctly.

## Audit order

For any meaningful UI change, review in this order:

1. Figma review
- confirm intended hierarchy
- confirm spacing and component sizing
- check desktop and mobile frames

2. Runtime review
- inspect the live app at `http://127.0.0.1:8011`
- capture screenshots at desktop and mobile widths
- inspect DOM, layout, console, and network behavior

3. Regression capture
- run `scripts/ui_visual_audit.py`
- run `scripts/diagnose_ui_flow.py` for auth/detail wire checks
- run `scripts/record_product_flows.py` for broader product flows
- run `python scripts/audit_runner.py --tier fast` for the wider OTS-backed audit layer

## Runtime audit script

Use the visual audit script to capture the current shell and key clipped surfaces:

```bash
cd /home/ron/proj/kink_cli
. .venv/bin/activate
python scripts/ui_visual_audit.py
```

Artifacts are written to `/tmp/kink_ui_audit`.

The script captures:
- desktop full-page screenshots
- mobile full-page screenshots
- clipped screenshots for `For You`, `Your Play List`, `Shared Play List`, and `Play Details`
- basic layout metrics like bounding boxes and scroll height
- console errors per scenario

## Minimum review surfaces

Every serious UI pass should inspect:
- onboarding or auth modal
- `For You`
- `Your Play List`
- `Play Details`
- `Shared Play List`
- mobile shell

## Defaults for this repo

- Browser reality is the runtime truth.
- Figma is the design-intent truth.
- Neither is sufficient alone.
- The wider audit stack lives under `audit/` and is orchestrated by `scripts/audit_runner.py`.
- Use the repo-specific Playwright scripts as the product truth layer, and the OTS tools as the cross-cutting quality layer.
- Do not add Storybook first. This app is not currently organized around a component lab.
- Add Storybook or Chromatic later only if the frontend becomes component-driven enough to justify it.