Your project's design quality — measured, not guessed.

Install · What it scores · Commands · Demo videos

Design reviews are vibes. This turns them into data.

ui-ux-suite scans your CSS, JSX, and Tailwind config and scores 12 design dimensions — color system, typography, layout, components, accessibility, hierarchy, interactions, responsiveness, and more. Every finding cites an authority (WCAG, APCA, Hick's Law, Miller's Law, Fitts's Law). Every fix comes with code.

npx ui-ux-suite

No dependencies. No config. No API keys. 100% local.

• ESLint for design. One command produces a quantified 1–10 score per dimension and a weighted overall grade you can track over time.
• Cites real UX laws, not opinions. WCAG 2.2, APCA contrast, OKLCH color science, deltaE near-duplicate detection — not "this feels off."
• Runs anywhere. Works with React, Vue, Svelte, Angular, vanilla. Detects Tailwind, shadcn, Radix, Framer Motion automatically.
• Talks to your AI editor. Ships as an MCP server. Just ask "audit my design" in Claude / Cursor / Copilot.
• Gives you the code. /uiux-fix generates the before/after patch for the top finding. uiux_generate_palette does an OKLCH-based recolor of your tokens.
• Zero dependencies. The project is vanilla JS, by design. Ships under 200KB.

# Claude Code
claude mcp add ui-ux-suite npx ui-ux-suite --mcp

# Codex CLI
codex mcp add ui-ux-suite -- npx -y ui-ux-suite --mcp

{ "mcpServers": { "ui-ux-suite": { "command": "npx", "args": ["ui-ux-suite", "--mcp"] } } }

{ "servers": { "ui-ux-suite": { "command": "npx", "args": ["-y", "ui-ux-suite", "--mcp"] } } }

{ "mcpServers": { "ui-ux-suite": { "command": "npx", "args": ["ui-ux-suite", "--mcp"] } } }

{ "mcpServers": { "ui-ux-suite": { "command": "npx", "args": ["ui-ux-suite", "--mcp"] } } }

mcpServers:
  ui-ux-suite: { command: npx, args: [ui-ux-suite, --mcp], type: stdio }

# In Claude Code
/plugin marketplace add Aboudjem/10x
/plugin install ui-ux-suite@10x

# Or from the terminal
claude plugin install ui-ux-suite@10x

# In Claude Code
/plugin marketplace add Aboudjem/ui-ux-suite
/plugin install ui-ux-suite@ui-ux-suite

# Or from the terminal
claude plugin install ui-ux-suite@ui-ux-suite

npm install -D ui-ux-suite

{ "scripts": { "design-audit": "ui-ux-suite" } }

12 weighted dimensions. Accessibility gets the highest weight because it affects the most users.

Findings are concrete, not vague:

"Button text contrast is 2.8:1, needs 4.5:1 for WCAG AA. Change #94a3b8 to #64748b on your white background."

Every finding cites the law it violates. Reports end with a Laws of UX coverage table counting violations per law.

Examples: Hick's Law (choice cost), Fitts's Law (target size), Miller's Law (7±2), Jakob's Law (conventions), Doherty Threshold (400ms), Peak-End Rule, Gestalt (Proximity, Similarity, Common Region, Prägnanz, Uniform Connectedness), Aesthetic-Usability Effect, Choice Overload, Cognitive Load, Tesler's Law, Postel's Law, Occam's Razor, Pareto, Parkinson, Serial Position, Von Restorff, Zeigarnik, Goal-Gradient.

Styling: Tailwind · CSS Modules · SCSS · styled-components · Emotion · vanilla-extract · plain CSS. Libraries: shadcn/ui · MUI · Chakra · Radix · Mantine · Headless UI · Ark UI.

Auto-detects your framework. No config.

ui-ux-suite              Audit current directory
ui-ux-suite <path>       Audit a specific project
ui-ux-suite --json       JSON output for scripts
ui-ux-suite --mcp        Start as MCP server

One-command audit via slash command (v0.3, recommended):

/ui-ux-suite:audit                 Full 12-dimension audit, one report
/ui-ux-suite:colors                Color-only audit
/ui-ux-suite:a11y [--deep]         Accessibility-only audit (Playwright + axe-core in deep mode)
/ui-ux-suite:typography            Typography and hierarchy audit
/ui-ux-suite:components            Component-quality audit

These dispatch to the single uiux_audit_run MCP tool, which chains scan -> extract -> score -> report in one call. No manual tool chaining.

npm i -D playwright-core @axe-core/playwright
npx playwright install chromium

/ui-ux-suite:a11y --deep

graph LR
    A["Your Project<br/><sub>CSS, JSX, Tailwind</sub>"] --> B["Extractors"]
    B --> C["Engines<br/><sub>Color · Type · Spacing · OKLCH</sub>"]
    C --> D["Scoring<br/><sub>12 weighted dimensions</sub>"]
    D --> E["Report<br/><sub>Score + fixes + citations</sub>"]

    style A fill:#f8fafc,stroke:#0ea5e9,color:#0c4a6e
    style B fill:#f0f9ff,stroke:#0ea5e9,color:#0c4a6e
    style C fill:#e0f2fe,stroke:#0ea5e9,color:#0c4a6e
    style D fill:#bae6fd,stroke:#0ea5e9,color:#0c4a6e
    style E fill:#0ea5e9,stroke:#0284c7,color:#ffffff

lib/
  mcp-server.js       MCP JSON-RPC server (15 tools)
  runner.js           Full 12-dimension audit orchestrator
  browser.js          Optional Playwright + axe-core deep mode
  color-engine.js     WCAG, APCA, deltaE, palette
  type-engine.js      Scale math, readability
  spacing-engine.js   Grid detection, consistency
  oklch-parser.js     OKLCH color space
  theme-parser.js     Tailwind v4 @theme / @theme inline parser
  tailwind-parser.js  Class extraction + breakpoint bucketing
  extractors.js       CSS, Tailwind, SCSS, stack detection
  scoring.js          12 weighted dimension scorers
  schema.js           Data structures
  knowledge.js        Built-in knowledge base

commands/    5 top-level slash commands (/ui-ux-suite:audit, ...)
knowledge/   19 markdown docs (3,081 lines)
agents/      12 specialist agents
skills/      14 specialist slash commands
templates/   5 report templates

Every recommendation traces to research.

Full evidence base with HIGH/MEDIUM/LOW confidence ratings lives in knowledge/evidence-base.md.

All analysis runs locally. Your code never leaves your machine. No telemetry. No API calls. No network.

Contributions are welcome. This project is maintained in public and every PR is reviewed.

git clone https://github.com/Aboudjem/ui-ux-suite
cd ui-ux-suite
npm test   # 234 tests, zero dependencies

• Bug fixes always welcome. Include a test that would have caught the bug.
• New scoring rules should cite a named UX law or a primary-source study in the finding. See knowledge/laws-of-ux.md for the 24-law vocabulary.
• New MCP tools must follow the registration pattern in lib/mcp-server.js. Add a test in test/ that exercises the handler without starting the server.
• Knowledge docs should be evidence-backed. Add new citations to knowledge/evidence-base.md with HIGH/MEDIUM/LOW confidence ratings.
• No new runtime dependencies. The suite is zero-dep by design; dev dependencies are fine.
• No em-dashes in user-facing copy (reports, README, knowledge files).

Look for the good first issue label. Typical starting points: add a new knowledge doc, extend a scorer with a new finding, add a new generator preset.

1. Fork and branch from main.
2. Add or update tests under test/.
3. Run npm test locally (CI also runs on Node 18 + 22).
4. Open a PR describing the problem, the approach, and any trade-offs.
5. Reviewer feedback usually within 48 hours.

See CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md for the full policies.

_{MIT · Built by Adam Boudjemaa · Star ⭐ to help others find it}

_{Academic and canonical sources for the 24 Laws of UX. Each finding in the audit report cites one or more of these primary sources. No content is copied from external UX reference sites; prose in knowledge/laws-of-ux.md is authored fresh from these papers.}