Update to Expo

{
  "name": "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.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 576
    },
    {
      "relative_path": "references/audit.md",
      "size_in_bytes": 8462
    },
    {
      "relative_path": "references/native-slop.md",
      "size_in_bytes": 8440
    }
  ],
  "skill_md_contents": "---\nname: expo-design-system\ndescription: 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.\nversion: 1.0.0\nlicense: MIT\n---\n\n# Expo Design Systems\n\nMake 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.\n\nSibling skills own the layers around this one:\n\n- `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**.\n- `expo-project-structure` - folder skeleton for new apps.\n\nFor 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.\n\n## References\n\nConsult these resources as needed:\n\n```\nreferences/\n  audit.md        Audit an existing app for design-system drift: grep checks,\n                  scoring rubric, incremental adoption plan, and templates for\n                  documenting or extending components\n  native-slop.md  The 20 named anti-pattern tells of AI-generated apps (The Web\n                  Modal, Everything's a Card, ...) with grep checks for the greppable ones\n```\n\n## Adopt Before You Build\n\nIn an app that already has screens, the first move is detection, not construction. Before writing any token file:\n\n1. **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).\n2. **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.\n3. **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).\n4. **Never introduce a second system beside an existing one.** A fresh `src/theme/` next to a Tamagui config is design-system drift, not adoption.\n\nOnly when nothing exists do the defaults below apply as written.\n\n## The Theme\n\nIn 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:\n\n```\nsrc/theme/\n  colors.ts       # see expo-native-ui \"Colors\" for the palette pattern\n  spacing.ts\n  typography.ts\n  radius.ts\n  shadows.ts\n  motion.ts\n  index.ts        # re-exports everything: import { spacing, type } from \"@/theme\"\n```\n\nA 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.\n\nRules that make a theme worth having:\n\n- **Every repeated visual value is a token.** A literal that appears twice belongs in the theme.\n- **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.\n- **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.\n\n### Colors\n\nBuild 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:)\n\n```tsx\n// theme/colors.ts\nimport { Platform } from \"react-native\";\nimport { Color } from \"expo-router\";\n\nexport const colors = {\n  label: Platform.select({\n    ios: Color.ios.label,\n    android: Color.android.dynamic.onSurface,\n    default: \"#000000\",\n  })!,\n  secondaryLabel: Platform.select({\n    ios: Color.ios.secondaryLabel,\n    android: Color.android.dynamic.onSurfaceVariant,\n    default: \"#3c3c43\",\n  })!,\n  separator: Platform.select({\n    ios: Color.ios.separator,\n    android: Color.android.dynamic.outlineVariant,\n    default: \"#c6c6c8\",\n  })!,\n  systemBackground: Platform.select({\n    ios: Color.ios.systemBackground,\n    android: Color.android.dynamic.surface,\n    default: \"#ffffff\",\n  })!,\n  systemBlue: Platform.select({\n    ios: Color.ios.systemBlue,\n    android: Color.android.dynamic.primary,\n    default: \"#007aff\",\n  })!,\n  // Deliberately fixed: text on a tinted (accent) surface stays white in both modes.\n  onTint: \"#ffffff\",\n};\n```\n\nAdd brand colors as explicit light/dark pairs only when the brand requires values the platform doesn't provide:\n\n```tsx\n// theme/colors.ts (brand additions)\nimport { useColorScheme } from \"react-native\";\n\nconst brandPalette = {\n  light: { accent: \"#5B21B6\", accentContrast: \"#FFFFFF\" },\n  dark: { accent: \"#A78BFA\", accentContrast: \"#1E1B4B\" },\n} as const;\n\nexport function useBrandColors() {\n  const scheme = useColorScheme();\n  return brandPalette[scheme === \"dark\" ? \"dark\" : \"light\"];\n}\n```\n\nKeep the brand set tiny (accent, accentContrast, maybe a tint per feature). Everything else stays semantic.\n\n**Static-safe vs hook-only.** The two patterns above have different reach - keep the boundary explicit:\n\n- 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.\n- 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.\n- 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.\n\n### Spacing\n\nOne scale, based on a 4-point grid. Name steps by size, not by use:\n\n```tsx\n// theme/spacing.ts\nexport const spacing = {\n  xs: 4,\n  sm: 8,\n  md: 16,\n  lg: 24,\n  xl: 32,\n  xxl: 48,\n} as const;\n```\n\n- Use `gap` with spacing tokens for layout rhythm (`expo-native-ui` prefers gap over margin).\n- Screen edge padding is `spacing.md` unless the design says otherwise - pick one and keep it.\n- If a layout needs a value between steps, use the nearest step. The grid is the point.\n- 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.\n\n### Typography\n\nDefine named text styles, not raw font sizes. Mirror the platform ramp (Apple text styles) so sizes feel native:\n\n```tsx\n// theme/typography.ts\nimport { TextStyle } from \"react-native\";\nimport { colors } from \"./colors\";\n\nexport const type = {\n  largeTitle: { fontSize: 34, fontWeight: \"700\", color: colors.label },\n  title: { fontSize: 22, fontWeight: \"600\", color: colors.label },\n  headline: { fontSize: 17, fontWeight: \"600\", color: colors.label },\n  body: { fontSize: 17, fontWeight: \"400\", color: colors.label },\n  subhead: { fontSize: 15, fontWeight: \"400\", color: colors.secondaryLabel },\n  caption: { fontSize: 12, fontWeight: \"400\", color: colors.secondaryLabel },\n} as const satisfies Record<string, TextStyle>;\n```\n\nIf 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:\n\n```tsx\nheadline: { fontSize: 17, fontFamily: \"SFProRounded-Semibold\", color: colors.label },\n```\n\nExpose them through one component so screens never touch `fontSize`:\n\n```tsx\n// components/themed-text.tsx\nimport { Text, TextProps } from \"react-native\";\nimport { type } from \"@/theme\";\n\nexport function ThemedText({\n  variant = \"body\",\n  style,\n  ...props\n}: TextProps & { variant?: keyof typeof type }) {\n  return <Text style={[type[variant], style]} {...props} />;\n}\n```\n\nScreen titles still come from the navigation stack header (`expo-native-ui` rule), so `largeTitle` is mostly for non-stack contexts.\n\n**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}`.\n\n### Radius\n\n```tsx\n// theme/radius.ts\nexport const radius = {\n  sm: 8,\n  md: 12,\n  lg: 16,\n  full: 9999, // capsules\n} as const;\n```\n\nPair every non-capsule radius with `borderCurve: \"continuous\"` (per `expo-native-ui`).\n\n### Shadows\n\nShadows are `boxShadow` strings (never legacy shadow/elevation props - see `expo-native-ui`). Two or three elevation levels are enough:\n\n```tsx\n// theme/shadows.ts\nexport const shadows = {\n  card: \"0 1px 2px rgba(0, 0, 0, 0.05)\",\n  raised: \"0 4px 12px rgba(0, 0, 0, 0.10)\",\n  overlay: \"0 8px 24px rgba(0, 0, 0, 0.18)\",\n} as const;\n```\n\n### Motion\n\nDurations and shared spring/easing configs, so animations across the app feel related:\n\n```tsx\n// theme/motion.ts\nexport const motion = {\n  fast: 150, // state feedback: press, toggle\n  base: 250, // element transitions: enter/exit\n  slow: 400, // large surfaces: sheets, screens\n} as const;\n```\n\nReanimated caveat: don't pass `Color`/`PlatformColor` token values into Reanimated styles - use static colors there (see `expo-native-ui`).\n\n## Reusable Components\n\nThe theme controls values; components control structure. Shared primitives live in `src/components/` (see `expo-project-structure`).\n\n### The component contract\n\nEvery design-system primitive defines, explicitly:\n\n- **Variants** - visual intent: `primary`, `secondary`, `ghost`, `destructive`. Add a variant only when a real screen needs it.\n- **Sizes** - `sm`, `md`, `lg`. Default `md`. Sizes map to spacing/typography tokens, never to fresh numbers.\n- **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.\n- **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.\n- **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.\n\n```tsx\n// components/button.tsx\nimport { Pressable, ActivityIndicator, ViewStyle, StyleProp } from \"react-native\";\nimport { colors, spacing, radius } from \"@/theme\";\nimport { ThemedText } from \"./themed-text\";\n\nconst variants = {\n  primary: { backgroundColor: colors.systemBlue, color: colors.onTint },\n  secondary: { backgroundColor: colors.separator, color: colors.label },\n} as const;\n\nconst sizes = {\n  sm: { paddingVertical: spacing.xs, paddingHorizontal: spacing.sm },\n  md: { paddingVertical: spacing.sm, paddingHorizontal: spacing.md },\n} as const;\n\nexport function Button({\n  variant = \"primary\",\n  size = \"md\",\n  title,\n  loading,\n  disabled,\n  style,\n  onPress,\n}: {\n  variant?: keyof typeof variants;\n  size?: keyof typeof sizes;\n  title: string;\n  loading?: boolean;\n  disabled?: boolean;\n  style?: StyleProp<ViewStyle>;\n  onPress?: () => void;\n}) {\n  return (\n    <Pressable\n      accessibilityRole=\"button\"\n      accessibilityLabel={title}\n      accessibilityState={{ disabled: !!(disabled || loading), busy: !!loading }}\n      disabled={disabled || loading}\n      onPress={onPress}\n      style={({ pressed }) => [\n        {\n          backgroundColor: variants[variant].backgroundColor,\n          borderRadius: radius.md,\n          borderCurve: \"continuous\",\n          alignItems: \"center\",\n          opacity: disabled ? 0.4 : pressed ? 0.7 : 1,\n          ...sizes[size],\n        },\n        style, // caller overrides merge last\n      ]}\n    >\n      {loading ? (\n        <ActivityIndicator color={variants[variant].color as string} />\n      ) : (\n        <ThemedText variant=\"headline\" style={{ color: variants[variant].color }}>\n          {title}\n        </ThemedText>\n      )}\n    </Pressable>\n  );\n}\n```\n\n### Composition over configuration\n\nWhen 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.\n\n### When to extract - and when not to\n\nPromote a view into `src/components/` when **all** of these hold:\n\n1. It appears (or is about to appear) in **two or more screens**. Until then it stays colocated in `screens/<name>/` (see `expo-project-structure`).\n2. It has a **nameable role** (\"Card\", \"EmptyState\", \"Badge\") - not \"the thing on the profile screen\".\n3. 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.\n\nPromotion 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.\n\nDo **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.\n\n## Where Decisions Live\n\n| Decision | Lives in | Example |\n|---|---|---|\n| A visual value used anywhere twice | `src/theme/` | brand accent, spacing step |\n| Structure + variants of a reused element | `src/components/` | Button, Card, EmptyState |\n| One screen's private composition | `screens/<name>/` | profile header layout |\n| One-off local adjustment | inline, with a comment | optical nudge on an icon |\n| Screen titles, top-level chrome | navigation stack options | header title, large title |\n\n## Self-Critique Pass\n\nAfter building or changing a screen, screenshot it and check it against these principles (from [Expo's design-principles guide](https://expo.dev/blog/how-to-apply-professional-design-principles-in-ai-app-development)). Each one maps to a system fix, not a local tweak:\n\n- **Hierarchy / contrast** - is the most important element obviously first? Fix with `type` ramp steps, not ad-hoc font sizes.\n- **Proximity / white space** - do related items sit closer than unrelated ones? Fix with `gap` + spacing tokens.\n- **Repetition / unity** - do all corners, shadows, and accents match? If not, a value escaped the theme - move it in.\n- **Alignment** - do edges share axes? Fix with consistent screen edge padding.\n\nRecheck 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.\n\n## Named Failures: Native Slop\n\nUse these names to recognize common mistakes when building and reviewing:\n\n- **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.\n- **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.\n- **Emoji Iconography** - 🔥 ⚙️ ✨ as tab or button icons. SF Symbols on iOS, Material icons on Android.\n- **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.\n- **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`).\n\nTreat 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.\n\n## Auditing an Existing App\n\nTo 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.\n\n## Submitting Feedback\nIf you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:\n```bash\nnpx --yes submit-expo-feedback@latest --category skills --subject \"expo-design-system\" \"<actionable feedback>\"\n```\nOnly submit when you have something specific and actionable to report. Include as much relevant context as possible.\nIf an AI agent repeatedly failed or the user had to take over an Expo task, load the expo-skill-feedback skill and follow its eval-candidate flow instead of reusing the command above.\n"
}