UI 界面与设计系统

设计系统把「一次设计得好」变成「一直设计得一致」。核心资产是设计令牌（Design Tokens）→ 组件规范 → 页面组装规则三层。本页讲设计侧如何搭这套体系；CSS 变量、主题切换等实现侧见前端样式方案。

体系分层：从原子到页面

设计令牌（色彩/字号/间距/圆角…）
  → 基础组件（Button / Input / Card…）
  → 复合组件（表单、对话框、数据表…）
  → 页面与模板（由上面的积木组装）

各层只依赖下一层，禁止页面里出现「一次性令牌」或私改组件。

设计令牌（Design Tokens）

令牌是可命名、可复用、可映射的设计变量，是设计稿与代码的交接协议。

命名：语义优先，不要按色值命名

• 错误：--red-500、#1890ff（换个主题就没法映射）；
• 正确：按「用途/角色」命名，例如：

/* 原始令牌（Raw/Primitive）——只在定义处出现一次 */
--palette-blue-600: #2563eb;

/* 语义令牌（Semantic）——组件里只允许引用它 */
--color-primary: var(--palette-blue-600);
--color-text-strong: var(--palette-gray-900);
--color-bg-danger-subtle: #fef2f2;

分两类维护

类型	作用	示例	变化频率
原始令牌	色板 / 字号表等原始值	gray-100、text-md	品牌升级才变
语义令牌	界面角色的当前取值	bg-danger、text-on-primary	换肤/主题时整体改

组件只引用语义令牌。这样切明暗主题或品牌换色时，只需改语义令牌映射表，组件零改动。

令牌该覆盖的最小集合

• 色彩：文字（主/次/禁用/反白）、背景（页面/浮层/交互）、边框、语义（成功/警告/错误/信息）两套深浅；
• 字号 / 字重 / 行高：与设计基础与视觉的「字体排印」对应；
• 间距 / 圆角 / 阴影 / 动效时长：每类给 3~5 档就够。

基础组件规范

每个组件文档至少包含三样东西：结构图、状态全集、使用规则。

示例：按钮 Button

状态	说明
default / hover / active / disabled	四态必做，hover 与 active 不能只是变个色
loading	提交中，防重复点击（见交互与信息架构的提交防抖）
focus-visible	键盘焦点环，勿用 outline: none 删掉（见可用性与无障碍）

使用规则示例：

• 一屏一个主按钮（primary），其余用 secondary / ghost；
• 危险操作（删除）用 danger 语义色，并配确认步骤；
• 按钮文案以动词开头（「保存」「新建项目」），禁用态要说明原因而非干置灰。

组件规范应有的「反规则」

文档除了写「怎么做」，还要写「不要怎么做」：例如「不要在错误色上自行加深来表示更严重」「不要把禁用组件当 loading 用」。反规则是防滥用最便宜的护栏。

图标与插画

• 统一网格：同套图标共用栅格（如 24×24）与关键线（stroke 1.5~2px），拐角半径统一；
• 两套语义：功能性图标（随文字色）与装饰性图标（可随品牌色）要分得清；
• 尺寸阶梯：图标随字号走阶梯（16/20/24…），不要每个地方单独缩放；
• 插画保持同一种线条语言 / 配色占比，避免一个产品里混三种画风。

明暗主题（Dark Mode）

设计侧原则

• 暗色不是「反色」：把灰色阶整体压低并减少饱和度，纯黑背景（#000）易产生光晕，通常用深灰（如 #0f1115）；
• 语义色在暗色下重新映射：错误红在暗底要用更亮的红保持对比；
• 对比度标准不变：暗色模式下正文 ≥ 4.5:1 依然要过（白字灰底常翻车点）。

交接方式

设计稿产出一张主题映射表（每个语义令牌的亮色值 / 暗色值），前端用 prefers-color-scheme + data-theme 覆盖实现，见前端样式方案的「主题」一节。

常见坑速查

坑	现象	解法
一次性令牌	组件里直接写 #ff7a45	页面与组件只许引用语义令牌
令牌两层混用	组件里出现 --palette-*	组件层禁止原始令牌，只在 tokens 定义处用
按钮只有两态	hover / active / focus 无差别	按状态全集表逐态实现
规范没有反规则	团队「自由发挥」出各种变体	文档写清 do / don't 与替代方案
换肤靠全局搜索替换	每处硬编码色值	全部收敛为语义令牌映射
图标画风不一	三个时期三套图标	统一网格 + 关键线规范，新图标入库前审查

检查清单

• [ ] 组件只引用语义令牌，无一次性色值/字号
• [ ] 每个基础组件有：结构图、状态全集、使用规则与反规则
• [ ] 危险操作有语义色 + 二次确认
• [ ] 键盘 focus-visible 环未删除且清晰可见
• [ ] 图标统一网格、描边与尺寸阶梯
• [ ] 暗色主题提供完整语义令牌映射表，对比度复测达标
• [ ] 新增组件走「入库评审」，不做页面私有复制品

令牌切主题的实现见前端样式方案；按钮 loading / 状态机等交互规则见交互与信息架构；焦点环与对比度的硬标准见可用性与无障碍。