tamagui-best-practices

This skill provides expert guidance for developers building user interfaces with the Tamagui library. It encompasses the entire lifecycle of a Tamagui-powered project, from initial setup of the v4 configuration to advanced compiler optimization techniques. The skill is designed for React Native and web developers who require high-performance, design-system-driven component architectures. It helps maintain structural integrity by enforcing consistent use of design tokens, media breakpoints, and theme management, ensuring that style performance remains optimal across different rendering targets.

• Configuring tamagui.config.ts with v4 standards, including styleCompat settings for React Native alignment.

• Applying compiler optimization rules, such as preferring styled() variants over inline style logic to maintain tree-shaking and flattening efficiency.

• Implementing advanced component patterns like compound components, context patterns, and proper use of the .styleable() method to ensure variant inheritance.

• Managing complex overlays, including Dialogs and Sheets using the Adapt component for cross-platform platform-specific UI adjustments.

• Handling animations with integrated drivers like react-native-reanimated and proper usage of enterStyle/exitStyle properties.

• Best practices for integrating form primitives with Zod validation and managing custom theme palettes.

• Always prioritize styled() components over inline style objects to prevent runtime performance degradation and breaking compiler flattening.

• Respect variant order during component composition, as later props take precedence in the Tamagui style engine.

• Use explicit token syntax with the $ prefix for design system values to ensure correct resolution from the theme.

• Maintain strict import consistency, choosing either @tamagui/core, tamagui, or specific sub-packages per project to avoid package bloat.

• Avoid mixing standard React Native StyleSheet objects with Tamagui components, as standard stylesheets cannot resolve Tamagui design tokens.

• Utilize the accept prop for non-standard token resolution when working with SVG properties like fill or stroke.