Back to Details

expo-design-system

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Airbnb DLS Expo React Native Design System Best Practices

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

Opinionated, strict design system engineering for Expo / React Native apps on the New Architecture, targeting both web and native iOS. Contains 63 rules across 11 categories, prioritized by impact. Derived from Airbnb's Design Language System (DLS), the Unistyles v3 documentation, and the React Native ecosystem (Reanimated, Gesture Handler, Skia, FlashList, Expo SDK). The styling engine is Unistyles v3; the component API follows the Airbnb DLS pattern of variant props over style escape hatches.
针对采用新架构、同时支持Web和原生iOS的Expo / React Native应用，提供具有明确观点的严格设计系统工程方案。包含11个分类下的63条规则，按影响优先级排序。方案源自Airbnb设计语言系统（DLS）、Unistyles v3文档及React Native生态（Reanimated、Gesture Handler、Skia、FlashList、Expo SDK）。样式引擎采用Unistyles v3；组件API遵循Airbnb DLS模式，优先使用变体属性而非样式逃逸通道。

Mandated Architecture Alignment

强制架构对齐

This skill is the infrastructure layer — it teaches how to BUILD the design system itself, the React Native counterpart to 
ios-design-system
. All code examples follow the same non-negotiable constraints:
  • Feature modules import 
    @clinic/design-system
    + 
    domain
    ; never another feature's internals
  • The design system owns the Unistyles theme (tokens, breakpoints) and exports a curated public surface
  • Reuse before you build: read the index, extend a variant, promote on the second use — never a parallel local component
  • Components expose variant and slot props (Airbnb DLS); no raw 
    style
    escape hatch
  • Animation and gestures run on the UI thread (Reanimated worklets + Gesture Handler)
  • Lists use FlashList; the body-chart drawing surface uses React Native Skia
  • One source feels native on both web and iOS: Unistyles 
    _web
    pseudo-states and 
    Platform
    splits, never a forked web stylesheet
  • Targets the New Architecture (Fabric/JSI), Expo SDK 53+ / React Native 0.81+
本技能属于基础设施层——教授如何构建设计系统本身，是
ios-design-system
对应的React Native版本。所有代码示例遵循以下不可协商的约束：
  • 功能模块仅导入
    @clinic/design-system
    + 
    domain
    ；绝不导入其他功能模块的内部代码
  • 设计系统拥有Unistyles主题（令牌、断点）并导出经过筛选的公共接口
  • 优先复用再构建：先查看索引，扩展变体，第二次使用时再升级为公共组件——绝不创建并行的本地组件
  • 组件暴露变体和插槽属性（Airbnb DLS）；不提供原始
    style
    逃逸通道
  • 动画和手势在UI线程运行（Reanimated worklets + Gesture Handler）
  • 列表使用FlashList；身体图表绘图界面使用React Native Skia
  • 单一代码库实现Web和iOS原生体验：使用Unistyles的
    _web
    伪状态和
    Platform
    拆分，绝不使用分叉的Web样式表
  • 目标为新架构（Fabric/JSI）、Expo SDK 53+ / React Native 0.81+

Scope & Relationship to Sibling Skills

范围与关联技能的关系

Sibling SkillIts FocusThis Skill's Focus
ios-design-system
The SwiftUI design system for the same clinic appThe Expo / React Native counterpart
expo-react-native-coder
Feature development (screens, navigation, data fetching)Design system infrastructure (tokens, components, theming)
expo-react-native-performance
App-wide performance optimizationNative-feel performance inside the design system
react
General React patternsExpo / React Native design system specifics
expo-ios-hig
iOS native-feel decisions (navigation, system controls, Liquid Glass)Cross-platform token/component architecture + web/iOS parity
关联技能其核心关注点本技能核心关注点
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一致性

Clinic Architecture Contract (Expo / React Native)

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

All guidance in this skill assumes the clinic modular architecture:
  • Feature modules depend on 
    @clinic/design-system
    + 
    domain
    only; the app target wires navigation (Expo Router) and dependency injection
  • The design system is a local package with a single public entry; raw token layers stay private
  • Token source of truth is the Unistyles theme; features never define local tokens
  • Server state uses TanStack Query: reads default to stale-while-revalidate, writes are optimistic and queued for offline sync
  • The New Architecture is required for Unistyles v3, Reanimated worklets, Skia, and FlashList v2
