Catalog
expo/expo-design-system

expo

expo-design-system

Create or extend an Expo app's theme, design tokens, and reusable component conventions. Use for inconsistent styling, generic or AI-generated screens, component libraries, or audits of hardcoded colors, spacing, and fonts. Works with existing NativeWind, Tamagui, Restyle, and Unistyles systems. For platform styling and native controls, use expo-native-ui; for new app folder layouts, use expo-project-structure.

NewUpdated Nov 20, 2026

Expo Design Systems

Make every screen in an app draw from one visual source of truth: a token theme and a small set of reusable components. This skill defines where tokens live, what they cover, how reusable components are shaped, and when a repeated view earns promotion into the system.

Sibling skills own the layers around this one:

  • expo-native-ui - platform styling rules (HIG, semantic colors, controls, shadows syntax). Follow it for what values look native; follow this skill for where values live and how they're reused.
  • expo-project-structure - folder skeleton for new apps.

For Tailwind projects, keep tokens in global.css as CSS variables and follow the styling library's own setup guidance. The scales and naming in this skill still apply; only the storage format changes.

References

Consult these resources as needed:

references/
  audit.md        Audit an existing app for design-system drift: grep checks,
                  scoring rubric, incremental adoption plan, and templates for
                  documenting or extending components
  native-slop.md  The 20 named anti-pattern tells of AI-generated apps (The Web
                  Modal, Everything's a Card, ...) with grep checks for the greppable ones

Adopt Before You Build

In an app that already has screens, the first move is detection, not construction. Before writing any token file:

  1. Look for a declared system. Check package.json for a styling library - NativeWind/Tailwind, Tamagui, Restyle, Unistyles, styled-components. Then look for a token file: theme.ts, src/theme/, constants/theme.ts, or constants/Colors.ts (the create-expo-app default).
  2. If one exists, it is the source of truth. Extend it in its own idiom - its names, its scale, its storage format. Audit drift against that system, not against the examples below.
  3. If only de facto values exist - the same greys and paddings repeated across screens, no theme file - there is no system yet. Those values are the input to the scales, not the authority: derive tokens from the most frequent ones, snapped to the 4-point grid (references/audit.md §5).
  4. Never introduce a second system beside an existing one. A fresh src/theme/ next to a Tamagui config is design-system drift, not adoption.

Only when nothing exists do the defaults below apply as written.

The Theme

In an app without an existing system, all design tokens live under src/theme/. In a project without a src/ folder (the default create-expo-app template has app/, components/, and constants/ at the root), use the equivalent top-level location - typically theme/ or the existing constants/ - and keep the same file layout. Start small and split by token class as it grows:

src/theme/
  colors.ts       # see expo-native-ui "Colors" for the palette pattern
  spacing.ts
  typography.ts
  radius.ts
  shadows.ts
  motion.ts
  index.ts        # re-exports everything: import { spacing, type } from "@/theme"

A brand-new app can begin with a single src/theme.ts holding all of the objects below, then promote it to the folder form once any one class needs its own file (same promotion rule as components). Either way there is exactly one theme entry point - never two competing token files.

Rules that make a theme worth having:

  • Every repeated visual value is a token. A literal that appears twice belongs in the theme.
  • Components import tokens; screens import components. A screen file that imports spacing for layout padding is fine; a screen file redefining a button color is drift.
  • Never hardcode hex colors, font sizes, or spacing multiples outside src/theme/. One-off values that are genuinely local (an icon's 17px optical nudge) may stay inline - with a comment saying why.

Colors

Build the palette from platform semantic colors: Color from expo-router wrapped in Platform.select, centralized in theme/colors.ts. Semantic colors resolve on-device and adapt to light/dark automatically - prefer them for backgrounds, labels, and separators. (expo-native-ui "Colors" covers the full palette and rationale; the minimal version is:)

// theme/colors.ts
import { Platform } from "react-native";
import { Color } from "expo-router";

export const colors = {
  label: Platform.select({
    ios: Color.ios.label,
    android: Color.android.dynamic.onSurface,
    default: "#000000",
  })!,
  secondaryLabel: Platform.select({
    ios: Color.ios.secondaryLabel,
    android: Color.android.dynamic.onSurfaceVariant,
    default: "#3c3c43",
  })!,
  separator: Platform.select({
    ios: Color.ios.separator,
    android: Color.android.dynamic.outlineVariant,
    default: "#c6c6c8",
  })!,
  systemBackground: Platform.select({
    ios: Color.ios.systemBackground,
    android: Color.android.dynamic.surface,
    default: "#ffffff",
  })!,
  systemBlue: Platform.select({
    ios: Color.ios.systemBlue,
    android: Color.android.dynamic.primary,
    default: "#007aff",
  })!,
  // Deliberately fixed: text on a tinted (accent) surface stays white in both modes.
  onTint: "#ffffff",
};

Add brand colors as explicit light/dark pairs only when the brand requires values the platform doesn't provide:

// theme/colors.ts (brand additions)
import { useColorScheme } from "react-native";

const brandPalette = {
  light: { accent: "#5B21B6", accentContrast: "#FFFFFF" },
  dark: { accent: "#A78BFA", accentContrast: "#1E1B4B" },
} as const;

export function useBrandColors() {
  const scheme = useColorScheme();
  return brandPalette[scheme === "dark" ? "dark" : "light"];
}

Keep the brand set tiny (accent, accentContrast, maybe a tint per feature). Everything else stays semantic.

Static-safe vs hook-only. The two patterns above have different reach - keep the boundary explicit:

  • Semantic/platform colors (colors above) are static-safe: they resolve on-device, so plain token files like theme/typography.ts can import them at module scope.
  • Brand light/dark pairs are hook-only: useBrandColors() reads the color scheme at render time, so brand colors can only be applied inside components. A static token file cannot call the hook.
  • Never mix the two in one file. If a static style (a type ramp step, a variants object) needs the brand accent, either apply the brand color in the component at render time, or wrap the pair in a static dynamic color (DynamicColorIOS on iOS) so it becomes static-safe.

Spacing

One scale, based on a 4-point grid. Name steps by size, not by use:

// theme/spacing.ts
export const spacing = {
  xs: 4,
  sm: 8,
  md: 16,
  lg: 24,
  xl: 32,
  xxl: 48,
} as const;
  • Use gap with spacing tokens for layout rhythm (expo-native-ui prefers gap over margin).
  • Screen edge padding is spacing.md unless the design says otherwise - pick one and keep it.
  • If a layout needs a value between steps, use the nearest step. The grid is the point.
  • If the same in-between multiple of 4 keeps recurring (12 and 20 are common), add it to the scale as a named step instead of scattering literals. The audit whitelist must then include it too.

Typography

Define named text styles, not raw font sizes. Mirror the platform ramp (Apple text styles) so sizes feel native:

// theme/typography.ts
import { TextStyle } from "react-native";
import { colors } from "./colors";

export const type = {
  largeTitle: { fontSize: 34, fontWeight: "700", color: colors.label },
  title: { fontSize: 22, fontWeight: "600", color: colors.label },
  headline: { fontSize: 17, fontWeight: "600", color: colors.label },
  body: { fontSize: 17, fontWeight: "400", color: colors.label },
  subhead: { fontSize: 15, fontWeight: "400", color: colors.secondaryLabel },
  caption: { fontSize: 12, fontWeight: "400", color: colors.secondaryLabel },
} as const satisfies Record<string, TextStyle>;

If the project bundles static font files (one file per weight, loaded with expo-font or the config plugin), set weight via fontFamily names instead and omit fontWeight - otherwise iOS synthesizes the weight or falls back to the system font:

headline: { fontSize: 17, fontFamily: "SFProRounded-Semibold", color: colors.label },

Expose them through one component so screens never touch fontSize:

// components/themed-text.tsx
import { Text, TextProps } from "react-native";
import { type } from "@/theme";

export function ThemedText({
  variant = "body",
  style,
  ...props
}: TextProps & { variant?: keyof typeof type }) {
  return <Text style={[type[variant], style]} {...props} />;
}

Screen titles still come from the navigation stack header (expo-native-ui rule), so largeTitle is mostly for non-stack contexts.

Dynamic Type. Text scales with the user's system text-size setting (allowFontScaling is on by default). Use padding or minHeight around text so rows can grow, and check large accessibility text sizes. Let labels wrap or reflow before considering a per-element maxFontSizeMultiplier for constrained chrome; dense rows alone are not a reason to cap readable text. Never disable scaling app-wide with allowFontScaling={false}.

Radius

// theme/radius.ts
export const radius = {
  sm: 8,
  md: 12,
  lg: 16,
  full: 9999, // capsules
} as const;

Pair every non-capsule radius with borderCurve: "continuous" (per expo-native-ui).

Shadows

Shadows are boxShadow strings (never legacy shadow/elevation props - see expo-native-ui). Two or three elevation levels are enough:

// theme/shadows.ts
export const shadows = {
  card: "0 1px 2px rgba(0, 0, 0, 0.05)",
  raised: "0 4px 12px rgba(0, 0, 0, 0.10)",
  overlay: "0 8px 24px rgba(0, 0, 0, 0.18)",
} as const;

Motion

Durations and shared spring/easing configs, so animations across the app feel related:

// theme/motion.ts
export const motion = {
  fast: 150, // state feedback: press, toggle
  base: 250, // element transitions: enter/exit
  slow: 400, // large surfaces: sheets, screens
} as const;

Reanimated caveat: don't pass Color/PlatformColor token values into Reanimated styles - use static colors there (see expo-native-ui).

Reusable Components

The theme controls values; components control structure. Shared primitives live in src/components/ (see expo-project-structure).

The component contract

Every design-system primitive defines, explicitly:

  • Variants - visual intent: primary, secondary, ghost, destructive. Add a variant only when a real screen needs it.
  • Sizes - sm, md, lg. Default md. Sizes map to spacing/typography tokens, never to fresh numbers.
  • States - default, pressed (not hover - this is touch), disabled, loading. Handle pressed with a Pressable style function; never leave a tappable element without pressed feedback.
  • Style override - accept a style prop and merge it last, so callers can adjust layout (margins, flex) without forking the component. Callers may override layout, not identity - a caller changing a button's colors is a signal the variant set is missing something.
  • Accessibility - custom interactive primitives expose their role and disabled/busy/selected state as applicable. Text children can supply the label; icon-only controls and buttons that replace text with a spinner need an explicit label that remains available while loading. Verify labels on native controls too.
// components/button.tsx
import { Pressable, ActivityIndicator, ViewStyle, StyleProp } from "react-native";
import { colors, spacing, radius } from "@/theme";
import { ThemedText } from "./themed-text";

const variants = {
  primary: { backgroundColor: colors.systemBlue, color: colors.onTint },
  secondary: { backgroundColor: colors.separator, color: colors.label },
} as const;

const sizes = {
  sm: { paddingVertical: spacing.xs, paddingHorizontal: spacing.sm },
  md: { paddingVertical: spacing.sm, paddingHorizontal: spacing.md },
} as const;

export function Button({
  variant = "primary",
  size = "md",
  title,
  loading,
  disabled,
  style,
  onPress,
}: {
  variant?: keyof typeof variants;
  size?: keyof typeof sizes;
  title: string;
  loading?: boolean;
  disabled?: boolean;
  style?: StyleProp<ViewStyle>;
  onPress?: () => void;
}) {
  return (
    <Pressable
      accessibilityRole="button"
      accessibilityLabel={title}
      accessibilityState={{ disabled: !!(disabled || loading), busy: !!loading }}
      disabled={disabled || loading}
      onPress={onPress}
      style={({ pressed }) => [
        {
          backgroundColor: variants[variant].backgroundColor,
          borderRadius: radius.md,
          borderCurve: "continuous",
          alignItems: "center",
          opacity: disabled ? 0.4 : pressed ? 0.7 : 1,
          ...sizes[size],
        },
        style, // caller overrides merge last
      ]}
    >
      {loading ? (
        <ActivityIndicator color={variants[variant].color as string} />
      ) : (
        <ThemedText variant="headline" style={{ color: variants[variant].color }}>
          {title}
        </ThemedText>
      )}
    </Pressable>
  );
}

Composition over configuration

When a component's props start describing content (leftIcon, subtitle, footerText, badgeCount), stop adding props and accept children instead. A Card that renders children with token padding outlives any Card with twelve content props. Reserve props for the contract above: variant, size, state, style.

When to extract - and when not to

Promote a view into src/components/ when all of these hold:

  1. It appears (or is about to appear) in two or more screens. Until then it stays colocated in screens/<name>/ (see expo-project-structure).
  2. It has a nameable role ("Card", "EmptyState", "Badge") - not "the thing on the profile screen".
  3. Its API is smaller than its implementation. If the props would just re-expose every internal style, it isn't a reusable component yet - it's a screen fragment.

Promotion path: inline JSX → component in screens/<name>/ → src/components/. Move one step at a time, when the trigger fires - never speculatively. Wrong abstractions cost more than duplication; a second copy of a view is cheaper than a primitive with a bad API.

Do not wrap platform components that already carry the design language (Switch, DateTimePicker, stack headers, @expo/ui views) just to route them through the system. Native styling is the design system for those.

Where Decisions Live

Decision Lives in Example
A visual value used anywhere twice src/theme/ brand accent, spacing step
Structure + variants of a reused element src/components/ Button, Card, EmptyState
One screen's private composition screens/<name>/ profile header layout
One-off local adjustment inline, with a comment optical nudge on an icon
Screen titles, top-level chrome navigation stack options header title, large title

Self-Critique Pass

After building or changing a screen, screenshot it and check it against these principles (from Expo's design-principles guide). Each one maps to a system fix, not a local tweak:

  • Hierarchy / contrast - is the most important element obviously first? Fix with type ramp steps, not ad-hoc font sizes.
  • Proximity / white space - do related items sit closer than unrelated ones? Fix with gap + spacing tokens.
  • Repetition / unity - do all corners, shadows, and accents match? If not, a value escaped the theme - move it in.
  • Alignment - do edges share axes? Fix with consistent screen edge padding.

Recheck the rendered result after fixing a value; moving it into the theme does not itself fix the layout. If the same defect recurs across screens, fix the shared token or component. Also run the primary-task and content checks in expo-native-ui's Behavior section; screenshots alone cannot verify interaction.

Named Failures: Native Slop

Use these names to recognize common mistakes when building and reviewing:

  • The Web Modal - a custom centered dialog used for composing or picking. Prefer a native sheet (formSheet, @expo/ui BottomSheet) or menu; native confirmation alerts remain appropriate for consequential actions.
  • Everything's a Card - every row and section in its own white rounded shadowed box. Use grouped lists; group with background and hairlines, not borders.
  • Emoji Iconography - 🔥 ⚙️ ✨ as tab or button icons. SF Symbols on iOS, Material icons on Android.
  • The Purple-Gradient Hero - a decorative gradient intro pushing the task below the fold. Lead task screens with useful content; retain a hero when it serves the requested experience.
  • The Spinner Blink - a full-screen spinner between every state, or "No items yet" flashing during the first load. Every screen has four states (see expo-data-fetching).

Treat visual tells as review prompts, not blanket bans on cards, fonts, or branding. Fix the observable problem and respect the user's brief and existing design system. The full list of 20 and candidate grep checks are in ./references/native-slop.md; use them to explain the problem and replacement when reviewing a screen.

Auditing an Existing App

To measure drift in an app that already has screens - hardcoded hex values, arbitrary spacing, inconsistent component APIs - follow ./references/audit.md. It contains grep-based checks, a scoring rubric, an incremental adoption order for fixing a drifted app, and templates for documenting existing components and proposing new ones.

Submitting Feedback

You can voluntarily report errors, misleading or outdated information in this skill, so Expo can improve it:

npx --yes @expo/agent-cli@latest feedback --category skills --subject "expo-design-system" --message "<actionable feedback>"

Use --category agent-cli for a problem with the agent CLI, and --category evals when an agent repeatedly fails at an Expo task. Run feedback --help for subjects and the data that the command sends. Each report goes to Expo with project and environment details. Show the user the message, and send it only if the user agrees. If you cannot ask the user, do not send it. Do not include secrets or personal data.

Files4
4 files · 18.1 KB

Select a file to preview

Overall Score

88/100

Grade

A

Excellent

Grades are signals, not a certification. Always review a skill yourself before use.

Safety

92

Quality

87

Clarity

89

Completeness

83

Summary

This skill teaches AI agents how to design and maintain a consistent visual design system in Expo React Native apps. It covers creating token themes (colors, spacing, typography, radius, shadows, motion), establishing reusable component conventions with clear contracts (variants, sizes, states, accessibility), and auditing existing apps for design-system drift. The skill includes comprehensive reference documentation (audit rubric, anti-pattern identification) and integrates with related skills (expo-native-ui for platform semantics, expo-project-structure for folder layouts).

Detected Capabilities

read and analyze TypeScript/JavaScript source filesreview component structure and naming conventionsexecute shell grep commands for static code analysisprovide guidance on file and folder creation within a projectsuggest TypeScript type definitions and component APIs

Trigger Keywords

Phrases that agents use to match this skill to user intent.

design system setuptoken themecomponent variantsdesign drift audithardcoded stylesreusable components

Referenced Domains

External domains referenced in skill content, detected by static analysis.

developer.apple.comexpo.dev

Use Cases

  • Create a design token file (colors, spacing, typography) for a new Expo app
  • Extend or migrate an existing app to adopt a centralized design system instead of hardcoded style values
  • Audit a drifted Expo app for hardcoded hex colors, raw font sizes, and inconsistent spacing to identify migration priority
  • Define reusable component primitives (Button, Card, etc.) with explicit variants, sizes, and states
  • Decide whether a repeated UI view should be promoted from a screen-local component to a shared design-system component
  • Review screens against named anti-patterns (The Web Modal, Everything's a Card, Emoji Iconography, etc.) to improve native platform alignment

Quality Notes

  • Excellent scope definition: skill is scoped to design systems and explicitly defers to sibling skills (expo-native-ui, expo-project-structure) for platform semantics and app structure
  • Very clear and practical: each section (Colors, Spacing, Typography, Radius, Shadows, Motion, Reusable Components) includes working code examples with inline explanation
  • Strong guardrails: explicitly teaches 'Adopt Before You Build' — detect existing systems first, never introduce a second system alongside an existing one
  • Comprehensive reference materials: audit.md provides grep-based detection, scoring rubric, and incremental adoption strategy; native-slop.md catalogs 20 named anti-patterns with detection patterns
  • Excellent component contract definition: variants, sizes, states, style overrides, and accessibility requirements are specified with concrete example (Button component)
  • Teaching emphasis on composition over configuration: explicitly discourages over-parameterized components in favor of children-based composition
  • Clear extraction criteria: teaches when to promote a view from inline → screen-local component → shared component (must appear 2+ times, have a nameable role, have smaller API than implementation)
  • Detailed accessibility guidance: covers dynamic type scaling, semantic color usage, touch target sizing, label persistence during loading
  • Strong teaching points on design principles: Self-Critique Pass maps visual problems (hierarchy, proximity, repetition, alignment) to system fixes, not local tweaks
  • Well-structured decision table: clarifies where different decisions live (theme values vs. components vs. screen-local composition)
  • Open-source feedback mechanism: encourages issue reporting via npx CLI, respects user consent for data collection
Model: claude-haiku-4-5-20251001Analyzed: Nov 20, 2026

Reviews

Add this skill to your library to leave a review.

No reviews yet

Be the first to share your experience.

Version History

  1. v4.0

    Contract changed: description

    ✦ AINarrows activation scope: now targets inconsistent styling and component libraries rather than general design system setup. Added cross-references to expo-native-ui and expo-project-structure skills.

    triggering2026-11-20

    LATEST
  2. v3.5

    Content updated

    ✦ AIRewords feedback submission guidance and adds privacy notice about project/environment details sent to Expo.

    2026-11-15

    View This Version
  3. v3.4

    Content updated

    ✦ AIFeedback command parameter changed from --subject flag argument to --message flag; adds character limits and expanded error-reporting guidance.

    2026-11-13

    View This Version
  4. v3.3

    Content updated

    ✦ AINo behavioral changes detected; SKILL.md body and frontmatter unchanged.

    2026-10-29

    View This Version
  5. v3.2

    Content updated

    ✦ AIUpdates feedback submission command from submit-expo-feedback to @expo/agent-cli.

    2026-10-23

    View This Version
  6. v3.1

    Content updated

    ✦ AIRevises feedback submission guidance for agent failures: removes reference to separate skill, specifies structured report format with category and subject.

    2026-10-22

    View This Version
  7. v3.0

    Contract changed: description

    ✦ AINarrowed skill activation scope by removing framework classification prefix from description.

    triggering2026-10-03

    View This Version
  8. v2.0

    Contract changed: description

    ✦ AIRemoves skill cross-reference to `expo-tailwind-setup`; adds native-slop.md anti-pattern guide and accessibility/dynamic type requirements; expands audit workflow.

    triggering2026-09-09

    View This Version
  9. v1.0

    2026-08-14

    View This VersionInitial version

Use expo/expo-design-system in your dev environment

Command Palette

Search for a command to run...