mcpField
D
design-audit

design-audit

github.com/athevon设计与 UI7051.0k 次安装3 周前更新
代码仓库

关于 design-audit

面向设计与开发流程的代码审查技能，用脚本检查动效、无障碍、性能和一致性问题。它区分发现项、检查干净和未适用项，并将常见设计套路单独列出供人工核对。

主要功能

  1. 01脚本扫描代码库
  2. 02检查动效与无障碍问题
  3. 03报告文件和行号证据
  4. 04区分未检查与通过
  5. 05单独列出设计套路

适用场景

  1. 01交付前检查界面代码
  2. 02定位动效与焦点可见性问题
  3. 03按严重程度整理审查结果

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/athevon/genjutsu --skill design-audit

安装后在 Claude Code 中输入/design-audit确认已加载。

详细介绍

版本敏感。 以下每个 API 名称、SDK 门槛和浏览器支持声明，均已于 2026-09-08 根据一手来源核实。核实依据和时间见 _jutsu/VERSIONS.md。如果这个日期已久远，请在依据版本号采取行动前重新核实。

设计审查

最后的检查点。由 /genjutsu:paint 在流程末尾加载。 扫描代码库，查找动效缺失、无障碍违规、性能问题和不一致之处。

静态检查

运行脚本。不要手动编写 grep 命令。

python3 "$SKILL_BASE/design-audit/scripts/audit.py" .

如果想对结果进行后处理，请添加 --json。--only <check-id> 可运行单项检查，--group tells 或 --group hygiene 可运行一个组。

它会报告三种结果，后两者的区别正是它存在的全部意义：

  • 发现项 - 检查已运行并发现问题。每个发现项都包含 file:line 和 匹配文本，因此你应报告证据，而不是下结论。
  • 无问题 - 检查针对实际文件运行，且未发现问题。
  • 不适用 - 没有此类文件，因此检查未运行。应报告为未检查。绝不能说检查通过。

这些 grep 过去写在本文件中，范围固定为 src/。默认的 Next.js app-router 或 Nuxt 3 项目没有 src/，所以它们匹配不到任何内容；流程却把空输出当作一切正常，并在交付前 这样告诉用户。脚本会检测项目根目录，跳过 node_modules 和构建输出，除 JSX 和 CSS 外，还会检查 .vue / .svelte / .astro，并且每项检查都有一个测试来断言 该检查仍能触发。

“套路”会单独报告。 脚本还会运行 tells 组：共十八项检查，查找模型在没有明确要求时惯用的默认模式，例如编号眉题、天气条、三张等宽卡片，或文案中的 U+2014（破折号）。大多数检查读取标记语言中显示的文本（标签之间的文本、alt、title、aria-label、placeholder），绝不会读取类名或样式对象，因此不会把 width: "100%" 当作完美设计的证据。另有五项直接读取源代码，因为它们检查的是类或 CSS 规则：渐变文字、玻璃质感、光晕、色块和持续动效。脚本看不到存放在 JavaScript 数据中的文案（例如特性数组或内容文件），需要手动查看。

它们会出现在自己的部分“套路 - 逐项对照设计论点”，且始终标为 nice-to-have；脚本绝不会将其计为问题，因为它无法读取设计论点。你需要逐项核对：

  • 经过验证的设计论点明确提到这种模式（例如，论点说工作室业务覆盖巴黎和东京，页眉也显示了两地时钟）：将其列为设计论点允许的模式，并引用相关句子；
  • 如果没有提到：该套路就是问题，应计入其他问题。

情绪词并没有明确含义。“编辑风”或“代理机构”都不能成为使用编号眉题的理由；大多数套路正是这类词会让人联想到的陈词滥调。加载 tells 模块后，以其规则为准。

清单还会列出颜色、圆角半径和字体系列，以及时长和缓动；每个值最多附带五处 file:line 位置。这里不会给出结论：请将它们与设计令牌和设计论点进行比较。

脚本不检查对比度。 请根据你输出的令牌值自行计算，并报告颜色组合及其比率：#831843 on #FDF2F8 = 9.4:1。正文文本需达到 4.5:1，大号文本和 UI 边界需达到 3:1。目测色样不等于测量结果。

如果无法使用 python3， 请用一行说明，然后按以下顺序检查你修改过的组件：减少动效设置防护、退出动画、布局属性动画、焦点可见性、非交互元素上的点击处理程序。请将结果报告为部分审查，并说明哪些检查无法运行。

特定技术栈的审查

选择与项目技术栈相符的小节。

Compose（Android / Multiplatform）
  • 运行 Layout Inspector（Android Studio）：检查重组，找出每次状态变更时都会重组的组件。
  • 运行 Macrobenchmark（androidx.benchmark.macro）：在真实设备上，模拟具有代表性的滚动 / 动画负载并测量帧耗时。目标：60fps 时每帧 <16.67ms，120fps 时每帧 <8.33ms。
  • 检查重组次数：Layout Inspector > Component Tree > View Options > Show Recomposition Counts（API 29+，Compose 1.2+）。每次交互前重置计数器，确保数据有意义。androidx 中没有 Modifier.recomposeHighlighter；它是一个需要自行引入到调试源码集中的示例。
  • 为生产构建生成 Baseline Profiles（BaselineProfileGenerator）。
  • 确认自定义组件已设置 Modifier.semantics（支持 TalkBack）。
SwiftUI（iOS / macOS）
  • 运行 Instruments Time Profiler：找出动画期间的热点路径（目标：耗时超过 16.67ms 的帧为零）。
  • 运行 Instruments Hitches Instrument（iOS 14+）：检测丢帧和卡顿。
  • 对 Metal 着色器运行 Instruments GPU Frame Capture：验证着色器编译时间以及 GPU 与 CPU 瓶颈。
  • 确认每个可交互视图都设置了 .accessibilityLabel / .accessibilityHint。
  • 使用 200% 大小的动态字体进行测试（Xcode 中的 Environment Overrides）。
  • 开启 Reduce Motion 进行测试。
Web
  • 使用上文已有的检查清单（Lighthouse、Chrome DevTools Performance 等）。

输出格式

按严重程度整理发现：

严重（发布前必须修复）
  • 未处理 prefers-reduced-motion
  • 可点击的 div 不支持键盘操作
  • 使用 outline: none，但没有用 :focus-visible 替代
  • 为布局属性设置动画（width/height/top/left）
重要（当前冲刺内修复）
  • 条件渲染未使用 AnimatePresence
  • 悬停状态没有过渡效果
  • 装饰性动画缺少 aria-hidden
  • 使用 setTimeout 创建动画循环
  • 持续时间不一致（唯一值 >8 个）
可选改进（待办事项）
  • 列表没有交错动画
  • 内联样式没有过渡效果
  • 过度使用 will-change
  • 进入 / 退出方向不对称（方向错误）
  • 动画库相对于实际用量过大

评论

支持 Markdown