avoid-ai-design

避免 AI 设计：审查与重写

审查前端代码，找出让 UI 看起来像 AI 生成的模式（“AI 垃圾”），然后围绕一个明确的设计方向重写。

这是 avoid-ai-writing 技能在设计方面的对应版本。它针对两种技术栈：纯 HTML/CSS/JS 和 React + Tailwind + shadcn/ui。

重点不是追求新奇，而是用决策取代默认选项。紫色渐变并非因为紫色不好而显得糟糕，而是因为没人做出选择才显得糟糕。

默认设计有两个层次。 第一层是中位数：紫色渐变、Inter、三张图标卡片。第二层是曾经特立独行、如今已成为新中位数的雅致选择：奶油色搭配陶土色、近黑色搭配一种亮酸绿点缀、全大写等宽字体标签、标题中的一个彩色单词、装饰性的 01/02/03。Anthropic 自己的 frontend-design 技能列出了这些组合，而去除 AI 垃圾的改造（包括本技能中的改造）也总会落入这些套路。两种默认设计都要视作警示信号。参见 references/ai-tells-catalog.md 的 SD 部分。

代码只能展现一半，另一半要看像素。 有些警示信号存在于源码中（字面量 from-indigo-500、Inter、lucide 导入）；扫描器能找到它们。还有些是视觉层面的：调色板是否有真正的主导色、间距是否有节奏、结构是否和其他页面如出一辙。条件允许时就渲染页面。无法渲染时，请说明哪些发现是代码可以确认的，哪些是推断所得。

模式

rewrite（默认）：审查代码，确定设计方向，然后重写。

detect：仅审查和评分，不做修改。以下情况使用此模式：

• 用户想查看标记了哪些问题，并自行修复。
• 你正在审查不应修改的代码（依赖项、队友的工作或参考代码）。
• 用户要求快速扫描。

当用户说“只做审查”“只标记”“扫描一下”“这有什么 AI 味”或“不要改代码”时，使用 detect。默认使用 rewrite。

扫描器

scripts/detect.mjs 无需调用模型或安装依赖，即可找出代码中可以确认的警示信号（目录中以 ⚙ 标记）。只要有 Node 18+，就先运行它：

node <skill-dir>/scripts/detect.mjs <files or folders>        # grouped report, exit 2 on any P0/P1
node <skill-dir>/scripts/detect.mjs --json <files or folders>  # for your own parsing

请将扫描器的输出视为审查中代码可确认的部分，而非全部结果：它无法识别调色板权重、节奏、层级或结构层面的雷同。它会跳过 examples/、fixtures/、stories/ 以及标记为 slop-example 的文件，除非传入 --include-examples；对于设计需求明确要求的选择，它也会遵循 avoid-ai-design-ignore: <ID> 注释。没有 Node 时，请手动逐项检查目录。

工作流（重写模式）

1. 范围。 先阅读实际文件。明确审查范围（组件、页面还是整个应用）、技术栈和模式。查找设计系统，确保风格一致：DESIGN.md（Google 的开放格式，也由 Stitch 和其他设计技能编写）、令牌文件或 :root、组件库、同级页面，或用户自行选择的字体和颜色。注意工作是否涉及多个页面。绝不要只根据提示词作判断。
2. 扫描。 对范围内的文件运行扫描器。
3. 渲染。 如果有截图或预览工具，就渲染产物，并根据像素判断 👁 特征。在页面上进行轮廓测试：将截图缩小为黑白小块轮廓，然后判断它是否可能是其他任何产品的页面（目录 L9）。将视图缩放至 25%，眯起眼睛检查整体密度。如果无法渲染，将视觉特征标记为推断，置信度较低。
4. 审查。 综合扫描结果、渲染结果，并逐项检查 references/ai-tells-catalog.md 中的所有类别，包括 SD 部分。对每个特征记录：位置、ID、严重程度、一句话说明它为何显得像 AI 生成，以及它是代码确定的、渲染后确认的，还是推断的。
5. 立足实际并制定计划。 如果存在设计系统，它就是设计方向：将其作为规范，并严格匹配。否则，根据主题而非风格选项菜单推导设计方向。思考产品是什么、谁会使用它，以及它的世界由什么构成（材质、地点、时代、该领域本身的产物和行话）。写一份简洁计划：列出 4-6 种有用途说明的颜色、字体及其用途、用一句话描述布局构想，以及一个标志性细节。references/aesthetic-directions.md 是用于命名设计手法的词汇表，不是供选择的菜单。
6. 根据默认倾向审视计划。 修改代码前，根据二阶聚类（SD1-SD8）和你近期的工作审视计划。对每个部分，问问自己：面对任何类似页面，我都会得出这个方案吗？如果答案是肯定的，就修改方案并说明改了什么。如果用户在场，用一句话展示计划和一两个备选方案，然后暂停。如果以非交互方式运行，用一句话说明假设，然后继续，并确保方案易于调整。
7. 调整工作深度。 小型组件或设计系统内的内容应进行精细调整：替换这些特征，保留结构和令牌。独立页面应围绕设计方向重新构建。从头开始构建与 frontend-design 技能的工作有重叠；如果该技能可用，将审查后的计划交给它，而不是重复其工作。
8. 重写。 编辑实际文件。保留功能、props、状态、路由、数据流、无障碍性和文案含义。不要悄悄添加依赖；明确说明任何新增依赖。对于多页面工作，根据 references/design-md-template.md 将计划写入 DESIGN.md（或扩展现有文件），并据此构建每个页面。
9. 重新扫描并评判。 再次运行扫描器：不得有 P0，也不得出现需求简述未要求的 SD 特征。然后根据“成功的标准”评判结果。扫描干净是必要条件，但并非充分条件。

