swift-web 设计语言

无论你在 Figma 还是 Claude Design 里工作，用到的都是同一套设计语言。本页讲清楚它的三个组成部分：语义 token（颜色 / 圆角 / 阴影 / 字体的命名系统）、组件形态（框架提供哪些现成组件、长什么样）、以及给新网站配色的正确工作流。

语义 token：设计决策的命名系统

swift-web 的所有视觉决策都收敛为一组语义化命名的变量（业界通称 design token）。「语义化」的意思是：名字描述用途而不是色值——--primary 是「品牌主色」，而不是「蓝色」。换品牌时改的是变量的值，所有用到它的地方自动跟随。

设计师需要认识的核心 token（完整清单见样式与 Token）：

三个阅读要点：

1. *-foreground 配对。每个「底色」token 都有一个配对的「文字色」token（--primary ↔ --primary-foreground）。设计时保证每对的对比度达标，代码侧就永远不会出现「深底配深字」。
2. 明暗两套值。每个颜色 token 在亮色 / 暗色主题下各有一个值，切主题就是整组换值——设计稿如果需要暗色版本，改的同样只是 token 值。
3. 命名遵循业界惯例（Shadcn 风格）。用过主流设计系统的设计师和 AI 工具都能零成本读懂。

组件形态：20 张卡片的清单

设计资源目前固化为 20 张预览卡片（Claude Design 侧的设计系统即由它们构成；Figma 侧组件库以同一清单为蓝本建设）。每张卡片的 CSS 直接取自框架组件源码，卡片长什么样，线上组件就长什么样：

一个重要标注：部分卡片带有「参考实现（非框架内置）」字样——比如按钮的彩色 variant、表单字段的输入框视觉。这表示框架有意不内置这部分样式（留给业务自定义），卡片展示的是按语义 token 的推荐画法。设计师可以照用，也可以重设计——只要仍然落在 token 词汇表内。

这 20 张卡片的整宽实卡预览与逐卡说明（每张卡展示什么、设计时怎么用、出稿时怎么对 AI 点名）单独成页：设计卡片总览——设计前当形态字典翻一遍，比这里的清单表直观得多。资源包下载（Claude Design / Open Design 两种形态）也在那一页。

框架组件的完整能力（属性、事件、交互细节）见组件总览；设计师通常只需要认识形态，不必读 API。

给新网站配色：正确的工作流

这是设计师最常问的问题：「设计系统带的是默认色 / 某个现有品牌的色，我要设计一个全新的网站，怎么换成我的配色？」

答案是这套体系的最大优势所在：换配色 = 覆盖十几个语义 token 的值。组件不写死任何颜色，只引用 token——你重定义 --primary、--background 等一组值，全部组件自动换装，不需要逐个改。

推荐工作流（以 Claude Design 为例，Figma 里改 Variables 集合同理）：

1. 从底版设计系统起稿（中性默认色），先专注结构与布局。
2. 在 token 层调色。对 AI 说「主色换成暗红金，整体奢华暗色调」这类意图，或直接给出具体值——关键约束是：调整发生在语义 token 上，而不是在稿子里散点取色。一处 token 变更全稿联动，这既是效率，也是后面能落地的前提。
3. 迭代到满意，产出定稿。
4. 交付「品牌 token 清单」：把最终确定的一组 token 值（--primary: #xxx、--background: #xxx……通常 15～25 个）整理成清单交给前端 / 框架维护者。
5. 维护侧一键落地：拿这张清单生成两样东西——该品牌的专属设计系统（供后续设计复用）和项目的品牌覆盖样式（代码侧 rebrand）。设计资源与代码同源更新，一次交付、两侧生效。

直观理解：品牌 token 清单是设计与代码之间的合同。清单之内的自由（值随便定）完全属于设计师；清单之外的散点色不进合同，落地时会丢失或被归一。语义 token 覆盖不了的品牌特有色（如 VIP 金色系、角标色），在清单里以补充项列出即可，代码侧有对应的扩展机制（--brand-* 命名空间）。

品牌变体机制

设计系统按品牌分层：底版（框架默认中性色，新项目 / 探索用）+ 品牌变体（每个业务品牌一套，底版卡片注入该品牌 token 后生成）。设计某个现有品牌的新页面时选它的品牌变体，颜色和组件形态与线上完全一致；设计全新网站时从底版开始，走上面的配色工作流。

品牌变体由维护侧的自动化流水线生成（不是手工维护的副本），需要新增品牌变体时联系框架维护者，提供品牌 token 清单即可。

相关链接

• 样式与 Token — token 在代码侧的完整清单与消费方式
• 组件总览 — 全部框架组件的能力文档
• 主题系统 — 明暗主题与 token 的关系
• 规范与治理 — token 层调色纪律与品牌接入流程