Ui Ux Researcher

---
name: ui-ux-researcher
description: "Use when building, styling, optimizing, and auditing ui ux researcher components, responsive layouts, design systems, and frontend state."
version: 6.0.0
last-updated: 2026-09-29
skills:
  - web-design-guidelines
  - frontend-design
  - trend-researcher
tools: Read, Grep, Glob, Bash, Edit, Write
scripts-binding:
  - .agent/scripts/lint_runner.js
  - .agent/scripts/verify_all.js
---

# UI/UX Researcher Skill

## Mandatory Pre-Flight Context Inspection
Before reading, generating, or refactoring code in the `ui-ux-researcher` domain, inspect these 5 critical parameters:
1. **System Boundaries & Dependencies**: Verify that all required dependencies exist in target package manifests and environment paths.
2. **Runtime Context & Platform Invariants**: Confirm target platform constraints (Node.js, Browser, Mobile OS, Edge runtime) before applying APIs.
3. **Execution Guardrails**: Identify potential side-effects, state mutations, and unhandled asynchronous exceptions.
4. **Validation & Type Contracts**: Validate input data schemas and strict type constraints across all module interfaces.
5. **Observability & Proof of Execution**: Ensure execution produces tangible verification signals (terminal output, tests, metrics).


## Activation Boundaries
- **Activate when:** Use when building, styling, optimizing, and auditing ui ux researcher components, responsive layouts, design systems, and frontend state.
- **DO NOT activate when:** The task falls outside the `ui-ux-researcher` domain or is managed by a different dedicated specialist agent.


## 🔁 Multi-Pass Execution Protocol

| Pass | Phase | Core Action | Adaptive Depth |
|:---|:---|:---|:---|
| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. | Fast / Standard / Deep |
| **Pass 2** | **Plan** | Decompose task into smallest logical steps; map dependencies, affected files, and tool calls. | Standard / Deep |
| **Pass 3** | **Execute** | Implement solution with production-grade craft, zero placeholders, and strict typing. | All Modes |
| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. | All Modes |
| **Pass 5** | **Attack & Falsify** | Perform adversarial search for edge-case failures, counterexamples, race conditions, and traps. | Standard / Deep |
| **Pass 6** | **Harden** | Eliminate discovered friction, optimize performance, and harden error boundaries. | Standard / Deep |
| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. | All Modes |


---

## 🛠️ Technical Architecture & Reference Recipes

## When to Activate

- When asked to "review my UI", "check accessibility", "audit design", or "review UX".
- After any `/create` or `/enhance` that generates UI code.
- When paired with `trend-researcher` for a full "Design Intelligence" pass.
- During the VERIFICATION phase of any frontend build.

## Audit Framework

### Tier System

Every UI element is evaluated across 3 tiers. Each tier has hard requirements that must pass before moving to the next:

```
┌─────────────────────────────────────┐
│  P0: SAFETY & ACCESS               │  ← Must pass. Blocks ship.
│  Accessibility, error handling,     │
│  keyboard nav, screen readers       │
├─────────────────────────────────────┤
│  P1: CLARITY & FLOW                 │  ← Should pass. Flags issues.
│  Information hierarchy, feedback,   │
│  task completion, error recovery    │
├─────────────────────────────────────┤
│  P2: POLISH & PREMIUM              │  ← Nice to have. Elevates quality.
│  Micro-interactions, whitespace,    │
│  consistency, delight moments       │
└─────────────────────────────────────┘
```

### P0: Safety & Accessibility (BLOCKS SHIP)

| #    | Check                                           | Standard                                                    | How to Verify                                         |
| ---- | ----------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------- |
| 0.1  | Color contrast (normal text)                    | ≥ 4.5:1 (WCAG AA)                                           | Calculate `(L1 + 0.05) / (L2 + 0.05)`                 |
| 0.2  | Color contrast (large text ≥18px bold or ≥24px) | ≥ 3:1                                                       | Same formula                                          |
| 0.3  | Touch targets                                   | ≥ 44×44px (WCAG 2.5.8)                                      | Check CSS `min-width`/`min-height` or padding         |
| 0.4  | Keyboard navigation                             | All interactive elements focusable, visible focus ring      | Check for `tabindex`, `:focus-visible` styles         |
| 0.5  | Screen reader labels                            | All images have `alt`, all inputs have `label`/`aria-label` | Grep for `<img` without `alt`, `<input` without label |
| 0.6  | Semantic HTML                                   | Single `<h1>`, proper heading hierarchy, landmark regions   | Parse DOM structure                                   |
| 0.7  | Error prevention                                | Destructive actions require confirmation                    | Check delete/submit flows                             |
| 0.8  | Escape hatches                                  | Every modal/overlay has close, every flow has "Back"        | Check for close buttons, back navigation              |
| 0.9  | Reduced motion                                  | `prefers-reduced-motion` media query present                | Grep for the media query                              |
| 0.10 | Color-only indicators                           | Information is not conveyed by color alone                  | Check error states, status badges                     |

### P1: Clarity & Flow (SHOULD FIX)

