ui-ux-suite

ตรวจสอบการออกแบบโปรเจกต์ในด้านสี ตัวอักษร การเข้าถึง และเลย์เอาต์ โดยให้คะแนน 12 มิติที่มีน้ำหนัก ตั้งแต่ 0-10 npm: ui-ux-suite.

เอกสาร

ui-ux-suite

CI npm version License MIT

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

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

Run it in any web project. No install, no config, no key.

npx ui-ux-suite .

Sample report

The report opens with the score, then the three fixes to start with, then the detail.

# Design audit: 3.7/10 (Needs Work)

**Verdict:** score 3.7/10, Needs Work. 46 located findings, 8 critical.

## Fix these first

1. 9 `.swatch*` color variants fail WCAG AA contrast (worst 1.75:1) at `src/styles.css:118`. Fix: Rebuild this color set against the surface it sits on so each meets ≥ 4.5:1 (e.g. the worst, `#b5c6d7`, should be `#6d7882` or darker), or reserve ...
2. No visible keyboard focus indicator anywhere at `src/styles.css:22`. Fix: Add a focus ring to all interactive elements: `:focus-visible { outline: 2px solid var(--ring, #2563eb); outline-offset: 2px; }`.
3. Fixed 1200px width on `.layout` with 0 media queries at `src/styles.css:57`. Fix: Use `max-width: 1200px; width: 100%` and add responsive breakpoints (sm/md/lg).

**Weakest areas:** Typography System 1.5/10, Accessibility 1.6/10, Component Quality 2/10.

_Scanned 3 CSS, 1 JSX/TSX/Vue/Svelte and 1 HTML files in 0.02s on 2026-11-17T11:33:48.104Z. The detail follows._

This is a real run, not a mock-up. It is the top of the output of npx ui-ux-suite test/fixtures/planted-ux-problems, run from a checkout of version 0.7.0. The fixture is broken on purpose, so it scores low.

Below those lines the report lists each finding in full. One of them:

### [!] Low text contrast on `.hero-subtitle`: 1.03:1
- **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.
- **Impact:** Users with low vision (and most users in bright light) cannot read this 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)

Install

Pick the line for your agent. Each one is a single command.

Claude Code. The plugin brings the 14 skills, 5 commands, 12 agents and the MCP server.

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

Any other agent that reads Agent Skills (Cursor, Codex, Gemini CLI, OpenCode, GitHub Copilot):

npx skills add Aboudjem/ui-ux-suite

Any MCP client. The server needs no key and no setup.

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

No agent at all. The command line needs no install step: npx ui-ux-suite . runs it.

Works with

Each row is a real install and check, run on the date shown on macOS with Node 22.

AgentHow it was installedTestedWhat the test showed
Claude CodePlugin loaded with claude --plugin-dir .2026-11-17claude plugin validate . --strict passes, and the MCP server connects
Cursor.cursor/mcp.json2026-11-17cursor-agent mcp list-tools ui-ux-suite lists the 16 tools
Codexcodex mcp add ui-ux-suite2026-11-17codex mcp list shows the server enabled
Gemini CLIgemini mcp add ui-ux-suite2026-11-17gemini mcp list shows the server connected
OpenCodeopencode.json2026-11-17opencode mcp list shows the server connected
Skills CLI 1.9.0npx skills add Aboudjem/ui-ux-suite2026-11-17The 14 skills land in .agents/skills and .claude/skills
Any stdio MCP clientnpx -y ui-ux-suite --mcp2026-11-17A raw MCP session lists 16 tools and audits the fixture at 3.7

Documented, not run on that date: VS Code, GitHub Copilot, Windsurf, Continue, Zed, Pi and install.sh. Their snippets are in docs/editors.md.

Use it

1. Point it at a project.

npx ui-ux-suite .

2. Fix the three lines at the top. Each one names a file, a line and the change to make.

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

npx ui-ux-suite . --fail-under 7           # exit 1 when the score drops below 7
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 . --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

In an agent, ask for it in plain words: "audit this project's design". In Claude Code, type /ui-ux-suite:audit.

Every flag and exit code is in docs/cli.md. Every MCP tool is in docs/tools.md.

How it works

It reads your source. It does not run your app, and it does not need a browser.

StepWhat happens
1. ReadIt walks the folder and reads CSS, SCSS, JSX, TSX, Vue, Svelte, HTML and Tailwind classes.
2. MeasureIt computes real values: contrast in WCAG 2.2 and APCA, font sizes, spacing, target sizes.
3. LocateIt ties each problem to a file, a line and a selector.
4. ScoreIt scores 12 weighted dimensions out of 10. Accessibility weighs the most, at 12%.
5. ReportIt prints the score, three fixes, then every finding with its before and after.

A finding carries three things:

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

Some findings are about the whole project, such as "5 font families, use 1 or 2". They count in the score and have no single line.

Scorecard: an overall score, per-dimension scores, and located findings

The weights and the scoring rules are in docs/scoring.md. The standards behind the findings are in docs/science.md.

Proof

Every number on this page comes from a command. Run it and compare.

ClaimCommand that prints it
377 tests pass, 0 failnpm test
The broken fixture scores 3.7 out of 10, with 46 located findingsnpx ui-ux-suite test/fixtures/planted-ux-problems
The MCP server exposes 16 toolsnode scripts/gen-tool-reference.js --check
The repo holds 14 skillsnpx skills add Aboudjem/ui-ux-suite --list
The package has no runtime dependencynpm view ui-ux-suite dependencies prints nothing
The plugin manifest is validclaude plugin validate . --strict

The fixture is the regression gate. It plants known problems, listed in PLANTED.md. The tests fail if one of them stops being found with a file, a line and a fix.

CI runs the same npm test on every push and pull request, on Node 18 and Node 22.

FAQ

Is it safe to run on my project? Yes. It never creates, edits or deletes a source file. It only writes the report or baseline file you name.

Does my code leave my machine? No. The audit makes no network call, needs no API key and sends no telemetry. Deep mode opens only the URL you give it.

Do I need a running app? No. The default audit reads source files. Deep mode is optional and adds live checks through Playwright and axe-core.

Does it fix my code for me? No. It prints each fix as a before and an after. You, or your agent, apply it.

My project already scores badly. Can I still gate CI? Yes. Write a baseline once, then fail only on a new finding or a score drop. The two commands are in step 3 above.

Which stacks does it read? React, Next.js, Vue, Svelte, Angular and plain HTML. Tailwind v3 and v4, CSS Modules, SCSS, styled-components, Emotion and plain CSS.

How is it different from Lighthouse or axe? Those two need a running page. This reads source, so it can name the file and the line. See docs/comparison.md.

More questions are answered in docs/faq.md.

Limits

  • It reads source, not pixels. A style set at runtime by JavaScript is not seen without deep mode.
  • It skips a contrast pair it cannot resolve. When the background is unknown, it reports nothing instead of guessing.
  • The score is a guide, not a certificate. A high score does not prove WCAG conformance. A manual review still does.
  • It audits, it never edits. Applying a fix is your step.
  • The skills call the MCP tools. Outside Claude Code, add the MCP server next to the skills.
  • Deep mode needs two extra packages. They are playwright-core and @axe-core/playwright. Without them you get the source findings only.
  • It looks six folders deep. Point it closer to the source in a very deep repo.
  • It needs Node 18 or newer.

Learn more


MIT · Built by Adam Boudjemaa