本文由 莫潇羽@无忆研习社（www.wuyi.wiki）撰写，转载请注明出处。
快速摘要（三分钟看完全文精华）
如果你只想要一句话结论：SkillUI 是一个纯静态分析的开源命令行工具，可以把任意网站、Git 仓库或者本地项目的完整设计系统——颜色、字体、间距、圆角、阴影、动画、组件结构——一次性逆向出来，打包成 Claude Code 能自动读取的 Skill 文件夹，让 AI 写出的前端页面不再是那种"Inter 字体 + 紫蓝渐变 + 卡片套卡片"的模板脸。
几个核心事实抓一抓：
- 它不调 AI，也不吃 API Key，颜色和字体是逐行解析 HTML 与 CSS 抠出来的，精确到像素级，可复现，可离线跑。
- 四种输入方式：
--url扒线上站点，--dir扫本地项目，--repo克隆并分析开源仓库，加--mode ultra还能开 Playwright 拉滚动截图和交互差异。 - 输出的不是一份 PDF 报告，而是一整套
SKILL.md / CLAUDE.md / DESIGN.md / tokens/*.json / references/*.md，直接扔给 Claude Code，AI 一进目录就自动读上下文。 - 本质上是给大模型注入"具体设计参考"，破解那个学术上叫"分布收敛"（distributional convergence）的通病——AI 缺乏具体参考时，只会从训练数据里最平均的样本里采样，于是家家网站都长一个样。
- 准入门槛：Node.js 18 以上，
npm install -g skillui一句话装完，Ultra 模式再加装 Playwright + Chromium 即可，全流程在本地跑，不用担心把设计稿传去哪里。 - 写稿时（2026 年）该项目已经迭代到 1.3.x 版本，GitHub Star 破千并持续上涨，被 Trending 榜单点名，属于典型的"社区爆款小工具"。
想看完整拆解，往下翻。下面这篇我会把它的原理、四种模式、输出结构、安装步骤、真实工作流、和 Claude Code 联动的方式，以及国内环境下的合规注意事项，逐个讲透。
一、AI 生成的界面为什么越来越"塑料味"：先聊清楚分布收敛这件事
先说个我自己反复踩过的坑。
我做过一段时间的 AI 辅助前端实验：给不同的大模型抛同一句"帮我写一个 SaaS 落地页"，然后把返回的 HTML 一个个渲染出来对比。神奇的事情发生了——不管是哪家模型，输出的页面几乎都长着同一张脸。字体清一色 Inter，主色不是紫蓝渐变就是蓝紫渐变，Hero 区永远居中大标题加副标题，下面标配三列 Feature 卡片，每张卡片顶部一个圆角小方块图标。翻十个页面，说是同一个模板生成的，我都信。
这不是错觉，也不是模型菜。它有一个正儿八经的学术名字，叫"分布收敛（Distributional Convergence）"，中文语境里也有人翻成"分布坍缩"。 Anthropic 官方在讲前端设计的技术博客里正面回应过这件事。
原理其实非常朴素。
大模型的本质是根据前文预测下一个 token 的概率分布。给它一个模糊的指令"写个落地页"，它没有具体的设计参考，就会在训练数据里那些"最不会出错"的选择里采样。而恰好过去几年整个前端生态里最普及的默认配置——Tailwind 早期默认的 indigo-500、Google Fonts 榜单第一的 Inter、SaaS 圈流行的卡片布局——在训练语料里出现的频率最高。统计意义上最"安全"的答案，就是最"平庸"的答案。
有人打了个比方我觉得挺贴切：AI 的审美分布，就像一个大正态分布。给它模糊指令，输出永远趋近于那个"均值 μ"，很难跑到长尾里去做出真正有个性的东西。你要它做出乔布斯风、Nothing 那种冷硬极简、或者 Linear 的高级性冷淡，光靠 prompt 反复描述"要高级""要有质感""要独特"是没用的——你越形容抽象，它越往中心塌。
这就带出了破局思路：给 AI 一个具体的、可测量的、结构化的设计参考。
以前大家怎么解决这个问题？我自己至少试过三条路，每条都别扭：
第一条路，是打开 DevTools 手抄。 我曾经很虔诚地干过——想模仿 Linear 的一个组件风格，就右键"检查"，把主色、次色、hover 色一个个复制到本子里，再量圆角、量间距、量字号字重，把 CSS 变量翻个底朝天。半小时抄一个组件下来，人已经不想写代码了。而且抄下来的是零散的十六进制色值，扔给 AI 它还是不知道该怎么组合使用。
第二条路，是截图给多模态模型认。 现在 GPT、Gemini、Claude 都支持看图，直觉上"上传截图让 AI 看着抄"应该行得通。实测下来它能抓个大概气质，但具体的色值、字号、间距全靠猜。同一张截图今天说主色是 #4F46E5，明天说是 #5B4FEE，模型每次生成的结果都在漂移，做不到工程可复现。
第三条路，是找现成的 Figma 设计规范。 前提是人家愿意公开、你还得会用 Figma 插件把 tokens 导出来。对没有设计背景的独立开发者，这条路基本走不通。
三条路都不好走，问题的根源是同一个——设计系统这种东西，本质上是"结构化的知识"，而人类过去处理它的方式是"零散的截图 + 一堆散装数值"，这种粒度的信息喂给 AI，AI 当然做不出精准复刻。
SkillUI 出现之前，"把一个网站的设计系统整体、结构化、无损地喂给 AI"这件事，几乎没有对普通开发者友好的解法。莫潇羽@无忆研习社 自己折腾这件事折腾了很久，直到看到这个项目才觉得思路对上了。
二、SkillUI 到底是什么：一句话说清它解决了什么问题
先把定位说清楚——SkillUI 不是又一个"AI 帮你生成设计系统"的工具，它反过来，是一个"帮你从现成设计系统里把数据搬出来"的搬运工。
它做的事情非常聚焦：给它一个网址、一个本地目录、或者一个开源 Git 仓库地址，它就用纯静态分析的方式，把里面藏在 CSS 变量、Tailwind 配置、内联样式、DOM 结构里的每一个设计 Token——颜色、字体栈、字号、字重、间距、圆角、阴影、动画关键帧——逐行解析出来，然后按照 Claude Code 认得的 Skill 格式打包成一个文件夹。
作者是海外开发者 Amaan（GitHub 账号 amaancoderx），项目在 npm 上叫 skillui，主仓库地址是 github.com/amaancoderx/npxskillui（作者另有一个 amaancoderx/skillui 同名镜像仓库）。写这篇稿子时项目已经迭代到 1.3.x 版本，两天连发 23 个 release，社区反馈热度非常高。这种迭代节奏一方面说明作者很勤，另一方面也提醒我们后面版本可能还会有小调整，命令细节请以官方 README 的实时口径为准。
它最反潮流的一个技术决定，是这条工具链里完全不接入任何大模型——不请求 OpenAI，也不请求 Anthropic，不需要你配 API Key，不用联网调远程服务。所有分析都是在本地 Node 进程里跑完的。这带来几个非常实在的好处：
第一是确定性。今天你扒 Notion 的设计系统，明天再扒一遍，输出的颜色列表、字号阶梯、间距数组一模一样。不像 Vision 模型"看图猜色"每次输出都不一样。
第二是成本可控。零 API Key，就意味着零 token 费用。扒十个网站和扒一百个网站，账单一样都是零。
第三是可离线跑。所有代码、CSS、字体资源都是拉到本地解析的，不会把你的目标 URL、本地代码泄露给第三方模型服务。做设计审计、做企业内部规范整理特别友好。
第四是结果精准。它抠出来的是页面实际使用的值，不是它猜出来的值——CSS 里写的是 #0066FF，输出里就是 #0066FF，不会四舍五入成 #0060FF。
那这套工具做出来的产出到底怎么用？核心用户是 Claude Code。 这里先剧透一下工作流，后面章节会展开：你运行完 skillui --url https://notion.so，会得到一个 notion-design/ 文件夹，cd 进去打开 Claude Code，直接说一句"帮我做一个匹配这个设计系统的 SaaS 落地页"，Claude 会自动读文件夹里的 SKILL.md 和 CLAUDE.md，把整套设计上下文吸进大脑里，然后按 Notion 的配色、字体、间距、动画规格生成代码。整个过程你不用再手把手把颜色喂给它。
从更宏观的角度讲，SkillUI 其实是在设计世界和 AI 编码世界之间架了一座桥。设计端负责产出真实的、能用的视觉资产（网页也好、组件库也好），SkillUI 负责把这些资产转译成 AI 认得的结构化上下文，AI 拿到上下文再回过头去生成有品牌辨识度的代码。三个环节各司其职，比任何一端硬扛都稳。
社区里已经出现了一些类似思路的项目，比如 arvindrk/extract-design-system、Manavarya09/design-extract 等，都是把网站设计系统结构化提取给 AI 编程助手用。SkillUI 的差异化点在于它的输出格式是围绕 Claude Code 的 Skill 机制原生设计的，一步到位，不需要你再写 glue code。当然如果你用的是 Cursor、Codex CLI 之类的其他 AI 编程工具，同一份 DESIGN.md 稍微改一下也能通用——莫潇羽@无忆研习社 后面章节会讲怎么迁移。
三、前置概念补课：先把 Design Tokens 和 Claude Code Skills 搞明白
要真正吃透 SkillUI 在干什么，得先把两个基础概念说清楚。这两个概念一个来自设计圈，一个来自 AI 编程圈，SkillUI 恰好是站在它们的交汇点上。
3.1 Design Tokens 是什么：设计系统里的"原子"
Design Tokens（中文常译作"设计令牌"或"设计标记"）是设计系统里的最小可复用单元。你可以把它想象成"设计版的 CSS 变量"——一个 Token 就是一个具名的设计决策。
举个例子。假设你在做一款 App，主品牌色是 #3B82F6。传统做法是每次用到这个色的时候，都在代码里硬写 color: #3B82F6;。这样做的问题是，哪天品牌想微调一下颜色，你得全项目搜索这个色值一处处改。而如果引入 Design Token 的思路，你会先在一个中心文件里定义：
{
"color": {
"brand": {
"primary": { "value": "#3B82F6" }
}
}
}然后在组件里引用它的名字：color: var(--color-brand-primary);。之后不管这颜色改成什么，你只需要动 Token 定义那一处，全应用同步生效。
Token 的意义远不止"方便改色"。它还建立起了一套设计和开发共享的语言——设计师说"这里用 color-button-primary-hover"，前端就知道该引用哪个变量；反过来前端改了 Token 定义，设计稿里也能自动同步。行业里把这套体系推到成熟形态的，就是所谓的设计系统（Design System），Google 的 Material Design、Ant Design、Shopify 的 Polaris 都是典型代表。
一套成熟的 Design Tokens 通常会分几层组织：
┌─────────────────────────────────────────────────┐
│ 语义层（Semantic） → color-button-primary │ ← 组件直接用
├─────────────────────────────────────────────────┤
│ 别名层（Alias） → color-brand-500 │ ← 中间抽象
├─────────────────────────────────────────────────┤
│ 基础层（Primitive） → color-blue-500 = #3B82F6 │ ← 原子色值
└─────────────────────────────────────────────────┘底层是纯粹的色值、字号、间距数字；中间层给它们语义化的别名；顶层是绑定到具体组件角色的引用。SkillUI 干的事情，就是把一个网站里散落在各种 CSS 文件、内联样式、Tailwind 配置里的这三层 Token 反向识别出来，重新组织成标准化的 JSON 文件。
有一点新手需要留意：不是每个 CSS 变量都值得成为 Token。只出现一次的临时补丁不该被识别成 Token，否则只会制造噪声。SkillUI 内部用了一套频次和位置权重的启发式规则，只把真正被多处复用、承担设计决策的变量抠出来——这也是它比"随手写个 CSS 变量扫描器"要精细的地方。
3.2 Claude Code Skills 是什么：给 AI 编程助手打专业培训班
再讲 Claude Code Skills。
Claude Code 是 Anthropic 官方推出的命令行 AI 编程助手，你在终端里输入 claude，就能进入一个对话式的编程环境，让 AI 直接读你的项目、改文件、跑测试。它默认已经很强，但作为一个"通才工程师"，它对具体某个领域的最佳实践、某个团队的编码规范、某个品牌的设计语言，是没有先验知识的。
Skills 就是给 Claude Code 打的"专业培训班"。 每个 Skill 是一个文件夹，核心是一份 SKILL.md，里面用 Markdown 告诉 Claude：在什么场景下应该调用这个 Skill、按什么步骤执行、有哪些约束、要产出什么格式。Skill 里还可以附带脚本、模板、参考资料，一起打包成一个可复用单元。
举几个 Skill 的实际例子帮你建立感觉：
docxSkill：告诉 Claude 怎么用 Python 生成规范的 Word 文档；pdfSkill：教它读取 PDF、填充表单、合并拆分；frontend-designSkill：Anthropic 官方出品，注入一套激进的前端设计哲学，强制 AI 用不对称布局、大留白、高质感动效，专治千篇一律的 AI slop；- 你自己写的
blog-rewriterSkill：告诉 Claude 该怎么把学习笔记改写成博文（比如我上传给它的这份）。
Skills 有两个关键机制：一个是自动触发，Claude 会根据用户请求和 Skill 里 description 字段的语义描述，自动判断要不要加载这个 Skill，不需要你手动 /skill xxx；另一个是渐进式加载，系统启动时只预加载所有 Skill 的名字和描述，只有真正需要用的时候才把完整内容读进上下文，节省 token。
从 2025 年 12 月 Anthropic 把 Skills 定为开放标准之后，Cursor、Codex CLI、Gemini CLI 等一批 AI 编程工具也在陆续兼容同一份 Skill 文件夹格式。也就是说你今天用 SkillUI 生成的 Skill 包，未来大概率能跨 AI 编程助手复用，这是一个属于工具链层面的红利。
理解了这两个概念，再回头看 SkillUI 就特别清楚了——它的输入是一个网站（背后是一整套 Design Tokens），输出是一个 Claude Code Skill 文件夹（把这套 Tokens 用 Skill 格式打包给 AI）。它是设计系统和 AI 编程之间的一个精准转译器，中间没有任何"猜"的成分。
四、SkillUI 的四种工作模式：URL、Ultra、Dir、Repo 逐个拆解
SkillUI 一共提供四种输入方式，覆盖了"看到喜欢的线上网站想扒""想审计自己项目的设计系统""想研究开源仓库怎么做设计"三类需求。四种模式的命令行长得挺像，但内部走的分析管线差别不小。
4.1 URL 模式：扒任意线上网站
这是绝大多数人上手时用的模式。命令非常简单：
skillui --url https://linear.app --name "Linear"它内部会做这么几件事：
第一步，通过 HTTP 请求把目标页面的 HTML 拉下来，解析 DOM 结构。
第二步，找出 HTML 里引用的所有 CSS 文件（外链的、<style> 标签里的、<link> 里的），把它们一并拉下来。
第三步，逐行扫 CSS 里的 --变量名、@font-face 声明、@keyframes 关键帧、常用属性值。同时统计每个色值、每个字号出现的频次，把高频的识别为设计 Token，低频的视为一次性用法丢掉。
第四步，识别页面用了哪些 Web Font（Google Fonts、字体巨匠、Adobe Fonts 等），把字体文件拉到本地打包（这样 Claude 在离线也能用）。
第五步，按 Claude Code Skill 的格式生成 SKILL.md、CLAUDE.md、DESIGN.md，把 Token 单独写到 tokens/*.json。
URL 模式的优势是轻量、快、不依赖浏览器，跑一次几秒到十几秒就完事。缺点是它拿不到运行时才生效的信息，比如 hover 后颜色的变化、JS 动画注入的样式、SPA 单页应用里靠 JS 才渲染出来的组件结构。要拿这些就得开 Ultra 模式。
4.2 Ultra 模式：连交互和动画一起扒下来
Ultra 模式是在 URL 模式基础上，追加了 Playwright 无头浏览器的深度分析。加一个参数就开：
skillui --url https://linear.app --mode ultra --screens 7--screens 7 表示滚动截图取 7 张（默认 5，上限 20）。Ultra 模式启动后，Playwright 会真的开一个 Chromium 实例，加载目标网页，然后干这些事：
滚动旅程截图：从页面顶部一路滚到底部，均匀取 N 张全屏截图。这不是简单的"截个首屏"，而是把整个页面的视觉节奏保留下来——Hero 区什么样、Feature 区块什么样、社会证明区块什么样、Footer 什么样，AI 拿到这些截图之后能理解页面的分层节奏。
交互状态差异：对页面里的关键元素（按钮、链接、卡片），自动触发 hover、focus 等状态，前后各截一次，diff 出交互时哪些样式发生了变化。比如按钮 hover 时背景色从 #3B82F6 变到 #2563EB、还叠加了一层阴影，这些细节会被结构化记录下来。
动画库指纹识别：扫全局 JS，检测有没有加载 GSAP、Lottie、Three.js、Framer Motion、AOS 等主流动画库。这一步特别关键——一个页面"看起来贵"的原因，往往不是配色多牛，而是滚动到某个位置时那个丝滑的入场动画。SkillUI 会把这些线索写到 references/ANIMATIONS.md 里，AI 生成代码时就知道该用什么库配合什么手感。
Flex/Grid 布局分析：把页面里的关键容器识别成布局模式（Flex 布局、Grid 布局、Absolute 定位），标出它们的 gap、column 数量、对齐方式，写到 references/LAYOUT.md。
DOM 组件指纹：把重复出现的 DOM 结构片段抽出来当作"组件指纹"，比如"这个网站的 Card 组件长这样：一个 div 里带一个 SVG 图标、一段标题文字、一段描述文字、一个 CTA 链接"，写到 references/COMPONENTS.md。
Ultra 模式的代价是速度慢、要额外装 Playwright 和 Chromium、对本地磁盘和内存有一定要求。但对追求高保真复刻的场景，它是唯一选择。
4.3 Dir 模式：扫本地项目
Dir 模式是给"想审计自己项目的设计系统"这类需求用的。指定一个本地目录，SkillUI 会递归扫描里面的 .css、.scss、.ts、.tsx、.js、.jsx 文件：
skillui --dir ./my-nextjs-app --name "MyApp"它会主动识别几种常见的设计 Token 载体：CSS 里的 :root 变量、Tailwind 配置文件（tailwind.config.js / .ts）里的 theme.extend、CSS-in-JS 里的 theme 对象、TypeScript 里的 tokens 常量。识别出来之后按同样的 Skill 格式打包。
我自己拿它扫过一个跑了两年的老项目，输出的 Token 报告特别有杀伤力——原来项目里有 27 种不同的灰色、14 种圆角值、还有几处硬编码的 #5A6C7D 从来没人写进变量。设计系统的熵（无序度）一目了然，接下来的重构方向就清楚了。
4.4 Repo 模式：克隆并分析远程仓库
Repo 模式是 Dir 模式的远程版。给一个公开的 Git 仓库地址，SkillUI 自动 clone 到临时目录，然后跑 Dir 模式的分析，跑完清理临时文件：
skillui --repo https://github.com/vercel/next.js --name "Next.js"这个模式特别适合研究开源项目的设计实现。比如你想了解 Vercel 官网、Shadcn UI、Cal.com 是怎么组织设计系统的，一条命令就能把它们的 tokens 全套抠出来供学习参考。
四种模式的选择逻辑，简单画个决策表：
|
需求 |
推荐模式 |
命令示例 |
|
想快速扒一个线上网站的配色和字体 |
URL 模式 |
|
|
追求高保真复刻，需要动画和交互细节 |
Ultra 模式 |
|
|
想审计自己本地项目的设计系统 |
Dir 模式 |
|
|
想研究一个 GitHub 开源项目的设计 |
Repo 模式 |
|
四种模式的共同产物都是同一套 Skill 文件夹结构，下一章会拆给你看。
五、扒出来的东西长什么样：输出目录结构逐个拆解
跑完一次 SkillUI 之后，输出目录长这个样子（以扒 Notion 为例）：
notion-design/
├── notion-design.skill # 打包好的 .skill ZIP 文件（内含全部内容）
├── SKILL.md # Skill 主入口，Claude 自动读取
├── CLAUDE.md # Claude Code 项目级上下文
├── DESIGN.md # 完整的设计系统文档
├── references/
│ ├── ANIMATIONS.md # 动画规格和 keyframes
│ ├── LAYOUT.md # 布局容器和栅格系统
│ ├── COMPONENTS.md # DOM 组件模式
│ ├── INTERACTIONS.md # Hover/Focus 状态差异
│ └── VISUAL_GUIDE.md # 所有截图按顺序嵌入的可视化指南
├── screens/
│ ├── scroll/ # 滚动旅程截图（Ultra 模式产出）
│ ├── pages/ # 整页截图（Ultra 模式产出）
│ └── sections/ # 区块截图（Ultra 模式产出）
├── tokens/
│ ├── colors.json # 颜色 Token
│ ├── spacing.json # 间距 Token
│ ├── typography.json # 字体 Token
│ ├── radius.json # 圆角 Token
│ └── shadows.json # 阴影 Token
└── fonts/ # 打包到本地的 Web Font 文件这个结构看起来文件不少，但每个文件都有非常明确的分工。莫潇羽@无忆研习社 逐个拆一下，你就能对着自己的输出文件对号入座。
5.1 SKILL.md：Claude 的入口地图
SKILL.md 是整个 Skill 包的入口。它的头部有一段 YAML frontmatter，里面写 Skill 的 name 和 description——这两个字段决定了 Claude 什么时候会自动加载这个 Skill。SkillUI 会根据你扒的目标网站自动填充，比如扒 Notion 之后 description 会写"用于生成匹配 Notion 视觉风格的前端页面"这类描述，触发关键词也会自动带上"Notion 风格"。
SKILL.md 的正文部分是一段简短的执行指南——告诉 Claude：看到"帮我做一个 XX 风格页面"这类请求时，读 CLAUDE.md 拿完整上下文，读 tokens/.json 拿具体色值，读 references/.md 拿组件和动画规格，然后再动手写代码。
5.2 CLAUDE.md：项目级的持续上下文
CLAUDE.md 是 Claude Code 官方约定的"项目自述文件"。只要项目根目录里有这个文件，Claude Code 每次打开都会自动把它读进上下文。SkillUI 生成的 CLAUDE.md 里通常会写清楚：这个项目是用来复刻某个网站设计系统的、主色是什么、字体是什么、常用组件模式有哪些、动画风格什么调调。
这份文件的好处是，你在一个会话里跟 Claude 反复对话时，它不会因为上下文过长把关键的设计约束忘掉——每次它都会通过 CLAUDE.md 复盘一次基线信息。
5.3 DESIGN.md：给人类看的完整设计文档
如果你希望人类阅读扒下来的设计系统，DESIGN.md 就是给你看的。它把颜色系统、字体系统、间距系统、圆角、阴影、动画规格全部按章节写成 Markdown，配上示例代码块。你可以直接把它当作设计规范文档提交给团队，也可以在项目 Wiki 里做参考。
举个 DESIGN.md 里典型的一节的样子：
## 色彩系统
### 主色（Brand）
- `--color-brand-500`: #3B82F6 — 主要操作按钮、链接
- `--color-brand-600`: #2563EB — Hover 态
- `--color-brand-700`: #1D4ED8 — Active 态
### 中性色（Neutral）
- `--color-gray-50`: #F9FAFB — 页面背景
- `--color-gray-100`: #F3F4F6 — 卡片背景
- `--color-gray-900`: #111827 — 正文文字这种粒度是"人和 AI 都能看懂"的。
5.4 tokens/*.json：给机器读的结构化数据
如果你希望用程序读取这套设计系统，tokens/ 目录下的 JSON 文件才是主战场。每个 JSON 都遵循业界比较通用的 Design Token 规范（大致遵循 W3C Design Tokens Community Group 的草案），格式类似这样：
{
"color": {
"brand": {
"500": { "value": "#3B82F6", "type": "color" },
"600": { "value": "#2563EB", "type": "color" }
}
}
}这种结构化数据可以直接被 Style Dictionary、Theo、Tokens Studio 之类的工具消费，转成 CSS 变量、Tailwind 配置、iOS/Android 原生代码等各种目标格式。也就是说 SkillUI 的输出不仅能给 Claude 用，还能顺势接入你现有的设计系统工具链。
5.5 references/*.md：给 AI 补齐"运行时"知识
references/ 目录里的四五份 Markdown 是 Ultra 模式的独门产物。它们弥补了纯 CSS 分析拿不到的运行时信息：
ANIMATIONS.md 会列出页面用了哪些 CSS @keyframes、检测到哪些第三方动画库、每个动画大致的时长和缓动函数是什么。Claude 拿到这份文件就知道要不要 import gsap、动画的 easing 应该用 cubic-bezier(0.4, 0, 0.2, 1) 还是 ease-out。
LAYOUT.md 描述页面的布局骨架——最外层容器多宽、最大宽度限制、栅格是 12 列还是 8 列、常用的 gap 值是多少。这些是 CSS 里能读到但不容易人肉总结的信息。
COMPONENTS.md 抽取重复出现的 DOM 结构，把它们归纳为"组件指纹"。比如识别出这个网站的 FeatureCard 组件的结构是"一个卡片容器包一个图标区域、一段标题、一段描述、一个链接"，Claude 复刻时就知道该按这个结构去搭。
INTERACTIONS.md 是所有 hover、focus 状态的前后差异列表。前面提到过，这是 Ultra 模式专门跑浏览器抓的。
5.6 .skill 文件：一键分享的打包版
最后那个 notion-design.skill 文件是把上面所有东西打成的一个 ZIP 包，专门方便分享给别人或者上传到 Skill 市场。别人拿到这个 .skill 文件，往自己的 ~/.claude/skills/ 目录一放，Claude Code 就能识别使用。SkillUI 相当于给你的设计系统输出了一份"可移植的成品"。
六、动手上手：安装 + 跑第一个例子
理论说了不少，动手才是硬道理。SkillUI 的门槛非常低。
6.1 环境要求
必需：
- Node.js 18 或以上版本；
- 一个能上 npm 的网络环境（首次安装拉包用）。
可选（用 Ultra 模式才需要）：
- Playwright 及其 Chromium 浏览器内核。
6.2 全局安装
打开终端，一条命令搞定：
npm install -g skillui装完之后跑一下 skillui --help，能看到帮助信息就说明装好了：
$ skillui --help
Usage: skillui [options]
Options:
--url <url> Crawl a live website
--dir <path> Scan a local project directory
--repo <url> Clone and scan a git repository
--mode ultra Enable cinematic extraction (requires Playwright)
--screens <n> Pages to crawl in ultra mode (default: 5, max: 20)
--out <path> Output directory (default: ./)
--name <string> Override the project name
--format design-md|skill|both Output format (default: both)
--no-skill Output DESIGN.md only, skip .skill packaging如果不希望全局装，也可以用 npx skillui --url https://xxx.com 临时跑，第一次会自动下载。
6.3 Ultra 模式的额外依赖
要用 --mode ultra，需要单独安装 Playwright 和 Chromium：
npm install playwright
npx playwright install chromium这一步会拉一个约 100 MB 左右的 Chromium 内核到本地。如果你之前装过 Playwright，直接跳过即可。
6.4 跑第一个例子
推荐第一次拿一个中等规模、设计感强的网站练手。比如：
# 基础模式，几秒跑完
skillui --url https://linear.app --name "Linear"
# Ultra 模式，一两分钟跑完
skillui --url https://linear.app --mode ultra --screens 7 --name "Linear"跑完之后当前目录下会出现一个 linear/ 文件夹（因为 --name "Linear"），打开 DESIGN.md 先扫一眼，你就能看到 Linear 那种"极简性冷淡"的整套色板、字体和圆角都被结构化地列在里面了。
小提示：某些网站对爬虫敏感或者用了强反爬手段，URL 模式可能会拿不到全部 CSS。这种时候优先用 Ultra 模式——Playwright 是真浏览器，反爬难度高得多。
6.5 常见报错和排查
莫潇羽@无忆研习社 自己上手时踩过几个小坑，帮你提前规避：
报错 1：command not found: skillui —— 全局安装没成功。多半是 npm 全局目录没在 PATH 里，或者用了 nvm 切了 Node 版本。跑一下 npm root -g，看看输出的路径是不是在 PATH 里。
报错 2：Ultra 模式提示找不到 chromium —— npx playwright install chromium 没跑或者跑失败。检查一下网络，Playwright 拉 Chromium 需要能访问它的 CDN。
报错 3：Windows 下路径有中文或空格 —— 用引号把路径包起来，skillui --dir "D:\我的项目\next-app"。
报错 4：目标网站超时 —— 加大超时时间目前需要改源码（后续版本可能会加参数），或者换用 Ultra 模式让浏览器帮你等页面加载完成。
七、四类典型实战场景：把 SkillUI 用出花来
装完不知道拿它做什么，是新工具最常见的死法。这一章挑四个我自己实测下来觉得最有价值的场景来展开。
7.1 场景一：快速复刻一个你欣赏的产品的视觉风格
这是最直接的用法。假设你打算做一款自己的 SaaS 产品，看了一圈觉得 Notion 那种"温和但克制"的风格挺合自己口味——但你既不想直接抄它的界面（那没意思也不合规），又想借鉴它的整体调调。
操作步骤：
skillui --url https://notion.so --mode ultra --screens 10 --name "Notion"
cd notion
claude进入 Claude Code 之后，直接说：
请参考当前项目里的设计系统（读 CLAUDE.md 和 SKILL.md），帮我用 Next.js + Tailwind 做一个 SaaS 落地页。产品是一款面向自由职业者的时间管理工具，主体功能是任务清单和时间统计。落地页要包含 Hero 区、三大核心功能介绍、三档定价卡片、以及 FAQ 折叠区。只借鉴视觉语言（颜色阶梯、字体、间距、圆角、动画感），不要照抄 Notion 的具体内容和排版结构。
Claude 会自动读 tokens 里的色值和字号，读 references 里的组件模式和动画规格，然后按自由职业者时间管理工具这个新主题独立生成结构。结果通常不再是"AI 味"的紫蓝渐变模板脸，而是带着 Notion 那种米白背景、深灰正文、暖调强调色的克制感。
这里有个非常关键的细节：你的 prompt 必须明确告诉 AI"借鉴视觉不抄结构"，否则它可能会顺手把 Notion 的 Hero 排版也搬过来。莫潇羽@无忆研习社 自己踩过这个坑——只说"参考 Notion 做落地页"，输出的页面 Hero 区跟 Notion 官网 layout 几乎一致，那就属于抄袭了，不合规。
7.2 场景二：审计和重构自己项目的设计系统
前面提过，Dir 模式对老项目审计特别有用。
假设你接手了一个跑了两三年的 Vue 或 React 项目，代码里到处是硬编码的色值、圆角、字号，从来没做过设计系统治理。你想在正式重构之前先摸清家底：
skillui --dir ./legacy-project --name "LegacyAudit"打开 DESIGN.md，你会得到一份触目惊心的报告——多少种灰色、多少种圆角、字号有多少级、有多少色值只出现过一次（一次性的"孤儿色"通常是需要清理的）。
拿到这份报告之后，你可以做几件事：
第一，把高频出现的色值确认为项目 Token，写到 :root 或 Tailwind 配置里。
第二，把只出现一两次的"孤儿色"评估一下——是设计师用错了？还是本来就该合并到某个已有色？
第三，基于 SkillUI 输出的 tokens/*.json，接入 Style Dictionary 之类的工具，生成一份可以给设计师用 Figma 变量、给 Web 用 CSS 变量、给 iOS/Android 用原生代码的多平台 Token 分发方案。
这套操作下来，等于免费拿到一份"设计系统体检报告"。
7.3 场景三：研究开源项目怎么组织设计系统
如果你是想学习"怎么做好一个设计系统"，Repo 模式是免费的教科书。
比如你想研究一下 Vercel、Shadcn UI、Cal.com 这些以设计著称的开源项目是怎么把 tokens 组织起来的：
skillui --repo https://github.com/vercel/next.js --name "NextJS"
skillui --repo https://github.com/shadcn-ui/ui --name "ShadcnUI"
skillui --repo https://github.com/calcom/cal.com --name "Cal"三条命令一跑，你会得到三份完全同构的分析报告。对着看它们的 Token 命名策略、层级划分、命名粒度——你会发现优秀项目在设计系统上的品味惊人地一致：语义化命名多、原始色值少；层级清晰、复用度高；命名短而准，不会出现 dark-blue-hover-active-focus 这种糟糕名字。这种横向对比得来的经验，比看十篇教程都实在。
7.4 场景四：给团队沉淀一份"竞品设计对比"文档
一个
