expo-design-system

Airbnb DLS Expo React Native 设计系统最佳实践

面向 Expo / React Native 应用的严格设计系统工程实践，适用于新架构，并同时支持 Web 和原生 iOS。包含 11 个类别中的 63 条规则，并按影响程度排序。内容源自 Airbnb 的 Design Language System（DLS）、Unistyles v3 文档和 React Native 生态系统（Reanimated、Gesture Handler、Skia、FlashList、Expo SDK）。样式引擎为 Unistyles v3；组件 API 遵循 Airbnb DLS 模式，优先使用变体属性，而非样式逃生口。

强制架构约束

此技能属于基础设施层——它讲解如何构建设计系统本身，是 React Native 版的 ios-design-system。所有代码示例均遵循以下不可协商的约束：

• 功能模块只导入 @clinic/design-system 和 domain；绝不导入其他功能模块的内部实现
• 设计系统负责 Unistyles 主题（令牌、断点），并导出经过精心筛选的公共接口
• 先复用再构建：先阅读索引，扩展变体，在第二次使用时提升为公共组件——绝不创建并行的本地组件
• 组件通过变体属性和插槽属性公开功能（Airbnb DLS）；不提供原始 style 逃生口
• 动画和手势在 UI 线程运行（Reanimated worklet + Gesture Handler）
• 列表使用 FlashList；身体图表绘制区域使用 React Native Skia
• 同一份代码在 Web 和 iOS 上都应呈现原生体验：使用 Unistyles _web 伪状态和 Platform 分流，绝不拆分为独立的 Web 样式表
• 目标平台为新架构（Fabric/JSI）、Expo SDK 53+ / React Native 0.81+

范围及与相关技能的关系

相关技能	其关注点	本技能的关注点
ios-design-system	同一款诊所应用的 SwiftUI 设计系统	Expo / React Native 对应方案
expo-react-native-coder	功能开发（屏幕、导航、数据获取）	设计系统基础设施（令牌、组件、主题）
expo-react-native-performance	全应用范围的性能优化	设计系统内部的原生体验性能
react	通用 React 模式	Expo / React Native 设计系统专项内容
expo-ios-hig	原生 iOS 体验相关决策（导航、系统控件、Liquid Glass）	跨平台令牌／组件架构 + Web/iOS 一致性

诊所架构约定（Expo / React Native）

本技能中的所有指导均基于诊所的模块化架构：

• 功能模块仅依赖 @clinic/design-system 和 domain；应用目标负责接入导航（Expo Router）和依赖注入
• 设计系统是一个本地包，只有一个公共入口；原始令牌层保持私有
• 令牌的唯一事实来源是 Unistyles 主题；功能模块绝不定义本地令牌
• 服务端状态使用 TanStack Query：读取操作默认采用 stale-while-revalidate，写入操作采用乐观更新，并排队等待离线同步
• Unistyles v3、Reanimated worklet、Skia 和 FlashList v2 均要求使用新架构

适用场景

在以下情况下，请参考这些指南：

• 为新的 Expo / React Native 应用搭建设计系统
• 在 Unistyles 主题中构建令牌架构（颜色、排版、间距、圆角、层级）
• 设计组件 API——变体、插槽、受控／非受控状态、引用、无障碍支持
• 使用 Unistyles StyleSheet、变体和动态函数编写组件样式
• 构建日历、治疗记录编辑器或基于 Skia 的身体图表绘制界面
• 将临时样式迁移到受治理的令牌系统
• 审查 PR，检查原始颜色、内联样式、泄露的 style 属性或功能本地令牌
• 调整原生体验——列表虚拟化、UI 线程动画、手势、触觉反馈、安全区域
• 让组件在 Web 和 iOS 上都能呈现原生体验——悬停／焦点／光标、Platform 分支，以及安全区域／触觉反馈差异
• 判断是新建还是复用——检查设计系统索引、扩展还是分叉，或使用原生／@expo/ui 控件，而不是重新实现

按优先级划分的规则类别

优先级	类别	影响	前缀	规则数
1	令牌架构	CRITICAL	token-	6
2	主题与自适应	CRITICAL	theme-	5
3	组件 API 契约	CRITICAL	api-	8
4	跨平台一致性	CRITICAL	platform-	5
5	复用与系统适配	HIGH	reuse-	4
6	样式引擎（Unistyles）	HIGH	style-	6
7	排版与图标	HIGH	type-	5
8	间距、布局与安全区域	HIGH	space-	5
9	原生体验与性能	HIGH	perf-	7
10	复杂领域组件	MEDIUM-HIGH	domain-	6
11	治理与一致性	MEDIUM	govern-	6

快速参考

1. 令牌架构（CRITICAL）

• token-three-layer-scale - 将令牌分为原始、语义和组件层级
• token-define-in-unistyles-theme - 将 Unistyles 主题作为唯一令牌来源
• token-no-raw-values-in-components - 所有颜色和尺寸都通过令牌指定
• token-semantic-naming - 按角色而非数值为令牌命名
• token-elevation-pairs - 将层级令牌化为表面和阴影配对
• token-avoid-over-abstraction - 令牌层级最多保留三层

