Design System 架构方法论

多端共享组件库的设计哲学、组织方式与业界最佳实践 · 更新于 2026-02-07

1. Design System 到底是什么

Design System（设计系统）不只是一个组件库。它是一套完整的标准体系，包括：

Design Token 是什么？

Design Token 是设计系统中最小的原子级决策。它把"设计师说的颜色"翻译成"开发者用的变量"：

// 设计师的 Figma 标注
Primary Gold: #C89B3C
Body Spacing: 16px

// 开发者的代码
static const Color brandGold = Color(0xFFC89B3C);
static const double spacingMd = 16.0;

Token 的关键价值：单点修改，全端生效。改一次 tokens.json，Flutter 三端 + Web 端同步更新。

2. Apple 的方法：扁平化组件库

核心架构

Foundation (日期、字符串、网络等基础工具)
    ↓
UIKit / SwiftUI (所有 UI 组件，扁平放置)
    ↓
App 层 (开发者用组件搭建页面)

关键特征

• 没有原子/分子/有机体的分层概念 — Text、Button、NavigationSplitView、DatePicker 全部平级放在同一个框架里
• 一个 import 解决一切 — import SwiftUI，所有组件可用
• 复杂度差异巨大 — Text 一行代码，NavigationSplitView 几十行配置，但 API 层面不做层级区分
• 通过 modifier 链组合 — 不是继承，而是 .font().padding().background() 链式修饰
• Human Interface Guidelines (HIG) — 组件库之外，有一套完整的设计指南文档

为什么 Apple 不分层？

优缺点

3. Google Material Design：Token → Theme → Component

核心架构

Design Tokens (颜色原语、间距、字体)
    ↓
Theme System (ColorScheme + ThemeData + ThemeExtension)
    ↓
Material Components (ElevatedButton, Card, AppBar...)
    ↓
App 层 (组装页面)

关键特征

• Token → Theme 的桥接层 — Material 3 的核心创新。不是组件直接引用 token 值，而是通过 ColorScheme / ThemeData 间接传递
• 组件不知道具体颜色 — ElevatedButton 只知道"我的背景色是 colorScheme.primary"，不知道 primary 到底是蓝色还是金色
• 一键换主题 — 换一个 ColorScheme.fromSeed(seedColor: ...)，全部组件自动更新
• Component Token — 每个组件有自己的 token 映射表（如 FilledButton.containerColor = primary）

Material 3 的 Token 分层

Reference Tokens (最底层原语)
├── md.ref.palette.primary40 = #6750A4
├── md.ref.palette.neutral90 = #E6E1E5
└── md.ref.typeface.brand = Roboto

     ↓ 映射

System Tokens (语义化)
├── md.sys.color.primary = md.ref.palette.primary40
├── md.sys.color.on-primary = md.ref.palette.primary100
└── md.sys.typescale.body-large = 16sp / Roboto

     ↓ 映射

Component Tokens (组件级)
├── md.comp.filled-button.container.color = md.sys.color.primary
├── md.comp.filled-button.label-text.color = md.sys.color.on-primary
└── md.comp.filled-button.container.shape = md.sys.shape.corner.full

优缺点

4. Atomic Design：原子化分层体系

五层结构

Atoms（原子）— 最小的不可再分组件
  Button, Input, Label, Icon, Avatar
      ↓ 组合
Molecules（分子）— 原子的功能组合
  SearchBar = Input + Button + Icon
  FormField = Label + Input + ErrorText
      ↓ 组合
Organisms（有机体）— 分子组成的独立区域
  Header = Logo + NavBar + SearchBar + Avatar
  DataTable = TableHeader + TableRow[] + Pagination
      ↓ 填入
Templates（模板）— 页面级布局结构（无真实数据）
  DashboardLayout = Sidebar + Header + ContentArea
      ↓ 填入
Pages（页面）— 填充真实数据的最终页面
  HomePage = DashboardLayout + 真实用户数据

核心哲学

Brad Frost 受化学启发：就像原子构成分子、分子构成有机体，UI 组件也应该从最小单位开始组合。关键是单向依赖：

• Atom 不知道 Molecule 的存在
• Molecule 不知道 Organism 的存在
• 每一层只依赖下一层

实际项目中的问题

优缺点

5. 三种方法的对比与取舍

6. 业界案例

Shopify Polaris

