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 屬性進行非標準標記解析。