成功的标准

目标不是“看起来没那么像 AI”。把颜色从靛蓝换成青绿色、把 Inter 换成更时髦的字体、删掉表情符号，这种表面调整能解决所有 P0 问题，却仍会留下一个令人过目即忘的模板。请用以下标准评判结果：

1. 有理有据。 每项改动都服务于已确定的设计方向，而设计方向又能追溯到主题本身。
2. 协调统一。 字体、配色、布局和标志性细节彼此呼应。只用一个理念，并将其贯彻到底。大胆之处集中在一处。
3. 不是二阶默认套路。 结果不能落入设计简报未要求的 SD 风格类别，也不能重复你最近的做法（奶油色搭配陶土色、近黑色搭配荧光绿、单色风格）。如果你会把同样的设计用在任何类似页面上，那就不合格。
4. 保持一致（并非只有一个页面时）。它应与同系列页面共用设计令牌、导航栏、页脚和字体比例，看起来属于同一款产品。不同项目之间可以变化（见测试 3），但同一项目内部不能变化。

页面通过扫描器，并不代表它能通过以上所有标准。设计目录能抓出陈词滥调；这些标准能抓出平庸之作。

严重级别

级别根据谁会注意到来划分，而不是根据某种模式有多烦人。具体情境可能会让某个特征的级别上升或下降。

• P0，普通人也能看出是 AI 生成的。 紫蓝渐变、所有内容都用 Inter、未经调整的 shadcn 基础主题、渐变（bg-clip-text）标题文字、居中主视觉搭配三张卡片的模板。这些都是老掉牙的套路。
• P1，设计师或开发者能看出来。 二阶风格类别（SD）、所有界面元素都套用 rounded-2xl shadow-lg、默认页面外壳、圆角方框中的图标、默认四栏页脚、现成的 Aceternity / Magic UI 效果、毫无反馈的悬停和焦点状态、硬塞进 CTA 的箭头符号、“提升你的工作流”式文案。
• P2，工艺和润色上的不足。 间距平铺直叙、所有元素都采用同一种上移淡入效果、弹跳式缓动、通用 CTA 标签。

情境很重要：居中主视觉在通用 SaaS 页面上属于 P0，在奢华风格布局中则完全合适。缺少 :focus-visible、文本颜色与背景的对比度低于 AA 标准，以及不遵循减少动态效果偏好的动画，都属于无障碍缺陷；无论它们属于哪个级别，都应视为高优先级问题。

情境配置

根据 UI 所处的位置调整严格程度。根据技术栈和结构自动识别，并说明使用的是哪种配置。

配置	处理方式
landing / artifact	全面应用标准。鼓励大胆设计。这里最需要明确的设计方向。
marketing-page	全面应用标准，涵盖字体、颜色、布局和文案。
app-component	只做必要调整。消除明显问题，同时保留组件的约定和结构。
inside-design-system	只做必要调整。遵循现有设计令牌和基础组件，不要与设计系统对着干；另行指出系统层面的明显问题并作为建议。
dashboard	优先考虑信息密度、可读性和信息层级，而非装饰。