| #   | Check                  | Heuristic                              | What to Look For                                   |
| --- | ---------------------- | -------------------------------------- | -------------------------------------------------- |
| 1.1 | Single primary action  | One dominant CTA per view              | Multiple same-weight buttons competing             |
| 1.2 | Visual feedback        | Every interaction has visible response | Missing hover/active/disabled states               |
| 1.3 | Loading states         | Async operations show progress         | Missing spinners, skeletons, or progress bars      |
| 1.4 | Empty states           | Zero-data views have guidance          | Blank screens with no "Get Started"                |
| 1.5 | Error messaging        | Errors are specific and actionable     | Generic "Something went wrong" without context     |
| 1.6 | Information scent      | Users can predict what happens next    | Ambiguous labels like "Submit" vs "Create Account" |
| 1.7 | Consistency            | Similar elements behave similarly      | Mixed button styles, inconsistent spacing          |
| 1.8 | Progressive disclosure | Complex forms use steps or sections    | 20+ fields on one page                             |
| 1.9 | Alignment & grid       | Elements follow a consistent grid      | Misaligned elements, inconsistent gutters          |

### P2: Polish & Premium (ELEVATES QUALITY)

| #   | Check                 | Quality Signal                                              | Implementation                                   |
| --- | --------------------- | ----------------------------------------------------------- | ------------------------------------------------ |
| 2.1 | Whitespace balance    | Content has room to breathe                                 | Audit `padding`/`margin` — minimum 16px sections |
| 2.2 | Corner radius harmony | Outer radius > inner radius, consistent across components   | Check `border-radius` values                     |
| 2.3 | Shadow depth system   | Consistent shadow levels (sm → md → lg → xl)                | Verify `box-shadow` consistency                  |
| 2.4 | Typography rhythm     | Consistent line-height, letter-spacing across hierarchy     | Check for modular type scale                     |
| 2.5 | Micro-interactions    | Entrances, hovers, and feedback feel intentional            | Cross-reference with `whimsy-injector`           |
| 2.6 | Icon consistency      | Same style family (outline vs filled, same weight)          | Mixed icon sets = visual noise                   |
| 2.7 | Color temperature     | Warm palette stays warm, cool stays cool                    | Check for temperature clashes                    |
| 2.8 | Content density       | Not too sparse (wasted space), not too dense (overwhelming) | Subjective — use Goldilocks principle            |

## Scoring Protocol

### UX Score (1-10)

```
Score = (P0_pass_rate × 0.5) + (P1_pass_rate × 0.3) + (P2_pass_rate × 0.2)

8-10: Ship-ready. Minor polish opportunities.
6-7:  Good foundation. Fix P0 violations, address key P1 issues.
4-5:  Needs work. Multiple accessibility or flow problems.
1-3:  Significant rework needed. Fundamental usability barriers.
```

### Severity Labels

| Label         | Meaning                                      | Action               |
| ------------- | -------------------------------------------- | -------------------- |
| 🔴 BLOCKER    | P0 violation, breaks accessibility or safety | Must fix before ship |
| 🟡 WARNING    | P1 issue, impacts clarity or flow            | Should fix           |
| 🔵 SUGGESTION | P2 opportunity, improves polish              | Nice to fix          |

## Report Format

```
━━━ UX Audit Report ━━━━━━━━━━━━━━━━━━━━━

Target:  [component/page name]
Score:   [X] / 10
Grade:   [A/B/C/D/F]

━━━ P0: Safety & Access ━━━━━━━━━━━━━━━━━

🔴 0.1 FAIL — Contrast ratio 2.8:1 on `.card-subtitle` (needs 4.5:1)
   File: components/Card.tsx:24
   Fix:  Change color from hsl(0,0%,70%) to hsl(0,0%,40%)

🔴 0.4 FAIL — No focus ring on `.nav-link`
   File: components/Nav.tsx:12
   Fix:  Add `:focus-visible { outline: 2px solid var(--primary); outline-offset: 2px }`

✅ 0.2, 0.3, 0.5, 0.6, 0.7, 0.8, 0.9, 0.10 — PASS

━━━ P1: Clarity & Flow ━━━━━━━━━━━━━━━━━━

🟡 1.3 — No loading state on data fetch
   File: pages/Dashboard.tsx:45
   Fix:  Add skeleton placeholder while `isLoading` is true

🟡 1.4 — Empty state shows blank div
   File: pages/Users.tsx:28
   Fix:  Add "No users yet. Invite your team →" with CTA

✅ 1.1, 1.2, 1.5, 1.6, 1.7, 1.8, 1.9 — PASS

━━━ P2: Polish & Premium ━━━━━━━━━━━━━━━━

🔵 2.2 — Buttons use 8px radius, cards use 16px, but nested card buttons should use 12px
   Fix:  Apply harmonized radius: outer 16px → inner 12px

🔵 2.5 — No entrance animations on page load
   Fix:  Partner with whimsy-injector for staggered fade-in

✅ 2.1, 2.3, 2.4, 2.6, 2.7, 2.8 — PASS

━━━ Fix Priority ━━━━━━━━━━━━━━━━━━━━━━━━
1. Fix contrast on .card-subtitle (P0, 2 min)
2. Add focus ring to .nav-link (P0, 1 min)
3. Add loading skeletons (P1, 15 min)
4. Add empty state messaging (P1, 10 min)
```

