UI 视觉设计 / 知识点
设计系统术语速查手册
Design Token
统一边框宽度、样式和语义颜色的设计决策,常用于控件边界、分隔与聚焦状态;可由多个基础 Token 组合形成。
定义
**Border Token(边框令牌)**用于统一界面中的边框宽度、颜色和样式决策。
边界
边框常由多个 Token 协同表达:
border.width.default
color.border.subtle
color.border.strong
color.focus最小例子
输入框默认使用弱边框,聚焦后切换到 Focus Token,而不是在组件内部手写另一套颜色。
常见误区
不要只按组件创建边框颜色。优先抽象“subtle / strong / danger / focus”等可复用语义。
为 Token 建立可预测的层级和语义命名规则,使名称在主题变化后仍成立;常按类别、角色、属性、状态等维度组合。
定义
**Token Naming(Token 命名)**是用稳定、可预测的名称表达 Token 在系统中的角色和层级。
一种常见思路是:
category.role.property.state
color.action.background.hover具体层级不要求所有系统完全一致。
边界
好名称描述“设计意图”,而不是当前实现细节。
最小例子
color.text.secondary 通常比 gray-500-text 更耐主题变化。
常见误区
命名层级过深同样有成本。只有真正参与检索、主题或治理的维度才值得进入 Token 名称。
组件模型
把设计 Token 从权威数据源转换、校验并输出到 Web、iOS、Android 等平台的自动化流程,避免不同端手工维护同一组值。
定义
**Token Pipeline(Token 管线)**负责把 Token 的源数据转换为各技术栈可消费的格式。
结构示意
Token Source
↓ validate
Transform
↓
├── CSS Variables
├── JSON
├── Swift
└── Android Resources边界
Pipeline 解决的是数据同步、格式转换和校验,不负责决定设计 Token 本身应该如何命名和使用。
最小例子
设计系统发布时,由同一份 Token 数据自动生成 CSS Custom Properties 和移动端资源文件。
常见误区
手动复制 Token 到多个平台不算真正的 Pipeline;一旦源值变化,人工同步很容易产生版本漂移。
封装结构、样式、行为和状态的可复用 UI 构件,例如 Button、Input、Dialog;组件应解决稳定问题,而不是包装任意页面片段。
定义
**Component(组件)**是具有明确职责、结构、视觉、行为和状态的可复用 UI 构件。
边界
一个组件应该拥有稳定问题边界和可复用价值,而不是因为“这块 UI 很大”就创建组件。
结构示意
Component
├── Anatomy
├── Properties
├── Variants
├── States
├── Behavior
└── Accessibility最小例子
Button 解决“触发动作”,Input 解决“录入文本”,Dialog 解决“小型上下文任务”。
常见误区
设计系统组件不是业务页面的任意封装。OrderRefundPanelV2 这类高度业务化对象通常属于产品组件,而不是系统基础组件。
提供低层、可组合的 UI 能力,通常业务语义较弱,例如 Stack、Box 或基础交互原语;适合构建更高层组件,不直接代表完整模式。
定义
**Primitive Component(基础组件 / 原语组件)**提供低层、稳定、可组合的界面能力。
它可能负责:
- Layout
- Surface
- Text
- Focus behavior
- Overlay behavior
边界
Primitive Component 与 Primitive Token 名字相似,但一个是组件层,一个是数据层。
对比
Primitive Components
↓ composition
Button / Card / Dialog
↓
Patterns最小例子
Stack 只处理纵向布局和 Gap,它可以被 Form、Card、Dialog 等更高层组件复用。
常见误区
不要为了“原子化”把所有 HTML 或原生控件逐一包装成 Primitive。只有能提供稳定系统价值时才值得沉淀。
由多个较小组件组合而成并形成独立交互职责的高层组件,例如 Date Picker、Data Table;应避免把完整业务页面包装成复合组件。
定义
**Composite Component(复合组件)**由多个基础组件或子组件组合形成,承担更完整的交互任务。
最小例子
Date Picker 可能组合:
Input
Popover
Calendar
Navigation Buttons
Grid但对使用者暴露的是一个完整日期选择能力。
边界
Composite Component 仍应具有跨业务复用价值;完整订单页、审批流页面通常属于 Feature 或 Pattern。
常见误区
复合组件不是越“全能”越好。职责过多会导致 API 膨胀、状态难以管理和定制困难。
描述一个组件由哪些稳定子区域组成,以及各部分的名称和关系;统一 Anatomy 可让设计、代码、文档与测试使用同一套部件语言。
定义
**Component Anatomy(组件结构)**定义组件内部可识别、可命名的稳定组成部分。
结构示意
Button
├── Container
├── Leading Icon
├── Label
└── Trailing Icon边界
Anatomy 描述“有哪些部分及其关系”,不是具体尺寸标注。
最小例子
团队约定 Text Field 的 Anatomy 为 Label、Input、Leading Icon、Trailing Action、Helper Text、Error Message,设计和代码即可使用统一术语沟通。
常见误区
Anatomy 不应暴露大量纯实现细节。只有对设计、内容、状态或扩展有意义的结构才值得命名。
组件中预留给调用方放置指定内容或子组件的位置,如 leading、trailing、header;Slot 用于可控扩展,不代表任意区域都能自由塞内容。
定义
**Slot(插槽)**是组件明确开放的内容占位位置,让使用者在受控结构中插入文本、图标或子组件。
结构示意
Button
[leading] [ label ] [trailing]边界
Slot 是组件 API 的扩展点,而不是无限制自由布局。
对比
- Slot:允许传入内容。
- Property:传入值或配置。
- Override:改变实例默认设置。
最小例子
List Item 可以开放 leading、title、description、trailing 等 Slot。
常见误区
“万能 children Slot”虽然灵活,却可能绕过系统布局和可访问性规则。设计系统应明确允许组合的边界。
用于配置组件内容或行为的公开参数,例如 label、disabled、icon;Property 是组件 API 的组成部分,应保持职责明确并避免互相冲突。
定义
**Property(组件属性)**是使用者配置组件内容、行为或表现的公开参数。
例如:
label
disabled
leadingIcon
size
tone边界
Property 是通用概念;Variant、State、Size 都可能通过某种 Property 在具体工具或代码中表达,但语义上并不完全相同。
最小例子
Button 的 disabled=true 表示状态属性,size=sm 表示尺寸属性。
常见误区
不要通过几十个布尔 Property 拼装组件,例如 isSmall + isDanger + isQuiet + isOutlined。互斥配置更适合明确枚举。
同一组件在稳定用途或视觉角色上的预定义版本,如 primary、secondary、danger;Variant 应表达长期存在的设计选择,而不是临时状态。
定义
**Variant(变体)**是同一组件针对不同稳定用途、强调程度或表现方式定义的预设版本。
例如 Button:
Primary
Secondary
Tertiary
Danger边界
Variant 是稳定配置,不是用户交互过程中瞬时变化的 State。
对比
Variant: Primary / Secondary
State: Default / Hover / Disabled
Size: Small / Medium / Large最小例子
一个 Primary Button 在 Hover 后仍然是 Primary Variant,只是进入 Hover State。
常见误区
不要把 hover、loading 命名成 Variant。混淆 Variant 与 State 会让组件矩阵快速失控。
组件在交互或系统条件下所处的瞬时状态,如 hover、focus、disabled、loading、error;State 通常跨多个 Variant 共享。
定义
**State(状态)**表示组件在用户交互、系统流程或数据条件下所处的当前状态。
常见状态:
- Default
- Hover
- Focus
- Pressed
- Selected
- Disabled
- Loading
- Error
边界
State 通常会随交互发生变化,而 Variant 是组件的稳定选择。
最小例子
Primary Button 可以从 Default → Hover → Pressed → Loading,但其 Primary Variant 没有改变。
常见误区
不要只设计 Default State。缺少 Focus、Disabled、Loading、Error 等状态,会在真实产品中产生大量临时补丁。
由指针、键盘、触摸等用户交互触发的组件状态,如 hover、focus、pressed;应与 disabled、loading 等系统状态区分。
定义
**Interaction State(交互状态)**是由用户输入方式触发的瞬时状态。
典型包括:
Default
↓ pointer
Hover
↓ press
Pressed
Keyboard → Focus边界
Disabled、Loading、Error 等状态虽然也是 State,但不一定由用户直接交互触发。
最小例子
键盘 Tab 到 Button 时应出现 Focus 表现,即使鼠标从未 Hover。
常见误区
不要只设计 Hover。触屏没有 Hover,键盘用户依赖 Focus,不同输入模式都需要可理解的反馈。
组件预定义的尺寸等级,如 sm、md、lg,通常同时影响高度、内边距、图标和排版;Size 应作为整体规格而非单独改变一个高度值。
定义
组件的 **Size(尺寸规格)**是一组协调变化的尺寸预设,而不是单独的宽高属性。
例如:
Button / sm
├── height
├── horizontal padding
├── label typography
└── icon size边界
Size 应解决稳定密度和使用场景差异,不应用于任意缩放组件。
对比
- Size:单个组件规格。
- Density:整个界面或系统的信息密度模式。
- Responsive:根据可用空间改变布局。
常见误区
只减小 Button 高度却不调整文字、图标和间距,不是完整的 Small Size。
从主组件创建并在具体页面中使用的实例,继承组件定义但可按允许范围配置内容和属性;修改主组件可影响其多个实例。
定义
**Instance(组件实例)**是某个 Component Definition 在具体界面中的一次实际使用。
结构示意
Button Component
├── Instance: 保存
├── Instance: 发布
└── Instance: 删除边界
实例共享组件结构和规则,但可以拥有不同内容、Variant、State 或允许的属性值。
最小例子
设计工具中从 Button 主组件拖出一个副本,把 Label 改为“提交”,这个副本就是 Instance。
常见误区
大量解除实例关联或修改内部结构,通常说明组件 API 不够满足实际场景,而不是实例机制本身有问题。
在不脱离主组件的前提下修改实例允许变化的内容或配置,例如文案、图标或 Variant;过度 Override 会削弱系统一致性。
定义
**Override(实例覆写)**是实例在继承主组件的同时,对允许变化的内容或属性进行局部修改。
常见 Override:
- Label text
- Icon
- Variant
- Boolean visibility
- Slot content
边界
Override 不应该突破组件明确规定的结构和设计约束。
最小例子
同一个 Button Component 的不同实例分别显示“保存”“取消”,属于正常文本 Override。
常见误区
如果每次使用组件都要修改 Padding、Radius、内部层级,说明团队实际上正在绕过组件系统。
通过组合多个小组件构建更复杂组件或 Pattern 的方式;Composition 倾向于复用稳定能力,而不是不断向单个组件增加配置开关。
定义
**Composition(组合)**通过组合多个职责清晰的组件,形成更复杂的界面能力。
结构示意
Dialog
├── Heading
├── Content
├── Form
└── Actions
├── Button
└── Button边界
Composition 强调组件之间的组合关系,而不是在一个组件内部加入无限数量的参数。
对比
- Composition:组合多个能力。
- Configuration:通过属性调整一个组件。
常见误区
当组件 API 已经出现大量互斥布尔值时,优先考虑是否应该拆分并通过 Composition 解决,而不是继续加开关。
组件对设计师或开发者公开的配置接口,包括属性、Variant、Slot、事件和约束;好的 API 应可预测、有限且难以组合出非法状态。
定义
Component API是组件允许使用者控制和扩展的公开接口。
设计端可能表现为:
- Properties
- Variants
- Slots
- Content rules
代码端还可能包含:
- Props
- Events
- Methods
边界
组件内部实现细节不应该自动成为公开 API。
最小例子
Button 暴露 variant、size、disabled、leadingIcon 和 onPress,这些共同构成它的 API。
常见误区
“越灵活越好”不是优质 API。允许任意颜色、任意 Padding、任意子结构,往往会直接破坏设计系统约束。
记录组件 Anatomy、尺寸、Token、状态、响应行为和无障碍要求的精确定义,是设计、代码和测试对齐组件实现的重要依据。
定义
**Component Spec(组件规格)**是组件实现与验收所依据的精确定义。
通常应覆盖:
- Anatomy
- Measurements
- Tokens
- Variants
- States
- Behavior
- Responsive rules
- Accessibility
边界
Spec 关注“组件准确是什么”;Guideline 更关注“什么时候应该使用”。
最小例子
Input Spec 指定 Label 间距、Field Height、Focus Border、Error Message 位置和 Disabled 状态,而不是只提供一张视觉截图。
常见误区
设计稿截图不是完整 Spec。缺少状态和行为说明时,开发只能依赖猜测补齐。
主题与适配
面向使用者说明组件何时使用、如何配置、行为、内容、无障碍与反例的文档;它比单纯的设计尺寸标注覆盖范围更广。
定义
**Component Documentation(组件文档)**帮助设计师和开发者正确选择、配置和实现组件。
高质量文档通常包含:
When to use
Anatomy
Variants
States
Behavior
Content
Accessibility
Do / Don't
Code / Design examples边界
Documentation 面向使用者;Spec 更偏组件精确定义和实现依据。
最小例子
Dialog 文档不仅写宽度,还解释什么时候该用 Dialog、什么时候应该使用独立页面。
常见误区
只有 API 参数表的文档,对设计师通常不够;只有视觉截图的文档,对开发者也不够。
组件 API 能组合出来但设计系统明确不允许出现的配置,例如互相冲突的 Variant 与属性;成熟系统应尽量在设计和代码层阻止它。
定义
**Invalid State(非法状态)**是组件配置在技术上可能被组合出来,但在设计规则中没有合法语义或无法正确工作的状态。
最小例子
Button
variant = link
iconOnly = true
label = required如果这组组合没有明确行为,就可能构成 Invalid State。
边界
它不同于 Error State。Error State 是组件合法的业务状态;Invalid State 是组件 API 本身产生了不允许的配置组合。
常见误区
不要只靠文档写“请不要这样用”。能通过 Variant 约束、类型系统或组件封装阻止的非法组合,应尽量从源头消除。