docs/ui_inspection_workflow.md

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:

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:

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:

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.