规范与治理

设计体系最大的敌人不是「建不起来」，而是漂移：资源与代码各改各的，半年后规范说一套、线上跑另一套。swift-web 用三条纪律防止这件事。它们都不复杂，但需要设计与前端两侧共同遵守。

纪律一：调色只在语义 token 层

设计新网站 / 改版配色时，颜色调整必须落在语义 token上（--primary、--background……），不允许在稿子里散点取色。

• 在 Claude Design：让 AI「把主色换成 X」而不是逐个元素改色（见上手教程第 4 步）。
• 在 Figma：改 Variables 集合的值，元素颜色一律绑定变量而非写死色值。

为什么：散点色出不了合同——落地时前端无从判断「这 7 种相近的金色哪个是主色」，只能猜或归一，设计意图在翻译中损失；而 token 层的修改天然全稿一致、天然可交付。语义 token 覆盖不了的品牌特有色（VIP 金、等级色、支付渠道色），作为补充 token 在清单中显式列出（代码侧对应 --brand-* 命名空间），同样是命名的、可交付的——纪律约束的是「散点」，不是「色彩丰富度」。

纪律二：设计资源是派生物，不手工修改

swift-web 的设计资源（Claude Design 的 20 张卡片、Open Design 的设计系统资源包、Figma 的 Variables 与组件库）全部由框架源码自动派生。这意味着：

• 不要在 Claude Design 里直接编辑设计系统卡片、不要手工改 Open Design 资源包里的 DESIGN.md / tokens.css，也不要在 Figma 里手工改动资源库的 token 值——手工改动会在下次派生时被覆盖，且改动期间稿与码已经悄悄分叉。
• 对组件形态 / token 默认值有诉求（觉得某组件默认样式不合理、想加一个通用 token），提给框架维护者，走框架正常迭代：源码更新 → 资源自动重新派生 → 两条轨道同步拿到新版。设计师的意见会推动框架进化，只是路径经过代码这个「唯一事实源」。
• 用资源做设计不受任何限制——纪律约束的是「改资源本体」，不是「用资源出稿」。稿子里怎么组合、怎么覆盖 token 都是设计自由。

为什么：一份资源两处维护必然漂移，这是所有设计系统烂掉的头号死因。把「可信来源」收敛到框架源码一处，资源永远反映真实线上形态——这也是设计师敢放心照着卡片出稿的底气。

这条纪律还有一个自然推论：接入新设计工具 = 为流水线新增一个派生目标，核心资产不动。Open Design 就是这么接入的——框架源码不变，只是多了一种从源码生成的资源形态。将来出现下一个值得用的工具，同理：先问「它吃什么格式的设计系统」，再让流水线多产出一份，而不是为那个工具单独手工维护一套资源。

组织管理提示：Claude Design 的 Team / Enterprise 组织默认任何成员都能发布 / 修改设计系统；Enterprise 计划可通过 Claude Design Admin 权限把发布权收敛给指定成员，从机制上保证单一事实源。组织接入时建议一并配置。

纪律三：新品牌接入 = 一张 token 清单

为新品牌 / 新网站建立设计资源，输入只有一样东西：品牌 token 清单（设计师定稿的 token 值列表，产出方式见配色工作流）。

流程：

1. 设计师从底版设计系统起稿探索，在 token 层定出品牌配色；
2. 整理品牌 token 清单（15～25 项 + 可选的 --brand-* 补充项），连同定稿一起交付；
3. 框架维护者把清单喂给自动化流水线，一次生成：该品牌的 Claude Design 设计系统变体（后续该品牌的设计都基于它出稿）+ 代码侧品牌覆盖样式（项目 rebrand 落地）;
4. 之后该品牌的设计与代码共享同一组 token 值，任何一侧的调色需求都回到清单更新、重新派生。

为什么：把「接入一个品牌」压缩成单一输入 + 自动化输出，成本低到可以为每个项目都建专属资源——这是「所有项目共用一套通用资源、越用越对不上」的反面。

快速自查表

相关链接

• swift-web 设计语言 — token 体系与配色工作流全文
• 设计师与前端协作 — 交付物约定
• 样式与 Token — 代码侧的 token 与 --brand-* 机制
• 官方文档：Claude Design admin guide