Shopify 的开源设计系统，服务于数千名开发者：

• Token 层: @shopify/polaris-tokens — JSON 定义，生成 CSS/JS/Figma
• 组件层: @shopify/polaris — React 组件库，扁平结构（不用 Atomic 分层）
• 治理: 专职 Design System 团队维护，严格的 PR 审查流程
• 关键教训: 最初用了 Atomic Design，后来放弃了，改为按功能分类（Actions, Layout, Navigation, Feedback…）

Alibaba / Meituan Flutter 实践

• 内部 Flutter pub 仓库 — 类似私有 npm registry，管理共享包版本
• 命名空间隔离 — 公共组件放 ali_ui_core，业务组件放 ali_ui_trade
• 三阶段演进: (1) 基础设施 → (2) 业务支撑 → (3) 跨端统一
• 关键教训: 不要一开始就追求完美的设计系统，先解决最痛的重复问题

Airbnb DLS (Design Language System)

• 跨平台统一: 同一套 Token 生成 iOS / Android / Web 三端代码
• 组件命名: 按照用户感知命名（Row, Panel, Toast），而不是技术层级
• "组件即文档": 组件自带使用示例和规范说明
• 关键教训: 设计系统的成功 80% 取决于推广和采用，只有 20% 取决于技术实现

7. Flutter 特有的 ThemeExtension 模式

Flutter 3.0 引入了 ThemeExtension<T>，解决了 Material 的 ColorScheme 不够用的问题。

问题

Material 的 ColorScheme 只有 ~30 个颜色槽位（primary, secondary, surface…）。但实际项目经常需要更多语义颜色：打卡状态色、评分星星色、品牌渐变色… 这些塞不进 ColorScheme。

解决方案：ThemeExtension

// 定义自定义 Token 集合
@immutable
class CeloriaBrandColors extends ThemeExtension<CeloriaBrandColors> {
  final Color brandPrimary;
  final Color brandAccent;
  final Color statusClockIn;
  final Color statusClockOut;
  final Color ratingStar;

  const CeloriaBrandColors({
    required this.brandPrimary,
    required this.brandAccent,
    required this.statusClockIn,
    required this.statusClockOut,
    required this.ratingStar,
  });

  @override
  CeloriaBrandColors copyWith({...}) => CeloriaBrandColors(...);

  @override
  CeloriaBrandColors lerp(CeloriaBrandColors? other, double t) {
    return CeloriaBrandColors(
      brandPrimary: Color.lerp(brandPrimary, other?.brandPrimary, t)!,
      // ... lerp 支持动画过渡
    );
  }
}

// 注册到 ThemeData
ThemeData(
  extensions: [
    CeloriaBrandColors(
      brandPrimary: CeloriaTokens.brandGold,
      brandAccent: CeloriaTokens.brandCocoaBrown,
      statusClockIn: CeloriaTokens.statusClockedIn,
      statusClockOut: CeloriaTokens.statusClockedOut,
      ratingStar: Color(0xFFFBBF24),
    ),
  ],
)

// 组件中使用
final brand = Theme.of(context).extension<CeloriaBrandColors>()!;
Container(color: brand.brandPrimary)

ThemeExtension 的价值

Theme 工厂模式

结合 Token + ThemeExtension，可以构建一个主题工厂，三端共用：

// celoria_ui/lib/theme/celoria_theme.dart
class CeloriaTheme {
  static ThemeData build({
    required Color primary,
    Color? secondary,
    Color? background,
    Color? surface,
    Color? error,
    Color? success,
    Brightness brightness = Brightness.light,
  }) {
    final scheme = ColorScheme.fromSeed(
      seedColor: primary,
      brightness: brightness,
    ).copyWith(
      primary: primary,
      secondary: secondary,
      surface: surface ?? CeloriaTokens.neutralSurface,
      error: error ?? CeloriaTokens.semanticError,
    );

    return ThemeData(
      useMaterial3: true,
      colorScheme: scheme,
      scaffoldBackgroundColor: background ?? CeloriaTokens.neutralBackground,
      extensions: [
        CeloriaBrandColors(brandPrimary: primary, ...),
      ],
      // ... 共享的按钮样式、卡片样式、输入框样式
    );
  }
}

// Guest App
theme: CeloriaTheme.build(
  primary: CeloriaTokens.brandGold,
  secondary: CeloriaTokens.brandCocoaBrown,
)

