PWA User Simulation Skill
Simulate real user journeys through a web application using Playwright MCP (accessibility tree, structured navigation, assertions) and Chrome DevTools MCP (visual screenshots, DOM inspection, JS evaluation). Produce structured reports with prioritized findings and actionable handoff recommendations.
When to Load References
- Persona definitions → load
references/personas.md - SXO audit checklist → load
references/sxo-checklist.md - MCP tools usage guide → load
references/mcp-tools-guide.md - Journey report template → copy from
assets/journey-report.md
Simulation Protocol (3 Phases)
Phase 1 — Bootstrap & Discovery
- Verify the app is running (
browser_navigateto$BASE_URLorhttp://localhost:3000) - Take an initial screenshot (Chrome DevTools
take_screenshot) + accessibility snapshot (Playwrightbrowser_snapshot) to confirm the landing state - Load the selected persona from
references/personas.md - List all navigable routes visible from the current page (links, nav items, CTAs)
Phase 2 — Route-by-Route Exploration
For each route in the persona's journey:
- Navigate — use Playwright
browser_navigate(structured, token-efficient) or Chrome DevToolsnavigate_page(if vision/screenshot needed) - Snapshot — take an accessibility snapshot (
browser_snapshot) to read the page structure as an accessibility tree - Screenshot — take a visual screenshot (
take_screenshot) to capture visual state. Do this at every significant state change: page load, form interaction, modal open, error state, loading state, hover state - Interact — simulate user actions: click CTAs (
browser_click), fill forms (browser_type), submit, navigate back, toggle dark mode, resize viewport - Analyze — for each state, evaluate against the SXO checklist (load
references/sxo-checklist.md):- Cognitive load: too many elements? Clear visual hierarchy?
- Affordances: are interactive elements obviously clickable?
- Navigation depth: how many clicks to reach the goal?
- Error handling: what happens on wrong input or 401/404/500?
- Loading states: are there skeletons or spinners?
- Responsiveness: does the layout adapt to mobile viewport?
- Log — record each finding with severity (P0/P1/P2), affected route, screenshot reference, and recommended handoff target
Phase 3 — Synthesis & Report
- Compile all findings using the template from
assets/journey-report.md - Group by severity: P0 (blocking UX), P1 (significant friction), P2 (polish)
- For each finding, specify:
- The affected component/route
- A description with screenshot reference
- Recommended fix approach
- Handoff target: UI (design/component issues), Backend (API errors, data problems), Review (quality gate, patterns)
- Provide an overall SXO score (0-100) based on the checklist
MCP Tool Selection Guide
| Task | Playwright MCP | Chrome DevTools MCP |
|---|---|---|
| Navigate to URL | browser_navigate ✅ | navigate_page |
| Read page structure | browser_snapshot ✅ (accessibility tree) | take_snapshot (DOM) |
| Visual screenshot | browser_screenshot (with --caps=vision) | take_screenshot ✅ |
| Click element | browser_click ✅ (by ref from snapshot) | click (by selector) |
| Type text | browser_type ✅ | fill |
| Evaluate JS | — | evaluate_script ✅ |
| Check console errors | browser_console_messages | get_console_message |
| Network monitoring | — | get_network_request |
| Run assertions | browser_snapshot + logic (with --caps=testing) | — |
| Emulate device | --device flag | emulate |
Default strategy: Use Playwright for navigation + interaction (token-efficient, structured). Use Chrome DevTools for screenshots + JS evaluation + network inspection (vision-powered, pixel-level).
Key Principles
- Think like a user, not a developer — navigate via visible UI elements, not code knowledge
- Screenshot at every state change — page load, interaction, error, success, loading
- Accessibility-first exploration — the accessibility tree reveals what screen readers see
- Mobile-first — always test the smallest viewport first (390×844), then desktop (1920×1080)
- Feature flags awareness — check which features are enabled/disabled and test both states
- No code editing — this skill is read-only/browser-only. Findings lead to handoffs, not direct fixes
- Structured reporting — every finding must be actionable with a clear handoff target
Anti-Patterns to Detect
- ❌ Click targets < 44×44px on mobile
- ❌ Missing loading states (content flash, layout shift)
- ❌ Forms without validation feedback
- ❌ Navigation dead-ends (no back button, no breadcrumbs)
- ❌ Inconsistent visual hierarchy (competing CTAs)
- ❌ Missing error handling (white screen on 500, generic "Error")
- ❌ Animations without
prefers-reduced-motionguard - ❌ Contrast ratio < 4.5:1 on body text
- ❌ No focus indicators on interactive elements
- ❌ Orphan pages (unreachable from main navigation)