Maintainer of this skill?
Automated security scan — not a certification.
by edisonmbli
Unofficial Claude Skill derived from the book Refactoring UI — a design rulebook and diagnostic layer for web UI. 151 tracked rules, design token generation, and Tailwind mappings.
# Add to your Claude Code skills
git clone https://github.com/edisonmbli/refactoring-ui-skillGuides for using ai agents skills like refactoring-ui-skill.
Last scanned: 10/21/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-10-21T09:09:32.071Z",
"npmAuditRan": true,
"pipAuditRan": true,
"promptInjectionRan": true
}See how refactoring-ui-skill compares with popular alternatives.
refactoring-ui-skill is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by edisonmbli. Unofficial Claude Skill derived from the book Refactoring UI — a design rulebook and diagnostic layer for web UI. 151 tracked rules, design token generation, and Tailwind mappings. It has 171 GitHub stars.
Yes. refactoring-ui-skill passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.
Clone the repository with "git clone https://github.com/edisonmbli/refactoring-ui-skill" and add it to your Claude Code skills directory (see the Installation section above).
refactoring-ui-skill is primarily written in Python. It is open-source under edisonmbli on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh refactoring-ui-skill against similar tools.
No comments yet. Be the first to share your thoughts!
30 days in the Featured rail · terms & refunds
⚠️ Third-Party Software Notice
This skill is third-party open-source software developed and hosted independently on GitHub. SkillsLLM is an informational directory and does not control or maintain the underlying repository.
Any security checks, ratings, or warnings displayed by SkillsLLM are automated and limited in scope. They do not constitute a security certification or guarantee that the software is safe, error-free, or free from malicious code, vulnerabilities, compromised dependencies, or prompt-injection risks.
Review the source code, permissions, dependencies, and configuration before installing or running any third-party skill. Use is at your own risk. To the maximum extent permitted by applicable law, SkillsLLM is not liable for losses arising from third-party software.
Automated security scan — not a certification.
一本 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 也照样能用，色板算法有一份可以手工执行的说明。
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 里解析。就这一条约定，它就不会闷声给你塞一堆靛蓝。.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 动样式表，这本书的判断力都在场。