Refactoring UI Skill：把经典设计书一键装进 Claude Code 的视觉 SOP

当你让 Claude Code 写前端，”looks off / 看起来有点廉价 / 配色总是不对”——这类模糊反馈每次都让 Agent 在 CSS 里盲调 30 分钟，最后吐出一份「能跑但很 AI」的界面。s0xDk/refactoring-ui-skill 把经典设计书《Refactoring UI》的硬规则直接塞进 SKILL.md，让 Claude 在预设的间距、字号、字重、颜色、阴影、圆角 scale 里做选择题，而不是凭感觉 ad hoc 选值。仓库 2026-08-26 上线，截至 2026-08-31 拿到 452 GitHub stars、44 forks，单日峰值 +291，被 Enterprise DNA、wondelai/skills 等多家独立仓库以”把设计书变成 Claude skill”为名复用，已经成了 SKILL.md 生态的一个新 genre。

功能与原则

核心能力是把《Refactoring UI》(Adam Wathan & Steve Schoger 著) 中所有被反复引用的具体数字决策打包成可加载指令，覆盖五个系统：spacing/sizing scale (4, 8, 12, 16, 24, 32, 48, 64, 96, 128, 192, 256, 384, 512, 640, 768)、type scale (12–72)、font weight (只用 400/500/600/700 四档)、颜色系统 (8–10 档灰阶 + 5–10 档主色 + 5–10 档每个 accent)、阴影与圆角组合，再加 depth via emulated light 这条书里反复强调的反直觉规则。设计原则是”决策一次、永远复用”——禁止 17px、lighten(5%) 这种 scale 之外的值；视觉层级靠字重和颜色，不用堆字号；所有 CSS 值都按页码回溯核对原书，不做摘要式转述。

认可度

• GitHub stars: 截至 2026-08-31 约 452 ⭐ (单日峰值 +291)
• Forks: 44
• Open issues: 1
• License: Other (MIT 内容，原书版权除外)
• Trending 经历: 上线 5 天内被多家独立开发者以相同主题 fork（wondelai/skills 等），被 Enterprise DNA 8月27日的 AI Pulse 单独点名，微博前端圈单独推过一轮
• 社媒讨论: Reddit r/ClaudeCode、Hacker News design 节点均有讨论，”Turn a design book into a Claude skill” 被作为新范式引用

链接

GitHub 仓库: https://github.com/s0xDk/refactoring-ui-skill

原作者

s0xDk — 仓库 owner 个人账号，公开信息有限。仓库 README 与原书《Refactoring UI》明确做版权切割：仅发布原创笔记与 CSS 派生内容，不包含原书文本或图片；建议读者支持原书购买。

介绍

这个 skill 的定位极其精准：AI 写前端最大的痛点不是”不会写代码”，而是”写出来的界面有一种平庸的 AI 模板感”。作者认为根因是训练数据里 CSS 值太杂、Agent 每次都临时 ad hoc 选值，所以他把 Wathan & Schoger 那本设计书的全部数值决策提取出来，做成一份 Claude 能逐字阅读的”视觉 SOP”。

仓库结构很轻量：一个 SKILL.md 主文件 + 三个 references（systems.md 教你从 HSL 搭灰阶与色板、diagnose.md 是”症状→修复”对照表、techniques.md 讲 depth/光照模拟/网格/图像处理）+ assets/tokens.css 一份可直接抄走的对比度验证 token 集。安装后只要对 Claude 说”这个 dashboard 看起来有点廉价 / 帮我统一一下设计 tokens / 这页字间距太挤”，skill 会自动触发，并强制从预设 scale 里选值。

特点

• 数值 scale 全部锁死: spacing/type/shadow/radius 都来自固定列表，Agent 不允许 scale 外选值，从源头消灭”17px、#3B82F6 这类 AI 味”
• 决策可追溯: 每条规则 README 注明对照书的具体页码，不做摘要式转述，避免大模型幻觉
• 症状→修复对照表: 把”看起来 cheap / 太挤 / 太灰 / 没层级”等口语化反馈，映射到具体 CSS 改动
• 完整 starter token 集: assets/tokens.css 直接给一份对比度通过验证的颜色、间距、阴影变量集合，可作为新项目设计系统起点
• 零运行时依赖: 纯 markdown + CSS 文件，无打包步骤、无 Node 模块

使用方法

安装（Claude Code 全局）：

git clone https://github.com/s0xDk/refactoring-ui-skill.git ~/.claude/skills/refactoring-ui

或项目本地：.claude/skills/refactoring-ui。装完重启 Claude Code（新会话）即可生效。

最小调用：

• 自动触发：让 Claude “build a pricing page” / “improve this dashboard” / “this hero looks amateur”
• 显式调用：/refactoring-ui make this admin panel less cheap
• 生成 token：要求 “use the bundled tokens.css as the base for our new app”

最小示例：

用户：把这份产品落地页 spacing 统一一下，看起来太挤
Claude（加载 refactoring-ui 后）：从 spacing scale 4/8/12/16/24/32/48 中选了 16/24/48，
section 之间 48px，标题与正文之间 16px，CTA 上下 padding 12/24，避免出现 18px、20px 这类
scale 外值；hero 标题字号从 30 升到 48 字重保持 700，颜色从 blue-500 提到 brand-600。

使用场景与人群

• 前端独立开发者: 用 Claude Code 做 MVP / 内部工具 / 落地页时，输出的 UI 直接具备”不廉价”的视觉一致性，不用反复 micro-manage CSS
• 产品设计师: 把团队已有的 design system / brand guideline 转成类似 SKILL.md 时的现成模板（spacing、type scale、color shades 的写法）
• AI Agent 重度用户: 给内部 coding agent 注入一套”像素级设计守则”，替代”让它自己审美”的不稳定输出
• 教学 / 内容创作者: 把任何方法论书（设计、写作、代码风格）打成 skill 的范式——这是 skill 生态”读一本书 = 一个 skill”路线的最干净示范

输入与输出案例

案例 1：模糊反馈 → 精确修复

• 输入：用户说 “my dashboard looks cheap, fix it”
• 输出：Claude 触发 skill，定位到三个具体问题：(1) 卡片间距 18px 不在 4/8/12/16/24 列表中 → 统一为 16；(2) 标题字号 22px 跳过 scale → 改用 24px 并用 700 字重而非 18px + 加粗；(3) 阴影 0 1px 2px rgba(0,0,0,.05) 用了 scale 外透明度 → 改用预定义 shadow-sm token。

案例 2：从零搭一套 token

• 输入：用户要求 “set up design tokens for our new React app, copy from the skill’s starter set”
• 输出：直接拉取 assets/tokens.css，得到 8 档灰阶 (grey-50 → grey-900)、5 档主色 (brand-100 → brand-900)、12 个 spacing、11 个字号、6 档阴影的对比度验证 token 集合，附 README 注释使用边界（如 bg-grey-50 用于页面底色，text-grey-600 用于次要正文）。

总结: 这不是又一个”AI 帮你做设计”的工具，而是把一本已经被反复验证的设计书转成 AI 能逐字执行的 SOP——452 颗星在 5 天内集中爆发，正是因为它击中了”AI 前端输出不稳定”这条所有独立开发者都踩过的痛点。把方法论书做成 skill 这个范式一旦铺开，受益的不只是设计，还有 code review、测试、写作、运维所有”靠经验拍脑袋”的领域。

GitHub: https://github.com/s0xDk/refactoring-ui-skill