/mobile-ui-components-tamagui

name: mobile-ui-components-tamagui
description: Tamagui universal UI - styled(), tokens, themes, optimizing compiler, responsive media queries, animations, Sheet/Dialog components

Tamagui Universal UI Patterns

> **Quick Guide:** Tamagui provides universal styled components for React Native and web with an optimizing compiler that flattens components to native primitives. Use `styled()` with variants for component APIs, `$`-prefixed tokens for consistent spacing/color, theme nesting for light/dark modes, and the `transition` prop for animations. The compiler extracts static styles to CSS on web and hoists style objects on native -- but only when props are deterministic at build time.

---

<critical_requirements>

CRITICAL: Before Using This Skill

**(You MUST use `$`-prefixed token values in style props (`$4`, `$color.blue`) -- raw pixel values bypass the token system and break theme consistency)**

**(You MUST keep the `transition` prop present in JSX when using animations -- conditionally removing it causes expensive hook teardown; pass `null` to disable instead)**

**(You MUST add `as const` to variant definition objects -- without it TypeScript cannot infer variant prop types correctly)**

**(You MUST use `Adapt` for responsive Dialog-to-Sheet behavior -- manual Platform.OS branching breaks compiler optimization and misses breakpoint changes)**

</critical_requirements>

---

**Auto-detection:** Tamagui, tamagui, styled(), createTamagui, createTokens, createTheme, XStack, YStack, ZStack, SizableText, Paragraph, Theme, useTheme, useMedia, $sm, $md, $lg, enterStyle, exitStyle, hoverStyle, pressStyle, transition prop, Sheet, Dialog, Adapt, GetProps, TamaguiProvider, @tamagui/core, @tamagui/config

**When to use:**

• Building universal React Native + web UIs that share components across platforms
• Creating design-system-driven components with typed token scales and theme variants
• Optimizing render performance via compiler flattening (styled components to native divs/Views)
• Implementing responsive layouts with media query style props (`$sm`, `$gtMd`)
• Adding enter/exit/hover/press animations with swappable animation drivers
• Building adaptive overlays (Dialog on desktop, Sheet on mobile) with `Adapt`

**When NOT to use:**

• Web-only projects where a web-native styling solution is simpler
• Apps needing pixel-perfect custom native UI beyond what React Native Views provide
• Performance-critical animations that need direct native driver control beyond Tamagui's animation abstraction

**Key patterns covered:**

• `styled()` with typed variants (spread, boolean, functional) and `GetProps` type extraction
• Token system (`createTokens`, `$`-prefix references, category-to-property mapping)
• Theme hierarchy (base, sub-themes, component themes, `useTheme`, dark/light switching)
• Optimizing compiler (flattening, CSS extraction, what prevents optimization)
• Responsive styles with media query props and `useMedia` hook
• Animation system with `transition` prop, `enterStyle`/`exitStyle`, and driver selection
• Sheet and Dialog with `Adapt` for responsive overlay behavior

**Detailed Resources:**

• [examples/core.md](examples/core.md) - styled(), variants, tokens, themes, compiler optimization
• [examples/responsive-animations.md](examples/responsive-animations.md) - Media queries, useMedia, animation drivers, enter/exit styles
• [examples/overlays.md](examples/overlays.md) - Sheet, Dialog, Adapt pattern
• [reference.md](reference.md) - Decision frameworks, token-to-property mapping, migration notes

---

<philosophy>

Philosophy

Tamagui solves the universal UI problem: write components once that render optimally on both React Native and web. The key insight is that **compile-time analysis can eliminate the runtime cost of a universal abstraction**.

**Core principles:**

1. **Tokens are the source of truth** -- spacing, color, radius, and font values flow from `createTokens` through themes to components via `$`-prefixed references. Raw values bypass the system. 2. **Themes override tokens contextually** -- themes are scoped CSS variables that change within React subtrees. Missing theme keys resolve upward to parent themes, then to tokens. 3. **The compiler rewards deterministic styles** -- static props, token references, and spread variants can be flattened to native primitives. Dynamic expressions, ternaries on non-media values, and function render props prevent optimization. 4. **Animation drivers are swappable** -- CSS transitions for web, Reanimated for native, configured once in `createTamagui`. Component code stays identical. 5. **Adapt replaces platform branching** -- `Adapt` transforms Dialog to Sheet at breakpoints without manual `Platform.OS` checks.

**Tamagui v2** is the current stable release. Key changes from v1: `animation` prop renamed to `transition`, config v5 with Tailwind-aligned breakpoints, expanded color system with Radix Colors v3, native portals for Sheet/Dialog/Popover, and headless/unstyled component variants.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: styled() with Typed Variants

`styled()` extends a base component with default styles and type-safe variants. Use `GetProps` to export the derived prop type.

import { GetProps, styled, View, Text } from "@tamagui/core";

export const Card = styled(View, {
  name: "Card",
  backgroundColor: "$background",
  borderRadius: "$4",
  padding: "$4",
  borderWidth: 1,
  borderColor: "$borderColor",

  variants: {
    size: {
      "...size": (val, { tokens }) => ({
        padding: tokens.size[val] ?? val,
      }),
    },
    elevated: {
      true: { elevation: "$2" },
    },
  } as const,
});

export type CardProps = GetProps<typeof Card>;

**Why good:** `name` property enables component-specific themes (`dark_Card`), spread variant `...size` maps all size tokens automatically, `as const` preserves literal types for variant inference, `GetProps` keeps prop type in s