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.

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

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.

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.

# 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.

/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

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

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

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

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

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

Rules are loaded based on what you're designing:

The plugin actively fights generic AI-generated aesthetics:

• Fonts: Inter, Roboto, Arial, system fonts
• Colors: Purple gradients on white, timid palettes without accent
• Layouts: Cookie-cutter structures, predictable grids
• Naming: V1/V2/V3 version names

• Distinctive fonts with weight extremes (100/200 vs 800/900)
• 3x+ size jumps between heading and body
• Gradient meshes, noise textures, grain overlays
• Dominant color + sharp accent
• Descriptive version names: "Classic", "Bold", "Minimal"

ux-pilot/
├── skills/ux-pilot.md        # Claude Code skill entry point
├── rules/                    # 376 UX rules in 31 markdown files
│   ├── ux-patterns/          # Accessibility, forms, navigation...
│   ├── conversion-funnel/    # CTA, pricing, 34 landing patterns...
│   ├── seo-aeo/              # Structure, meta, schema.org...
│   ├── psychology/           # Social proof, trust, persuasion...
│   ├── aesthetics/           # Anti-slop, typography, 67 styles...
│   └── product-type/         # 30 product recommendations
├── data/                     # Palettes, fonts, styles (JSON)
├── src/
│   ├── discovery/            # Questions, router, brief generator
│   ├── audit/                # Framework detector, scanner, report
│   ├── preview/              # HTTP server, SSE, file watcher, toolbar
│   ├── rules/                # On-demand context-based rule loader
│   ├── data/                 # Palette/font/style/product-type lookup
│   └── export/               # Spec generator, component converter
├── templates/                # Preview shell + 10 screen templates
├── hooks/                    # PostToolUse UX check hook
└── tests/                    # 77 tests

Run /plugin in Claude Code and look for ux-pilot. The current version should be 0.1.1. If you see an older version (e.g. 0.1.0), follow the steps below.

The skill isn't installed. Run:

/plugin marketplace add Sakaax/ux-pilot
/plugin install ux-pilot@ux-pilot
/reload-plugins

Claude Code caches plugins aggressively. To force a clean reinstall:

1. Quit Claude Code completely
2. Delete the cache:

   rm -rf ~/.claude/plugins/cache/ux-pilot

3. Relaunch Claude Code
4. Reinstall:

   /plugin marketplace add Sakaax/ux-pilot
   /plugin marketplace update ux-pilot
   /plugin install ux-pilot@ux-pilot
   /reload-plugins

This is a known Claude Code plugin cache issue, not specific to ux-pilot.

Same cache issue. Follow the steps above — the rm -rf of the cache folder is the key step.

The HTML report is saved to ux-pilot/audit-report.html in your project root. If it doesn't auto-open:

• Linux: xdg-open ux-pilot/audit-report.html
• macOS: open ux-pilot/audit-report.html
• Windows: start ux-pilot/audit-report.html

Make sure you validated the brief when prompted. The file is saved to ux-pilot/ux-brief.md in your project root. The ux-pilot/ directory is auto-added to .gitignore.

Rules enriched from:

• ui-ux-pro-max (MIT) — 99 UX guidelines, styles, palettes, font pairings
• frontend-design (Anthropic) — Design principles, anti-patterns
• WCAG 2.1, Nielsen Norman Group, Laws of UX

MIT — free forever.

_{Built by Sakaax — this README's landing page was designed using ux-pilot.}