本技能中的所有指导均基于诊所应用的模块化架构：
  • 功能模块仅依赖
    @clinic/design-system
    + 
    domain
    ；应用入口负责配置导航（Expo Router）和依赖注入
  • 设计系统是一个本地包，仅有一个公共入口；原始令牌层保持私有
  • 令牌的唯一可信来源是Unistyles主题；功能模块绝不定义本地令牌
  • 服务端状态使用TanStack Query：读取默认采用stale-while-revalidate策略，写入采用乐观更新并支持离线同步排队
  • 新架构是使用Unistyles v3、Reanimated worklets、Skia和FlashList v2的必要条件

When to Apply

适用场景

Reference these guidelines when:
  • Setting up a design system for a new Expo / React Native app
  • Building token architecture (colors, typography, spacing, radius, elevation) in the Unistyles theme
  • Designing component APIs — variants, slots, controlled/uncontrolled state, refs, accessibility
  • Authoring component styles with Unistyles StyleSheet, variants, and dynamic functions
  • Building the calendar, treatment-note editor, or Skia body-chart drawing surfaces
  • Migrating ad-hoc styles to a governed token system
  • Reviewing PRs for raw colors, inline styles, leaked 
    style
    props, or feature-local tokens
  • Tuning native feel — list virtualization, UI-thread animation, gestures, haptics, safe areas
  • Making a component render and feel native on both web and iOS — hover/focus/cursor, 
    Platform
    splits, and safe-area/haptics divergences
  • Deciding whether to build new or reuse — checking the design system index, extending vs forking, or using a native/
    @expo/ui
    control instead of reimplementing one
在以下场景中参考本指南：
  • 为新的Expo / React Native应用搭建设计系统
  • 在Unistyles主题中构建令牌架构（颜色、排版、间距、圆角、阴影层级）
  • 设计组件API——变体、插槽、受控/非受控状态、refs、无障碍支持
  • 使用Unistyles StyleSheet、变体和动态函数编写组件样式
  • 构建日历、诊疗笔记编辑器或Skia身体图表绘图界面
  • 将临时样式迁移到受治理的令牌系统
  • 评审PR，检查是否存在原始颜色、内联样式、泄露的
    style
    属性或功能模块本地令牌
  • 调优原生体验——列表虚拟化、UI线程动画、手势、触觉反馈、安全区域
  • 让组件在Web和iOS端均能原生渲染并交互——悬停/焦点/光标、
    Platform
    拆分、安全区域/触觉反馈差异处理
  • 决定是构建新组件还是复用现有组件——查看设计系统索引、选择扩展而非分叉、优先使用原生/
    @expo/ui
    控件而非重新实现

Rule Categories by Priority

按优先级排序的规则分类

PriorityCategoryImpactPrefixRules
1Token ArchitectureCRITICAL
token-
6
2Theming & AdaptivityCRITICAL
theme-
5
3Component API ContractsCRITICAL
api-
8
4Cross-Platform ParityCRITICAL
platform-
5
5Reuse & System FitHIGH
reuse-
4
6Styling Engine (Unistyles)HIGH
style-
6
7Typography & IconographyHIGH
type-
5
8Spacing, Layout & Safe AreasHIGH
space-
5
9Native-Feel & PerformanceHIGH
perf-
7
10Complex Domain ComponentsMEDIUM-HIGH
domain-
6
11Governance & ConsistencyMEDIUM
govern-
6
优先级分类影响级别前缀规则数量
1令牌架构关键
token-
6
2主题与适配性关键
theme-
5
3组件API约定关键
api-
8
4跨平台一致性关键
platform-
5
5复用与系统适配高
reuse-
4
6样式引擎（Unistyles）高
style-
6
7排版与图标系统高
type-
5
8间距、布局与安全区域高
space-
5
9原生质感与性能高
perf-
7
10复杂领域组件中高
domain-
6
11治理与一致性中
govern-
6

Quick Reference

快速参考

1. Token Architecture (CRITICAL)

