Refactoring UI：一个 Claude Skill
一本 AI 编码助手真正能执行的 Web 界面设计规则书，外加一层诊断。从 《Refactoring UI》（Adam Wathan & Steve Schoger 著）里拆出来。
⚠️ 非官方独立项目，与原书作者无隶属关系，未经其审阅，也未获其背书。
它替代不了读原书，感兴趣建议读原版，写得真的好。
详见 ATTRIBUTION.md。
目录
问题在哪
AI 写得出合格的 HTML 和 CSS，做出来的界面却总是差点意思。虽然不是直接报错，但有时候会隐隐感觉“不对劲”。
譬如，什么都居中。间距从头到尾一个值。主色总是偏好靛蓝或紫色。每个操作一律做成实心按钮。没有空状态。
这些单拎出来看好像也没什么。但问题在于：生成是局部的，设计要全局看。
中间缺的东西，可以用一本“规则书”来补。
这是什么
市面上的 AI 设计工具大多在做生成：你描述一个界面，它给你一个界面。
这个 Skill 干的是反过来的活。它是约束层和诊断层，是规则书和评审员，不是造型师。
所以它跟那些生成工具不是竞争关系，是可以充分互补的：生成之前把约束交给它，生成之后让它把产物走查一遍。
Refactoring UI 是一本规则书，不是灵感书。几乎每一页都是 症状 → 机制 → 具体做法 → 具体数值，而且作者也写了 Tailwind CSS，所以从原则到代码这一段几乎没有损耗：书里的字号阶、间距阶、色阶，就是 Tailwind 的默认值。这个项目把整本书拆成了可执行规则，151 条，每一条都可追溯。
用起来是什么样
“帮我看看这个设置页，总觉得哪里不对但说不上来。”
它会先摸清你的技术栈，分别在桌面和移动端两种宽度下把页面渲染出来，然后按固定顺序换七个视角逐一扫查：层级 → 间距 → 排版 → 色彩 → 深度 → 图像 → 收尾。
顺序是有因果的。层级没理顺，什么算间距问题就会跟着变；而间距一改，“这里到底要不要加条边框”这个问题往往自己就没了。
它交回来的每一条 finding（问题项）都按严重度排好序，而且必须挂着规则号：
| 严重度 | 规则 | 现状 | 建议 |
|---|---|---|---|
| P0 | §3.6 | 标签间距等于组间距，标签离自己的输入框和离下一组一样远 | 组内mb-1，组间 mb-6 |
| P1 | §2.8 | 三个按钮都是主操作样式 | 只留一个主操作，其余改描边和链接 |
| P1 | §6.2 | 静态卡片用了shadow-lg |
换shadow-sm。阴影表达的是 elevation，不是重要性 |
后面还有一段“系统性问题”，主要抓整体，譬如“当前项目缺少间距阶”。
安装
/plugin marketplace add edisonmbli/refactoring-ui-skill
/plugin install refactoring-ui
就这样，没有中心化的包仓库，也不往任何地方上传东西。marketplace add 做的事，是把仓库 clone 下来、读一下 .claude-plugin/marketplace.json；install 再从约定目录里把内容加载进来。所谓更新，其实就是换了个名字的 git pull：/plugin marketplace update refactoring-ui。
脚本要 Python 3.9+，零第三方依赖。没有 Python 也照样能用，色板算法有一份可以手工执行的说明。
其他安装方式：普通 Skill，以及非 Claude Code 的工具
Claude Code，作为普通 Skill
git clone https://github.com/edisonmbli/refactoring-ui-skill.git cp -r refactoring-ui-skill/skills/refactoring-ui ~/.claude/skills/ # 个人级 cp -r refactoring-ui-skill/skills/refactoring-ui .claude/skills/ # 项目级
其他编码助手
插件机制是 Claude Code 专属的，但 Skill 本身不是。它就是一堆 Markdown，而且刻意做成了“一个索引 + 按需加载的引用文件”，任何能读文件的助手都能照着走，告诉它一次就行。
先把 Skill 放到一个固定位置：
git clone https://github.com/edisonmbli/refactoring-ui-skill.git .refactoring-ui
然后直接拷贝现成的指路文件，别手抄——description 触发这种指令，模型一忙就是最先被跳过的那种：
# Codex、Copilot、Windsurf、Cline/Roo、Aider，或者作为 Cursor 的 AGENTS.md 兜底 cp .refactoring-ui/templates/AGENTS.md AGENTS.md # 或合并进你已有的那份 # Cursor 专用——靠文件类型匹配挂载，不靠 Cursor 从 description 猜意图 mkdir -p .cursor/rules && cp .refactoring-ui/templates/cursor/refactoring-ui.mdc .cursor/rules/
| 工具 | 放哪 |
|---|---|
| OpenAI Codex | 仓库根目录的AGENTS.md |
| Cursor | .cursor/rules/refactoring-ui.mdc（glob 匹配，见上），或 AGENTS.md |
| GitHub Copilot | .github/copilot-instructions.md |
| Windsurf | .windsurf/rules/design.md |
| Cline / Roo | .clinerules/design.md |
| Aider | CONVENTIONS.md，启动时用 --read 带上 |
| 其他 | 会话开始时它会读的任何文件；实在不行，把 templates/AGENTS.md 的内容贴进对话也管用 |
AGENTS.md 正在变成跨工具的通用约定，能用就优先用它；这些路径变动挺频繁，哪个不生效就去翻一下该工具的最新文档。
离开 Claude Code 会损失什么：脚本需要 Python 和执行命令的权限，但有手工降级方案；视觉验证需要浏览器工具，没有的话结论只能来自源码，Skill 会自动标成 code-only；并行走查需要 subagent，而串行本来就是默认模式。这些都不是承重结构，规则、诊断、走查纪律，在任何能读文件的助手里都成立。
它还能干什么
搭一套设计系统——“这个项目没有设计规范，帮我定一套。”
先来一段简单问答：产品是什么、想要什么调性、什么技术栈，也可以直接给它一个参考站 URL，它能读出那个站的字体栈和主色。问完交付五样东西：token JSON、对应你实际版本的 Tailwind 主题、框架无关的 CSS、一份写给人看的 DESIGN.md 说明书，以及可以直接发给同事看的 preview.html。
颜色是算出来的，不是拍脑袋定的。书里给了完整的色板算法，却一个具体色值都没给，所以脚本实现的就是那个算法：从基准色开始二分，明度偏离 50% 时提高饱和度，色相朝更亮或更暗的方向旋转，幅度控制在 20–30° 以内。每一组文字配色在交付前都过一遍对比度检查。
从零做新东西——按书里的顺序来，而不是上来就抠像素。
先功能后外壳，先灰度后上色，内容先分好层级。取值必须来自既定的阶，行长和节奏先定下来，然后才轮到颜色、深度和收尾。空状态是跟功能一起设计的，不是事后补的。
问个为什么——“为什么灰字放在我们那个蓝色 banner 上就那么难看？”
它只加载一个引用文件，然后把机制讲给你听：灰字在白底上管用，不是因为它“灰”，而是因为对比度降下来了，文字在往背景色靠近。在白底上，“变灰”和“降对比”恰好是同一个方向，真正的机制就被盖住了；换到蓝底上，这两件事立刻分道扬镳。§2.3
几件需要前置说明的事
不用 Tailwind 也完全没问题。 Tailwind 之所以贯穿全文，是因为这本书的作者后来写了它，那是最省事的一种表达法，不是因为哪里离不开它。层级、行长、分组间距、对比度、elevation，没有一样是 Tailwind 的概念。
Skill 会先看你实际用的是什么再适配：v4 给 @theme，v3 给 config；用了 shadcn/MUI/Ant，就把 token 注进它们自己的主题配置；已经有自己的 token，就翻译成你现有的那套命名；什么都没有，就给一份框架无关的 CSS 变量。它不会给你装 Tailwind、不迁移你的样式方案、不替换你已有的设计系统。
如果你还在用别的设计生成工具（Design 模式、frontend-design 之类），需要单独说明要走查。 这背后的原因是：当你让设计工具做点什么，它也顺利做出来了，这时候没有任何地方会报警，走查根本不会发生，因为生成器不会回头挑自己的毛病。这时候你只需要补一句：“现在按设计规则审一遍。” 或者更省事的是反过来做：在它动手之前就先把 Design Token 给它。
这两件事看着像在打架，其实并不。frontend-design 那一类追求的是有个性，这个追求的是成体系，两条不同的轴。设计系统告诉你用哪个蓝、哪一档间距，它可从来没让你再做一个无聊的下拉菜单。（这话是书里自己说的，§8.6。）
哪个环节是故意而为之的，建议一开始就说明。 譬如，间距阶故意做成线性的、圆角故意混用、品牌色故意压低对比等等，在启动前提一句就行。项目本身的刻意约定会压过书里的规则，Skill 会把冲突标出来，而不是判成缺陷。但如果你不说，它就无从知道那是有意为之，而一份报告，头一页全是你早就拍过板的决定，估计你翻两下就不会再看了。
工作原理
三层结构，渐进式加载。SKILL.md（约 220 行）放路由、12 条通用铁律和 4 个工作流，常驻上下文；14 个引用文件按需加载，一次只装一个；脚本和模板垫在最底下。
每条规则都是同样的六段式——规则 · 为什么 · 怎么做 · 数值 · Tailwind 写法 · 失败长什么样——让模型能顺着机制推理，而不是背结论。“失败长什么样”是诊断入口：从看着不对的地方出发，反查到规则。
四条底线撑着它不跑偏：
- 已有系统永远优先。 它只做两件事：把原则映射到你已有的命名上，或者在缺失的地方提个建议。绝不覆盖、绝不迁移、绝不擅自安装。
- 给的是占位符，不是色板。 示例一律写
bg-{primary}-600，绝不写bg-indigo-600：这种写法在语法上根本粘不进代码，颜色只能从你自己的 token 里解析。就这一条约定，它就不会闷声给你塞一堆靛蓝。 - 不变量有标记。 加粗的数字是书里的规则，不随项目变；其余的只是一个合法取值，不是标准答案。
- 扩展有标注。 暗色模式、focus 状态、动效、z-index 都是这本书之后才有的东西，这些都收了，但单独放一个文件，里面每一条都写明“书里没有这条”。
项目结构
.claude-plugin/ 插件与 marketplace 清单
skills/refactoring-ui/
SKILL.md 路由、12 条铁律、4 个工作流
references/
00-coverage-matrix 151 条规则逐条追踪，防遗漏的兜底机制
01-08 对应原书八章，一章一个
10-15 Tailwind 映射、token、组件配方、走查判据、
反模式、书外扩展
scripts/ generate_palette · check_contrast · emit_tokens
assets/ token 模板、可手填的主题骨架
examples/ before → after 实例，兼作 eval 样本
许可证
仓库内所有内容采用 MIT。原书受版权保护，是独立作品，本项目只是独立地重新实现了书里的原则，与原书作者无隶属关系，细节见 ATTRIBUTION.md。
一个设计功底不足的产品经理做的。他想要的很简单：每次 AI 动样式表，这本书的判断力都在场。