Esta skill fornece padrões para Tamagui v1.x que vão além dos fundamentos. Ela foca em Config v4, otimização do compilador, componentes compostos e erros comuns.
Carregamento de Contexto Obrigatório
Ao trabalhar com esses componentes, leia o arquivo de padrão correspondente ANTES de escrever código:
| Tipo de Componente | Leitura Obrigatória | Competências Cruzadas |
|---|---|---|
| Dialog, Sheet, modal overlays | @DIALOG_PATTERNS.md | |
| Form, Input, Label, validação | @FORM_PATTERNS.md | typescript-best-practices (zod) |
| Animações, transições | @ANIMATION_PATTERNS.md | |
| Popover, Tooltip, Select | @OVERLAY_PATTERNS.md | |
| Otimização do compilador | @COMPILER_PATTERNS.md | |
| Tokens de design, temas | @DESIGN_SYSTEM.md |
Início Rápido com Config v4
Use @tamagui/config/v4 para configuração simplificada:
// tamagui.config.ts
import { defaultConfig } from '@tamagui/config/v4'
import { createTamagui } from 'tamagui'
export const config = createTamagui(defaultConfig)
type CustomConfig = typeof config
declare module 'tamagui' {
interface TamaguiCustomConfig extends CustomConfig {}
}
Configuração recomendada para novos projetos (alinha flexBasis ao React Native):
export const config = createTamagui({
...defaultConfig,
settings: {
...defaultConfig.settings,
styleCompat: 'react-native',
},
})
Padrão createThemes
Para temas personalizados, use createThemes com paleta/destaque/temas filhos:
import { createThemes, defaultComponentThemes } from '@tamagui/config/v4'
const generatedThemes = createThemes({
componentThemes: defaultComponentThemes,
base: {
palette: {
dark: ['#050505', '#151515', /* ...12 cores */ '#fff'],
light: ['#fff', '#f8f8f8', /* ...12 cores */ '#000'],
},
extra: {
light: { ...Colors.blue, shadowColor: 'rgba(0,0,0,0.04)' },
dark: { ...Colors.blueDark, shadowColor: 'rgba(0,0,0,0.2)' },
},
},
accent: {
palette: { dark: lightPalette, light: darkPalette }, // invertido
},
childrenThemes: {
blue: { palette: { dark: Object.values(Colors.blueDark), light: Object.values(Colors.blue) } },
red: { /* ... */ },
green: { /* ... */ },
},
})
Sintaxe de Token e Tema
Regras do Prefixo $
- Props: Use prefixo
$para referências a tokens:<Text color="$color" fontSize="$4" /> - Chaves de tema: Acesse sem
$nas definições de tema:{ color: palette[11] } - Acesso a tokens em variantes: Use o padrão
tokens.size[name]
Operadores de Espalhamento de Variantes
Operadores especiais mapeiam categorias de tokens para valores de variantes:
const Button = styled(View, {
variants: {
size: {
// Mapeia tokens de tamanho: $1, $2, $true, etc.
'...size': (size, { tokens }) => ({
height: tokens.size[size] ?? size,
borderRadius: tokens.radius[size] ?? size,
gap: tokens.space[size]?.val * 0.2,
}),
},
textSize: {
// Mapeia tokens de fontSize
'...fontSize': (name, { font }) => ({
fontSize: font?.size[name],
}),
},
} as const,
})
Importante: Use as const no objeto de variantes até que o TypeScript suporte genéricos const inferidos.
Componentes Compostos com createStyledContext
Para APIs compostas como <Button><Button.Text>Clique</Button.Text></Button>:
import {
SizeTokens,
View,
Text,
createStyledContext,
styled,
withStaticProperties,
} from '@tamagui/core'
// 1. Crie contexto com tipos de variantes compartilhados
export const ButtonContext = createStyledContext<{ size: SizeTokens }>({
size: '$medium',
})
// 2. Crie frame com contexto
export const ButtonFrame = styled(View, {
name: 'Button',
context: ButtonContext,
variants: {
size: {
'...size': (name, { tokens }) => ({
height: tokens.size[name],
borderRadius: tokens.radius[name],
gap: tokens.space[name].val * 0.2,
}),
},
} as const,
defaultVariants: {
size: '$medium',
},
})
// 3. Crie texto com mesmo contexto (variantes sincronizam automaticamente)
export const ButtonText = styled(Text, {
name: 'ButtonText',
context: ButtonContext,
variants: {
size: {
'...fontSize': (name, { font }) => ({
fontSize: font?.size[name],
}),
},
} as const,
})
// 4. Componha com withStaticProperties
export const Button = withStaticProperties(ButtonFrame, {
Props: ButtonContext.Provider,
Text: ButtonText,
})
Uso:
<Button size="$large">
<Button.Text>Clique em mim</Button.Text>
</Button>
// Ou sobrescreva padrões de cima:
<Button.Props size="$small">
<Button><Button.Text>Pequeno</Button.Text></Button>
</Button.Props>
Nota: O padrão context não funciona com achatamento do compilador. Use para componentes de alto nível (Button, Card), não para primitivos (Stack, Text).
styleable() para Componentes Wrapper
Ao encapsular um componente estilizado em um componente funcional, use .styleable() para preservar a herança de variantes:
const StyledText = styled(Text)
// SEM styleable - Herança de variante QUEBRADA
const BrokenWrapper = (props) => <StyledText {...props} />
// COM styleable - CORRETO
const CorrectWrapper = StyledText.styleable((props, ref) => (
<StyledText ref={ref} {...props} />
))
// Agora isso funciona:
const StyledCorrectWrapper = styled(CorrectWrapper, {
variants: {
bold: { true: { fontWeight: 'bold' } },
},
})
Adicionando Props Extras
Passe um argumento de tipo genérico para props adicionais:
type ExtraProps = { icon?: React.ReactNode }
const IconText = StyledText.styleable<ExtraProps>((props, ref) => {
const { icon, ...rest } = props
return (
<XStack>
{icon}
<StyledText ref={ref} {...rest} />
</XStack>
)
})
Prop accept para Componentes Personalizados
Permite resolução de token/tema em props não padrão:
// Para fill/stroke de SVG que devem aceitar cores de tema
const StyledSVG = styled(SVG, {}, {
accept: { fill: 'color', stroke: 'color' } as const,
})
// Uso: <StyledSVG fill="$blue10" />
// Para objetos de estilo (como contentContainerStyle do ScrollView)
const MyScrollView = styled(ScrollView, {}, {
accept: { contentContainerStyle: 'style' } as const,
})
// Uso: <MyScrollView contentContainerStyle={{ padding: '$4' }} />
Importante: Use as const no objeto accept.
A Ordem das Props é Importante
Em styled(), a ordem das props determina a prioridade de sobrescrita:
// backgroundColor pode ser sobrescrito por props
const Overridable = (props) => (
<View backgroundColor="$red10" {...props} width={200} />
)
// width NÃO PODE ser sobrescrito (vem após o spread)
// A ordem das variantes também importa:
<Component scale={3} huge /> // scale = 3 (scale vem primeiro)
<Component huge scale={3} /> // scale = 2 (huge sobrescreve)
Anti-Padrões
Estilos Dinâmicos Quebram a Otimização
// RUIM - quebra a otimização do compilador
<View style={{ width: someVariable * 2 }} />
<View backgroundColor={isDark ? '$gray1' : '$gray12'} />
// BOM - use variantes
const Box = styled(View, {
variants: {
dark: { true: { backgroundColor: '$gray1' }, false: { backgroundColor: '$gray12' } },
},
})
<Box dark={isDark} />
Funções Inline
// RUIM - nova função a cada renderização
<View onPress={() => handlePress(id)} />
// BOM - referência estável
const handlePressCallback = useCallback(() => handlePress(id), [id])
<View onPress={handlePressCallback} />
Caminhos de Importação Errados
// Estes são pacotes diferentes com conteúdos diferentes:
import { View } from 'tamagui' // Kit UI completo
import { View } from '@tamagui/core' // Apenas core (menor)
import { Button } from '@tamagui/button' // Componente individual
// Escolha uma abordagem e seja consistente
Misturando RN StyleSheet com Tamagui
// RUIM - valores de StyleSheet não resolvem tokens
const styles = StyleSheet.create({ box: { padding: 20 } })
<View style={styles.box} backgroundColor="$blue10" />
// BOM - tudo Tamagui
<View padding="$4" backgroundColor="$blue10" />
Ramificação Platform.OS para Dialog/Sheet
// RUIM - ramificação manual de plataforma
if (Platform.OS === 'web') {
return <Dialog>...</Dialog>
}
return <Sheet>...</Sheet>
// BOM - use Adapt (veja @DIALOG_PATTERNS.md)
<Dialog>
<Dialog.Portal>...</Dialog.Portal>
<Adapt when="sm" platform="touch">
<Sheet><Adapt.Contents /></Sheet>
</Adapt>
</Dialog>
Obtendo Documentação Atual
Para detalhes mais recentes da API, busque documentos markdown diretamente:
# Documentação do core
curl -sL "https://tamagui.dev/docs/core/configuration.md"
curl -sL "https://tamagui.dev/docs/core/styled.md"
curl -sL "https://tamagui.dev/docs/core/variants.md"
curl -sL "https://tamagui.dev/docs/core/animations.md"
# Documentação de componentes
curl -sL "https://tamagui.dev/ui/sheet.md"
curl -sL "https://tamagui.dev/ui/dialog.md"
curl -sL "https://tamagui.dev/ui/select.md"
# Índice completo de documentação
curl -sL "https://tamagui.dev/llms.txt"
Para páginas HTML, use a skill web-fetch com seletores apropriados.
Referência Rápida
Atalhos do Config v4 (alinhados com Tailwind)
| Atalho | Propriedade |
|---|---|
bg | backgroundColor |
p | padding |
m | margin |
w | width |
h | height |
br | borderRadius |
Breakpoints de Consulta de Mídia
| Token | Padrão | Padrão do Servidor |
|---|---|---|
$xs | 660px | true |
$sm | 800px | false |
$md | 1020px | false |
$lg | 1280px | false |
$xl | 1420px | false |
Drivers de Animação
| Driver | Plataforma | Caso de Uso |
|---|---|---|
css | Web | Padrão, melhor desempenho |
react-native-reanimated | Nativo | Necessário para animações nativas |
Arquivos de Padrão Adicionais
- @DIALOG_PATTERNS.md - Dialog, Sheet, Adapt, acessibilidade
- @FORM_PATTERNS.md - Form, Input, Label, validação com zod
- @ANIMATION_PATTERNS.md - Drivers de animação, enterStyle/exitStyle
- @OVERLAY_PATTERNS.md - Popover, Tooltip, Select
- @COMPILER_PATTERNS.md - Detalhes de otimização do compilador
- @DESIGN_SYSTEM.md - Tokens de design e temas