ui-ux-suite

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

面向设计的 ESLint。它能找到确切的代码行、测量出的错误值，以及确切的修复方案。

功能 · 安装 · 使用 · 你将获得什么 · 在你的编辑器中使用 · 须知

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

功能

大多数设计评审只会告诉你要提高对比度。这个工具会告诉你，src/styles.css 第 14 行的 .hero-subtitle 使用了 #fbfbfb，背景为 #ffffff，对比度测量值为 1.03:1，而 #767676 可以通过检查。它像代码检查器一样报告设计问题。

它会读取你的 CSS、JSX、HTML 和 Tailwind 类。默认情况下不会执行任何内容，不会有任何数据离开你的设备，也不需要密钥。发现的问题分为两类。其中，定位类问题占大多数，也是你主要会处理的问题，它包含三项信息：

• 已定位。 文件、行号和选择器。
• 已测量。 实际的错误值，而不是模糊的描述。
• 已修复。 确切的 before 到 after 修改，以及所依据的 WCAG 标准或具名 UX 法则。

其余问题属于项目级问题，例如“使用了 5 种字体，建议使用 1 或 2 种”。它们会给出评分并指出问题，但没有可指向的具体代码行。

安装

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

这是 Claude Code 的安装方式。对于其他任何能够读取 Agent Skills 格式的 Agent，都可以直接从此仓库安装这 14 个技能：

npx skills add Aboudjem/ui-ux-suite

命令行工具无需安装：运行 npx ui-ux-suite . 即可。

npm install -D ui-ux-suite

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

使用

1. 指定一个项目。

npx ui-ux-suite .

你会得到按优先级排序的问题列表，以及涵盖 12 个维度的加权评分（满分 10 分）。无需配置文件，也无需设置步骤。

2. 查看问题。 这是本仓库随附的错误示例项目的实际输出。该项目因特意设置了以下问题而只得 3.7 分（满分 10 分）：

- **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)

在仓库检出目录中运行 npx ui-ux-suite test/fixtures/planted-ux-problems，即可亲自试用。

3. 将其加入 CI。 选择适合你流水线的输出格式和门禁：

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

所有标志都列在 docs/cli.md 中。

你将获得什么

• 一份排名报告，支持 Markdown、JSON、HTML 或 SARIF 格式，无论读者是机器还是人。
• 一项 10 分制评分，涵盖 12 个加权维度，其中无障碍性权重最高。
• 一个 CI 门禁，可通过 --fail-under 设置绝对门槛，也可以基于基线，在出现新问题或分数下降时失败。
• 14 项技能和 16 个工具，你的 Agent 可以调用，因此在聊天中说“审计这个项目的设计”即可。

在你的编辑器中使用

可在 Claude Code、Cursor、Codex、Copilot、Gemini CLI 以及其他 70 多种 Agent 中使用，通过 npx skills add 安装即可。这些技能采用 Markdown 编写，因此可使用编辑器所指向的任意模型运行。

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

需要了解的信息

重要

它只审计，绝不编辑。它绝不会修改你指定项目中的源文件；修复方案会以 before 到 after 的形式输出，供你自行应用。它只会写入报告和基线文件，且仅写入你指定的位置。

• 不会有任何内容离开你的设备。 仅使用 Node 内置模块，无需 API 密钥，也不收集遥测数据。静态审计不会发起网络请求；深度模式只会访问你提供的 URL。
• 默认使用静态源代码审计。 深度模式需主动启用，需要安装 playwright-core 和 @axe-core/playwright；若缺少这些依赖，则会退回到源代码问题检查。
• 这些数字有测试保障。 npm test 会运行 356 项测试，并且项目附带的缺陷样例必须持续产出带有文件、行号和修复方案的问题。

了解更多

• docs/cli.md：所有标志、退出代码和示例
• docs/editors.md：各编辑器的安装方式和 MCP 配置
• docs/scoring.md：12 项权重以及评分的计算方式
• docs/science.md：问题背后的 WCAG 准则和 UX 定律
• docs/faq.md 和 docs/comparison.md
• CHANGELOG.md、CONTRIBUTING.md、LICENSE

_{MIT · 由 Adam Boudjemaa 构建}