ui-audit-skill

ui-audit

A multi-platform UI/UX audit tool that runs a structured diagnose-redesign-verify workflow against any frontend codebase. Available as a Claude Code skill, standalone Go CLI, platform rule files for Cursor/Windsurf/Codex/Continue.dev, and an npm package.

What It Does

ui-audit chains two complementary AI skills into a repeatable three-phase cycle:

1. Diagnose — Audit the current UI against 99 evidence-based UX rules (accessibility, touch targets, performance, typography, color, animation, forms, navigation, and more)
2. Redesign — Fix diagnosed issues while elevating visual quality with a bold, intentional aesthetic direction
3. Verify — Re-audit changed components to catch regressions, looping back to redesign until clean

Each phase produces a structured markdown report in .ui-audit/ so findings persist across sessions and context resets.

How to Use It

There are four ways to run ui-audit, depending on your setup:

Option 1: Claude Code Skill

If you use Claude Code, install ui-audit as a skill:

# macOS / Linux
git clone https://github.com/scottkw/ui-audit-skill.git
cd ui-audit-skill && ./install.sh

# Windows (PowerShell)
git clone https://github.com/scottkw/ui-audit-skill.git
cd ui-audit-skill; .\install.ps1

# Cross-platform (Node.js)
git clone https://github.com/scottkw/ui-audit-skill.git
cd ui-audit-skill && node install.mjs

Then navigate to any frontend project and invoke:

/ui-audit

Or use natural language — "audit my UI", "review the UX", "diagnose and fix my UI issues".

Dependencies: The skill requires two Claude Code plugins (ui-ux-pro-max and frontend-design). On first run, it checks for both and walks you through installation if either is missing.

Option 2: Claude Code Marketplace Plugin

Install directly from the marketplace:

/plugin install scottkw/ui-audit-skill

Option 3: Go CLI (Standalone)

The Go CLI calls the Claude API directly — no Claude Code required.

Homebrew (macOS):

brew install scottkw/tap/ui-audit

From source:

go install github.com/scottkw/ui-audit-skill@latest

First run prompts for your Anthropic API key and saves it to ~/.ui-audit/config. Set ANTHROPIC_API_KEY as an environment variable to skip the prompt.

# Full three-phase audit
ui-audit run

# Individual phases
ui-audit diagnose
ui-audit redesign
ui-audit verify

# Show config and detected framework
ui-audit config get

Option 4: npm

# Install skill + rule files into your project
npx @scottkw/ui-audit install

# Update to latest version
npx @scottkw/ui-audit update

# Remove installed files
npx @scottkw/ui-audit uninstall

# Run CLI directly (requires API key)
npx @scottkw/ui-audit run

Option 5: Platform Rule Files

Copy the appropriate rule file into your project for native AI assistant integration:

Platform	File	Location
Cursor	ui-audit.mdc	.cursor/rules/ui-audit.mdc
Windsurf	ui-audit.md	.windsurf/rules/ui-audit.md
Codex (OpenAI)	AGENTS.md	Project root
Continue.dev	ui-audit.md	.continue/rules/ui-audit.md

The npm installer (npx @scottkw/ui-audit install) copies all rule files automatically.

Targeted Phases

You don't have to run the full cycle. Request a specific phase:

Request	What happens
"Just diagnose my UI, don't change anything"	Phase 1 only — writes ui-audit-diagnosis.md
"Redesign this component"	Phase 2 only — reads diagnosis if it exists, writes ui-audit-redesign.md
"Verify my UI changes didn't break accessibility"	Phase 3 only — reads prior reports, writes ui-audit-verification.md

Supported Frameworks

The tool auto-detects your stack:

• Web SPAs — React, Vue, Svelte, Next.js, Nuxt, Angular
• Desktop apps — Electron, Wails (Go + web), Tauri (Rust + web)
• Mobile — React Native, Flutter, SwiftUI
• Static — Plain HTML/CSS/JS, Tailwind, Astro

Output

All reports are written to .ui-audit/ in your project root:

File	Phase	Contents
ui-audit-diagnosis.md	1	Every issue found — rule, file, line, current vs. required value, severity
ui-audit-redesign.md	2	Aesthetic direction, issues addressed, files changed, design decisions
ui-audit-verification.md	3	Before/after comparison table, score, regressions, PASS/FAIL verdict
ui-audit-summary.md	Final	Roll-up — counts, key changes, remaining work, links to all reports

Reports persist to disk so context survives long sessions, context window compression, and session restarts.

Consider adding .ui-audit/ to your .gitignore unless you want to track reports in version control.

Audit Categories