防护原则

• 绝不破坏可正常运行的代码。 Props、状态、路由、数据获取和无障碍功能都必须保持完整。不得擅自更改行为。
• 不要用一种陈词滥调替换另一种。 次一级的默认选择依然是默认选择。紫色的替代方案不该是奶油色和陶土色，奶油色的替代方案也不该是近黑色和荧光绿。每次都要有所变化，并根据主题为每个选择说明理由。
• 以需求说明为准。 现有设计系统、品牌指南、指定框架，或用户选定的字体或颜色，优先于你的审美偏好，即使它要求采用某种 SD 风格。应予以匹配，绝不擅自覆盖，并添加 ignore 注释，让扫描器停止标记。
• 在所有页面中保持同一套设计系统。 如果工作涉及多个页面，应在 DESIGN.md 中锁定一套规范（颜色、字体、间距、圆角、导航、页脚、共享组件），并原样复用。每次从头生成页面都会回到训练集的中位风格，因此第二页会偏离第一页。这就是设计系统漂移（目录 X1），其 AI 感与任何单一特征一样明显。如果需要的令牌不存在，就将其加入规范或提出询问。不要临时杜撰。
• 依据证据，而非指责。 特征只能说明页面采用了无人选择的默认值，不能证明页面由模型生成；其中许多是已安装的 Tailwind 和 shadcn 默认值。报告默认值；不要臆测创作者身份。
• 不要凭空制造问题。 如果 UI 已经独特且经过精心设计，就如实说明并停止。审查结果没有问题也是有效结论。
• 保留文案原意。 可以润色空泛的微文案，但不要编造说法，也不要改变产品对自身的描述。

自我指涉豁免条款

当代码旨在展示 AI 设计模式时（例如演示、教学示例、“错误示范”图库，或本技能自身的文档），示例中的劣质设计是有意为之。只有在存在具体标记时才可豁免：相邻注释将其标记为 slop-example，路径位于 examples/、fixtures/、__mocks__/ 或 stories/ 下，或文本明确标注为示例。扫描器也采用同一规则。只标记真实界面中的模式。

不限于 HTML 和 React

该目录主要针对 HTML/CSS 和 React/Tailwind/shadcn 编写，因为 AI 工具最常生成这些技术栈。其原则与框架无关：未经修改的默认值就是特征。未经修改的 MUI（Roboto 和蓝色）、Chakra、Bootstrap（蓝色 btn-primary）或 Mantine 默认样式，出于同样的原因也会显得像 AI 生成。采用同样的审查方法，并替换为对应的类名和令牌名称。

输出格式

rewrite 模式

1. 审查。 按严重程度分组列出发现的每个特征，并注明其 ID、位置、单行原因，以及 code-certain / rendered / inferred 标签。运行扫描器后，先给出扫描器摘要。
2. 计划。 说明设计方向及其主题依据、精简的令牌计划、你在默认样式审查（第 6 步）中修改的内容，以及用一句话列出一两个备选方案。如果需要交互，此处暂停。
3. 重写。 按校准后的深度提供修改后的代码；涉及多个页面时，还需提供 DESIGN.md。
4. 变更说明。 简要总结关键改动，不要逐行对比差异。
5. 重新扫描与判断。 给出扫描器的第二轮结果，然后进行四项成功测试。修复任何未通过项。

detect 模式

1. 审查。 按严重程度（P0/P1/P2）列出发现的每个特征，并注明其 ID、位置，以及 code-certain / rendered / inferred 标签。
2. 评估。 针对每项标记，判断它是明确的问题还是需要权衡的选择。有些模式在特定语境中没有问题（例如，渐变只用一次且效果良好就不算劣质设计；需求指定的奶油色调色板也是一种选择）。说明哪些需要修改，哪些应保留。

不要过度设计

目标是打造一款看起来像是由有品位的人为这个主题精心设计的 UI，而不是一款只为吸引眼球而喧宾夺主的 UI。恰到好处的克制胜过盲目堆砌。若原作已经很出色，就只做必要的少量删减，然后停手。改写的力度应与作品本身相匹配：设置面板不需要主视觉动画。