2. 主题与自适应（CRITICAL）

• theme-runtime-not-rerender - 通过运行时切换主题，无需重新渲染
• theme-stylesheet-theme-arg - 从 StyleSheet 参数读取主题
• theme-adaptive-system - 默认遵循系统配色方案
• theme-breakpoints-responsive - 使用断点，而非检查 Dimensions
• theme-config-single-module - 使用一个类型化配置模块管理主题和断点

3. 组件 API 契约（关键）

• api-variants-over-style-prop - 使用变体属性表达视觉选项
• api-no-style-escape-hatch - 组件上不提供原始 style 属性
• api-compound-variants - 使用复合变体，而非为每种组合创建组件
• api-slots-for-composition - 使用插槽属性，而非为每个元素单独设置属性
• api-controlled-uncontrolled - 同时支持受控和非受控状态
• api-forward-ref - 从叶组件转发 ref
• api-accessibility-in-contract - 在契约中要求提供无障碍属性
• api-aschild-polymorphism - 提供 asChild，而非嵌套包装器

4. 跨平台一致性（关键）

• platform-web-pseudo-states - 为交互组件添加 Web 悬停、焦点和光标样式
• platform-guard-native-only - 使用 Platform 检查保护仅限原生平台的 API，并提供 Web 回退方案
• platform-divergence-split - 通过单一组件 API 隔离平台差异
• platform-input-model - 同时考虑指针和触摸输入，绝不只依赖悬停
• platform-shared-theme-parity - Web 和原生平台共用一个主题，并明确已知的差异

5. 复用与系统集成（高）

• reuse-inventory-first - 编写任何样式前，先阅读设计系统索引
• reuse-extend-not-fork - 为共享组件添加变体，而非在本地派生一个组件
• reuse-promote-on-second-use - 某个模式第二次使用时，将其纳入系统
• reuse-platform-component-first - 优先使用原生控件，而非重新实现

6. 样式引擎（Unistyles）（高）

• style-stylesheet-create - 使用 StyleSheet.create，而非内联对象
• style-variants-api - 使用变体，而非三元样式数组
• style-dynamic-functions - 使用动态函数处理由属性驱动的值
• style-no-inline-array-merge - 列表中不使用内联数组合并
• style-withunistyles-third-party - 使用 withUnistyles 为第三方组件应用主题
• style-press-states-from-variants - 将按下和禁用状态设为变体

7. 排版与图标（高）

• type-scale-tokens - 定义具名的排版比例
• type-respect-font-scaling - 遵循操作系统字体缩放设置
• type-text-component-wrapper - 通过一个类型化组件处理文本
• type-font-loading-expo-font - 在首次绘制前加载字体
• type-icon-registry - 在类型化注册表中集中管理图标

8. 间距、布局与安全区域（HIGH）

• space-spacing-scale - 使用基于 4pt 网格的间距比例
• space-safe-area-insets - 在屏幕边缘应用安全区域内边距
• space-touch-targets - 将触控目标尺寸设为至少 44 points
• space-gap-over-margins - 优先使用 gap，而不是为每个子项设置边距
• space-radius-tokens - 按用途将圆角半径定义为令牌

9. 原生体验与性能（HIGH）

• perf-flashlist-for-lists - 列表使用 FlashList，而不是 ScrollView
• perf-reanimated-ui-thread - 在 UI 线程上执行动画
• perf-gesture-handler - 使用 Gesture Handler，而不是 PanResponder
• perf-expo-image - 使用 expo-image 和缓存加载图像
• perf-memoize-list-items - 对行和回调进行记忆化
• perf-haptics-key-actions - 在确认操作和切换操作时添加触觉反馈
• perf-defer-offscreen-work - 将工作延后到过渡完成后执行

10. 复杂领域组件（MEDIUM-HIGH）

• domain-calendar-virtualization - 按天对预约日历进行虚拟化
• domain-note-editor-autosave - 离线优先、经防抖处理的笔记自动保存
• domain-bodychart-skia-canvas - 在 Skia 画布上绘制身体图表
• domain-bodychart-gesture-paths - 通过手势和共享值捕获笔画
• domain-compose-from-primitives - 使用基础组件构建领域组件
• domain-optimistic-writes - 为写入操作渲染乐观 UI

11. 治理与一致性（MEDIUM）

• govern-design-system-package - 将设计系统打包为单一入口
• govern-lint-no-raw-values - 通过 lint 检查禁止使用原始颜色和内联样式
• govern-prevent-local-tokens - 防止使用功能局部令牌
• govern-storybook-catalog - 在 Storybook 中汇总组件变体
• govern-naming-conventions - 强制采用统一的命名规范
• govern-incremental-migration - 逐步迁移到令牌

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 分类结构和影响级别
• 规则模板 - 添加新规则的模板

参考文件

文件	描述
references/_sections.md	分类定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息