UX Review

Performs a UX review optimized for productivity tools and admin interfaces. Based on the principle: "Hands stay on keyboard, mouse is optional."

This review evaluates features against efficiency-first UX patterns used in best-in-class productivity tools: command palettes, keyboard-first navigation, inline editing, optimistic UI, and minimal context switching.

When to use

Use this skill when the user needs to:

• Validate that a feature feels fast and professional
• Check if keyboard shortcuts and command palette are properly integrated
• Verify inline editing vs unnecessary page transitions
• Ensure optimistic UI and instant feedback
• Review a feature for "pro tool" experience quality

Core UX Principles

The interface should think faster than the user

1. Command Palette — single entry point for all actions (⌘K / Ctrl+K)
2. Keyboard-First — frequent actions have shortcuts, arrow navigation works
3. Inline Editing — no modals for simple edits, Enter saves, Esc cancels
4. Minimal States — side panels over pages, overlays without context loss
5. Search-First — search is the primary navigation method
6. Strong Defaults — zero decisions needed for common actions
7. Optimistic UI — instant response, no spinners when avoidable
8. List-Centric — lists as main screens, saved views, fast filters
9. Context > Settings — actions next to objects, not buried in settings
10. Visual Clarity — no noise, color = meaning only

Instructions

Step 1: Determine Review Target

Parse

<args>

to determine what to review:

1. Spec name — if provided, read documents from

   .specs/<spec-name>/

   (requirements, design, tasks)
2. File paths — if provided, review specific files or directories
3. Branch diff — if

   branch

   is specified, review all changes on the current branch vs main

If no arguments provided:

1. Check if there are specs in

   .specs/

   and list them
2. Check if there are uncommitted changes or branch changes
3. Ask the user what to review

Step 2: Gather Context

Read all available materials depending on the target:

From spec documents (if available):

• requirements.md

  — extract user stories, acceptance criteria, and described user flows

• design.md

  — extract UI components, data flow diagrams, and interaction patterns

From codebase:

Use parallel sub-agents (

subagent_type: "Explore"

) to investigate:

1. Command palette agent — find command palette implementation, registered commands, keyboard shortcut definitions
2. UI patterns agent — find forms, dialogs, pages, lists; identify inline editing vs modal patterns
3. Navigation agent — find route definitions, side panels, drawers, overlay patterns
4. Feedback agent — find optimistic updates, loading states, toast notifications, undo mechanisms

Launch all four agents in a single message (parallel tool calls).

Step 3: Evaluate Efficiency-First Patterns

For each pattern, evaluate the current implementation level:

3a. Command & Control

Pattern	❌ Missing	⚠️ Basic	✅ Good	🚀 Excellent
Command Palette	No ⌘K	Opens but limited actions	Search + navigation + actions	Context-aware commands, recent items, fuzzy search
Keyboard Shortcuts	None	Only global (save, close)	CRUD shortcuts (C/E/D) + navigation (↑↓)	Full coverage, discoverable hints, customizable
Focus Management	Random focus	Focus on page load	Logical tab order	Keyboard trap-free, skip links, roving tabindex

3b. Editing & Data Entry

Pattern	❌ Missing	⚠️ Basic	✅ Good	🚀 Excellent
Inline Editing	Always navigate away	Modal for every edit	Click-to-edit in lists	Enter=save, Esc=cancel, blur=save, multi-field inline
Strong Defaults	All fields required	Some defaults	Smart defaults based on context	Auto-fill from context, minimal required fields
Form Efficiency	One field per page	Standard form	Logical grouping, clear optionals	Auto-advance, paste-to-fill, batch entry

3c. Navigation & Context

Pattern	❌ Missing	⚠️ Basic	✅ Good	🚀 Excellent
Minimal States	Full page transitions	Modals for everything	Side panels for details	Overlays preserve context, split views, peek preview
Search-First	No search	Basic text match	Instant search, multiple entities	Filters, saved searches, search by ID/status/user
List-Centric	Card grids only	Basic lists	Sortable, filterable lists	Saved views, column customization, bulk actions

3d. Feedback & Performance

Pattern	❌ Missing	⚠️ Basic	✅ Good	🚀 Excellent
Optimistic UI	Wait for server	Spinner on every action	Optimistic for reads	Full optimistic with rollback, background sync
Response Time	Visible delays	< 500ms responses	< 200ms, skeleton loading	< 100ms, no spinners, prefetching
Undo/Redo	Confirm dialogs only	Toast with undo for delete	Undo for all destructive	Full undo stack, Ctrl+Z support

3e. Visual Design

Pattern	❌ Missing	⚠️ Basic	✅ Good	🚀 Excellent
Visual Clarity	Cluttered, many icons	Some organization	Clean, purposeful layout	Typography-driven, color = status only
Context > Settings	Actions in settings page	Actions in dropdown menu	Actions visible on hover	Inline actions, contextual toolbars
Information Density	Too sparse or too dense	Acceptable density	Scannable, grouped info	Progressive disclosure, smart truncation

