无代码 UI 构建器中的设计 token：保持主题一致性的实践

为什么团队会出现不一致的 UI

UI 不一致很少一开始就是“设计问题”。它通常是时间问题。有人现在就需要一个按钮，于是他们从别的页面复制一个并做点修改，直到看起来差不多为止。

这就是微小差异悄悄出现的方式：两个几乎相同的蓝色，圆角从 6 变到 8，标题“有点粗”，内边距取决于谁搭建了页面。在无代码构建器里，更容易做出一次性的微调，因为控件触手可及，改动看起来无害。

随着产品增长，漂移会加速。页面越多，重复模式就越多。参与构建的人越多，个人偏好就越显著。团队成员越多，“临时修复”在孤立情况下就越常见。如果一个人做客户门户，另一个人做管理面板，你最终会得到同一品牌的两种不同诠释。

“凭感觉”在日常工作中随处可见：挑颜色直到“看着对”，把间距挪几像素因为屏幕感觉“太紧”，创建新的按钮样式而不是使用现有的，混用字号因为默认看起来“有点小”，或者修复一个屏幕却没有检查其他地方。

成本会在后期显现。评审变慢，因为反馈变得主观（“让它感觉更像另一个页面”）。返工堆积，因为难以将更改应用到所有地方。Web 与移动走样，因为不同的人做出了相似但不相同的选择。

设计 token 通过用共享的值替代“差不多合适”的决策来解决这个问题。即使团队和应用增长，UI 也能保持一致。

用通俗的话说什么是设计 token

设计 token 是对 UI 的命名决策。不是说“用这个蓝色”或“让按钮感觉宽松”，而是把这些选择用清晰的名字标注，任何人都能复用。

Token 本身并不是原始值。原始值可能是 16px、#2563EB 或 600（字体粗细）。token 是解释该值在产品中含义的标签，比如 space-4、color-primary 或 font-weight-semibold。

这种转变能阻止凭感觉选择的习惯。当人们按感觉挑值时，会慢慢积攒出五个略有不同的蓝、三个稍有差异的标题和在不同屏幕间变化的间距。

Token 最好作为单一真相来源（single source of truth）存在。如果每个屏幕和组件都引用同一套名字，那么你可以通过更新少数 token 值来改变整个应用的外观，而不是在几十个屏幕里逐个查找并修改。

Token 还搭建了设计与构建之间的桥梁。设计师在规范中使用 token 名称，构建者在无代码 UI 构建器中使用相同名称，这样设计在交接时得以保留。

大多数 token 集合分为几类：颜色角色（primary、background、text、danger）、排版（字体系列、字号、粗细、行高）、间距步进（内边距、外边距、间隙）、形状与层次（圆角、边框宽度、阴影），有时还有动效（时长与缓动）。

大多数产品实际需要的 token 集合

大多数团队并不需要庞大的 token 库。他们需要一套小而清晰的集合来覆盖大多数页面，以便人们不再猜测数值。在无代码工具中这点尤为重要，因为“就这一次”的微调传播得很快。

一个实用的入门集覆盖五类：

• 颜色：一些品牌角色（primary、secondary）、一套中性色（文本、背景、边框）和状态角色（success、warning、error）。如果经常用到，添加 hover 和 disabled 角色。
• 排版：一种字体（最多两种）、一个小的字号尺度（例如 12/14/16/20/24/32）、实际使用的粗细以及匹配的行高。
• 间距：简洁的阶梯（例如 4/8/12/16/24/32）用于内边距和间隙。
• 形状与效果：几种圆角（none/sm/md/lg）、边框宽度和一小套阴影（0-3）。
• 动效（可选）：仅在应用使用动画时添加，2-3 种时长和 1-2 种缓动命名即可。

有一条规则能让库保持理智：如果某个值在三处或更多地方出现，就把它做成 token。如果只有一次出现，就先怀疑一下，别让它变成“新常态”。

防止 token 混乱的命名规则

好的 token 名称能在争论发生前就阻止它们。如果人们能在不搜索的情况下猜到 token，便会复用它们。猜不到就会创建新 token，你的主题就会分裂。

