expo-design-system
Build and maintain a design system inside an Expo app - a reusable theme of design tokens (color, spacing, typography, radius, shadow, motion), reusable component structure with variant/size/state prop conventions, and rules for when to extract a repeated view into a shared component
Install / Use
npx skills add expo/skills --skill expo-design-systemInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
DesignSupported Platforms
Our assessment of expo-design-system
expo-design-system scores 95/100 on our quality scale, 30th of 260 Design skills we index (top 12%).
Its SKILL.md is 19 KB long, well organised into 19 sections with 13 code examples: a thorough specification that gives an agent plenty to work with.
With 2,602 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so expo-design-system is actively maintained.
- Our last check on 2026-11-16 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-29. Automated pattern scan on 2026-09-29. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
expo-design-system compared with similar skills
All 4 of these similar skills score higher than expo-design-system; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| expo-design-system (this skill)by expo | 95 | 2.6k | 53d ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| Claude-Code-Game-Studiosby Donchitos | 100 | 39.7k | 7d ago | CLAUDE.md |
| x402by browser-use | 100 | 121.0k | 3d ago | SKILL.md |
| algorithmic-artby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
Frequently asked questions
- How do I install expo-design-system?
- Run
npx skills add expo/skills --skill expo-design-system. The install tabs above show the steps for each supported agent. - Which AI agents does expo-design-system work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is expo-design-system safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is expo-design-system still maintained?
- The repository was last updated about 2 months ago, so expo-design-system is actively maintained.
Skill content
View source on GitHubname: expo-design-system description: Framework (OSS). Build and maintain a design system inside an Expo app - a reusable theme of design tokens (color, spacing, typography, radius, shadow, motion), reusable component structure with variant/size/state prop conventions, and rules for when to extract a repeated view into a shared component. Use when creating or organizing theme files and design tokens (theme.ts / theme/), extending an existing theme or styling library (NativeWind, Tamagui, Restyle, Unistyles) in its own idiom, standardizing styles so screens (including AI-generated ones) look consistent and polished, fixing an app that looks AI-generated or generic instead of native (the named native-slop tells), building an in-app component library, or auditing an app for design-system drift (hardcoded colors, spacing, fonts). For platform styling specifics (semantic colors, HIG rules, native controls) use expo-native-ui; for folder layout of a new app use expo-project-structure. version: 1.0.0 license: MIT
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:
- Look for a declared system. Check
package.jsonfor a styling library - NativeWind/Tailwind, Tamagui, Restyle, Unistyles, styled-components. Then look for a token file:theme.ts,src/theme/,constants/theme.ts, orconstants/Colors.ts(the create-expo-app default). - 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.
- 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). - 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
spacingfor 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 (
colorsabove) are static-safe: they resolve on-device, so plain token files liketheme/typography.tscan 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
typeramp step, avariantsobject) needs the brand accent, either apply the brand color in the component at render time, or wrap the pair in a static dynamic color (DynamicColorIOSon 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
gapwith spacing tokens for layout rhythm (expo-native-uiprefers gap over margin). - Screen edge padding is
spacing.mdunless 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. Defaultmd. Sizes map to spacing/typography tokens, never to fresh numbers. - States - default, pressed (not hover - this is touch), disabled, loading. Handle pressed with a
Pressablestyle function; never leave a tappable element without pressed feedback. - Style override - accept a
styleprop and mer
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Claude-Code-Game-Studios
39.7kTurn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.
x402
121.0kSet up Browser Use Cloud payments with x402 — pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key.
algorithmic-art
177.9kCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
