corgispec-qa-ui

name	corgispec-qa-ui
description	UI walkthrough — real user path verification with screenshots, component state checks, keyboard navigation, and cross-browser testing
license	MIT
compatibility	Requires a running application with browser access. Works with Playwright MCP or manual browser.
metadata	{"author":"corgispec","version":"1.0","generatedBy":"1.0.0"}

Verify UI quality by walking real user paths, checking component states, and capturing evidence.

Overview

This skill guides a systematic UI walkthrough that verifies the application works correctly from a real user's perspective. It covers:

• Full user path walkthroughs (enter → interact → observe → exit)
• Component state verification (loading, empty, error, edge cases)
• Screenshot capture as evidence (minimum 3)
• Error path testing
• Responsive boundary checks
• Keyboard navigation verification
• Cross-browser validation

When to Use

• After implementing a UI feature, before marking it complete
• During /corgi-review when UI verification is required
• When qa-testcases.md contains UI walkthrough test cases
• Standalone QA pass on any page or flow

Do not use for API-only changes, backend logic, or pure data validation.

Preconditions

• Application is running and accessible in a browser
• Target pages/flows are identified
• Screenshot capture is available (Playwright MCP or manual)

Steps

1. Read test cases (if available)

Check for qa-testcases.md in the change directory:

openspec/changes/<change-name>/qa-testcases.md

If it exists, read and use its UI test cases as the walkthrough guide. Each test case should map to one or more steps below. If it does not exist, derive test cases from the feature's specs and tasks.

2. Define the user path

Identify the complete user journey for the feature under test:

1. Enter — How does the user arrive at this page/feature? (URL, navigation, redirect)
2. Interact — What actions does the user take? (clicks, form fills, selections)
3. Observe — What feedback does the user see? (success states, transitions, data updates)
4. Exit — How does the user leave? (navigation, completion, back button)

Document the path before executing it.

3. Walk the happy path

Execute the user path end-to-end with valid inputs:

1. Navigate to the entry point
2. Perform each interaction step
3. Verify each expected observation
4. Capture screenshot after key state transitions (minimum 1 here)
5. Confirm the exit state is correct

4. Verify component states

For each significant UI component in the flow, verify these states:

State	What to check
Loading	Spinner/skeleton shown, no layout shift on resolve
Empty	Empty state message displayed, no broken layout
Error	Error message shown, recovery action available
Edge	Long text truncation, maximum items, boundary values

Capture screenshot of at least one non-happy state (minimum 1 here).

5. Test error paths

Trigger realistic error conditions:

• Submit forms with invalid data — verify inline validation
• Simulate network failure (if possible) — verify error messaging
• Attempt unauthorized actions — verify graceful handling
• Navigate to invalid routes — verify 404/fallback behavior

Document each error path tested and its result.

6. Check responsive boundaries

Test at these viewport breakpoints (minimum):

Breakpoint	Width	What to verify
Mobile	375px	Layout stacks, touch targets ≥44px, no horizontal scroll
Tablet	768px	Grid adjusts, navigation adapts
Desktop	1280px	Full layout, no excessive whitespace

Capture screenshot at mobile or tablet width (minimum 1 here).

7. Verify keyboard navigation

Without using a mouse:

1. Tab through all interactive elements — verify visible focus indicator
2. Enter/Space activates buttons and links
3. Escape closes modals/dropdowns
4. Arrow keys navigate within lists/menus (if applicable)
5. No keyboard traps (user can always Tab away)

Document any keyboard navigation failures.

8. Cross-browser spot check

If the project supports multiple browsers, verify the happy path in at least one additional browser beyond the primary:

• Chrome (primary)
• Firefox or Safari (secondary)

Note any rendering differences or functional issues.

Reporting Format

After completing the walkthrough, produce a report in this structure:

## UI Walkthrough Report

**Feature:** <feature name>
**Date:** <date>
**Browser:** <primary browser and version>

### User Path
- Entry: <how user arrives>
- Steps: <numbered interaction steps>
- Exit: <how user leaves>

### Results

| Check | Status | Notes |
|-------|--------|-------|
| Happy path | PASS/FAIL | |
| Loading state | PASS/FAIL/SKIP | |
| Empty state | PASS/FAIL/SKIP | |
| Error state | PASS/FAIL/SKIP | |
| Edge cases | PASS/FAIL/SKIP | |
| Error paths | PASS/FAIL | |
| Responsive (mobile) | PASS/FAIL | |
| Responsive (tablet) | PASS/FAIL | |
| Keyboard navigation | PASS/FAIL | |
| Cross-browser | PASS/FAIL/SKIP | |

### Screenshots
1. <description> — <path or inline>
2. <description> — <path or inline>
3. <description> — <path or inline>

### Issues Found
- [ ] <issue description> — severity: high/medium/low
- [ ] <issue description> — severity: high/medium/low

### Verdict
PASS / FAIL (with blockers listed)

9. Record results

• If part of a /corgi-review, include the report in the review evidence
• If standalone, save to qa-ui-report.md in the change directory
• Any blocking issues become tasks or bug reports

Tips

• Take screenshots at moments of state change, not static pages
• Test with realistic data volumes (not just 1-2 items)
• Check that loading states actually appear (throttle network if needed)
• Verify error messages are user-friendly, not stack traces
• Mobile testing: check that modals/popovers don't overflow viewport