---
---
## What is ui-ux-suite?
**ui-ux-suite is a zero-dependency design linter that audits your CSS, JSX, HTML, and Tailwind config and returns specific, located, measured findings with a concrete fix, not generic advice.**
Most "design review" tools tell you *"improve your contrast."* This tool tells you:
> `.hero-subtitle` at `src/styles.css:14`: text `#fbfbfb` on `#ffffff` = **1.03:1**, fails WCAG 2.2 AA (needs 4.5:1). Fix: change `color` to `#767676` (4.54:1 on white) or darker.
That is the whole point. Every finding is **located** (file:line + selector), **measured** (the real wrong number), and **fixed** (the exact change). It scores **12 design dimensions** grounded in **WCAG 2.2**, **APCA** contrast, and the **Laws of UX**, citing the WCAG success criterion or the named law it depends on.
- **It audits, it never edits.** Every run is read-only and outputs suggestions (`before` → `after`). Applying a fix is your call.
- **It runs anywhere.** One MCP server + one `npx` CLI → works in Claude Code, Cursor, VS Code, Codex, Gemini, Windsurf, and Continue.
- **It needs nothing.** Pure Node built-ins. No install weight, no API keys, no network, no telemetry. Your code stays on your machine.
**See a real run:** [sample audit report](docs/demo/sample-audit.html) · [sample terminal output](docs/demo/sample-run.txt)
---
## How to use it (3 steps)
### 1. Run it on any project
```bash
npx ui-ux-suite .
```
You get a ranked list of located + measured + fixed findings and a weighted 0–10 score across 12 dimensions. No config, no setup.
### 2. Pick the output you need
```bash
npx ui-ux-suite . # human-readable report (default)
npx ui-ux-suite . --json | jq # machine-readable JSON (banner goes to stderr)
npx ui-ux-suite . --html report.html # standalone dark-theme HTML report
npx ui-ux-suite . --fail-under 7 # exit 1 if the score drops below 7 (CI gate)
```
Exit codes: `0` ok · `1` audit error or below `--fail-under` · `2` path not found · `3` insufficient evidence.
### 3. Wire it into your AI editor (optional)
```bash
npx ui-ux-suite --mcp # start the MCP server over stdio
```
Then ask your editor: *"Audit this project's design."* The MCP tool `uiux_audit_run` runs the same engine and returns the same located findings.
One-line MCP setup per editor
```bash
# 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
```
**Cursor** (`~/.cursor/mcp.json`):
```json
{ "mcpServers": { "ui-ux-suite": { "command": "npx", "args": ["ui-ux-suite", "--mcp"] } } }
```
**VS Code + Copilot** (`.vscode/mcp.json`):
```json
{ "servers": { "ui-ux-suite": { "command": "npx", "args": ["-y", "ui-ux-suite", "--mcp"] } } }
```
**Gemini CLI** (`~/.gemini/mcp_config.json`):
```json
{ "mcpServers": { "ui-ux-suite": { "command": "npx", "args": ["ui-ux-suite", "--mcp"] } } }
```
**Windsurf** (`~/.codeium/windsurf/mcp_config.json`):
```json
{ "mcpServers": { "ui-ux-suite": { "command": "npx", "args": ["ui-ux-suite", "--mcp"] } } }
```
**Continue.dev** (`.continue/mcpServers/ui-ux-suite.yaml`):
```yaml
mcpServers:
ui-ux-suite: { command: npx, args: [ui-ux-suite, --mcp], type: stdio }
```
### Or install the skills into any AI CLI
The MCP server above works in every MCP-capable client. To also load the `/design-*` skills directly into another CLI, run the one-line installer. It symlinks the skills into that CLI's skills directory; `--update` pulls the latest and relinks, `--uninstall` removes them.
```bash
curl -fsSL https://raw.githubusercontent.com/Aboudjem/ui-ux-suite/main/install.sh | bash -s codex
```
On Windows, run `install.ps1 ` from a checkout (Developer Mode or an elevated shell is needed for symlinks).
| Platform | Skills directory | One-liner |
|:--|:--|:--|
| Claude Code | (plugin) | `claude plugin install ui-ux-suite@10x` |
| Codex / Gemini / OpenCode / Pi | `~/.agents/skills` | `install.sh codex` |
| VS Code (Copilot) | `~/.copilot/skills` | `install.sh copilot` |
| Trae | `~/.trae/skills` | `install.sh trae` |
| Vibe | `~/.vibe/skills` | `install.sh vibe` |
| OpenClaw | `~/.openclaw/skills` | `install.sh openclaw` |
| Antigravity | `~/.gemini/antigravity/skills` | `install.sh antigravity` |
| Hermes / Cline / Kimi | `~/./skills` | `install.sh hermes` |
Skill-directory conventions change between CLI releases. If a link does not resolve, fall back to the MCP server (it works everywhere). Run `install.sh all` to link every platform at once.
Install as a Claude Code plugin
```bash
# From the 10x marketplace
claude plugin marketplace add Aboudjem/10x
claude plugin install ui-ux-suite@10x
```
Wires up the slash commands, specialist agents, knowledge base, and the MCP server in one step.
Install as a dev dependency
```bash
npm install -D ui-ux-suite
```
```json
{ "scripts": { "design-audit": "ui-ux-suite . --fail-under 7" } }
```
Requires Node 18+.
---
## Real before / after
The repo ships a fixture with **12 deliberately planted UX problems** and their ground truth (`test/fixtures/planted-ux-problems/PLANTED.md`). It is the regression gate for every release.
The thing that changed in this rebuild is **specificity**: whether a finding is detected **and** located **and** measured **and** fixed:
| | Detected | Located (`file:line`) | Measured (real value) | Fixed (`before`→`after`) | Specificity |
|:--|:--:|:--:|:--:|:--:|:--:|
| **Before (v0.3 baseline)** | partial | ✗ | ✗ | ✗ | **0 / 12** |
| **After (v0.4)** | ✓ | ✓ | ✓ | ✓ | **12 / 12** |
The old engine concatenated every CSS file into one blob and emitted bare `{severity, msg}` strings; file identity died before scoring, so it could never point at a line. The new engine carries `{value, file, line, col, selector}` from the extractor all the way to the finding.
**A real finding from that fixture** (verbatim from `npx ui-ux-suite test/fixtures/planted-ux-problems`):
```
Low text contrast on `.hero-subtitle`: 1.03:1
src/styles.css:14 · WCAG 1.4.3 Contrast (Minimum) (AA)
measured: 1.03:1 (APCA Lc 0)
fix: change color on `.hero-subtitle` from #fbfbfb to #767676
(meets 4.5:1 on #ffffff), or darken further.
```
That fixture currently scores **3.8 / 10 ("Needs Work")**, because it is supposed to be broken. Run it yourself:
```bash
npx ui-ux-suite test/fixtures/planted-ux-problems
```
---
## How it compares
The differentiator is **located + measured + fixed, with a WCAG SC or UX-law citation, from your source *or* a URL**, in one zero-dep command across every editor.
| | ui-ux-suite | Lighthouse | axe-core | CSS / design linters |
|:--|:--:|:--:|:--:|:--:|
| Points at the exact `file:line` + selector | ✓ | ✗ (URL only) | ✗ (DOM node only) | ✓ (lint rules) |
| Reports the **measured wrong value** | ✓ | partial | ✓ (contrast) | ✗ |
| Gives a concrete `before` → `after` fix | ✓ | ✗ | ✗ | partial (autofix) |
| Cites WCAG 2.2 **and** APCA | ✓ | WCAG only | WCAG only | ✗ |
| Cites named **Laws of UX** (Hick, Fitts, Miller…) | ✓ | ✗ | ✗ | ✗ |
| Works on **static source** (no running URL) | ✓ | ✗ (needs URL) | ✗ (needs DOM) | ✓ |
| Works on a **running URL** (deep mode) | ✓ (opt-in) | ✓ | ✓ | ✗ |
| Covers **12 design dimensions** (beyond a11y) | ✓ | partial | a11y only | per-rule |
| Zero runtime dependencies | ✓ | ✗ | ✗ | ✗ |
ui-ux-suite does not replace Lighthouse or axe. It covers the gap they leave: design quality grounded in your **source**, with a fix you can paste.
---
## What it scores
12 weighted dimensions. Accessibility carries the most weight because it affects the most users.
| Dimension | Weight | Checks |
|:----------|:------:|:-------|
| Accessibility | 12% | Focus visible, alt text, labels, target size, reduced motion |
| Color System | 10% | WCAG + APCA contrast, duplicate hues, semantic roles, dark mode |
| Typography System | 10% | Scale consistency, font count, body size, line height |
| Layout & Spacing | 10% | Grid, off-scale values, breakpoints, container widths |
| Component Quality | 10% | States: hover, focus, disabled, loading, error |
| Visual Hierarchy | 10% | Type scale, information priority, scannability |
| Interaction Quality | 8% | Animation timing, easing, feedback |
| Responsiveness | 8% | Breakpoints, container queries, viewport meta |
| Visual Polish | 7% | Shadow quality, radius tokens, off-scale arbitrary values |
| Performance UX | 5% | Loading states, perceived speed |
| Information Architecture | 5% | Validation, navigation, command palette |
| Platform Appropriateness | 5% | Dark mode, component lib, a11y primitives |
---
## How it works
```mermaid
graph LR
A["Your project CSS · JSX · HTML · Tailwind"] --> B["Located extractors keep file · line · selector"]
B --> C["Engines WCAG · APCA · OKLCH · ΔE"]
C --> D["12 weighted scorers"]
D --> E["Findings located · measured · fixed · cited"]
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
```
Static analysis is the default and the primary deliverable; it needs no browser. **Deep mode** is opt-in: install the optional peer deps (`playwright-core`, `@axe-core/playwright`) and pass a `baseUrl` to also measure live contrast, flag touch targets under 44×44px, and screenshot routes. When the deps are absent, it degrades gracefully to source-based findings.
The 16 MCP tools
| Tool | What it does |
|:-----|:-------------|
| `uiux_audit_run` | **One-call full audit.** Scan → extract → score 12 dimensions → located findings. Supports `depth: quick\|deep`, `dimensions`, `baseUrl`, `format`. |
| `uiux_scan_project` | Detect framework, styling (Tailwind v3 vs v4), component/theme/icon libs. |
| `uiux_extract_colors` / `uiux_extract_typography` / `uiux_extract_spacing` | Pull values **with** file/line/selector. |
| `uiux_check_contrast` | WCAG 2.2 + APCA contrast for any pair. |
| `uiux_score_dimension` / `uiux_score_overall` | Score one of 12 dimensions, or the weighted total. |
| `uiux_generate_palette` / `uiux_generate_type_scale` / `uiux_generate_spacing_scale` / `uiux_generate_tokens` | OKLCH-based token generators. |
| `uiux_knowledge_query` / `uiux_laws_query` | Query the knowledge base and the Laws of UX. |
| `uiux_audit_log` / `uiux_audit_report` | Append a finding · render a report. |
Slash commands (Claude Code)
```
/ui-ux-suite:audit Full 12-dimension audit, one report
/ui-ux-suite:colors Color-only audit
/ui-ux-suite:a11y [--deep] Accessibility audit (Playwright + axe-core in deep mode)
/ui-ux-suite:typography Typography and hierarchy audit
/ui-ux-suite:components Component-quality audit
```
Plus 14 specialist `/design-*`, `/color-audit`, `/a11y-audit`, … commands and 12 specialist agents.
---
## FAQ
**Is it safe to run on my project?**
Yes. Every audit is strictly read-only. The tool never creates, edits, or deletes files in the project you audit; it only reads and reports. Deep-mode screenshots happen in a throwaway browser page, never against your source.
**Does my code leave my machine?**
No. All analysis runs locally with Node built-ins. No network calls, no API keys, no telemetry.
**Which frameworks does it support?**
React, Next.js, Vue, Svelte, Angular, and vanilla. Styling: Tailwind (v3 and v4 `@theme`), CSS Modules, SCSS, styled-components, Emotion, vanilla-extract, plain CSS. It auto-detects the stack; no config.
**Is it really zero-dependency?**
Yes. The runtime uses only Node built-ins. `playwright-core` and `@axe-core/playwright` are **optional** peer deps for deep mode only; the default install pulls nothing.
**Do I need a running app?**
No. Source-based findings are the default. A running URL plus deep mode is a bonus, not a requirement.
**Does it fix my code automatically?**
No. It audits and *suggests* (`before` → `after`). Applying a fix is a separate, deliberate step you take.
**Can I use it in CI?**
Yes. `npx ui-ux-suite . --fail-under 7` exits non-zero when the score drops below your threshold. `--json` gives machine-readable output for any pipeline.
---
## Why trust it
- **Real color science.** Contrast is computed with the tool's own WCAG 2.2 and APCA math, not estimated. The fixture's measured ratios (e.g. `1.03:1`) are reproducible from `lib/color-engine.js`.
- **Cited WCAG success criteria.** Accessibility findings cite the exact SC: `1.4.3` Contrast (Minimum), `1.4.11` Non-text Contrast, `2.5.8` Target Size, `2.4.7` Focus Visible, `1.1.1` Non-text Content, `3.3.2` Labels or Instructions.
- **Verified Laws of UX.** UX findings cite a named law from a primary-source allow-list, each linking to its canonical [lawsofux.com](https://lawsofux.com/) page (e.g. Hick's Law, Fitts's Law, Law of Prägnanz). A wrong citation is treated as worse than none, so the citation set is pinned by a test.
- **A regression gate, not a vibe.** **311 tests** (run `npm test`) assert real behavior, including a 12-problem fixture where every finding must carry `evidence.file`, `evidence.line`, and a `fix`. If specificity regresses, the test suite fails.
---
## Privacy
All analysis runs locally. Your code never leaves your machine. No telemetry, no API calls, no network.
---
## Star History
---
## Contributing
Contributions welcome. The project is maintained in public.
```bash
git clone https://github.com/Aboudjem/ui-ux-suite
cd ui-ux-suite
npm test
```
- **Bug fixes** should include a test that would have caught the bug.
- **New scoring rules** must cite a WCAG SC or a named UX law from the allow-list and emit a `createFinding(...)` with `evidence: {file, line, selector, measured, threshold}` plus a `fix`.
- **No new runtime dependencies.** The suite is zero-dep by design.
- **No em-dashes** in user-facing copy.
See [CONTRIBUTING.md](CONTRIBUTING.md), [AGENTS.md](AGENTS.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and [SECURITY.md](SECURITY.md).
---
MIT · Built by Adam Boudjemaa · Star ⭐ to help others find it
