UI 堆疊顧問
挑選技術棧是專案中槓桿效應最高的 UI 決策：它決定了無障礙品質、主題彈性、套件大小以及結果的「模板化」程度。謹慎地做出選擇，一次定案，並記錄下來。
知識快照：2026 年 11 月。函式庫演進快速——安裝前，請確認當前主要版本與 API（參閱新鮮度檢查）。優先使用專案中已有的函式庫，而非此處列出的任何選項。
步驟 1 — 先閱讀專案
檢查 package.json / pubspec.yaml / Package.swift / build.gradle 中現有的 UI 函式庫、樣式設定（Tailwind 版本、CSS-in-JS）、框架版本，以及任何 components.json (shadcn)、DESIGN.md 或 token 檔案。不要在一個現有元件庫旁邊引入第二個元件庫——擴展現有的，或將其包裝起來。如果專案已使用此處推薦的競爭對手產品，請提及它，但不要在未經要求的情況下隨意變更依賴關係。
步驟 2 — 回答五個問題
- 平台: 僅限 Web、僅限行動端，或從同一程式碼庫同時涵蓋兩者？
- 歸屬: 是複製原始碼進來，你可以完全擁有並自由重新樣式化（shadcn 模型），還是作為一個帶有主題 API 的版本化依賴項（MUI/Mantine 模型）？複製進來 = 最大的設計自由 + 你自行維護。依賴項 = 更快、一致、免費升級、更難做出區別。
- 產品類型: 行銷/著陸頁（表現力強、動態豐富）、產品 UI/儀表板（密集、一致、鍵盤友好）、內容（字體優先）、行動消費者應用程式（原生感覺、手勢操作）。
- 無障礙門檻: 公共部門 / 企業 / 歐盟（歐洲無障礙法案）→ 選擇經過驗證的無障礙基礎元件（React Aria、Base UI、Radix），不要手刻互動小工具。
- 樣式系統: Tailwind v4（新 Web 專案的預設選項）、CSS Modules/vanilla-extract 或 CSS-in-JS；在 React Native 上：NativeWind vs Unistyles vs Tamagui。
步驟 3 — 預設選擇（當沒有其他限制時）
| 情境 | 預設 | 原因 |
|---|---|---|
| React/Next.js 產品 UI | shadcn/ui（Base UI 基礎元件——自 2026 年 7 月以來的預設選項；也支援 Radix 和 React Aria）+ Tailwind v4 | 你擁有程式碼、優良的無障礙、龐大的註冊表生態系、AI 工具非常熟悉它 |
| React，無障礙關鍵 / 複雜小工具（日期範圍、組合框、拖放、i18n） | React Aria Components（或 shadcn 的 React Aria 變體 / HeroUI v3，它們基於此構建） | 最嚴謹的無障礙 + i18n 行為 |
| React，功能齊全，無 Tailwind | Mantine | 100+ 個元件 + hooks + 表單 + 日期，文件齊全 |
| React，企業級/Material 風格或重型資料表格 | MUI v9（+ MUI X 資料表格 / 日期選擇器 / 圖表） | 成熟、完整；更難做出區別 |
| 企業級管理後台（特別是中國/亞太團隊） | Ant Design | 龐大的元件集，資料密集模式 |
| Vue / Nuxt | Nuxt UI v4（免費，基於 Reka UI + Tailwind v4）或 shadcn-vue | |
| Svelte / SvelteKit | shadcn-svelte（基於 Bits UI） | |
| Solid | Kobalte / solid-ui（shadcn 移植版）/ Ark UI | |
| Angular | Spartan UI（類似 shadcn）或 Angular Material / PrimeNG | |
| 框架無關的基礎元件 | Ark UI（Zag.js 狀態機；React/Vue/Solid/Svelte） | |
| 行銷 / 著陸頁亮點 | shadcn + Motion + 來自 Magic UI / Aceternity / Animate UI / React Bits 的選定部分 | 使用 1–3 個標誌性效果，而不是拼湊一堆 |
| React Native / Expo（新應用程式） | Expo + Expo Router + NativeWind v5 + React Native Reusables（RN 版的 shadcn）或 HeroUI Native；@expo/ui 用於真正的原生 SwiftUI/Compose 控制項；Reanimated 4 + Gesture Handler 用於動畫 | |
| React Native，注重 StyleSheet 風格的效能 | Unistyles 3 + 你自己的元件 | |
| 從同一程式碼庫支援 React Native + Web | Tamagui（編譯器，通用）或 Expo + NativeWind 搭配 react-native-web | |
| Flutter | Material 3（內建）/ Cupertino；forui 或 shadcn_ui 用於非 Material 風格 | |
| iOS 原生 | SwiftUI 系統元件（iOS 26+ 上的 Liquid Glass 會隨標準控制項免費提供） | 盡量不要跟平台對抗 |
| Android 原生 | Jetpack Compose Material 3（material3 1.5 系列中的 Expressive API） |
每個平台的詳細資訊、替代方案與權衡取捨，請參閱參考文件——閱讀與你相符的那一份：
references/web-react.md— React 基礎元件、樣式化套件、shadcn 生態系與註冊表、Tailwind 工具references/web-other.md— Vue、Svelte、Solid、Angular、Astro、純 HTML/Web Componentsreferences/mobile.md— React Native/Expo、Flutter、SwiftUI、Compose、Kotlin Multiplatformreferences/motion.md— 各平台的動畫函式庫以及何時 CSS/原生就已足夠references/building-blocks.md— 圖示、字型、圖表、表格、表單、提示、日期、拖放、虛擬化、編輯器、指令選單、輪播、地圖、3Dreferences/inspiration.md— 尋找參考資料的地方（Mobbin、Refero 等）以及 AI 設計工具
步驟 4 — 記錄決策
將選擇寫入專案中（DESIGN.md 或 README 的「UI 技術棧」章節）：函式庫 + 版本、樣式方法、圖示集、動畫函式庫、字型，以及原因。未來的對話（以及其他代理）將讀取此記錄，而無需重新決策。
新鮮度檢查（安裝前執行）
npm view <pkg> version time.modified repository.url # 目前版本 + 最後發布時間
npm view <pkg> deprecated # 棄用通知（如有）
# Flutter: https://pub.dev/packages/<pkg> (讚數、pub 點數、最後發布時間)
# Swift: 檢查儲存庫的最新發布標籤
應避免使用的函式庫跡象：超過 12 個月未發布且有未解決的關鍵問題、README 標示「未維護/已封存」、對等依賴鎖定在舊版 React/RN、沒有 TypeScript 類型、忽略了無障礙問題。已知已退役/有風險的例子：react-beautiful-dnd（已棄用 → 改用 @atlaskit/pragmatic-drag-and-drop 或 dnd kit）、@base-ui-components/react（已重新命名 → @base-ui/react）、Chakra v2 API（v3 是在 Ark UI/Panda 上的重寫）、Reanimated 2/3 手勢 API（useAnimatedGestureHandler 在 v4 中已移除）。
如果文件 MCP 可用（例如 Context7、shadcn MCP、用於設計系統查詢的 Figma MCP），請使用它們來閱讀當前文件，而不是依賴記憶。
反模式
- 在一個應用程式中使用兩個元件庫（MUI + shadcn）→ 焦點、間距、主題不一致。
- 手刻對話框、選單、組合框、日期選擇器、提示、工具提示 → 無障礙錯誤（焦點陷阱、離開、aria、滾動鎖定、碰撞）。請使用基礎元件。
- 完整安裝一個「動畫元件」函式庫 → 只複製你需要的那 1–3 個部分。
- 在 React Native 內透過 WebView 使用 Web UI 套件，或強迫 iOS 使用者使用 Material 元件。
- 不變更函式庫的預設主題 → 「每個 shadcn 應用程式看起來都一樣」的問題。至少更改：字型、圓角半徑、強調色、中性色溫與密度（請參閱 design-system-builder 和 color-theory 技能）。