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_navigate to $BASE_URL or http://localhost:3000)
- Take an initial screenshot (Chrome DevTools
take_screenshot) + accessibility snapshot (Playwright browser_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 DevTools navigate_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-motion guard
- ❌ Contrast ratio < 4.5:1 on body text
- ❌ No focus indicators on interactive elements
- ❌ Orphan pages (unreachable from main navigation)
1---2name: pwa-user-simulation3description: Simulate real user journeys through a PWA using browser automation MCPs (Playwright MCP + Chrome DevTools MCP). Combines SXO (Search eXperience Optimization), neuro-ergonomic heuristics, WCAG 2.2 AA checks, and Core Web Vitals analysis via structured accessibility snapshots and visual screenshots. Triggers on: simulate user, user journey, PWA test, SXO audit, UX walkthrough, browser automation, e2e exploration, user simulation, test the app, parcourir comme un utilisateur, tester le flow, vérifier le parcours.4---56# PWA User Simulation Skill78Simulate 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.910## When to Load References1112- **Persona definitions** → load `references/personas.md`13- **SXO audit checklist** → load `references/sxo-checklist.md`14- **MCP tools usage guide** → load `references/mcp-tools-guide.md`15- **Journey report template** → copy from `assets/journey-report.md`1617---1819## Simulation Protocol (3 Phases)2021### Phase 1 — Bootstrap & Discovery22231. Verify the app is running (`browser_navigate` to `$BASE_URL` or `http://localhost:3000`)242. Take an initial screenshot (Chrome DevTools `take_screenshot`) + accessibility snapshot (Playwright `browser_snapshot`) to confirm the landing state253. Load the selected persona from `references/personas.md`264. List all navigable routes visible from the current page (links, nav items, CTAs)2728### Phase 2 — Route-by-Route Exploration2930For **each route** in the persona's journey:31321. **Navigate** — use Playwright `browser_navigate` (structured, token-efficient) or Chrome DevTools `navigate_page` (if vision/screenshot needed)332. **Snapshot** — take an accessibility snapshot (`browser_snapshot`) to read the page structure as an accessibility tree343. **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 state354. **Interact** — simulate user actions: click CTAs (`browser_click`), fill forms (`browser_type`), submit, navigate back, toggle dark mode, resize viewport365. **Analyze** — for each state, evaluate against the SXO checklist (load `references/sxo-checklist.md`):37 - Cognitive load: too many elements? Clear visual hierarchy?38 - Affordances: are interactive elements obviously clickable?39 - Navigation depth: how many clicks to reach the goal?40 - Error handling: what happens on wrong input or 401/404/500?41 - Loading states: are there skeletons or spinners?42 - Responsiveness: does the layout adapt to mobile viewport?436. **Log** — record each finding with severity (P0/P1/P2), affected route, screenshot reference, and recommended handoff target4445### Phase 3 — Synthesis & Report46471. Compile all findings using the template from `assets/journey-report.md`482. Group by severity: P0 (blocking UX), P1 (significant friction), P2 (polish)493. For each finding, specify:50 - The affected component/route51 - A description with screenshot reference52 - Recommended fix approach53 - Handoff target: **UI** (design/component issues), **Backend** (API errors, data problems), **Review** (quality gate, patterns)544. Provide an overall SXO score (0-100) based on the checklist5556---5758## MCP Tool Selection Guide5960| Task | Playwright MCP | Chrome DevTools MCP |61|------|---------------|-------------------|62| Navigate to URL | `browser_navigate` ✅ | `navigate_page` |63| Read page structure | `browser_snapshot` ✅ (accessibility tree) | `take_snapshot` (DOM) |64| Visual screenshot | `browser_screenshot` (with `--caps=vision`) | `take_screenshot` ✅ |65| Click element | `browser_click` ✅ (by ref from snapshot) | `click` (by selector) |66| Type text | `browser_type` ✅ | `fill` |67| Evaluate JS | — | `evaluate_script` ✅ |68| Check console errors | `browser_console_messages` | `get_console_message` |69| Network monitoring | — | `get_network_request` |70| Run assertions | `browser_snapshot` + logic (with `--caps=testing`) | — |71| Emulate device | `--device` flag | `emulate` |7273**Default strategy:** Use Playwright for navigation + interaction (token-efficient, structured). Use Chrome DevTools for screenshots + JS evaluation + network inspection (vision-powered, pixel-level).7475---7677## Key Principles78791. **Think like a user, not a developer** — navigate via visible UI elements, not code knowledge802. **Screenshot at every state change** — page load, interaction, error, success, loading813. **Accessibility-first exploration** — the accessibility tree reveals what screen readers see824. **Mobile-first** — always test the smallest viewport first (390×844), then desktop (1920×1080)835. **Feature flags awareness** — check which features are enabled/disabled and test both states846. **No code editing** — this skill is read-only/browser-only. Findings lead to handoffs, not direct fixes857. **Structured reporting** — every finding must be actionable with a clear handoff target8687---8889## Anti-Patterns to Detect9091- ❌ Click targets < 44×44px on mobile92- ❌ Missing loading states (content flash, layout shift)93- ❌ Forms without validation feedback94- ❌ Navigation dead-ends (no back button, no breadcrumbs)95- ❌ Inconsistent visual hierarchy (competing CTAs)96- ❌ Missing error handling (white screen on 500, generic "Error")97- ❌ Animations without `prefers-reduced-motion` guard98- ❌ Contrast ratio < 4.5:1 on body text99- ❌ No focus indicators on interactive elements100- ❌ Orphan pages (unreachable from main navigation)
TheWatcher01