安装与开始使用
00. 开始前
- Git，用于安装和更新完整目录。
- Node.js 22 或以上，随附的预览、快照和质量检查脚本需要它。
- 一个能读写文件、执行命令的本地 Agent：Codex、Claude Code 或其他。
- 一个真实项目目录。空目录也可以，会生成独立 HTML。
01. 安装完整技能目录
在本机终端执行。仅复制 SKILL.md 不够，还需保留 skills、scripts 和 references 等目录。如果目标目录已经存在，不要再次克隆覆盖，先查看目录内容。
Codex
git clone https://github.com/YuqingNicole/variant-design-skill.git ~/.codex/skills/variant-design如果你自定义了 Codex 的技能目录，换成自己的路径。也可以在项目目录里运行 npx skills add YuqingNicole/variant-design-skill -a codex，只装到这个项目。安装后重新打开 Codex 会话。
Claude Code
git clone https://github.com/YuqingNicole/variant-design-skill.git ~/.claude/skills/variant-design项目级安装可改为项目内的 .claude/skills/variant-design，或者在项目目录里运行 npx skills add YuqingNicole/variant-design-skill -a claude-code。也可以作为插件安装：claude plugin marketplace add YuqingNicole/variant-design-skill，再运行 claude plugin install variant-design@variant-design（已在 Claude Code 2.1.316 上验证）。安装后重新启动 Claude Code 会话。
DeepSeek Harness
git clone https://github.com/YuqingNicole/variant-design-skill.git ~/.agents/skills/variant-designDeepSeek Harness（dsh）读取 ~/.agents/skills 和项目里的 .agents/skills，与 Codex 和 npx skills 用同一个文件夹，所以在项目目录里运行 npx skills add YuqingNicole/variant-design-skill -a codex 也能装到这个项目（已在 dsh 0.2.0-rc.2 上验证）。安装后新开一个会话。
其他 Agent
git clone https://github.com/YuqingNicole/variant-design-skill.git ~/variant-design克隆到任意位置，再让 Agent 读取入口的绝对路径（例如 ~/variant-design/SKILL.md）。Hermes/OpenClaw 在 AGENTS.md 中指向这个入口，不要粘贴入口文本。
确认安装成功
先检查 Node 版本和已安装的技能版本：
node --version # 需要 v22 或以上
cat ~/.codex/skills/variant-design/VERSIONnode --version # 需要 v22 或以上
cat ~/.claude/skills/variant-design/VERSIONnode --version # 需要 v22 或以上
cat ~/.agents/skills/variant-design/VERSIONnode --version # 需要 v22 或以上
cat ~/variant-design/VERSION然后在项目中新开会话，发送下面这句。Agent 能复述项目的页面范围和约束，就说明技能已被发现：
用 Variant Design 只读检查当前项目：复述页面范围、核心任务和品牌约束，先不要生成。02. 在真实项目里开始
在 Agent 中打开你的代码项目，粘贴下面的指令。首次尝试可从一个页面或 hero 区域开始。模型由你的 Agent 提供；本网站不会自动修改你的项目。
使用完整 Variant Design 技能。在当前项目中先检查页面结构和设计系统，再生成保留核心任务的 A/B/C 三个设计方向。已有品牌保持字体与 tokens；没有品牌约束时探索三种鲜明风格。打开三版预览，说明优化、取舍与适用场景，并给出有理由的推荐，但先不要替我选定最终方案。你会得到
- A/B/C 三个完整版本，共享相同的核心任务、数据和必要功能。
- 比较页与每版独立的预览地址。没有浏览器工具时，Agent 会返回准确地址。
- 每版优化什么、牺牲什么、适合什么场景，以及有理由的推荐，但不替你选定。交付前 Agent 会运行 delivery-check.mjs 核对这些记录，以及品牌锁定的字体和颜色有没有被改。
- 产物写入项目的 variant-output/。React 项目输出 .tsx，其他情况输出零依赖 HTML。
03. 比较、试改、撤回
比较页先展示预览，方案说明可展开查看。试改一版不等于选定它。下面的简写可以直接发给 Agent，也可以用自然语言描述同样的意图。
compare- 重新打开三版比较页。
open B- 在浏览器中重新打开 B。
B vary subtle — hero- 只精修 B 的 hero。先保存快照，其他区域和品牌 tokens 不变，也不会选定 B。
B vary strong- 把 B 的方向推到极致。
B remix colors- 为 B 生成三组替代色板。
C → mobile- 查看 C 的移动端视图。
Mix A + B- 合并两版，并说明冲突时的取舍。
undo B- 恢复 B 上一次的文件和 tokens。A/C 与最终选择不受影响。
show context- 查看当前记住的色板、字体、方向与版本。
04. 选定并接入项目
pick B- 把 B 记为最终方案，再从 B 提炼出完整的设计系统：色板、字体层级、间距、圆角、阴影、动效，以及 B 用到的每个组件的全部状态，并写明使用规则（DESIGN.md）。确认（ds confirm）后，之后的页面都用它，并导出可导入 Figma 变量的 DTCG 令牌文件。修改与选定分开记录。
react B- 把 B 导出为 React .tsx 组件。
tokens B- 把 B 的设计令牌导出为 CSS 变量。
设计系统检查会列出已检查的颜色配对、失败和未验证项，并检查组件 token 的引用层级。品牌文件保留自己的命名。静态检查不能代替实际页面验收；导出的令牌文件会列出无法表达的值。确认系统保留原页面，明确应用时才一起对齐代码和 token；撤回会同时恢复。产物验证会自动记录注册系统主文件、扩展及应用状态；变化后旧证据失效，其他共享依赖仍需列明。接入前的基准同样绑定扩展与应用状态，旧计划缺少覆盖时需重新准备。
选定后，用下面的指令接入：
把 B 接入项目。生成接入文件前先准备源稿与目标文件基准，覆盖前先备份，运行现有类型检查与构建，返回可打开的预览地址，并列出改动的文件和撤回方式。接入完成时，确认 Agent 交代了
- 改动了哪些文件，代码在哪里。
- 怎么运行，预览地址是什么。
- 撤回命令。技能会把接入前的文件备份在 variant-output/.integrations/，你之后手动改过的文件不会被撤回覆盖。
- 实际跑过哪些检查（类型检查、构建、测试），结果如何。记录绑定产物版本；浏览器检查可复用指定元素与交互的检查计划。没跑过的要明确说没跑。
05. 不只是三版生成
同一个技能还能评审、审计已有站点和制作组件：
ux review- 对当前设计做启发式可用性评估，按严重程度列问题。
accessibility- 检查 WCAG 2.1 AA、键盘导航与对比度。
audit- 扫描已有站点，输出风格一致性报告。
tokens- 从现有 CSS 中提取设计令牌。
new page pricing- 按现有设计系统新增 /pricing 页面。
设计一个带校验的注册表单组件- 生成符合项目风格、状态完整的组件。
常见问题
为什么没有出现技能？
确认完整目录已安装到当前 Agent 使用的技能路径，再开启新会话；也可以在指令中直接提供 SKILL.md 的绝对路径。
提示 Node 版本不够怎么办？
随附脚本需要 Node.js 22 或以上，升级后重开会话。缺少 Node 时 Agent 仍可给出候选设计，但应说明快照和预览验证没有运行。
预览打不开怎么办？
Codex 等沙箱环境常常不允许启动本地服务。这时技能会生成可直接双击打开的静态预览（variant-output/_static/），没有 Vite 时，可为独立客户端组件使用隔离预览工具包；Next 原生功能仍可能需要服务器。你也可以在自己的终端运行 Agent 给出的预览命令。其他情况下，让 Agent 检查依赖、预览路由和端口，并确认三版页面都能打开。
会话中断了，能接着做吗？
可以。技能会读取项目里的 variant-output/.variant-context.json，恢复色板、字体、方向与版本。用 show context 查看，用 reset context 从头开始。
怎么更新？
Git 克隆安装：执行 git -C <安装路径> pull --ff-only。用 npx skills 安装：执行 npx skills update variant-design。也可以对 Agent 说“检查 Variant Design 更新”，它最多每 24 小时检查一次，只提示，不会自动更新。
卸载会删掉我的设计吗？
不会。设计、历史和快照都在项目自己的 variant-output/ 里，删除技能目录不影响它们。reset context 只删除 .variant-context.json。
已经上架插件市场了吗？
尚未上架。当前可安装完整开源技能；仓库提供插件候选包与发布验证说明。