tamagui-best-practices

此技能为使用 Tamagui 库开发 UI 的开发者提供专家级指引。内容涵盖了 Tamagui 项目的完整生命周期，从 v4 配置的初始架构到高级编译器优化技巧。此技能专为需要高性能且基于设计系统架构的 React Native 与 Web 开发者所设计。它通过强制执行设计标记 (Design Tokens)、媒体断点 (Media Breakpoints) 与主题管理的一致性，帮助维护代码结构的完整性，确保样式在不同渲染目标下皆能保持最佳性能。

• 使用 v4 标准配置 tamagui.config.ts，包括针对 React Native 对齐的 styleCompat 设置。

• 应用编译器优化规则，例如优先使用 styled() 变体而非内联样式逻辑，以维持 Tree-shaking 与扁平化效率。

• 实现高级组件模式，如复合组件、Context 模式，以及正确使用 .styleable() 方法来确保变体继承。

• 管理复杂的重叠层 (Overlays)，包括使用 Adapt 组件处理跨平台的特定 UI 调整。

• 处理包含 react-native-reanimated 等驱动程序的动画，并正确使用 enterStyle 与 exitStyle 属性。

• 整合表单原型与 Zod 验证的最佳实践，以及自定义主题色板的管理。

• 请务必优先选择 styled() 组件而非内联样式对象，以防止运行时性能下降并避免损坏编译器扁平化功能。

• 在组件组合时注意变体顺序，因为 Tamagui 样式引擎中后方的属性具有较高的优先级。

• 使用带有 $ 前缀的明确标记语法来定义设计系统值，以确保从主题中正确解析。

• 维持严格的导入一致性，在单一项目中选择使用 @tamagui/core、tamagui 或特定子包，以避免包臃肿。

• 避免将标准 React Native StyleSheet 对象与 Tamagui 组件混用，因为标准样式表无法解析 Tamagui 设计标记。

• 在处理 SVG 属性 (如 fill 或 stroke) 时，使用 accept 属性进行非标准标记解析。