Step 4: Cross-Reference with Spec

If spec documents are available, verify:

1. Keyboard flows documented — spec mentions keyboard shortcuts and navigation
2. Inline editing specified — design prefers inline over modal where appropriate
3. Performance requirements — response time and optimistic UI mentioned
4. Command palette integration — new actions registered in command palette

Step 5: Generate UX Review Report

Present a structured report:

# UX Review: [Feature Name]

**Scope:** [What was reviewed — spec docs, files, branch diff]
**UX Maturity:** [🚀 Pro-tool / ✅ Good / ⚠️ Basic / ❌ Needs Work]

---

## Efficiency-First Assessment

### Command & Control
| Pattern | Level | Evidence |
|---------|-------|----------|
| Command Palette | [emoji] | [What was found] |
| Keyboard Shortcuts | [emoji] | [What was found] |
| Focus Management | [emoji] | [What was found] |

### Editing & Data Entry
| Pattern | Level | Evidence |
|---------|-------|----------|
| Inline Editing | [emoji] | [What was found] |
| Strong Defaults | [emoji] | [What was found] |
| Form Efficiency | [emoji] | [What was found] |

### Navigation & Context
| Pattern | Level | Evidence |
|---------|-------|----------|
| Minimal States | [emoji] | [What was found] |
| Search-First | [emoji] | [What was found] |
| List-Centric | [emoji] | [What was found] |

### Feedback & Performance
| Pattern | Level | Evidence |
|---------|-------|----------|
| Optimistic UI | [emoji] | [What was found] |
| Response Time | [emoji] | [What was found] |
| Undo/Redo | [emoji] | [What was found] |

### Visual Design
| Pattern | Level | Evidence |
|---------|-------|----------|
| Visual Clarity | [emoji] | [What was found] |
| Context > Settings | [emoji] | [What was found] |
| Information Density | [emoji] | [What was found] |

---

## 🔴 Critical Issues

> Blocks keyboard users or forces unnecessary navigation

### [Issue Title]
**Pattern violated:** [Which efficiency pattern]
**Location:** `path/to/component.tsx`

[What the user experiences and why it slows them down]

**Fix:** [Specific recommendation]

---

## 🟠 Friction Points

> Slows down power users

- **[Location]** — [What's slow and why]
- **[Location]** — [What's slow and why]

---

## 🟡 Polish Opportunities

> Would elevate to pro-tool level

- [Opportunity 1]
- [Opportunity 2]

---

## ✅ What's Already Great

- [Positive finding 1]
- [Positive finding 2]

---

## Edge Cases

| Scenario | Status | Notes |
|----------|--------|-------|
| Empty state | [emoji] | [Has CTA? Keyboard accessible?] |
| Error state | [emoji] | [Dismissible? Undo available?] |
| Loading state | [emoji] | [Skeleton? Optimistic?] |
| Bulk operations | [emoji] | [Keyboard select? Batch actions?] |

---

## Quick Wins

> Low effort, high impact improvements

1. [ ] [Quick win 1]
2. [ ] [Quick win 2]
3. [ ] [Quick win 3]

---

## Summary

| Category | Score |
|----------|-------|
| Command & Control | [X/3 patterns at Good+] |
| Editing & Data Entry | [X/3 patterns at Good+] |
| Navigation & Context | [X/3 patterns at Good+] |
| Feedback & Performance | [X/3 patterns at Good+] |
| Visual Design | [X/3 patterns at Good+] |
| **Overall** | [X/15 patterns at Good+] |

Step 6: Offer Next Steps

After presenting the report, offer actions:

1. Add keyboard shortcuts — help implement missing shortcuts
2. Convert to inline editing — refactor modals to inline patterns
3. Add to command palette — register new actions in ⌘K
4. Implement optimistic UI — add optimistic updates for slow operations
5. Re-review — run the review again after changes

Severity Levels

Level	Criteria	Examples
🔴 Critical	Keyboard users blocked; forced full-page navigation for simple actions	No keyboard access to primary action; modal required for single-field edit
🟠 Friction	Power users slowed down; inconsistent with app patterns	Missing shortcut for frequent action; spinner where optimistic would work
🟡 Polish	Good but not pro-level; minor efficiency gains possible	Could add to command palette; could show undo toast

Arguments

• <args>

  - Spec name, file paths, or review scope

  • <spec-name>

    — review UX based on spec documents and related code

  • <file-path>

    — review UX of specific files or directories

  • branch

    — review UX of all changes on current branch vs main

Examples:

• review:ux user-auth

  — review UX for the user-auth feature spec

• review:ux src/pages/settings/

  — review UX of the settings pages

• review:ux branch

  — review UX of all UI changes on the current branch