Spaces:
Sleeping
Sleeping
| # 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. | |