更新记录

网站

• 网站包 0.2.3：打开来自 X 的灵感帖子时，X 的嵌入内容到达后页面不再整体移动。手机上嵌入内容排在说明下面而不是上面，先显示的存档正文和嵌入内容在同一帧里替换，桌面上弹层改为靠近顶部对齐而不是居中，所以嵌入内容变高时弹层向下增长。实验室现在用一个来得晚、又很高的嵌入内容代替 X 的脚本；这次改动前，手机上首页的版面位移测得 0.35，桌面 0.18，改动后不超过 0.01。生产环境在改动前测得手机上 /browse/interaction 为 0.16，改动后为 0.06。同一次生产测量里桌面端首页仍是 0.36：真实的嵌入内容约 1,270px 高（含被引用的帖子），把「访问原站」按钮和加载提示推了下去。现在这两项在所有宽度下都排在帖子上方，并有桌面端测试覆盖；桌面端的生产数字还没有重测。站点地址改为 https://variantdesign.xyz（canonical 链接、站点地图、订阅源、llms.txt、方向卡），原来的 variant-design-skill.vercel.app 仍指向同一个站点。

技能可以作为 Claude Code 插件安装，在 pick B 之后推导并检查设计系统，并为生成页面的动效增加规则。网站的每个灵感分类都有自己的页面，并且会测量自己的首屏速度。

网站

• 网站包 0.1.1 新增中英双语的编辑式页脚，可直接返回灵感流；更新记录页也会标出当前技能版本。
• 网站包 0.2.0：灵感的每个分类都有自己的页面（/browse/web、/browse/interface、/browse/interaction、/browse/motion、/browse/branding 和 /en/browse/...），有各自的标题、描述和预渲染的列表。一条参考只属于一个分类，所以 tab 之间不会重复；首页仍是完整列表。暂时没有参考的分类（插画、海报、印刷）在收录第一条后才出现 tab。旧的 ?category= 链接会改写到新地址。
• 手机上：六个分类 tab 排成一行横向滚动，当前 tab 在可见范围内，筛选栏不再一直盖在列表上。指针、手指或键盘焦点一碰到 tab 链接，就开始预取对应页面。
• 动效：页面之间切换时淡入淡出（开启减少动效时不启用）。信息流卡片悬停放大从 360ms 缩到 200ms，搜索框改为固定宽度，不再做展开动画；案例卡片和首页按钮的悬停位移只在能悬停的设备上生效。生成的参考指令面板会上移出现。收藏按钮用颜色填充和按下反馈代替会重播的弹跳，导航 tab 悬停不再上移。减少动效时，页面保留透明度和颜色反馈，弹层仍然淡入；实验室的预览框不再动画布局。
• 可发现性：feed.xml 现在同时列出参考和方向案例，sitemap.xml 为每个有记录日期的页面带上 lastmod，没有对应页面的路径返回真正的 404（404.html，带 noindex），不再用状态码 200 显示首页。只在浏览器里运行的路由（/lab/canvas、/lab/workbench、/directions、/showcase）不变。
• 网站包 0.2.1：灵感详情页和卡片弹层在预览图到达时不再整页跳动；实验室测得的版面位移，手机上从 0.138 降到 0，桌面从 0.084 降到 0.0005。新增的实验室预算用例把版面位移限制在 0.1 以内，并限制首页的脚本和样式体积。
• 网站包 0.2.2：所有公开页面的键盘焦点环现在是同一种品牌绿、2px。此前导航、页脚、案例、技能、指南、更新记录、关于和实验室页面用的是写死的蓝色。新增的用例在中英文共 16 个页面上逐个 Tab，检查焦点环的颜色、宽度，以及与背景至少 3:1 的对比度；这只检查焦点环，不是 WCAG 合规结论。

安装