1. 令牌架构（关键）

  • token-three-layer-scale
     - Layer tokens as raw, semantic, and component scales
  • token-define-in-unistyles-theme
     - Keep the Unistyles theme as the single token source
  • token-no-raw-values-in-components
     - Route every color and size through tokens
  • token-semantic-naming
     - Name tokens by role, not by value
  • token-elevation-pairs
     - Tokenize elevation as surface and shadow pairs
  • token-avoid-over-abstraction
     - Stop at three token layers
  • 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. Theming & Adaptivity (CRITICAL)

2. 主题与适配性（关键）

  • theme-runtime-not-rerender
     - Switch themes via the runtime, no re-render
  • theme-stylesheet-theme-arg
     - Read theme from the StyleSheet argument
  • theme-adaptive-system
     - Follow the system color scheme by default
  • theme-breakpoints-responsive
     - Use breakpoints, not Dimensions checks
  • theme-config-single-module
     - One typed config module for themes and breakpoints
  • theme-runtime-not-rerender
     - 通过运行时切换主题，无需重新渲染
  • theme-stylesheet-theme-arg
     - 从StyleSheet参数中读取主题
  • theme-adaptive-system
     - 默认跟随系统配色方案
  • theme-breakpoints-responsive
     - 使用断点，而非Dimensions检查
  • theme-config-single-module
     - 使用单个类型化配置模块管理主题和断点

3. Component API Contracts (CRITICAL)

3. 组件API约定（关键）

  • api-variants-over-style-prop
     - Express visual options as variant props
  • api-no-style-escape-hatch
     - No raw style prop on components
  • api-compound-variants
     - Compound variants over per-combination components
  • api-slots-for-composition
     - Slot props over a prop per element
  • api-controlled-uncontrolled
     - Support controlled and uncontrolled state
  • api-forward-ref
     - Forward refs from leaf components
  • api-accessibility-in-contract
     - Require accessibility props in the contract
  • api-aschild-polymorphism
     - Offer asChild instead of wrapper nesting
  • api-variants-over-style-prop
     - 将视觉选项表示为变体属性
  • api-no-style-escape-hatch
     - 组件不提供原始style属性
  • api-compound-variants
     - 使用复合变体而非为每种组合单独创建组件
  • api-slots-for-composition
     - 使用插槽属性而非为每个元素单独设置属性
  • api-controlled-uncontrolled
     - 支持受控和非受控状态
  • api-forward-ref
     - 从叶子组件转发refs
  • api-accessibility-in-contract
     - 约定中强制要求无障碍属性
  • api-aschild-polymorphism
     - 提供asChild属性而非嵌套包装器

4. Cross-Platform Parity (CRITICAL)

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

  • platform-web-pseudo-states
     - Add web hover, focus, and cursor to interactive components
  • platform-guard-native-only
     - Guard native-only APIs behind Platform checks with web fallbacks
  • platform-divergence-split
     - Isolate platform differences behind one component API
  • platform-input-model
     - Design for pointer and touch, never hover-only
  • platform-shared-theme-parity
     - One theme for web and native, with a known divergence map
  • 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 & System Fit (HIGH)

5. 复用与系统适配（高）

  • reuse-inventory-first
     - Read the design system index before writing any style
  • reuse-extend-not-fork
     - Extend a shared component with a variant, don't fork a local one
  • reuse-promote-on-second-use
     - Promote a pattern to the system on its second use
  • reuse-platform-component-first
     - Reach for a native control before reimplementing one
  • reuse-inventory-first
     - 编写任何样式前先查看设计系统索引
  • reuse-extend-not-fork
     - 通过扩展变体复用共享组件，而非创建本地分叉组件
  • reuse-promote-on-second-use
     - 模式第二次使用时升级为系统公共组件
  • reuse-platform-component-first
     - 优先使用原生控件而非重新实现

6. Styling Engine (Unistyles) (HIGH)

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

  • style-stylesheet-create
     - StyleSheet.create over inline objects
  • style-variants-api
     - Variants over ternary style arrays
  • style-dynamic-functions
     - Dynamic functions for prop-driven values
  • style-no-inline-array-merge
     - No inline array merges in lists
  • style-withunistyles-third-party
     - Theme third-party components with withUnistyles
  • style-press-states-from-variants
     - Press and disabled states as variants
  • 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. Typography & Iconography (HIGH)

