UX Doctor

A CLI that scans your codebase for UX, accessibility, and design quality issues. It outputs structured diagnostics with exact file paths, line numbers, WCAG criteria, and fix suggestions.

Built for AI coding agents (Claude Code, Cursor, Codex, Gemini CLI, Amp Code, OpenCode) and human developers alike.

Quick Start

npx ux-doctor@latest . --verbose

How It Works

1. Detects your project framework, CSS approach, and UI library
2. Runs analysis passes in parallel:
   • Source Lint - AST-based checks on JSX/TSX via oxlint custom plugin
   • CSS Analysis - Static analysis of stylesheets via PostCSS
   • Runtime Audit - Optional browser audit via Playwright + axe-core
3. Outputs diagnostics with file paths, line numbers, and fix examples
4. Scores your project 0-100

Supported Stacks

| Category | Detected | |----------|----------| | Frameworks | Next.js, Vite, CRA, Remix, Gatsby, Expo, React Native | | CSS | Tailwind, CSS Modules, styled-components, Emotion, SCSS, Less, vanilla CSS | | UI Libraries | shadcn, MUI, Chakra UI, Ant Design, Radix, Headless UI, Mantine |

Usage

# Full scan with details
npx ux-doctor@latest . --verbose

# JSON output
npx ux-doctor@latest . --json > report.json

# LLM-optimized output (grouped by file, with fix examples)
npx ux-doctor@latest . --agent

# Score only
npx ux-doctor@latest . --score

# Scan only changed files
npx ux-doctor@latest . --diff main

# Skip specific passes
npx ux-doctor@latest . --no-source-lint
npx ux-doctor@latest . --no-css-analysis

# Use APCA contrast algorithm
npx ux-doctor@latest . --verbose --contrast apca

CLI Options

| Option | Description | |--------|-------------| | --verbose | Show file-level details per rule | | --json | Output diagnostics as JSON | | --agent | Output in LLM-optimized markdown format | | --score | Output only the score | | --diff [base] | Scan only files changed vs a base branch (default: main) | | --no-source-lint | Skip source code linting | | --no-css-analysis | Skip CSS/token analysis | | --url <url> | Run a runtime audit on a live URL (requires Playwright) | | --wcag-level <level> | Target WCAG level: A, AA, or AAA (default: AA) | | --contrast <standard> | Contrast algorithm: wcag2 or apca (default: wcag2) | | --project <name> | Select a workspace project in a monorepo | | -y, --yes | Skip confirmation prompts | | --install-skill | Install the ux-doctor skill for AI agents | | --uninstall-skill | Remove the skill from all AI agents | | -v, --version | Show version |

What It Checks

Source Lint (AST-based)

| Category | Examples | |----------|----------| | ARIA | Invalid roles, missing required props, redundant roles, hidden focusable elements | | Forms | Missing labels, autocomplete attributes, error identification | | Keyboard | Click without key handler, positive tabindex, missing focus management | | Media | Missing alt text, SVG accessibility, video captions | | Semantic Structure | Page language, heading content, div soup, skip navigation | | Navigation | Landmark regions, heading hierarchy | | Framework | Next.js Image alt text, React Native accessibility props, tooltip triggers |

CSS Analysis (Static)

| Category | Examples | |----------|----------| | Contrast | Text/background ratios, placeholder contrast, focus ring contrast, Tailwind class pairs | | Typography | Base font size, line height, heading hierarchy, px vs rem | | Touch Targets | Minimum 24px sizing, recommended 44px for interactive elements | | Focus Indicators | outline:none without replacement, :focus vs :focus-visible | | Motion | Missing prefers-reduced-motion, transition:all, permanent will-change | | Color System | Hardcoded colors vs design tokens, dark mode coverage | | Responsive | Fixed widths, zoom prevention, horizontal scroll |

AI Agent Integration

Install the ux-doctor skill so your AI coding agent can scan, interpret results, and fix issues automatically.

npx ux-doctor@latest --install-skill

This installs SKILL.md and 11 reference guides into each agent's skill directory:

| Agent | Install Path | |-------|-------------| | Claude Code | ~/.claude/skills/ux-doctor/ | | Cursor | ~/.cursor/skills/ux-doctor/ | | Amp Code | ~/.config/amp/skills/ux-doctor/ | | Codex | ~/.codex/skills/ux-doctor/ | | Gemini CLI | ~/.gemini/skills/ux-doctor/ | | OpenCode | ~/.config/opencode/skills/ux-doctor/ | | Project local | .agents/ux-doctor/ |

To remove the skill from all agents:

npx ux-doctor@latest --uninstall-skill

Workflow inside an AI agent

1. Run npx ux-doctor . --agent to scan
2. The agent reads the prioritized, file-grouped output
3. The agent applies fixes using the fixTarget and fixExample fields
4. Re-scan to verify the score improved

Configuration

Create ux-doctor.config.json in your project root:

{
  "wcagLevel": "AA",
  "contrastStandard": "wcag2",
  "ignore": {
    "rules": ["typography/max-line-length"],
    "files": ["src/generated/**"],
    "categories": ["Color System"]
  }
}

Or add an "uxDoctor" key in your package.json with the same structure.

All CLI flags can also be set in the config file: sourceLint, cssAnalysis, runtime, verbose, diff, wcagLevel, contrastStandard.

Programmatic API

import { diagnose } from "ux-doctor/api";

const result = await diagnose("./my-project", {
  sourceLint: true,
  cssAnalysis: true,
  wcagLevel: "AA",
  contrastStandard: "apca",
});

console.log(result.scoreResult);  // { score: 72, label: "Needs work" }
console.log(result.diagnostics);  // Diagnostic[]

Exported types: Diagnostic, ScanOptions, ScanResult, ScoreResult, ProjectInfo, JsonOutput, UxDoctorConfig.

Requirements

• Node.js >= 20.19.0
• Runtime audit (--url) requires Playwright (installed automatically as optional dependency)

License

MIT