挑選函式庫
在任何決策之前，先套用 product-ui §1（品味日誌與優先順序）和 §5（哪個技能負責什麼）。如果日誌規則中提及某個函式庫，則以該規則為準。
當未指定任務時，用一行文字詢問任務並停止。
決策順序
從上到下執行。在第一個能完全解決任務的步驟停止。
- 已經安裝了什麼？ 讀取
package.json。如果已安裝的函式庫或競爭對手已經能勝任，就直接使用。如果發現更好的選擇，只用一行文字標記，且絕不未經詢問就更換相依套件。原因：為了同一個功能安裝第二個函式庫會使套件體積加倍，並增加慣例衝突。 - 平台本身能完全解決嗎？ 檢查下表。原因：平台方案沒有套件負擔，沒有升級路徑，也沒有棄用風險。
- 清單中有對應項目嗎？ 打開 references/catalogue.md，找到分類，選取標記為 Default 的項目。只推薦一個函式庫，不要列出選單。
- 該項目還在維護嗎？ 檢查狀態欄。如果標示為 Unmaintained，絕不推薦；改用該項目中指定的替代品。
- 沒有符合的？ 說「這個任務不在清單上」，然後從自身知識中挑選，並對其執行下方的驗證程序。原因：未經檢查的套件通常是棄用程式碼進入專案的主要途徑。
「完全解決」表示任務的所有需求都得到滿足，包括鍵盤操作、焦點管理和螢幕閱讀器行為。如果有一項需求失敗，則跳到步驟 3。
平台優先
| 任務 | 平台方案 | 何時轉用函式庫 |
|---|---|---|
| 模態框 | <dialog> 搭配 showModal() | 需要支援可疊加、在不同瀏覽器上有動畫進出效果的對話框，或需要非模態的焦點管理 |
| 彈出視窗、下拉面板、工具提示卡片 | popover 屬性，以及支援處的 CSS anchor positioning | 需要在所有地方都能進行碰撞翻轉，或需要 roving-focus 選單 |
| 手風琴、揭露元件 | <details name> | 需要受控狀態或超越 interpolate-size 的動畫高度 |
| 無切換按鈕的深色模式 | prefers-color-scheme、color-scheme、light-dark() | 使用者手動選擇主題且需持久儲存 |
| 日期、時間、月份輸入 | <input type="date"> 及其同類型元素 | 需要範圍選擇、自訂日曆或一致的外觀 |
| 數字格式化、相對時間、複數、清單 | Intl.NumberFormat、RelativeTimeFormat、PluralRules、ListFormat | 從不。永遠使用 Intl |
| 一次性驗證碼、單一欄位 | <input autocomplete="one-time-code" inputmode="numeric"> | 需要每個數字一個輸入框 |
| 進入、退出和佈局動畫 | CSS transitions、@starting-style、WAAPI、View Transitions | 需要彈簧效果、手勢或可中斷的佈局動畫 |
| 表單驗證 | 約束驗證（required、pattern、setCustomValidity） | 需要跨欄位或非同步規則，或需要型別 schema |
| 選項較少的選擇器 | <select> | 需要搜尋、多選或豐富的行內容 |
| 固定標題、滾動吸附、惰性列表 | CSS position: sticky、scroll-snap、content-visibility: auto | 列表包含 1,000 行以上 |
常見錯誤配對
| 錯誤用法 | 正確用法 | 原因 |
|---|---|---|
使用 <div> 搭配手寫焦點陷阱的模態框 | <dialog> 和 showModal() | 焦點陷阱、Esc 鍵關閉和背景 inert 都是現成的 |
npm i react-beautiful-dnd | @dnd-kit/react | 前者已棄用且未維護 |
使用 npm i vaul 實作抽屜 | Base UI Drawer，或將 <dialog> 樣式設為 sheet | vaul 的 README 也說它未維護 |
| 從模態框函式庫建立的 Toast | Base UI Toast | 疊加、暫停和滑動關閉都已解決 |
使用 setInterval 計數數字 | NumberFlow | 數字會以正確的佈局和減少動畫效果滾動 |
一次渲染 5,000 個 <tr> | 在 TanStack Table 之下使用 TanStack Virtual，或列表使用 Virtuoso | 渲染成本隨行數增長，而非視口大小 |
使用貨幣套件取代 new Intl.NumberFormat | Intl.NumberFormat | 語言環境規則內建於瀏覽器中 |
推薦前請驗證
對任何套件（不論是否在清單上）執行此驗證。目錄中的狀態可能比你的會話時間更舊。
npm view <pkg> time.modified license version
- 已維護：最近一次發布在 12 個月內，或 6 個月內有儲存庫推送並包含已發布的版本。
- 慢速：功能完整，12–24 個月內未發布新版本，但儲存庫仍在回覆 issue。可使用。需說明是慢速。
- 未維護：已封存、README 中標示未維護、或超過 24 個月未發布且有未解決的損壞問題。絕不推薦。
- 閱讀授權條款。回報任何非 MIT、ISC、BSD 或 Apache-2.0 的授權（MPL-2.0 和 AGPL 需要附註說明）。
- 檢查同儕依賴是否與專案的 React 版本相符。
回答格式
單一區塊，不提供選單：
Base UI Toast 用於 Toast。它能疊加、懸停時暫停並可滑動關閉。不適用於需要執行動作的情況；這類 Toast 應保留在畫面上。MIT 授權，已維護。
npm i @base-ui/react。
一律提供：用途、何時不該使用、授權條款、狀態以及你查詢的日期。
完成前請檢查
- 已讀取
package.json，所選函式庫不會與已安裝的函式庫重複。 - 已檢查平台方案，若跳過，原因需在一個子句中說明。
- 已對所選函式庫執行
npm view，回答中的狀態是今天的日期，而非目錄中的日期。 - 未推薦任何標記為 Unmaintained 的函式庫。