优先使用语义名称（不要只写颜色）

优先使用描述 UI 职能的名字，而不是描述外观的名字。text-primary 告诉大家何时使用它。blue-600 只是油漆桶。

一个有用的模式是双层结构：

• 基础 token：原始构建块，如 color-blue-600、space-16、font-14
• 语义 token：基于意义的 UI 角色，如 text-primary、bg-surface、border-muted

在无代码 UI 构建器中，语义 token 能帮助非设计者快速选择正确的值，而不凭感觉乱改。

新增 token 的规则

大多数 token 库变得混乱是因为“新增”成了默认。把“复用”设为默认。

把规则保持简单：

• 仅当某个值在 2+ 处 使用，或支持实际的 状态（hover、disabled、error）时才新增 token。
• 若是一次性的样式，把它保留在组件内部。
• 若两个 token 的差异微乎其微，就选一个并删除另一个。
• 若你无法用一句话说明该 token 的用途，就别添加它。

然后统一命名风格。选择一种大小写风格（kebab-case 非常实用），使用稳定前缀（text-、bg-、border-、icon-、space-），并保持数值刻度一致（space-4、space-8、space-12、space-16）。

步骤指南：从已有的使用情况定义 token

把当前 UI 当作证据。在创建任何新东西前做个快速清点：收集截图、检查样式，写下生产环境中实际看到的每个颜色值、字号和间距（包括那些只在单屏出现的“一次性”值）。

接下来，有目的地减少重复。你通常会发现五种略有差异的同一灰色，或间距在 14、15、16 之间跳来跳去。选一个值保留，然后把旧值映射到它。这正是 token 变得实用的地方：你不再为品味争论，而是就一小套共享选择达成一致。

一个合理的第一版可以在一次迭代中完成：

• 调色板 token：原始颜色（品牌色、中性色、反馈色）
• 语义 token：基于意义的颜色（文本、背景、边框、success、warning）
• 排版尺度：6-8 个字号并赋予清晰角色（body、label、H1-H3）
• 间距尺度：6-10 个可复用步进
• 组件基础：几种标准圆角和阴影

为每个 token 添加一句使用指引：在哪里使用以及哪里不该使用。例如：“text-muted 用于辅助文本，不用于主按钮。”

最后，决定归属。指定一个人（或小团队）来批准变更，并制定简单规则："只有当现有 token 无法适配时才新增 token。" 这能在产品增长时保持系统稳定。

在无代码 UI 构建器中如何应用 token

从每个屏幕继承的默认值开始：基础文本样式（字体、字号、行高、颜色）、标题样式（H1-H3），以及一小套布局间距规则，避免页面显得随意。

接着，将 token 映射到工具中的主题设置：主题变量、全局样式、样式预设或设计系统设置。目标是选择“Primary”或“Space/16”时选择的是一个 token，而非一次性数值。

把可复用样式集中在日常使用的模式上。入门集可以包含卡片样式（背景、边框、圆角、内边距、阴影）、表单字段样式（标签、输入、帮助文本）、按钮样式，以及表格行密度和 hover 状态。

状态是混乱潜入之处，所以要及早定义。每个交互组件的 hover、focus、disabled、error 都应使用 token 驱动的值。聚焦（focus）应在任何地方使用相同的环形颜色和粗细；错误（error）应在边框和文本颜色配对上始终如一。

最后，规划共享。如果你的工作区支持模板或可复用模块，把 tokens 和基础样式放在一个“起始应用”里，新项目从它复制。这样新屏幕默认就一致了。

保持组件变体一致性

变体是 UI 系统要么变得平静可预测，要么变成一堆一次性修改的地方。变体在映射到颜色、排版和间距的 token 时最有效。

先从少量常用组件入手：按钮、输入、徽章、提示和卡片。为它们提供两条相同的选择维度：尺寸 和 意图。尺寸应是机械性的（影响排版与间距）；意图应代表含义（语义颜色）。