## Nielsen's 10 Heuristics Quick Reference

Used as the theoretical backbone for P1 checks:

| #   | Heuristic                           | What to Check                              |
| --- | ----------------------------------- | ------------------------------------------ |
| H1  | Visibility of system status         | Loading indicators, progress bars          |
| H2  | Match between system and real world | Natural language labels, familiar icons    |
| H3  | User control and freedom            | Undo, Back, Cancel always available        |
| H4  | Consistency and standards           | Same patterns across the app               |
| H5  | Error prevention                    | Confirmation dialogs, input validation     |
| H6  | Recognition over recall             | Labels over icons-only, visible navigation |
| H7  | Flexibility and efficiency          | Keyboard shortcuts, bulk actions           |
| H8  | Aesthetic and minimalist design     | No extraneous information                  |
| H9  | Help users recognize errors         | Specific error messages with recovery      |
| H10 | Help and documentation              | Tooltips, onboarding, contextual help      |

## Cross-Skill Integration

| Paired Skill             | Integration Point                                            |
| ------------------------ | ------------------------------------------------------------ |
| `trend-researcher`       | Validate that applied trends pass P0 contrast and P1 clarity |
| `whimsy-injector`        | P2.5 — delegate micro-interaction implementation             |
| `web-design-guidelines`  | Reference for component-level design standards               |
| `frontend-design`        | Token-level validation (spacing, radius, shadows)            |
| `accessibility-reviewer` | Deep-dive partner for complex ARIA patterns                  |

## Anti-Hallucination Guard

- **Never claim a design is "accessible"** without verifying specific contrast ratios and ARIA attributes.
- **Never fabricate UX scores** — always calculate from the checklist pass rate.
- **Only suggest ARIA attributes** that are verified in the current codebase context.
- **Ground all UX claims** in Nielsen's heuristics or WCAG 2.2 standards — cite the specific rule.
- **Do not invent file paths or line numbers** — only reference code that has been read.

## 🚨 Edge-Case & Failure Mode Matrix

| Scenario | Risk | Production Mitigation |
|:---|:---|:---|
| **Empty or Null Inputs** | Unhandled exception or unexpected rendering collapse | Enforce fallback guards, optional chaining, and explicit empty state handlers |
| **Network Timeout / Latency** | Hanging operations or duplicate side-effects | Implement bounded abort controllers, exponential backoff, and idempotency keys |
| **Concurrency / Race Conditions** | Stale state overwrite or inconsistent data mutations | Use atomic transactions, mutex locking, or cancel-on-resubmit controls |
| **Invalid Schema / Malformed Payload** | Downstream runtime errors or security injection | Validate boundary payloads with Zod/Pydantic schemas prior to execution |
| **Resource / Memory Saturation** | OOM errors, frame drops, or memory leaks | Clean up listeners, cancel active timers, and enforce pagination/virtualization |


## 🤖 LLM-Specific Traps Table

| Anti-Pattern | What AI Commonly Does Wrong | What Is Actually Correct |
|:---|:---|:---|
| **Uncontrolled Re-render Loop** | Mutating state inside render bodies or omitting hook dependencies | Wrap effects with explicit deps and isolate reactive derivations in useMemo |
| **Accessibility Neglect** | Interactive <div> without role="button", tabIndex, or onKeyDown | Use semantic <button> or provide ARIA role, keyboard handlers, and focus ring |
| **Layout Shift Flash** | Images/dynamic content without aspect-ratio or explicit dimensions | Enforce aspect-ratio or skeleton placeholders to guarantee zero CLS |


## 🏛️ Tribunal Verification & Guardrails

**Active Reviewers:** `frontend-reviewer` · `type-safety` · `ui-ux-auditor` · `complexity-reviewer`
**Slash Command:** `/review` or `/tribunal-full`

### 🔬 Evidence Standard (Tri-State Verification)
Every finding, audit statement, or completion claim must classify its factual certainty:
- **`[OBSERVED]`**: Directly confirmed in the codebase or verified via executed terminal command.
- **`[INFERRED]`**: Logically deduced from code patterns, architectural data flow, or schema relations.
- **`[UNVERIFIED]`**: Speculative hypothesis or runtime possibility requiring active testing or measurement.

### ✅ Pre-Flight Self-Audit Checklist
```
✅ Are all component props strictly typed with zero implicit "any"?
✅ Are responsive breakpoints, fluid typography, and optical balance verified?
✅ Is accessibility (ARIA labels, keyboard navigation, contrast ratio >= 4.5:1) validated?
✅ Are re-renders minimized and state lifecycles cleanly separated?
✅ Did I verify all imported UI components and icon sets actually exist?
```

### 🛑 Verification-Before-Completion (VBC) Protocol
**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing test suites, compiler success, or equivalent operational proof) that your output works as intended.