README.md

English · 简体中文 · 日本語 · Español · Français

ESLint for design. It finds the exact line, the measured wrong value, and the exact fix.

What it does · Install · Use it · What you get · Works in your editor · Good to know

claude plugin marketplace add Aboudjem/10x
claude plugin install ui-ux-suite@10x

What it does

Most design review tells you to improve your contrast. This tells you that .hero-subtitle on line 14 of src/styles.css is #fbfbfb on #ffffff, which measures 1.03 to 1, and that #767676 would pass. Same shape as a linter error, applied to design.

It reads your CSS, JSX, HTML and Tailwind classes. By default nothing is executed, nothing leaves your machine, and no key is ever needed. Findings come in two kinds. A located finding, which is most of what you act on, carries three things:

• Located. The file, the line and the selector.
• Measured. The real wrong value, not an adjective.
• Fixed. The exact before to after change, plus the WCAG criterion or named UX law it rests on.

The rest are project-level, like "5 font families, use 1 or 2". They score and they name the problem, but there is no single line to point at.

Install

claude plugin marketplace add Aboudjem/10x
claude plugin install ui-ux-suite@10x

That is Claude Code. For any other agent that reads the Agent Skills format, install the 14 skills straight from this repo:

npx skills add Aboudjem/ui-ux-suite

The command-line tool needs no install step: npx ui-ux-suite . runs it.

npm install -D ui-ux-suite

{ "scripts": { "design-audit": "ui-ux-suite . --fail-under 7" } }

Use it

1. Point it at a project.

npx ui-ux-suite .

You get a ranked list of findings and a weighted score out of 10 across 12 dimensions. No config file, no setup step.

2. Read a finding. This is real output from the broken fixture shipped in this repo, which scores 3.7 out of 10 because it is supposed to:

- **Where:** `src/styles.css:14` · selector `.hero-subtitle`
- **Measured:** 1.03:1 (APCA Lc 0) (needs 4.5:1)
- **Why:** Text `#fbfbfb` on `#ffffff` measures 1.03:1 (APCA Lc 0). WCAG 2.2 §1.4.3 requires ≥ 4.5:1 for normal text.
- **Fix:** Change `color` on `.hero-subtitle` from `#fbfbfb` to `#767676` (meets 4.5:1 on `#ffffff`), or darken further.
- **Cites:** WCAG 1.4.3 Contrast (Minimum) (AA)

Run it yourself with npx ui-ux-suite test/fixtures/planted-ux-problems from a checkout.

3. Put it in CI. Pick the output and the gate that fit your pipeline:

npx ui-ux-suite . --json | jq              # machine-readable, banner goes to stderr
npx ui-ux-suite . --html report.html       # standalone HTML report
npx ui-ux-suite . --sarif ui-ux.sarif      # SARIF 2.1.0 for GitHub code scanning
npx ui-ux-suite . --fail-under 7           # exit 1 when the score drops below 7
npx ui-ux-suite . --write-baseline .uiux-baseline.json   # freeze today's debt
npx ui-ux-suite . --baseline .uiux-baseline.json --fail-on-regression
npx ui-ux-suite . --tags dimension:accessibility --exclude-tags severity:nice-to-have

Every flag is in docs/cli.md.

What you get

• A ranked report in Markdown, JSON, HTML or SARIF, whichever the reader is a machine or a person.
• A score out of 10 across 12 weighted dimensions, with accessibility carrying the most weight.
• A CI gate, either an absolute bar with --fail-under or a baseline that fails on a new finding or a score drop.
• 14 skills and 16 tools your agent can call, so "audit this project's design" works in chat.

Works in your editor

Works in Claude Code, Cursor, Codex, Copilot, Gemini CLI, and 70+ other agents through npx skills add. The skills are Markdown, so they run on whatever model your editor points at.

claude mcp add ui-ux-suite -- npx -y ui-ux-suite --mcp
codex mcp add ui-ux-suite -- npx -y ui-ux-suite --mcp

Good to know

• Nothing leaves your machine. Pure Node built-ins, no API key, no telemetry. The static audit makes no network call, and deep mode only visits the URL you hand it.
• Static source is the default. Deep mode is opt-in, needs playwright-core plus @axe-core/playwright, and degrades to source findings when they are absent.
• The numbers are gated. npm test runs 356 tests, and the shipped broken fixture must keep producing findings that carry a file, a line and a fix.

Learn more

• docs/cli.md, every flag, exit code and recipe
• docs/editors.md, install and MCP config per editor
• docs/scoring.md, the 12 weights and how the score is built
• docs/science.md, the WCAG criteria and UX laws behind the findings
• docs/faq.md and docs/comparison.md
• CHANGELOG.md, CONTRIBUTING.md, LICENSE

_{MIT · Built by Adam Boudjemaa}