无猜测的尺寸与意图

当尺寸变体只改变少数基于 token 的属性（字体大小、内边距、圆角）时，它们会保持一致。意图变体应主要改变颜色角色（背景、文本、边框），绝不可悄悄改变间距。

一套覆盖大多数产品的集合：

• 尺寸：sm、md、lg
• 意图：primary、secondary、danger
• 状态：default、hover、focus、disabled

团队可以遵循的交互规则

定义应用于每个组件的状态规则，而不只是按钮。例如：focus 始终显示可识别的环，hover 在一致的方式下提高对比度，disabled 使用相同的不透明度并阻止点击。

只有当某个变体代表经常出现的含义（比如“danger”）时才添加新变体。如果只是一次性布局需求，通常应该是新组件或外层包装，而不是大家日后会滥用的变体。

让 Web 与移动主题保持一致

当产品同时发布到 Web 与移动端时，“同一品牌”不总是“像素一致”。目标是屏幕彼此感觉像一家人，即便各平台有不同的默认值。

先从可以跨平台通行的共享 token 开始：颜色角色（background、surface、text、primary、danger）、排版尺度（字号与粗细）和间距 token（4、8、12、16、24）。这些能消除猜测并使更新可预测。

然后接受实际差异。移动端需要更大的触控目标，通常也需要稍大的间距。Web 端需要更密集的表格、侧栏和多栏布局。字体也可能不同：你可能在 Web 上用品牌字体，但为可读性与性能在 iOS/Android 上使用平台默认字体。

一个实用方法是两层：全局 token 定义含义，平台 token 定义该含义如何呈现。

• 全局：color.text、color.primary、space.md、radius.sm、type.body
• 仅 Web：type.family.web、control.height.web、space.tableRow
• 仅移动：type.family.mobile、control.height.mobile、space.touch

保持组件名称一致（如 Button/Primary），即便尺寸不同。发布前对两个主题都进行对比度检查。

治理：如何让 token 随时间保持健康

只有当 token 保持稳定且易懂时它们才有效。没有轻量治理，团队会悄悄新增“又一个蓝”或“又一个内边距”，你又回到凭感觉阶段。

轻量的 token 变更流程

保持流程小而真实：

• 请求：任何人都可以提出新增或修改 token 的请求，并附上截图与原因。
• 审查：一名设计师与一名开发/构建者检查对关键屏幕的影响。
• 批准：确认命名、可访问性（对比度、触控大小）以及该 token 是否确实是新需求。
• 发布：按计划发布更新（每周或每个迭代），而不是零散发布。
• 通知：说明变更内容以及推荐使用的替代项。

保留简单的变更日志并标注弃用。如果旧 token 被替换，说明应使用何种替代方案，保持旧 token 在一段时间内可用，并明确标记以免新页面继续采用它。

清理工作也是职责的一部分。每月一次移除未使用的 token 与组件变体（或至少标记它们）。

让每个人都能用好 token

非设计者需要示例，而不是理论。

做到：使用间距阶梯控制间隙，使用 Primary Button 变体作为主要操作。

别做：把内边距设为“13px 因为看起来合适”，或者为匹配某屏创建新的按钮样式。

把 token 工作与产品优先级挂钩：新功能、品牌重塑和无障碍修复应驱动 token 更新，而不是个人偏好。

常见错误与陷阱

失去 token 好处的最快方式是把它们当成杂物收集地。一开始出发点正确，但几个临时修复堆积后，团队又回到凭感觉选择。

一个常见的陷阱是过早创建太多 token。若每个页面都有自己的颜色或间距 token，你不是在构建系统，而是在编目例外。只有当某个值会被共享使用时才新增 token。

另一个隐蔽问题是让原始值偷偷进入组件。有人为按钮设为 14px 的内边距“就这一次”，或在卡片中直接用十六进制颜色。几周后没人记得为何它不同。养成习惯：若是可见且会重复出现，就应该是 token。

