Tamagui Skill

Universal React UI framework for web and native with an optimizing compiler.

Getting Project-Specific Config

Before writing Tamagui code, get the project's actual configuration:

npx tamagui generate-prompt

This outputs tamagui-prompt.md with the project's specific:

• Design tokens (space, size, radius, color, zIndex)
• Theme names and hierarchy
• Available components
• Media query breakpoints
• Shorthand properties
• Font families

Always reference this file for token/theme/media query names rather than guessing or using defaults.

---

Core Concepts

styled() Function

Create components by extending existing ones:

import { View, Text, styled } from '@tamagui/core'

const Card = styled(View, {
  padding: '$4',           // use tokens with $
  backgroundColor: '$background',
  borderRadius: '$4',

  variants: {
    size: {
      small: { padding: '$2' },
      large: { padding: '$6' },
    },
    elevated: {
      true: {
        shadowColor: '$shadowColor',
        shadowRadius: 10,
      },
    },
  } as const,  // required for type inference

  defaultVariants: {
    size: 'small',
  },
})

// usage
<Card size="large" elevated />

Key rules:

• Always use as const on variants objects
• Tokens use $ prefix: $4, $background, $color11
• Prop order matters - later props override earlier ones
• Variants defined later in the object override earlier ones

Stack Components

import { XStack, YStack, ZStack } from 'tamagui'

// XStack = flexDirection: 'row'
// YStack = flexDirection: 'column'
// ZStack = position: 'relative' with absolute children

<YStack gap="$4" padding="$4">
  <XStack justifyContent="space-between" alignItems="center">
    <Text>Label</Text>
    <Button>Action</Button>
  </XStack>
</YStack>

Themes

Themes nest and combine hierarchically:

import { Theme } from 'tamagui'

// base theme
<Theme name="dark">
  {/* sub-theme */}
  <Theme name="blue">
    {/* uses dark_blue theme */}
    <Button>Blue button on dark</Button>
  </Theme>
</Theme>

// access theme values
const theme = useTheme()
console.log(theme.background.val)  // actual color value
console.log(theme.color11.val)     // high contrast text

12-step color scale convention:

• $color1-4: backgrounds (subtle to emphasized)
• $color5-6: borders, separators
• $color7-8: hover/active states
• $color9-10: solid backgrounds
• $color11-12: text (low to high contrast)

Responsive Styles

Use media query props (check your tamagui-prompt.md for actual breakpoint names):

<YStack
  padding="$4"
  $gtSm={{ padding: '$6' }}   // check your config for actual names
  $gtMd={{ padding: '$8' }}
  flexDirection="column"
  $gtLg={{ flexDirection: 'row' }}
/>

// or with hook
const media = useMedia()
if (media.gtMd) {
  // render for medium+ screens
}

Animations

import { AnimatePresence } from 'tamagui'

<AnimatePresence>
  {show && (
    <YStack
      key="modal"  // key required for exit animations
      animation="quick"
      enterStyle={{ opacity: 0, y: -20 }}
      exitStyle={{ opacity: 0, y: 20 }}
      opacity={1}
      y={0}
    />
  )}
</AnimatePresence>

Animation drivers:

• @tamagui/animations-css - web only, CSS transitions
• @tamagui/animations-react-native - native Animated API
• @tamagui/animations-reanimated - best native performance
• @tamagui/animations-motion - spring physics

CSS driver uses easing strings, others support spring physics.

---

Compound Components

Use createStyledContext for components that share state:

import { createStyledContext, styled, View, Text } from '@tamagui/core'
import { withStaticProperties } from '@tamagui/helpers'