Terminal
Terminal/Skill
Builds cross-platform React web and native UI with Tamagui, covering styled components, design tokens, themes, and animations.
By Tamagui
Works with
npx skills add tamagui/tamagui --skill tamaguiUniversal React UI framework for web and native with an optimizing compiler.
Before writing Tamagui code, get the project's actual configuration:
npx tamagui generate-prompt
This outputs tamagui-prompt.md with the project's specific:
Always reference this file for token/theme/media query names rather than guessing or using defaults.
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: {
boxShadow: '0 8px 24px $shadow4',
},
},
} as const, // required for type inference
defaultVariants: {
size: 'small',
},
})
// usage
<Card size="large" elevated />
Key rules:
as const on variants objects$ prefix: $4, $background, $color11import { 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 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)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
}
import { AnimatePresence } from 'tamagui'
<AnimatePresence>
{show && (
<YStack
key="modal" // key required for exit animations
transition="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 physicsCSS driver uses easing strings, others support spring physics.
Use createStyledContext for components that share state:
import { createStyledContext, styled, View, Text } from '@tamagui/core'
import { withStaticProperties } from '@tamagui/helpers'
const CardContext = createStyledContext({ size: 'medium' as 'small' | 'medium' | 'large' })
const CardFrame = styled(View, {
context: CardContext,
padding: '$4',
backgroundColor: '$background',
variants: {
size: {
small: { padding: '$2' },
medium: { padding: '$4' },
large: { padding: '$6' },
},
} as const,
})
const CardTitle = styled(Text, {
context: CardContext, // inherits size from parent
fontWeight: 'bold',
variants: {
size: {
small: { fontSize: '$4' },
medium: { fontSize: '$5' },
large: { fontSize: '$6' },
},
} as const,
})
export const Card = withStaticProperties(CardFrame, {
Title: CardTitle,
})
// usage - size cascades to children
<Card size="large">
<Card.Title>Large Title</Card.Title>
</Card>
import { Dialog, Sheet, Adapt, Button } from 'tamagui'
<Dialog>
<Dialog.Trigger asChild>
<Button>Open</Button>
</Dialog.Trigger>
<Adapt when="sm" platform="touch">
<Sheet modal dismissOnSnapToBottom>
<Sheet.Frame padding="$4">
<Adapt.Contents />
</Sheet.Frame>
<Sheet.Overlay />
</Sheet>
</Adapt>
<Dialog.Portal>
<Dialog.Overlay
key="overlay"
transition="quick"
opacity={0.5}
enterStyle={{ opacity: 0 }}
exitStyle={{ opacity: 0 }}
/>
<Dialog.Content
key="content"
transition="quick"
enterStyle={{ opacity: 0, scale: 0.95 }}
exitStyle={{ opacity: 0, scale: 0.95 }}
>
<Dialog.Title>Title</Dialog.Title>
<Dialog.Description>Description</Dialog.Description>
<Dialog.Close asChild>
<Button>Close</Button>
</Dialog.Close>
</Dialog.Content>
</Dialog.Portal>
</Dialog>
import { Input, Label, YStack, XStack, Button } from 'tamagui'
<YStack gap="$4" padding="$4">
<YStack gap="$2">
<Label htmlFor="email">Email</Label>
<Input
id="email"
placeholder="email@example.com"
autoCapitalize="none"
keyboardType="email-address"
/>
</YStack>
<XStack gap="$2" justifyContent="flex-end">
<Button variant="outlined">Cancel</Button>
<Button theme="blue">Submit</Button>
</XStack>
</YStack>
animation propThere is no animation prop. It is the most commonly invented one. The prop is
transition, and its value is a TransitionProp: a configured animation name,
an object, or an array. A CSS transition string is not one.
// bad - no such prop
<View animation="quick" />
// bad - a CSS string is not a TransitionProp
<View transition="all 0.2s ease" />
// good - a name the config registers under `animations`
<View transition="quick" />
Use animatedBy="<driver>" only when the config registers more than one driver.
backdropFilter, mixBlendMode, boxShadow, filter, backgroundImage,
transition, cursor, and userSelect are first-class typed props that React
Native's New Architecture implements natively. backdropFilter is a real native
gaussian backdrop blur, so frosting a surface needs no separate blur view
package. Treating one of these as a no-op on iOS is a stale assumption.
// bad - the legacy RN shadow group splits web and native
<View shadowColor="$shadowColor" shadowOffset={{ width: 0, height: 8 }} shadowRadius={10} />
// good - one tokenized path for both
<View boxShadow="0 8px 24px $shadow4" />
Tamagui is moving this way itself: a config setting removes the border, outline,
and shadow longhands from the type system in favor of the combined border,
outline, and boxShadow props, because mixing shorthand and longhand fights
over atomic CSS specificity.
// bad
<View padding={16} backgroundColor="#fff" />
// good - uses design tokens
<View padding="$4" backgroundColor="$background" />
as const on variants// bad - TypeScript can't infer variant types
variants: {
size: { small: {...}, large: {...} }
}
// good
variants: {
size: { small: {...}, large: {...} }
} as const
// bad - won't be extracted by compiler
const Box = styled(View, {
padding: Platform.OS === 'web' ? 10 : 20,
})
// good - use platform modifiers
const Box = styled(View, {
padding: 20,
'$platform-web': { padding: 10 },
})
// bad - exit animation won't work
{show && <View exitStyle={{ opacity: 0 }} />}
// good
<AnimatePresence>
{show && <View key="box" exitStyle={{ opacity: 0 }} />}
</AnimatePresence>
// bad - runtime variable prevents compiler extraction
const dynamicPadding = isPremium ? '$6' : '$4'
<View padding={dynamicPadding} />
// good - inline ternary is extractable
<View padding={isPremium ? '$6' : '$4'} />
// bad - base value overrides responsive
<View $gtMd={{ padding: '$8' }} padding="$4" />
// good - base first, then responsive overrides
<View padding="$4" $gtMd={{ padding: '$8' }} />
// bad - CSS driver doesn't support spring physics
import { createAnimations } from '@tamagui/animations-css'
const anims = createAnimations({
bouncy: { type: 'spring', damping: 10 } // won't work
})
// good for CSS driver - use easing strings
const anims = createAnimations({
bouncy: 'cubic-bezier(0.68, -0.55, 0.265, 1.55) 300ms'
})
The Tamagui compiler extracts static styles to CSS at build time. For styles to be extracted:
$4 extracts, 16 may notpadding={x ? '$4' : '$2'} extractsCheck if extraction is working:
data-tamagui attributes in dev modeimport { GetProps, styled, View } from '@tamagui/core'
const MyComponent = styled(View, {
variants: {
size: { small: {}, large: {} }
} as const,
})
// extract props type
type MyComponentProps = GetProps<typeof MyComponent>
// extend with custom props
interface ExtendedProps extends MyComponentProps {
onCustomEvent?: () => void
}
| Pattern | Example |
|---|---|
| Token | padding="$4" |
| Theme value | backgroundColor="$background" |
| Color scale | color="$color11" (high contrast text) |
| Responsive | $gtSm={{ padding: '$6' }} |
| Variant | <Button size="large" variant="outlined" /> |
| Animation | transition="quick" enterStyle={{ opacity: 0 }} |
| Theme switch | <Theme name="dark"><Theme name="blue"> |
| Compound | <Card><Card.Title> with createStyledContext |