UX QA Gate#

Run this gate after completing any user-facing work. Do not deliver work to the user until this gate passes.

When to Run#

• After building or modifying any page, component, or flow
• After completing a feature request
• Before saying "done" or presenting work to the user

Process#

1. Functional Completeness Check#

Before examining UX, verify the feature actually works end-to-end:

• Every button/link has a working handler
• Forms submit and process data correctly
• Navigation flows connect (no dead ends)
• Data displays where expected (not placeholder or undefined)
• The feature does what was asked — re-read the original request

2. Heuristic Review#

Walk through each of Nielsen's 10 heuristics against the work just completed. Load references/heuristics-checklist.md and evaluate each applicable item. Not every heuristic applies to every change — skip items that are clearly irrelevant to the scope of work, but err on the side of checking.

3. State & Edge Case Sweep#

Check these states exist and are handled for every data-driven view:

StateWhat to verifyEmptyNo data yet — helpful message, not blank screenLoadingSpinner, skeleton, or indicator while fetchingErrorClear message with recovery path (retry, go back)SuccessConfirmation after actions (toast, redirect, message)PartialSome data missing — graceful degradation, not crashOverflowLong text, many items, large images handledAuthProtected routes redirect or show appropriate state

4. Interaction & Responsiveness#

• Click every interactive element — does it respond?
• Tab through focusable elements — logical order?
• Resize viewport — does layout hold at mobile/tablet/desktop?
• Check touch targets on mobile — minimum 44×44px

5. Severity Classification#

For each issue found:

SeverityMeaningAction🔴 BlockerUser cannot complete the taskFix before delivering🟠 MajorUser struggles significantlyFix before delivering🟡 MinorUser notices but can work aroundNote to user, fix if quick🔵 EnhancementPolish or improvementNote to user for backlog

6. Decision#

• Any 🔴 or 🟠 issues → Fix them, then re-run the gate
• Only 🟡 or 🔵 → Deliver the work with a brief note of known issues
• No issues → Deliver confidently

Output Format#

When reporting to the user, keep it brief:

text

✅ QA Gate passed — [summary of what was checked]

Or if issues were found and fixed:

text

🔧 QA Gate — found and fixed [N] issues:
- [brief description of each fix]

Or if minor issues remain:

text

⚠️ QA Gate — [N] minor items noted:
- [brief description + severity]

Do not produce a full heuristic evaluation report unless the user asks for one. The gate is a self-check, not a deliverable.