| name | ui-ux-testing |
| description | UI/UX audit skill for the browser test agent — screenshot-driven review for common usability defects beyond predefined TC-* cases. Log UX-* bugs with severity; P0/P1 block the browser gate. |
UI/UX Testing Skill
Process guidance for the browser test agent when auditing rendered UI beyond the mandatory TC-* checklist. Functional PASS on predefined cases is insufficient when UX defects are present.
Related: 00-production-ui-quality-bar.md · visual-design skill · ui-visual-verification.md · ux-bug-logging.md
When to apply
After executing layer: browser cases (or during execution when a screenshot reveals an issue), run this checklist on every distinct page/state captured. Log defects that are not already covered by a failing TC-* line.
Defect taxonomy
| Category | Look for | Example UX bug |
|---|
| Layout / responsive | Overflow, clipped content, horizontal scroll on 320px viewport | Submit button below fold on narrow mobile width |
| Touch / interaction | Targets < 44×44 px, dead clicks, missing focus ring on desktop | Icon-only nav item 32px wide |
| Visual hierarchy | Low contrast (< 4.5:1), identical error/success styling, missing headings | All outcome states use same alert styling |
| Copy / i18n | Wrong locale on user paths, raw API text, missing recovery CTA | Generic "Submit" on localized route |
| Forms | Missing labels, toast vs inline misuse, validation on blur vs submit | Email error only in console, not UI |
| Navigation | Forbidden links in chrome, dead-end pages, broken back | Wrong role sees privileged route in sidebar |
| Loading honesty | Infinite spinner, layout shift, optimistic success before server | Success copy with spinner still visible |
| Craft | Generic template UI, flat gray SaaS, undifferentiated cards | Interchangeable white cards, no signature moment |
| Aesthetic / style craft | Token drift vs DESIGN.md, missing borders/elevation per design-system, wrong fonts | Flat borderless cards, default framework buttons, no outcome differentiation |
Cross-reference visual-design and the ui-visual-verification checklist for craft-specific FAIL criteria.
Bug ID and severity
| Field | Rule |
|---|
| ID | UX-<slice-id>-NNN — e.g. UX-web-auth-login-003; increment per slice per run |
| Severity | P0–P3 per 11-testing-plan.md §12 |
| Gate | P0/P1 → BROWSER_TEST_FAIL; P2/P3 logged but do not block alone |
Severity guide (UX-specific)
| Severity | UX examples |
|---|
| P0 | Auth bypass via UI; data loss on form submit; success shown before server confirms |
| P1 | Core flow blocked (cannot submit, cannot navigate to required screen); forbidden link visible to wrong role; visual hierarchy so poor that the primary flow is hard to understand |
| P2 | Should-capability degraded; confusing but recoverable messaging; slow perceived load (> 2s spinner); ugly but usable UI such as generic templates, flat gray tables, or missing signature moments |
| P3 | Cosmetic misalignment; minor copy typo; non-blocking spacing issue |
Required bug fields
Each logged bug must include:
- title — one line summary
- severity — P0 | P1 | P2 | P3
- page — URL path (e.g.
/dashboard)
- screenshot — absolute path under
ai-harness/generated/runs/screenshots/<slice-id>/browser-test/
- repro — numbered steps
- expected — what should happen per docs/quality bar
- actual — what you observed
- relatedTags — optional
AC-* / FR-* / NFR-* if applicable
Output formats
Markdown (in browser test report)
UX-<slice-id>-001: P1 — touch target too small on submit — screenshot: .../20250630T120000Z-register-submit.png
JSON artifact
Write structured bugs to the path specified in the browser test agent prompt (ux-bugs.json per slice run). Schema: ux-bugs.schema.json.
Related
