| name | expo-design-system |
| description | Airbnb-DLS-aligned design system engineering for Expo / React Native apps targeting both web and native iOS, built on Unistyles v3, Reanimated, Skia, and FlashList. Use whenever building, reviewing, or refactoring shared UI — design tokens, theming, variant-driven component APIs, typography, spacing, cross-platform web/iOS parity, native-feel performance, or complex surfaces like calendars and drawing canvases (examples use a clinic app). Covers token architecture, theming, component API contracts (variants over style props), web/iOS parity (Unistyles `_web` hover/focus/cursor, Platform splits, one shared theme), the Unistyles styling engine, and governance. Trigger even when the user does not say "design system" but is creating or changing reusable React Native components, tokens, theme code, or making a component behave natively on both web and iOS. Teaches how to BUILD the design system; pair with expo-react-native-coder for features and expo-ios-hig for iOS native-feel decisions. |
Airbnb DLS Expo React Native Design System Best Practices
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.
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+
Scope & Relationship to Sibling Skills
| Sibling Skill | Its Focus | This Skill's Focus |
|---|
ios-design-system | The SwiftUI design system for the same clinic app | The 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 optimization | Native-feel performance inside the design system |
react | General React patterns | Expo / 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 |
Clinic Architecture Contract (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
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
Rule Categories by Priority
| Priority | Category | Impact | Prefix | Rules |
|---|
| 1 | Token Architecture | CRITICAL | token- | 6 |
| 2 | Theming & Adaptivity | CRITICAL | theme- | 5 |
| 3 | Component API Contracts | CRITICAL | api- | 8 |
| 4 | Cross-Platform Parity | CRITICAL | platform- | 5 |
| 5 | Reuse & System Fit | HIGH | reuse- | 4 |
| 6 | Styling Engine (Unistyles) | HIGH | style- | 6 |
| 7 | Typography & Iconography | HIGH | type- | 5 |
| 8 | Spacing, Layout & Safe Areas | HIGH | space- | 5 |
| 9 | Native-Feel & Performance | HIGH | perf- | 7 |
| 10 | Complex Domain Components | MEDIUM-HIGH | domain- | 6 |
| 11 | Governance & Consistency | MEDIUM | govern- | 6 |
Quick Reference
1. Token Architecture (CRITICAL)
2. Theming & Adaptivity (CRITICAL)
3. Component API Contracts (CRITICAL)
4. Cross-Platform Parity (CRITICAL)
5. Reuse & System Fit (HIGH)
6. Styling Engine (Unistyles) (HIGH)
7. Typography & Iconography (HIGH)
8. Spacing, Layout & Safe Areas (HIGH)
9. Native-Feel & Performance (HIGH)
10. Complex Domain Components (MEDIUM-HIGH)
11. Governance & Consistency (MEDIUM)
How to Use
Read individual reference files for detailed explanations and code examples:
Reference Files
