UX Gap Detector

UX Gap Detector

Codex Compatibility

When running this skill in Codex, translate Claude Code-only primitives before acting: AskUserQuestion -> chat/request_user_input, TodoWrite -> update_plan, Task/TaskCreate/TeamCreate/SendMessage -> spawn_agent/send_input/wait_agent when available and allowed, and EnterPlanMode/ExitPlanMode -> a concise chat plan plus explicit approval. Resolve Read/Write/Edit/Bash/WebSearch/WebFetch to Codex file/shell/web tools, and map ~/.claude/... paths to ~/.agents/... or ~/.codex/... unless the task explicitly targets Claude Code.

Cursor Compatibility

When running this skill in Cursor Agent, translate Claude Code-only primitives before acting: AskUserQuestion -> AskQuestion; TodoWrite -> Cursor TodoWrite or an equivalent checklist; Task/TaskCreate/TeamCreate/SendMessage/multi-agent flows -> Cursor Task (subagents), parallel Tasks, or run_in_background when allowed (TeamCreate/SendMessage may have no exact match); EnterPlanMode/ExitPlanMode -> Plan mode (SwitchMode / CreatePlan) plus explicit user approval. Resolve Read/Write/Edit/StrReplace/Bash/web/search/MCP via Cursor Composer or Agent equivalents. MCP names written as mcp__server__tool typically map to call_mcp_tool with configured server identifiers. Map ~/.claude/... to ~/.cursor/skills/, .cursor/skills/, and .cursor/rules/ unless the task explicitly targets Claude Code.

Detect UI/UX quality gaps in authenticated SaaS web applications through live browser interaction using the user's logged-in session via playwright-cli.

Quick Start

/ux-gap-detector                              <- interactive: asks category + URL
/ux-gap-detector --category dashboard         <- audit dashboard screens
/ux-gap-detector --category data-management   <- audit tables, CRUD, search/filter

Prerequisite: The user must be logged into their app in Chrome with the playwright-cli extension connected.

Workflow

Phase 0: Setup (Authenticated Session)

Before any browser interaction: invoke /dnd to load the drag-and-drop verification protocol. Required even when DnD is not yet known to be involved — ref-based drag returns false success on dnd-kit and similar libraries.

1. Verify playwright-cli connection: Take a browser_screenshot to confirm the extension is active
2. Navigate to target: If a URL is provided, browser_navigate to it. Otherwise ask the user:

AskUserQuestion:
  "What is your app's URL? (You must already be logged in via Chrome)"
  Options:
    - "http://localhost:3000"
    - "http://localhost:5173"
    - "http://localhost:8080"
    (User can type custom URL)

3. If no category specified, ask the user:

AskUserQuestion:
  "Which area of your app should I audit?"
  Options:
    - "Dashboard" (overview, widgets, charts, KPIs)
    - "Data Management" (tables, lists, CRUD, search/filter)
    - "Form Workflow" (multi-step forms, input validation, submission)
    - "Navigation Shell" (sidebar, top-bar, command palette, breadcrumbs)
    - "Settings & Profile" (user settings, preferences, account)

4. Create output directory:

mkdir -p docs/ux-gap-reports/screenshots

5. Generate report filename: docs/ux-gap-reports/YYYY-MM-DD-{category}.md

Phase 1: App Discovery

Using the authenticated session, explore the app structure:

1. Screenshot current state: browser_screenshot to see the logged-in app
2. Snapshot for navigation: browser_snapshot to get the accessibility tree
3. Identify navigation elements: Find sidebar links, top-bar menus, breadcrumbs from the snapshot
4. Map available routes: List the major sections/pages discoverable from navigation
5. Report discovered routes to the user before proceeding with scenarios

Phase 2: Scenario Execution

Execute the scenarios defined in categories.md for the selected category.

For EACH step in each scenario:

1. Snapshot the page: browser_snapshot to get element refs
2. Perform the action using the ref:
   • Navigation: browser_click on nav links or browser_navigate
   • Interactions: browser_click, browser_hover
   • Text input: browser_type
   • Dropdowns: browser_select_option
   • Keyboard: browser_press_key
   • Wait for load: browser_wait (1-3 seconds for transitions)
3. Screenshot: browser_screenshot after the action
4. Save screenshot to docs/ux-gap-reports/screenshots/target-{scenario}-{step}.png

Phase 3: Gap Analysis

Use mcp__sequential-thinking__sequentialthinking to analyze each dimension:

3a. Screenshot Review (Vision)

For each captured screenshot:

• Analyze visual quality, consistency, polish
• Compare against known best practices from top-tier SaaS apps
• Note specific elements that fall short

3b. Score Each Dimension (0-100)

Apply the scoring rubric from scoring-rubric.md:

1. Typography & Spacing (25 points max)
2. Interactive States (25 points max)
3. Content Hierarchy (25 points max)
4. Loading & Error UX (25 points max)

Overall Score = Sum of all dimensions (0-100)

Reference benchmarks (what top-tier looks like):

• Linear: Micro-interactions, skeleton loading, dark theme polish, keyboard shortcuts
• Notion: Content blocks, drag-and-drop, inline editing, empty states
• Vercel: Dashboard layout, deployment cards, real-time status updates
• Stripe: Form validation, data tables, error handling, documentation quality
• Figma: Toolbar interactions, canvas controls, collaborative indicators

3c. Generate Fix Recommendations

For each gap scored below 75:

• Describe the specific gap with concrete examples
• Reference what top-tier apps do differently (by known patterns)
• Provide actionable CSS/code fix suggestions
• Classify priority: Critical (< 50) / Moderate (50-75)

Phase 4: Report Generation

Write the Markdown report to docs/ux-gap-reports/YYYY-MM-DD-{category}.md:

# UX Gap Report: {project-name} -- {category}

**Date**: YYYY-MM-DD
**Target**: {target-url}
**Category**: {category}
**Session**: Authenticated (user's browser profile via playwright-cli)

## Overall Score: {score}/100

| Dimension | Score | Verdict |
|-----------|-------|---------|
| Typography & Spacing | {n}/25 | {Excellent/Good/Needs Work/Poor/Critical} |
| Interactive States | {n}/25 | {verdict} |
| Content Hierarchy | {n}/25 | {verdict} |
| Loading & Error UX | {n}/25 | {verdict} |

---

## Critical Gaps (Score < 50)

### 1. {Gap Title} ({score}/{max})

**What top-tier apps do**: {description, referencing Linear/Notion/Stripe etc.}

**Your app**:
![target](./screenshots/target-{scenario}-{step}.png)

**Gap**: {Specific description}

**Fix**: {Actionable recommendation with code example}

---

## Moderate Gaps (Score 50-75)
...

## Strengths (Score > 75)
...

## Recommendations Summary

| Priority | Gap | Estimated Effort |
|----------|-----|-----------------|
| Critical | ... | ... |
| Moderate | ... | ... |

Phase 5: Issue Registration

1. Present the gap list to the user:

AskUserQuestion (multiSelect: true):
  "Which gaps should be registered as GitHub Issues?"
  Options: [list of Critical and Moderate gaps with scores]

2. For each selected gap, create a GitHub Issue:

gh issue create \
  --title "UX Gap: {gap-title}" \
  --label "ux-gap,priority/{level}" \
  --body "$(cat <<'EOF'
## Gap Detection

**Dimension**: {dimension}
**Score**: {score}/{max}
**Detected**: {date}

## Description

{gap description}

## Screenshots

{screenshot or description}

## Recommended Fix

{actionable fix with code examples}

## Acceptance Criteria

- [ ] Gap score improves to >= 75/{max} on re-audit
EOF
)"

Important Notes

Authenticated Session via playwright-cli

• The skill NEVER logs in itself. The user must already be logged in via Chrome.
• playwright-cli uses the user's real Chrome profile (cookies, sessions, localStorage).
• This means all authenticated SaaS apps are accessible without any credential handling.
• Be careful not to perform destructive actions (delete data, change settings) unless explicitly told to.

Interaction Pattern

browser_snapshot  ->  get element refs
browser_click(ref)  ->  interact with element
browser_wait(1-2s)  ->  wait for transitions
browser_screenshot  ->  capture result

Always browser_snapshot before interacting to get fresh element refs.

Screenshot Strategy

• Capture both default and interaction states (hover, focus, active)
• Wait for animations/transitions to complete before capturing
• Name screenshots descriptively for easy identification in the report

Scope Boundaries

Success Criteria

• playwright-cli connection verified (screenshot taken)
• User's authenticated app navigated successfully
• App navigation structure discovered
• Category-specific scenarios executed with screenshots
• All 4 dimensions scored with specific evidence
• Markdown report generated with screenshot references
• Report includes actionable fix recommendations referencing top-tier apps
• User offered GitHub Issue creation for gaps