7. 排版与图标系统（高）

  • type-scale-tokens
     - Define a named typography scale
  • type-respect-font-scaling
     - Respect OS font scaling
  • type-text-component-wrapper
     - Route text through one typed component
  • type-font-loading-expo-font
     - Load fonts before first paint
  • type-icon-registry
     - Centralize icons in a typed registry
  • type-scale-tokens
     - 定义命名的排版比例
  • type-respect-font-scaling
     - 尊重系统字体缩放设置
  • type-text-component-wrapper
     - 所有文本均通过单个类型化组件传递
  • type-font-loading-expo-font
     - 首次绘制前加载字体
  • type-icon-registry
     - 将图标集中管理在类型化注册表中

8. Spacing, Layout & Safe Areas (HIGH)

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

  • space-spacing-scale
     - Use a spacing scale on a 4pt grid
  • space-safe-area-insets
     - Apply safe-area insets at screen edges
  • space-touch-targets
     - Size touch targets to at least 44 points
  • space-gap-over-margins
     - Use gap over per-child margins
  • space-radius-tokens
     - Tokenize corner radius by role
  • space-spacing-scale
     - 使用基于4pt网格的间距比例
  • space-safe-area-insets
     - 在屏幕边缘应用安全区域内边距
  • space-touch-targets
     - 触摸目标尺寸至少为44pt
  • space-gap-over-margins
     - 使用gap而非子元素margin
  • space-radius-tokens
     - 按角色为圆角设置令牌

9. Native-Feel & Performance (HIGH)

9. 原生质感与性能（高）

  • perf-flashlist-for-lists
     - FlashList over ScrollView lists
  • perf-reanimated-ui-thread
     - Animate on the UI thread
  • perf-gesture-handler
     - Gesture Handler over PanResponder
  • perf-expo-image
     - Load images with expo-image and caching
  • perf-memoize-list-items
     - Memoize rows and callbacks
  • perf-haptics-key-actions
     - Add haptics on confirmations and toggles
  • perf-defer-offscreen-work
     - Defer work past transitions
  • 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. Complex Domain Components (MEDIUM-HIGH)

10. 复杂领域组件（中高）

  • domain-calendar-virtualization
     - Virtualize the appointment calendar by day
  • domain-note-editor-autosave
     - Offline-first debounced note autosave
  • domain-bodychart-skia-canvas
     - Draw body charts on a Skia canvas
  • domain-bodychart-gesture-paths
     - Capture strokes via gestures and shared values
  • domain-compose-from-primitives
     - Build domain components from primitives
  • domain-optimistic-writes
     - Render optimistic UI for writes
  • 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. Governance & Consistency (MEDIUM)

11. 治理与一致性（中）

  • govern-design-system-package
     - Package the design system with one entry
  • govern-lint-no-raw-values
     - Lint against raw colors and inline styles
  • govern-prevent-local-tokens
     - Prevent feature-local tokens
  • govern-storybook-catalog
     - Catalog component variants in Storybook
  • govern-naming-conventions
     - Enforce one naming convention
  • govern-incremental-migration
     - Migrate to tokens incrementally
  • govern-design-system-package
     - 将设计系统打包为单个入口的包
  • govern-lint-no-raw-values
     - 通过Lint禁止原始颜色和内联样式
  • govern-prevent-local-tokens
     - 禁止功能模块定义本地令牌
  • govern-storybook-catalog
     - 在Storybook中展示组件变体
  • govern-naming-conventions
     - 强制执行统一命名规范
  • govern-incremental-migration
     - 逐步迁移到令牌系统

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:
  • Section definitions - Category structure and impact levels
  • Rule template - Template for adding new rules
阅读单个参考文件获取详细说明和代码示例：
  • 分类定义 - 分类结构和影响级别
  • 规则模板 - 添加新规则的模板

Reference Files

参考文件

FileDescription
references/_sections.mdCategory definitions and ordering
assets/templates/_template.mdTemplate for new rules
metadata.jsonVersion and reference information
文件描述
references/_sections.md分类定义与排序
assets/templates/_template.md新规则模板
metadata.json版本与参考信息