Este skill proporciona patrones para Tamagui v1.x que van más allá de los fundamentos. Se enfoca en Config v4, optimización del compilador, componentes compuestos y errores comunes.
Carga de Contexto Obligatoria
Al trabajar con estos componentes, lee el archivo de patrón correspondiente ANTES de escribir código:
| Tipo de Componente | Lectura Requerida | Habilidades Cruzadas |
|---|---|---|
| Dialog, Sheet, superposiciones modales | @DIALOG_PATTERNS.md | |
| Form, Input, Label, validación | @FORM_PATTERNS.md | typescript-best-practices (zod) |
| Animaciones, transiciones | @ANIMATION_PATTERNS.md | |
| Popover, Tooltip, Select | @OVERLAY_PATTERNS.md | |
| Optimización del compilador | @COMPILER_PATTERNS.md | |
| Tokens de diseño, temas | @DESIGN_SYSTEM.md |
Inicio Rápido con Config v4
Usa @tamagui/config/v4 para una configuración 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 {}
}
Configuración recomendada para proyectos nuevos (alinea flexBasis con React Native):
export const config = createTamagui({
...defaultConfig,
settings: {
...defaultConfig.settings,
styleCompat: 'react-native',
},
})
Patrón createThemes
Para temas personalizados, usa createThemes con palette/accent/childrenThemes:
import { createThemes, defaultComponentThemes } from '@tamagui/config/v4'
const generatedThemes = createThemes({
componentThemes: defaultComponentThemes,
base: {
palette: {
dark: ['#050505', '#151515', /* ...12 colores */ '#fff'],
light: ['#fff', '#f8f8f8', /* ...12 colores */ '#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: { /* ... */ },
},
})
Sintaxis de Tokens y Temas
Reglas del Prefijo $
- Props: Usa el prefijo
$para referencias a tokens:<Text color="$color" fontSize="$4" /> - Claves de tema: Accede sin
$en definiciones de tema:{ color: palette[11] } - Acceso a tokens en variantes: Usa el patrón
tokens.size[name]
Operadores de Propagación en Variantes
Los operadores especiales de propagación mapean categorías de tokens a valores de variantes:
const Button = styled(View, {
variants: {
size: {
// Mapea tokens de tamaño: $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: {
// Mapea tokens de fontSize
'...fontSize': (name, { font }) => ({
fontSize: font?.size[name],
}),
},
} as const,
})
Importante: Usa as const en el objeto de variantes hasta que TypeScript soporte genéricos constantes inferidos.
Componentes Compuestos con createStyledContext
Para APIs compuestas como <Button><Button.Text>Click</Button.Text></Button>:
import {
SizeTokens,
View,
Text,
createStyledContext,
styled,
withStaticProperties,
} from '@tamagui/core'
// 1. Crear contexto con tipos de variantes compartidos
export const ButtonContext = createStyledContext<{ size: SizeTokens }>({
size: '$medium',
})
// 2. Crear marco con 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. Crear texto con el mismo contexto (las variantes se sincronizan automáticamente)
export const ButtonText = styled(Text, {
name: 'ButtonText',
context: ButtonContext,
variants: {
size: {
'...fontSize': (name, { font }) => ({
fontSize: font?.size[name],
}),
},
} as const,
})
// 4. Componer con withStaticProperties
export const Button = withStaticProperties(ButtonFrame, {
Props: ButtonContext.Provider,
Text: ButtonText,
})
Uso:
<Button size="$large">
<Button.Text>Click me</Button.Text>
</Button>
// O sobrescribir valores por defecto desde arriba:
<Button.Props size="$small">
<Button><Button.Text>Small</Button.Text></Button>
</Button.Props>
Nota: El patrón context no funciona con la optimización del compilador. Úsalo para componentes de alto nivel (Button, Card), no para primitivas (Stack, Text).
styleable() para Componentes Envoltorio
Cuando envuelves un componente con estilo en un componente funcional, usa .styleable() para preservar la herencia de variantes:
const StyledText = styled(Text)
// SIN styleable - Herencia de variantes ROTA
const BrokenWrapper = (props) => <StyledText {...props} />
// CON styleable - CORRECTO
const CorrectWrapper = StyledText.styleable((props, ref) => (
<StyledText ref={ref} {...props} />
))
// Ahora esto funciona:
const StyledCorrectWrapper = styled(CorrectWrapper, {
variants: {
bold: { true: { fontWeight: 'bold' } },
},
})
Agregar Props Extra
Pasa un argumento de tipo genérico para props adicionales:
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
Habilita la resolución de tokens/temas en props no estándar:
// Para fill/stroke de SVG que deben aceptar colores de tema
const StyledSVG = styled(SVG, {}, {
accept: { fill: 'color', stroke: 'color' } as const,
})
// Uso: <StyledSVG fill="$blue10" />
// Para objetos de estilo (como contentContainerStyle de ScrollView)
const MyScrollView = styled(ScrollView, {}, {
accept: { contentContainerStyle: 'style' } as const,
})
// Uso: <MyScrollView contentContainerStyle={{ padding: '$4' }} />
Importante: Usa as const en el objeto accept.
El Orden de las Props Importa
En styled(), el orden de las props determina la prioridad de sobrescritura:
// backgroundColor puede ser sobrescrito por props
const Overridable = (props) => (
<View backgroundColor="$red10" {...props} width={200} />
)
// width NO PUEDE ser sobrescrito (viene después del spread)
// El orden de las variantes también importa:
<Component scale={3} huge /> // scale = 3 (scale viene primero)
<Component huge scale={3} /> // scale = 2 (huge sobrescribe)
Anti-Patrones
Estilos Dinámicos Rompen la Optimización
// MALO - rompe la optimización del compilador
<View style={{ width: someVariable * 2 }} />
<View backgroundColor={isDark ? '$gray1' : '$gray12'} />
// BUENO - usa variantes
const Box = styled(View, {
variants: {
dark: { true: { backgroundColor: '$gray1' }, false: { backgroundColor: '$gray12' } },
},
})
<Box dark={isDark} />
Funciones en Línea
// MALO - nueva función en cada render
<View onPress={() => handlePress(id)} />
// BUENO - referencia estable
const handlePressCallback = useCallback(() => handlePress(id), [id])
<View onPress={handlePressCallback} />
Rutas de Importación Incorrectas
// Estos son paquetes diferentes con contenidos diferentes:
import { View } from 'tamagui' // Kit de UI completo
import { View } from '@tamagui/core' // Solo núcleo (más pequeño)
import { Button } from '@tamagui/button' // Componente individual
// Elige un enfoque y sé consistente
Mezclar RN StyleSheet con Tamagui
// MALO - los valores de StyleSheet no resuelven tokens
const styles = StyleSheet.create({ box: { padding: 20 } })
<View style={styles.box} backgroundColor="$blue10" />
// BUENO - todo Tamagui
<View padding="$4" backgroundColor="$blue10" />
Ramificación Platform.OS para Dialog/Sheet
// MALO - ramificación manual de plataforma
if (Platform.OS === 'web') {
return <Dialog>...</Dialog>
}
return <Sheet>...</Sheet>
// BUENO - usa Adapt (ver @DIALOG_PATTERNS.md)
<Dialog>
<Dialog.Portal>...</Dialog.Portal>
<Adapt when="sm" platform="touch">
<Sheet><Adapt.Contents /></Sheet>
</Adapt>
</Dialog>
Obtener Documentación Actualizada
Para detalles actualizados de la API, obtén los documentos markdown directamente:
# Documentos del núcleo
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"
# Documentos 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 documentos
curl -sL "https://tamagui.dev/llms.txt"
Para páginas HTML, usa el skill de web-fetch con los selectores apropiados.
Referencia Rápida
Abreviaturas de Config v4 (alineadas con Tailwind)
| Abreviatura | Propiedad |
|---|---|
bg | backgroundColor |
p | padding |
m | margin |
w | width |
h | height |
br | borderRadius |
Puntos de Ruptura de Media Query
| Token | Predeterminado | Predeterminado del Servidor |
|---|---|---|
$xs | 660px | true |
$sm | 800px | false |
$md | 1020px | false |
$lg | 1280px | false |
$xl | 1420px | false |
Controladores de Animación
| Controlador | Plataforma | Caso de Uso |
|---|---|---|
css | Web | Predeterminado, mejor rendimiento |
react-native-reanimated | Nativa | Requerido para animaciones nativas |
Archivos de Patrones Adicionales
- @DIALOG_PATTERNS.md - Dialog, Sheet, Adapt, accesibilidad
- @FORM_PATTERNS.md - Form, Input, Label, validación con zod
- @ANIMATION_PATTERNS.md - Controladores de animación, enterStyle/exitStyle
- @OVERLAY_PATTERNS.md - Popover, Tooltip, Select
- @COMPILER_PATTERNS.md - Detalles de optimización del compilador
- @DESIGN_SYSTEM.md - Tokens de diseño y temas