• Claude Code 插件市场：先运行 claude plugin marketplace add YuqingNicole/variant-design-skill，再运行 claude plugin install variant-design@variant-design。用这种方式安装时，更新检查会给出插件的更新命令。
• 子流程文件从 SKILL.md 改名为 skills/*/ROUTE.md，所以 Claude Code 插件、Codex 和 npx skills 都只会把入口注册为技能。
• DeepSeek Harness（dsh）会在 ~/.agents/skills/variant-design 或项目的 .agents/skills 里找到技能，也就是 npx skills add 使用的文件夹。

设计系统

• confirm-system 先备份上下文，再记录已确认的系统身份，不修改选中页面。明确执行 apply-system 时，把对齐后的代码、token 记录和应用状态存入同一快照；undo B 恢复此前状态。普通修改仍保留 token 锁，候选基准覆盖全部系统扩展。
• 对比度报告列出已检查配对和未验证项；生成系统用明确角色配对或底色注释，只有 --brand 文件沿用旧命名。组件 token 必须引用语义 token；产品代码引用其他组件 token 时会被报告。DTCG 新增可选的 --group-by layer，保留类型和跨层别名；有多个条件值时列为未导出，不再静默取其中一个。
• pick B 之后，技能从 B 提炼出完整的设计系统（variant-output/design-system.css，以及包含 B 用到的每个组件、每种状态的预览），然后等待 ds confirm。品牌文件已锁定时，只补品牌没规定的部分，并记入 designSystem.extensions。
• delivery-check 会读取这些扩展（重新定义品牌变量算错误），并对不在已确认系统刻度上的间距、字号、圆角给出警告，指出最接近的 token。从 B 提炼的系统只用来检查 B。
• ds confirm 会把系统导出为 DTCG 2025.10 设计令牌（scripts/ds-export.mjs → design-system.tokens.json），并列出 DTCG 表达不了的值，例如 clamp() 字号。
• 提炼出的系统附带 variant-output/DESIGN.md：写给 agent 和人的使用规则（哪个文字 token 用在哪种背景上、各级标题用哪一级字号、组件有哪些状态），段落顺序沿用 Google 的 DESIGN.md 草案。
• scripts/ds-check.mjs 检查系统自身的文字/背景色和 on-色组合是否达到 4.5:1：草稿在展示前修好，delivery-check 会报告已确认系统中不合格的组合。
• 设计系统现在由几条针对产品的决策和落实这些决策的 token 组成，不再是填满的模板（references/design-system/system-decisions.md）。技能写下三到五条决策；丢掉选中方向里的生成套路（眉标、口号式标题、装饰数字、处处套卡片、默认字体）；只写产品用得到的 token，并注明每个用在哪里。预览用产品自己的画面展示系统，不再是色板网格。
• 分层：产品代码用语义 token；复用且状态多的组件有组件 token；只有被共用时才写基础值；模式（移除确认、空状态）写进 DESIGN.md。ds-check.mjs --used-by 列出没被用到的 token；产品代码直接用基础值时 delivery-check 会警告；ds-export 把每个 token 的用途说明导出为 DTCG 的 $description。
• 按钮遵循一份规范，参照 Material 3、Apple HIG、Radix、Primer、Atlassian、Polaris 和 Geist 的公开文档制定（references/ux/component-specs.md → Button）：品牌是衬线体时，按钮文字也用界面无衬线字体；内边距和圆角随高度按比例取值；每个视图只有一个实心主按钮；悬停和按下状态用 color-mix 推导，焦点是单层 2px 的环；危险按钮在确认框之前都只是红字。预览里放真实按钮，不放一排假的悬停状态。
• 生成的方向避开生成套路（references/workflow/quality-baseline.md → Generator habits）：已有页面保持原来的作用、标题和文案，产品页上不放口号和宣传卡片；三个方向先在结构上不同，再谈风格，只换配色不算一个方向。quality-gate 把眉标、补零的装饰数字、界面里的方向名列为 review 项，要求删掉或说明理由；它们不会让 --strict 失败。
• 动效参考：新增 references/design-system/motion-rules.md，按用户遇到这个元素的频率决定要不要动效，界面动效保持在 300ms 内，并覆盖按下反馈、变换原点、可中途反转的过渡、只在能悬停的设备上做悬停动效，以及保留透明度和颜色反馈的减少动效。生成路径会和 motion-design.md 一起加载它。micro-interactions.md 不再示范 transition: all、带弹跳的开关，以及没有频率说明的悬停动效；style-audit.md 把 transition: all 当作要报告的问题，不再当成惯例。
• quality-gate.mjs 不再因 padStart(2, "0") 报 decorative-number，前提是文件里读取了日期或时间的部分（getMonth()、getHours()、toISOString()、Intl.DateTimeFormat）：这种补零是在格式化 2026-03-07 或 09:05，不是装饰性计数。给步骤编号补零，以及 >04< 这样的标记，仍会被报出。

品牌锁定

• 品牌由项目自己的文件规定时（例如 app/globals.css），技能直接登记这个文件，不再把副本锁定在 variant-output/ 里。

技能现在可以在已有项目里从检查一路做到接入，并且每一步都保护用户自己的改动。

结合项目的流程

• 生成前先只读检查项目（scripts/project-profile.mjs），任务说明和检查结果绑定，并记录运行时的观察（scripts/design-task.mjs）。
• 任务说明里记录设计参考及其复用条款。Variant Design 方向库的方向卡可以转成这种记录（scripts/direction-card.mjs）。
• 展示 A/B/C 之前做交付检查（scripts/delivery-check.mjs）：三个已登记的方向取舍各不相同，共享同一份任务约定，推荐不等于选定，设计系统锁定没有被破坏。

安全修改和接入

• 候选版本带内容基准；过期的候选版本和区域外的改动会被拒绝（variant-history.mjs prepare / apply）。
• 一次请求就是一次撤回，即使它分了几次 apply。
• variant-integrate.mjs 在接入方向前备份每个目标文件；文件之后被改过，就拒绝回滚。
• 产物验证绑定版本，记录哪些检查针对哪个版本运行过。

预览

• React 预览用项目自己的 Vite 挂载；react-preview.mjs --static 生成不需要服务器就能打开的预览，供沙箱里的 Agent 使用。
• 修复静态预览的一个问题：打包代码里含有 $&、$$ 或 $` 时内容会被破坏。

技能文字

• 按阶段加载。入口只有路由表和共用规则；生成流程开头是一张加载表。变体动作、区域修改、历史、预览、导出和接入分成不同文件，用到那一步才读。code-output.md 不再每次都强制加载交互模式库。
• 参考文件按用途分组：workflow/、sources/、domains/、design-system/、ux/、tasks/。
• 质量检查跳过生成的预览包（_static/、_preview/），所以可以用严格模式扫描整个 variant-output/。
• 从领域参考里删掉了转录的第三方“社区示例”。
• 只有根目录的 SKILL.md 声明技能，Codex 和 npx skills 不再把子流程注册成无法使用的独立技能。
• 组件交接说明和网页界面检查。

安装

• npx skills add YuqingNicole/variant-design-skill -a claude-code -a codex 安装完整技能。

给贡献者

升级：Git 克隆安装运行 git -C <install path> pull --ff-only，或者运行 npx skills update variant-design。对没有 .git 的安装，更新检查现在会给出 npx skills 命令。升级不会改动 variant-output/ 里的项目文件；上下文结构仍是 v2。

• evals/run.mjs 在示例项目上用 Claude Code 和 Codex 运行当前工作区的技能，并自动评分。
• scripts/skill-links.test.mjs 检查技能提到的每个文件都存在，每个参考文件都能从入口找到。