ux-pilot

Your UX co-pilot — from idea to validated flow, in your terminal.

Install  ·  How it works  ·  Rules  ·  Try the demo  ·  Landing page

---

A Claude Code plugin that acts as a senior UX designer. It doesn't generate code blindly — it understands your product, challenges your choices, shows you the result in a live browser preview, and helps you iterate until the flow is validated.

What's New (v0.1.3)

• HTML Audit Report — audit results open as a styled HTML page in your browser with score, severity grouping, and category breakdown
• Fix Prompts (natural language) — each finding includes a no-coder-friendly prompt you can paste into Claude Code to fix the issue. No HTML tags, just plain instructions
• Persistent UX Brief — discovery saves ux-pilot/ux-brief.md in your project, updated as you make decisions
• Visual Audit with Playwright — if Playwright MCP is installed, the audit captures screenshots at 375px, 768px, and 1280px and analyzes the visual result. Falls back to static CSS analysis if not available
• 6 Mobile CSS Checks — detects tables without responsive wrapper, fixed widths > 500px, small touch targets (< 44px), small fonts (< 14px), nav without flex-wrap, and CSS widths without media queries
• Mobile Score Calibration — mobile findings now carry 1.5x penalty weight for more accurate scoring
• Screenshot References — findings from visual audit include clickable screenshot thumbnails in the HTML report
• Anti AI-Slop: No Emojis — the plugin now uses inline SVG icons instead of emojis (emojis render differently across OS/browsers)
• Finding Numbering — each finding shows its index (1/10, 2/10...) for easier tracking
• Back to Top — link at the bottom of the HTML report

Having issues updating? See Troubleshooting.

Optional: Playwright MCP for Visual Audit

For the best audit results, install Playwright MCP to enable screenshot-based visual analysis:

npm install -g @playwright/mcp

Then add it to your Claude Code MCP config (~/.claude/mcp.json):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp"]
    }
  }
}

Without Playwright, the audit uses static CSS analysis only — still useful, but can't detect visual overflow or layout issues that only appear when the page is rendered.

Why ux-pilot?

Every AI tool generates the same generic output: Inter font, purple gradient on white, centered hero, done. ux-pilot exists to fix this.

Instead of jumping straight to code, it runs a structured discovery flow — asks about your product, users, and goals — then applies the right rules from 376 UX rules sourced from WCAG 2.1, Nielsen Norman Group, and Laws of UX.

What makes it different

	Existing tools	ux-pilot
Approach	Generate code directly	Dialogue first, code after
Output	One-shot result	Iterative, named versions
Scope	Landing pages mostly	Full apps (dashboards, CRUD, onboarding...)
Preview	No live preview	Local server with hot reload
UX knowledge	Few or no rules	376 rules loaded on-demand
Context	Loads everything	Token-efficient (rules loaded per screen)
Version naming	V1, V2, V3	Descriptive: "Classic", "Bold", "Minimal"
Design quality	Generic AI aesthetic	Anti "AI slop" rules built-in

Installation

# Step 1 — Add from marketplace
/plugin marketplace add Sakaax/ux-pilot

# Step 2 — Install the skill
/plugin install ux-pilot@ux-pilot

No API keys. No subscription. Free and open source.

Usage

/ux-pilot              # Full flow (Discovery -> Audit -> Preview -> Export)
/ux-pilot audit        # Scan existing code for UX issues
/ux-pilot preview      # Jump to preview server
/ux-pilot export       # Generate UX spec + components

4 Phases

1. Discovery

The plugin asks you questions one at a time (ABCD choices + free text). It understands your product, users, business model, flows, design preferences, and SEO needs.

• Adapts questions based on your answers — skips irrelevant ones
• Goal: get to the Brief in as few questions as possible
• Output: a structured UX Brief saved to ux-pilot/ux-brief.md in your project
• Brief is updated as you make design decisions and validate screens
• Auto-added to .gitignore

2. Audit

If you have existing code, the plugin scans it automatically:

• Detects framework (Next.js, React, Vue, Svelte, vanilla)
• Scans routes, HTML, forms, images, navigation, accessibility, SEO, mobile
• Produces a scored report (XX/100) with findings by severity
• Each finding references the violated rule and suggests a fix
• HTML report opens in your browser — dark themed, grouped by severity
• Fix prompts under each finding — ready to copy-paste into Claude Code to fix the issue

3. Preview

The plugin opens a local server and generates your screens in vanilla HTML/CSS:

• 2-3 named versions per screen (not V1/V2/V3 — descriptive names)
• Hot reload via SSE — changes appear instantly
• Approve, reject, or comment per screen
• Rules loaded per-screen for token efficiency

4. Export

• Complete UX spec in markdown
• Converts approved screens to React, Svelte, or Vue components
• Detects your project's framework and follows its conventions

376 UX Rules

Rules are organized in 6 categories, loaded on-demand (never all at once):

Category	Files	What's inside
UX Patterns	10	Accessibility, touch, forms, navigation, layout, typography, animation, empty states, tables, charts
Conversion & Funnel	7	CTA, pricing, signup, checkout, retention, c