让 AI 帮你搭 Design System：三层 Token 架构详解

为什么你的 Design System 总是建着建着就烂了？

做过设计系统的团队，大概都踩过这几个坑：颜色 token 越加越多，最后命名乱七八糟；暗色模式写着写着发现和亮色根本对不上；换个产品线要全部重写，因为 token 名字里直接写了”blue-500″。

其实这些问题不是因为团队不行，而是设计系统的分层架构没搭对。Design System Patterns 这个 Skill，恰恰就是来治这个病的。

三层 Token 架构，才是正确答案

很多团队建 Design System，第一步就错了——直接往组件里填颜色值。这个 Skill 给出的是严格的三层结构：

• Primitive Tokens（原始值）：最底层，纯粹的数值。gray-50: #fafafa，蓝-500: #3b82f6。这层永远不变。
• Semantic Tokens（语义层）：给值赋予意义。text-primary 引用 gray-900，surface-default 引用 white。调性在这里定义，换主题只换这层。
• Component Tokens（组件层）：具体到按钮的圆角、卡片的边框。button-bg 引用 semantic 层的 interactive-primary，组件自己不再知道具体颜色值。

这样做最大的好处是——换品牌色的时候，你不需要改任何一个组件代码，只需要动 semantic 层。设计师给你一套新规范，你也能快速接入。

暗色模式不用写两套代码

传统的暗色模式实现方式是在组件里写条件：color: darkMode ? #111 : #fff。这不叫 Theming，这叫硬编码。

Design System Patterns 教你用 CSS Custom Properties 配合 React Context 做真正的主题切换：

• Theme Context 统一管理当前主题状态（light / dark / system）
• Semantic Tokens 通过 CSS 变量引用 primitive，主题切换时变量值整体切换
• System Preference Detection 自动检测用户是否开了 prefers-color-scheme
• Persistent Theme Storage 让用户偏好跨会话保存

一个组件，零条件判断，天然支持所有主题。

组件架构比 Token 还重要

这个 Skill 不只讲 Token，还覆盖了现代组件架构的核心模式：

• Compound Components：Select/Option 那种组合方式，父组件控制状态，子组件负责渲染
• Polymorphic Components：as=”button” 还是 as=”a” 不用你手动判断，一个 prop 全搞定
• Variant & Size Systems：告别 if/else 写死的 size，用 variant 映射表
• Slot-based Composition：让使用者往里塞自定义内容，但不影响整体样式

配合 Style Dictionary 做 Token 自动化

最有价值但最容易被忽略的部分：把 Figma 的设计变量直接同步到代码。

Style Dictionary 可以把一套 token 定义，转换成 CSS、iOS、Android、Flutter 多平台代码。设计师在 Figma 里改一个颜色值，CI/CD 自动触发，全平台代码同步更新。

这才是 Design System 真正该有的工作流。

谁应该用这个 Skill？

• 正在搭 Design System，但感觉越做越乱的团队
• 需要支持多品牌 / 多主题（暗色/亮色/品牌色）的产品
• 设计师和开发者协作时设计稿总对不上的情况
• 想建立 Figma-to-Code 自动化流水线的团队

老实说，很多团队觉得 Design System 难做，真正的问题不在于工具，而在于没有一套经过验证的架构思路。Design System Patterns 给你的是经过大量实践验证的分层方法论，装一个 Skill，省下的重构时间远比安装成本值钱。

GitHub 源码地址 →

GitHub: https://github.com/wshobson/agents/tree/main/plugins/ui-design/skills/design-system-patterns