enmerasoftware/ai-design-check

项目介绍

AI 编程代理产出的界面常有可识别的“机器味”：字号不在比例尺上、间距偏离 4 px 栅格、用 emoji 当图标、去掉焦点环、只有图标的按钮没有可访问名称。这个项目提供 76 条设计规则和一个基于 Node 的检查器，按规则 ID、文件和行号报告这些可测量的缺陷。规则来自 Enmera 和 Searvia 实际上线的界面，并用 16 个高评分仪表盘设计做了对照；每条规则都用英文和土耳其文写明是什么、为什么、怎么改。

它面向仪表盘、管理后台、SaaS 界面和落地页，也能读取 SwiftUI（.swift）与 Jetpack Compose（.kt）应用代码。需要人工判断的规则（如布局、选择器）标为 review，交由人或代理处理。

快速使用

需要 Node 20 或更高版本。在项目根目录通过 npx 运行检查器：

npx @enmera/ai-design-check

要检查特定目录或语言，可传入路径和语言，例如 npx @enmera/ai-design-check src lang。结果按文件和行号列出；有 error 时退出码为 1（加 --strict 则 warn 也失败）。--json 输出机器可读结果，--format github 输出 PR 注解。

要让编程代理修复界面，先安装随包提供的技能，再让代理修复这个界面的设计：

npx skills add enmerasoftware/ai-design-check

代理会先读规则，分轮修改并重新运行检查器，报告修改前后的问题数量。对已有项目，先记录当前问题，之后只报新增项：

npx @enmera/ai-design-check --write-baseline

配置写在 ai-design-check.json 或 .design-rules.json：包含/忽略的路径、i18n 字典、共享组件映射、按规则允许的例外以及严重级别覆盖。

其他命令

inventory 统计按钮、输入框、标题、徽标和卡片各有多少种不同外观。narrow 用本机 Chrome 在手机宽度（默认 320 px）渲染页面，报告横向滚动、文字被截断和只在桌面显示的内容。system 根据风格词和品牌色生成设计系统（字体、字号阶梯、通过 WCAG 对比度检查的颜色、形状 token），输出 CSS、Tailwind v4、JSON、Swift 和 Compose 文件。story 生成方形的修改前后视频，需要 Chrome 和 ffmpeg。hook 从 stdin 的 JSON 中取单个已编辑文件做检查，适合接入代理钩子。

使用约束

• 检查器是纯 Node 实现、不依赖 npm 包，但 narrow 和 story 会通过 DevTools 协议驱动本机 Chrome，story 还需要 ffmpeg。
• 基于 class 的规则只检查 class 字符串（class、className、cn()、clsx()、cva()、twMerge()），不检查注释和文案。
• 在源码中写忽略必须带 -- 之后的理由，没有理由的忽略不会被认可。
• 需要判断的规则只做 review 提示，不会自动判定。
• 新增规则要编辑 rules.json，再用 npm run docs 重新生成文档，提交前运行 npm test。
• 使用 MIT 许可证。

HotRepo 点评

2026-11-01，该项目出现在 HotRepo 的 JavaScript 新项目榜上，在不到两小时的统计窗口内新增 21 个 Star，记录为 121 Star、8 Fork。Star 曲线显示早期增长很快，最后两个每小时采样从 100 升到 121，但观察窗口很短，不足以判断趋势。它区别于同类工具的地方，是把零依赖检查器和代理技能配在一起：不只清理一次，还试图阻止下一次代理编辑把问题带回来。

项目源码与说明