设计系统搭建最佳实践

本文面向设计团队管理者，讲解如何从零规划、搭建和维护一个可扩展的 MasterGo 设计系统。

设计系统的核心组成

在 MasterGo 中，设计系统由以下四部分组成：

组成部分	对应功能	作用
组件	组件、组件集、变体	可复用的 UI 元素（按钮、卡片、导航等）
样式	颜色样式、文本样式、效果样式	统一的基础视觉属性
变量	颜色变量、数值变量、字符串变量、布尔变量	设计 Token 的底层存储单元
团队库	发布团队库	将组件和样式分发给团队使用

变量命名与组织

使用斜杠层级命名

MasterGo 支持斜杠 / 分隔符来组织变量层级，形成树状结构：

color/brand/primary
color/brand/secondary
color/text/primary
color/text/secondary
color/background/page
color/background/card
spacing/sm
spacing/md
spacing/lg
font/size/heading
font/size/body
font/weight/normal
font/weight/bold
radius/sm
radius/md

使用语义化命名，避免色值命名

命名应表达变量的用途而非具体值。这样当品牌色变更时，只需修改变量值，所有引用自动更新。

变量集合组织

将变量按功能分组到不同集合中，便于管理和导出：

集合	内容示例
Colors	brand、text、background、border、icon 等颜色组
Spacing	spacing、gap、padding、margin 等间距层级
Typography	字号、字重、行高、字体系列
Radius & Border	圆角、描边宽度
Effects	阴影参数、模糊参数
Component Tokens	组件级别的专属 Token（按钮高度、卡片宽度等）

利用变量模式实现主题切换

MasterGo 支持在一个变量集合中创建多个模式（Mode）。利用此功能实现明暗主题切换：

创建一个颜色变量集合，添加「Light」和「Dark」两个模式
同一变量在不同模式下设置不同颜色值
切换模式时，所有引用自动更新

组件命名规范

斜杠命名法

使用 / 分隔符组织组件层级，组件在资源面板中自动归类：

Button / Primary / Default
Button / Primary / Hover
Button / Primary / Disabled
Button / Secondary / Default
Input / Default
Input / Focus
Input / Error
Card / Product / Default
Card / Product / Hover
Modal / Default
Modal / WithIcon

对齐设计与开发的命名

组件和属性的命名应尽量与前端代码对齐。例如：

设计中的 Button / Primary / Large 对应代码中的 <Button type="primary" size="large">
变量属性名应与 CSS 属性或设计 Token 名一致

这不意味着必须使用英文——选择团队统一的语言即可，关键是一致。

文本图层命名

组件内的文本图层使用语义化命名，确保：

替换组件实例时，相同名称的文本图层会保留覆盖内容
例如：按钮内文本统一命名为 Label，卡片标题统一命名为 Title

避免使用 Rectangle 3、Frame 42 等默认名称。

组件库文件组织

页面结构

在一个组件库文件中，建议按以下结构组织页面：

页面	内容
📋 概览	设计系统简介、使用指南、更新日志
🎨 基础样式	颜色、字体、阴影、间距等基础样式
🧩 基础组件	按钮、输入框、图标等原子级组件
🧱 复合组件	卡片、列表、导航栏等复合组件
📱 页面模板	完整页面布局、常见页面结构
📦 归档	旧版组件、已废弃设计

按字母/数字顺序排列页面，方便在资源面板中按序显示。

单文件 vs 多文件策略

策略	适用场景	优点	缺点
单文件	小团队、单一产品	维护简单，一个发布入口	文件大、加载慢
多文件	大团队、多产品线	按需订阅，职责清晰	跨文件引用需协调

建议从单文件开始，当组件超过 100 个或团队超过 20 人时，考虑拆分为多个库文件：

基础样式库（颜色、字体、间距）
图标库
基础组件库（按钮、输入框等）
业务组件库（特定产品的复杂组件）

组件设计原则

从原子开始组合

先创建最小的原子组件（图标、文本标签），再组合为复合组件（输入框 = 标签 + 输入区 + 错误提示）。修改原子组件时，所有复合组件自动更新。

充分利用自动布局

为组件设置自动布局，确保：

内容变化时组件自动适应（按钮文案变长时按钮自动变宽）
嵌套组件保持间距一致
Dev Mode 中开发者能准确识别布局逻辑

使用组件属性而非隐藏图层

用组件属性（布尔值、变体切换）来控制组件的不同状态，而非在一个组件中隐藏/显示图层。这能：

减少文件体积
提高组件面板的可用性
让开发者在 Dev Mode 中更清晰地理解组件结构

为组件添加描述

在组件属性面板中为每个组件添加描述，说明：

用途：这个组件用于什么场景
使用规范：何时使用、何时不用
变体说明：各变体的适用场景差异
开发备注：对应的前端组件名或 API

描述内容会出现在资源面板的悬浮提示中，帮助团队成员选择正确的组件。

发布与版本管理

发布前检查清单

[ ] 所有组件已正确命名（无默认名称）
[ ] 组件变体和属性已完整配置
[ ] 样式和变量已绑定到组件（而非硬编码值）
[ ] 自动布局设置正确
[ ] 组件描述已填写
[ ] 已删除未使用的隐藏图层和草稿组件

发布流程

在组件库文件中完成修改
打开团队库面板 → 点击「保存历史版本」
填写版本说明（明确描述本次变更内容）
选择发布范围（团队库或组织库）
团队成员收到更新通知，可选择更新

版本管理建议

每次发布标注清晰的版本说明，方便团队成员了解变更
重大变更（如删除组件）应在发布前通知团队
旧版本组件可以先移到归档页面，确认无人使用后再删除

常见反模式

反模式	问题	正确做法
一个组件内包含大量隐藏图层	文件卡顿、组件面板混乱	用布尔属性或变体控制可见性
组件名保留默认（Frame 42）	团队难以找到和使用	用语义化斜杠命名
颜色/间距直接写死数值	修改时需逐个改动	绑定变量或样式
把所有东西放在一个页面	加载慢、难管理	按功能分页组织
发布不写版本说明	团队不知变更了什么	每次发布写清晰的 Changelog
组件库和个人设计文件混用	污染组件库	组件库文件独立管理

设计系统搭建最佳实践 ​

设计系统的核心组成 ​

变量命名与组织 ​

使用斜杠层级命名 ​

使用语义化命名，避免色值命名 ​

变量集合组织 ​

利用变量模式实现主题切换 ​

组件命名规范 ​

斜杠命名法 ​

对齐设计与开发的命名 ​

文本图层命名 ​

组件库文件组织 ​

页面结构 ​

单文件 vs 多文件策略 ​

组件设计原则 ​

从原子开始组合 ​

充分利用自动布局 ​

使用组件属性而非隐藏图层 ​

为组件添加描述 ​

发布与版本管理 ​

发布前检查清单 ​

发布流程 ​

版本管理建议 ​

常见反模式 ​