还要注意混用 token 类型。基础 token（如 gray-900 或 space-4）描述原始值。语义 token（如 text-primary 或 surface-muted）描述含义。当某个组件使用基础 token，而另一个组件为相同角色使用语义 token 时，就会出问题。

状态也是后期的痛点。团队常常先定义正常样式，然后在发布前拼凑 focus、hover、disabled 和 error。这就是你最终看到不一致的 focus 环和三种不同“错误红”的原因。

在扩展前做个快速陷阱检查：

• 将新 token 限制为共享需求，而非一次性页面
• 尽量避免在组件内部使用原始值
• 区分基础 token 与语义 token 并一致地应用它们
• 及早定义状态（focus、error、disabled）
• 给暗色模式或未来品牌更新留出余地，通过替换语义 token 来实现，而不是重写组件

在扩展前的快速清单

在把 UI 推广到更多页面、团队或产品前，检查基础是否足够清晰以便复制而不会猜测。

• 颜色角色为语义化。 Token 覆盖文本（默认、muted、inverse）、表面（页面、卡片）、边框（默认、focus）和状态（success、warning、danger）。
• 类型映射到小尺度。 少量文本样式（H1-H3、body、small），并定义大小、粗细与行高。
• 间距使用易记步进。 常用内边距与间隙来自紧凑阶梯（4、8、12、16、24）。若“14”不断出现，说明阶梯需要调整。
• 核心组件有变体。 常用组件应有尺寸（sm/md/lg）和意图（primary/secondary/danger），并与 token 角色匹配。
• 归属明确。 一个人或小组批准变更，并用轻量例行流程说明：为什么、影响、何时发布。

示例：在门户与管理面板中阻止 UI 漂移

一个小团队同时构建两个应用：客户门户和内部管理面板。不同人负责不同屏幕，并在无代码 UI 构建器中快速搭建。几周后，尽管没人能指出具体问题，界面开始让人感觉“不对”。

在使用 token 之前，审查意见叠加：按钮几乎相同但不完全一样，间距在屏幕间跳变，表单字段不一致，门户无意间显得“友好”，而管理面板显得“严格”。

他们通过引入一套小而实用的 token 集修复了问题。定义了语义颜色（Primary、Success、Danger、TextMuted）、间距尺度（4、8、12、16、24）以及按钮变体（Primary、Secondary、Ghost），统一了圆角和状态。

现在贡献者不再在每个页面挑随机的十六进制颜色或字号。他们选择 token 和变体，因此每个新页面都继承相同的决策。

构建速度加快，因为选择已经做出。评审从琐碎的视觉修正转向真正的 UX 问题。“把这个按钮设为 primary 变体”取代了“你能把它调成更蓝点、稍微高一点吗？”

随后一次小规模的品牌重塑到来：主色改变、字号尺度收紧。借助 token，团队只需更新少数值，门户和管理面板就会同时刷新。

下一步：先小规模试点，再逐步标准化

挑一个使用频繁且明显存在漂移的问题流程，如入职流程、设置页面或一个简单表单。把单个流程转换为 token 驱动是最快证明方法并停止凭感觉选择。

从一套小而安全的 token 开始：primary/background/text/border/danger、一个短的字号尺度、一个间距阶梯，以及 2-3 个圆角与阴影等级。然后创建一小套仅使用 token 的组件：一个按钮、一个输入、一个卡片、一个提示。仅在确有必要时才添加变体。

与团队进行短评审，使用两张截图：一张是含有不一致内边距与字体的“之前”屏幕，另一张是用 token 与变体搭建的“之后”屏幕。就几条规则达成一致（例如“不得使用硬编码颜色”和“间距必须使用 token”），先修复最重要的不一致项。

推广时，先把新屏幕转换，随后在触及旧页面时逐步回填。如果支持请求需要新增管理筛选面板，用 token 驱动的组件重建该面板并只替换你正在编辑的部分。

如果你在 AppMaster 中构建完整产品（后端、Web 与移动），尽早设置 token 与可复用 UI 样式能让新页面默认继承相同决策。这样视觉一致性与应用逻辑可以同时向前推进，而不必在后期反复清理。