ant-design

Ant Design

S - 範圍

• 目標：antd@^6 + React 18-19，必要時搭配 ant-design-pro@^5 / @ant-design/pro-components 和 @ant-design/x@^2。
• 工具：@ant-design/cli 用於離線元件元資料、範例、更新日誌、遷移、Lint、醫生檢查和使用分析。
• 重點：僅提供決策指導，不包含終端使用者教學。
• 來源政策：僅使用官方文件；不採用未公開的 API 或內部 .ant-* 耦合。

預設假設

• 語言：TypeScript。
• 樣式：優先使用 Token，其次 classNames/styles；避免全域覆寫。
• Provider：一個根 ConfigProvider，除非需要嚴格隔離。

強制規則

• 在撰寫或修改 antd 元件程式碼前，先使用 antd info <Component> --format json 查詢元件 API。當 CLI 可離線回答時，不要依賴記憶。
• 使用 antd CLI 指令時，一律加上 --format json。
• 如果專案版本重要，請使用 --version <x.y.z> 指定版本，或讓 CLI 從本地 node_modules 自動偵測。
• 修改 antd 程式碼後，執行 antd lint <changed-path> --format json。
• 如果 antd CLI 指令崩潰、回傳錯誤資料或違反其文件行為，請準備 antd bug-cli 預覽供使用者確認，而非默默繞過問題。
• 對於元件問題，先將元件名稱對應到官方路由 slug {components}（小寫 kebab-case，例如 TreeSelect -> tree-select、Button -> button），然後依以下順序請求文件（先中文，英文備用）：
  1. https://ant.design/components/{components}-cn
  2. https://ant.design/components/{components}
  • 範例：tree-select-cn -> tree-select、button-cn -> button。
• 僅使用已公開的 antd/Pro/X API。
• 不要發明 props/events/元件名稱。
• 不要依賴內部 DOM 或 .ant-* 選擇器。
• 主題優先順序：全域 Token -> 元件 Token -> 別名 Token。

P - 流程

1) 分類

• 識別層級：核心 antd、Pro 或 X。
• 確認版本、渲染模式（CSR/SSR/串流）、資料規模，以及是否應以 @ant-design/cli 為主要查詢路徑。

2) 查詢權威來源

• 優先使用本地 @ant-design/cli 進行結構化查詢：
  • antd info 用於 props/API
  • antd demo 用於可運作範例
  • antd doc 用於完整文件
  • antd token / antd semantic 用於主題和樣式掛鉤
  • antd doctor、antd lint、antd usage、antd migrate、antd changelog 用於除錯或升級
• 當需要敘述性文件或交叉驗證時，再請求官方元件文件（先 -cn，英文備用）。

3) 決策

• Provider 基準：CSR -> ConfigProvider；SSR -> ConfigProvider + StyleProvider。
• 主題基準：全域 Token -> 元件 Token -> classNames/styles。
• 輸出建議 + 風險 + 驗證點（SSR/無障礙/效能），並引用 CLI 發現。

O - 輸出

• 提供簡短的決策理由（1-3 句）。
• 包含精簡的 Provider/主題策略。
• 包含具體的 SSR/無障礙/效能檢查。
• 針對 Pro：包含路由/選單/權限和 CRUD 結構方向。
• 針對 X：包含訊息/工具結構和串流狀態方向。

參考資料

檔案	使用時機
references/antd-cli.md	當你需要精確的離線 CLI 工作流程進行 API 查詢、範例、Lint、醫生檢查、遷移、更新日誌審查、使用分析或錯誤回報時。

回歸檢查清單

• [ ] 一個根 ConfigProvider；SSR 樣式順序/水合已驗證。
• [ ] 優先使用 Token；無廣泛的全域 .ant-* 覆寫。
• [ ] Table 有穩定的 rowKey；排序/篩選/分頁入口統一。
• [ ] Select 遠端模式在使用遠端搜尋時停用本地篩選。
• [ ] Upload 受控/非受控模式明確，並包含失敗/重試路徑。
• [ ] Pro 路由/選單/權限與後端強制一致。
• [ ] X 串流支援停止/重試和確定性工具渲染。
• [ ] 如果使用了 antd CLI，指令需加上 --format json，任何 CLI 缺陷需透過 antd bug-cli 預覽升級。