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

• Command Palette — single entry point for all actions (⌘K / Ctrl+K)

• Keyboard-First — frequent actions have shortcuts, arrow navigation works

• Inline Editing — no modals for simple edits, Enter saves, Esc cancels

• Minimal States — side panels over pages, overlays without context loss

• Search-First — search is the primary navigation method

• Strong Defaults — zero decisions needed for common actions

• Optimistic UI — instant response, no spinners when avoidable

• List-Centric — lists as main screens, saved views, fast filters

• Context > Settings — actions next to objects, not buried in settings

• Visual Clarity — no noise, color = meaning only

Instructions

Step 1: Determine Review Target

Parse <args> to determine what to review:

• Spec name — if provided, read documents from .specs/<spec-name>/ (requirements, design, tasks)

• File paths — if provided, review specific files or directories

• Branch diff — if branch is specified, review all changes on the current branch vs main

If no arguments provided:

• Check if there are specs in .specs/ and list them

• Check if there are uncommitted changes or branch changes

• 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:

• Command palette agent — find command palette implementation, registered commands, keyboard shortcut definitions

• UI patterns agent — find forms, dialogs, pages, lists; identify inline editing vs modal patterns

• Navigation agent — find route definitions, side panels, drawers, overlay patterns

• 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:

• Keyboard flows documented — spec mentions keyboard shortcuts and navigation

• Inline editing specified — design prefers inline over modal where appropriate

• Performance requirements — response time and optimistic UI mentioned

• 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

Editing & Data Entry

Navigation & Context

Feedback & Performance

Visual Design

🔴 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

Quick Wins

Low effort, high impact improvements

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

Summary

Step 6: Offer Next Steps

After presenting the report, offer actions:

• Add keyboard shortcuts — help implement missing shortcuts

• Convert to inline editing — refactor modals to inline patterns

• Add to command palette — register new actions in ⌘K

• Implement optimistic UI — add optimistic updates for slow operations

• 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