// Employee App
theme: CeloriaTheme.build(
  primary: CeloriaTokens.brandIndigo,
  background: CeloriaEmployeeTokens.neutralBackground,
  error: CeloriaEmployeeTokens.semanticError,
)

// Kiosk App
theme: CeloriaTheme.build(
  primary: CeloriaTokens.brandTeal,
  secondary: CeloriaTokens.brandCoral,
)

8. 反模式：Design System 的常见坑

组件直接引用 Token

class MyButton extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      style: ElevatedButton.styleFrom(
        // 组件直接耦合 token 常量
        backgroundColor: CeloriaTokens.brandGold,
        foregroundColor: CeloriaTokens.textOnPrimary,
      ),
      ...
    );
  }
}

class MyButton extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    // 从 Theme 获取，不直接引用 Token
    return ElevatedButton(
      // 样式由 ThemeData 统一控制
      // 组件本身不关心具体颜色
      onPressed: onPressed,
      child: child,
    );
  }
}

更多反模式

9. Celoria 项目的选择与理由

我们选择：Apple 扁平式 + Material Theme 系统

tokens.json (Single Source of Truth)
    ↓ generate.js
CeloriaTokens / CeloriaGuestTokens / CeloriaEmployeeTokens / CeloriaKioskTokens
    ↓
celoria_ui/
├── tokens/celoria_tokens.dart      # 自动生成，不手动编辑
├── theme/celoria_theme.dart        # ThemeData 工厂 (待建)
└── components/                     # 扁平组件库，按功能命名
    ├── loading_indicator.dart
    ├── error_view.dart
    ├── empty_state.dart
    ├── toast.dart
    ├── selectable_chip.dart         # 待建
    ├── selectable_card.dart         # 待建
    ├── pin_input.dart               # 待建
    ├── settings_menu_item.dart      # 待建
    └── tappable_contact.dart        # 待建

为什么这样选

重复组件审计结果

10. 演进路线：从简单到成熟

Phase 0 — 值统一 ✅ 已完成

tokens.json → 生成 Dart Token → 三端 app_theme.dart 引用 Token 而不是硬编码 hex 值

Phase 1 — Theme 工厂 + 已有组件替换

• 创建 CeloriaTheme.build() 工厂方法
• 三端用已有的 celoria_ui 组件替换本地 Loading/Error/Empty/Toast

Phase 2 — 提取高频共享组件

• 从 Guest + Kiosk 提取 CeloriaSelectableChip、CeloriaSelectableCard
• 从 Employee + Kiosk 提取 CeloriaPinInput
• 从 Employee 提取 CeloriaSettingsMenuItem
• Rule of Three: 只有 ≥2 个 App 需要的组件才提取

Phase 3 — 新功能直接用共享库开发

• 新增 feature 时，通用 UI 组件先在 celoria_ui 开发 + Widgetbook 预览
• App 层只做页面组装和业务逻辑

Phase 4 — 工具链成熟化（可选）

• Widgetbook Golden Tests — 截图对比，防止视觉回归
• CI 守护 — 禁止 App 中出现硬编码 hex 颜色值
• Figma Token Studio — 设计师直接编辑 Token，自动同步到代码

11. 延伸阅读

书籍与文章

• Atomic Design by Brad Frost — 原始方法论。即使不采用，理解概念有助于和设计师沟通
• Material Design 3 Guidelines — Google 的完整设计规范，Token 系统文档尤其有价值
• Apple Human Interface Guidelines — 理解 Apple 的"扁平组件 + 设计原则"哲学
• Design Systems by Alla Kholmatova (Smashing Magazine) — 设计系统的组织与治理

开源设计系统参考

• Shopify Polaris — React 组件库 + Token 包，从 Atomic 回归扁平的典型案例
• GitHub Primer — GitHub 的设计系统，Token-first 方法的优秀实现
• Atlassian Design System — 大规模团队的设计系统治理模型
• Chakra UI — Theme-driven 组件库，ThemeExtension 思路的 Web 版对标

Flutter 特定资源

• Widgetbook — Flutter 版 Storybook，组件目录预览工具
• ThemeExtension 官方文档 — Flutter API docs 中 ThemeExtension 的用法
• Very Good Ventures 的 Flutter 架构 — 业界知名 Flutter 咨询公司的项目结构最佳实践