Name: lzhbhlrPython/antd-admin-template
Author: 社群技能

Ant Design Web 應用設計系統（中後台優先）

本技能提供一套經驗證的 React 19 + TypeScript + Ant Design 6 實現方式，以及一個可直接執行的完整模板。它的核心不是某一套頁面，而是：

一層參照 Ant Design 官方 Design Token 的可配置設計系統；
兩種可切換的應用外殼（側邊 / 頂部）；
一組經驗證的頁面配方，覆蓋中台、入口網站、文檔、看板、AI 工作台等 36 種型態；
一條強制的組件復用優先規則：先找 antd / 已有函式庫 / 已有組件，再手寫。

目標是「原生 antd」觀感：組件、間距、狀態、主題都來自 Ant Design，而不是在 antd 之上再造一套設計系統。

載入技能時，資源區塊會給出本技能的絕對目錄。下文用 <SKILL_DIR> 表示它，執行命令前請替換成實際路徑。技能目錄包含：

SKILL.md
design.md                               # 機器可讀設計語言（官方 design.md 的模板落地）
scripts/scaffold.mjs                    # 一鍵生成專案（改名 + 可選安裝）
scripts/scan-ui.mjs                     # 掃描現有組件/依賴/antd 使用，先於任何 UI 程式碼
scripts/fetch-antd-docs.mjs             # 按專案 antd 版本批次刷新組件文檔快照
scripts/check-antd-docs.mjs             # 初始化自檢：專案 antd 版本 vs 文檔快照
assets/template/                        # 完整可執行模板（無 node_modules / dist）
assets/preview/                         # 效果圖
references/antd-official.md            # Ant Design 官方設計語言與基本資訊（直接內置）
references/for-agents.md                # 官方 For Agents 提示詞、CLI / MCP / LLMs 工作流程
references/ecosystem.md                 # 官方生態庫與社群推薦、選型順序
references/antd-design-language.md      # 官方設計語言、Token、配置映射
references/component-reuse.md           # 強制：復用檢索、antd 組件映射、自定義規則
references/app-patterns/README.md       # 型態索引：先讀這個，只選一個
references/app-patterns/_common.md      # 通用外殼/寬度/密度/狀態/驗收
references/app-patterns/*.md            # 36 個類型檔案，依任務唯讀命中項
references/architecture.md              # Provider、驗證、外殼、服務層
references/fullstack-design.md          # 前後端分離、API 契約、資料模型、React 狀態歸屬
references/backend-design.md            # 後端範式：分層、驗證、事務、冪等、審計、安全
references/ant-motion.md                # Ant Motion 動效規範、組件接入、效能與可及性
references/code-quality.md              # 阿里巴巴前端規約 + React 19/TS 程式碼品質與審查清單
references/components/README.md         # 36 個常用組件文檔快照索引（按需讀 1–2 個）
references/components/manifest.json     # 快照版本、檔案大小與 SHA-256，自檢依據
references/components/*.md              # antd 6.7.0 中文組件文檔快照
references/ux-scenarios.md              # 載入/空/錯誤/批次/長時間任務/權限等 UI/UX 場景
references/page-recipes.md              # 清單/彈窗/詳情/權限/看板配方
references/design-rules.md              # 視覺與互動規範

調用邊界（優先於下文配方）

全域僅明確使用：使用者明確要求採用 Ant Design / antd 設計語言，或指名 $antd-admin-template，才可以載入和執行本技能。使用者明確為特定專案設定「設計工作必須使用本技能」時，專案 AGENTS.md 可記錄該持續授權；該專案設計工作必須讀取並使用本技能輔助，其他專案不繼承此例外。
一般前端設計、管理後台、文檔、入口網站、看板、CRUD、主題配置、不要 Tailwind、專案已依賴 antd，均不構成調用授權。不得因這些關鍵詞自行選擇本技能。
授權按當前任務範圍判斷。一次調用不代表以後所有設計任務都使用 antd；專案持續授權僅在其明確範圍內生效；提及、安裝、審閱本技能也不代表要求用它設計介面。
尊重既有專案的產品定位、DESIGN.md、AGENTS.md、組件體系與套件管理器；只在授權範圍內使用所需參考，不自動遷移設計語言或複製整個模板。
下文頁面配方與新專案驗收項按實際需求採用；既有專案的局部修改不強加登入、RBAC、多個業務頁、設計設置或後台外殼。入口網站和行銷頁面不強套 BasicLayout。
agents/openai.yaml 設定 policy.allow_implicit_invocation: false。不要改為自動調用，也不要安裝到跨工具共用的技能目錄。

靈感與資料來源

本技能的 AI 友善設計組織方式受到 Ant Design 官網 For Agents 的啟發：讓 Agent 查詢實際版本的組件知識，而不是僅憑訓練記憶猜測 API；並參考 LLMs.txt 與 design.md 將組件知識、語義結構與設計語言提供為可按需讀取的資料。

這是獨立整理的社群技能，不是 Ant Design 官方技能或官方背書專案。快照是歸檔參考，不代表當前最新版本；使用時核對目標專案實際依賴。內置官方文檔材料及許可請見 THIRD_PARTY_NOTICES.md。

交付標準

以下是完整新建應用程式的參考驗收項；按授權的應用型態與範圍選用，既有專案以自身約束為準：

pnpm typecheck 與 pnpm build 均通過。
應用型態與外殼匹配：中後台用側邊導航；入口網站/工具型可用頂部導航；內容寬度與密度合理。
需要身份與權限管理的完整後台，按需求提供登入、受保護佈局、業務頁面及 403/404；公開內容或局部修改不強加這些結構。
1440px 與 390px 寬度下都可正常使用；行動端側欄變抽屜。
亮/暗主題、品牌色、導航佈局、內容寬度、密度、圓角可配置並持久化。
不引入 Tailwind、shadcn 或第二套組件庫；顏色來自 Token。
頁面文案與使用者語言一致（預設中文）。
新增領域說明前後端邊界、API 契約與資料模型；用 Mock 時寫清楚替換點。
非同步頁面覆蓋 loading / empty / error / forbidden；危險操作二次確認，長時間任務可追蹤。
寫頁面前讀過 design.md；組件 API 經官方 CLI 或對應版本文檔核對（無 CLI 時註明版本）。
進入既有專案先跑組件文檔快照自檢；版本不一致時先重新整理或明確說明差異，不能用舊快照冒充當前 API。
程式碼符合 references/code-quality.md：無 any 偷懶、Hooks 依賴完整、狀態/錯誤/權限處理齊全、無深層 .ant-* 覆蓋；有 lint 腳本時 lint 通過。
動效符合 references/ant-motion.md：後台組件級 ≤300ms、支援 prefers-reduced-motion；不為了裝飾引入舊 rc-* 動效庫。

Ant Design 官方基線（直接內置）

antd 是基於 Ant Design 設計體系的 React UI 組件庫，適合企業級中後台與桌上型網站。當前模板使用 antd 6.7 + @ant-design/icons 6.3 + React 19。antd 6 要求 React >= 18，僅支援現代瀏覽器，預設啟用 CSS Variables，支援 SSR 與 Electron。

四大設計價值觀：

自然：符合直覺，降低認知成本；少發明、少裝飾。
確定性：統一的組件、Token、頁面模式，跨頁面一致。
意義感：每個介面服務於明確的工作目標，主操作唯一、回饋即時。
生長性：可組合、可擴展，隨業務與使用者成長演進。

視覺基線（官網規範）：

項	基線
畫板 / 柵格	1440px；4px 基礎網格、8px 主節奏；24 柵格
主要字型	14px / 22px；系統字型堆疊；字重 400/600
品牌色	`#1677ff`（基礎藍色板第 6 個）
功能色	成功 `#52c41a` / 警告 `#faad14` / 錯誤 `#ff4d4f`
中性色	88% / 65% / 45% / 25%；邊框 `#d9d9d9`；背景 `#f5f5f5`
圓角	2 / 4 / 6 / 8；基礎 6
間距	4 / 8 / 16 / 24 / 32（4px 網格）
佈局	左右佈局（導航固定）或上下佈局（中間縮放）
動效	克制，0.1–0.3s；中後台不做裝飾動畫

Token 三層：Seed（品牌/圓角/字型大小）→ Map（派生色/文字/邊框）→ Alias（組件級）。頁面唯讀 theme.useToken()，不寫死視覺值。

官方生態（詳見 references/ecosystem.md）：

庫	用途
`antd` + `@ant-design/icons`	核心組件與圖示（antd 6 ↔ icons 6）
`@ant-design/pro-components`	ProLayout / ProTable / ProForm；穩定版 2.x peer 仍是 antd ^5，antd 6 需 3.x beta 並鎖定版本
`@ant-design/charts`	複雜統計圖表；無 antd peer，主題需手動對齊
`@ant-design/x` + `@ant-design/x-markdown`	AI 對話 / Copilot / 串流 Markdown；peer `antd ^6.1.1`
`@xyflow/react`	工作流程/拓撲畫布；替代 antd 6 下 peer 仍為 v5 的 Pro Flow
`antd-mobile`	行動端 H5（獨立產品線）
`antd-mini`	支付寶/微信小程式
`@ant-design/web3`	Web3 / 錢包
Ant Design CLI	專案檢查與 v5→v6 遷移
Ant Motion / Landing / Pro	動效、首頁模板、完整腳手架

生態選型、版本矩陣、體積與相容性檢查請見 references/ecosystem.md。不要為了一個 Table 把 antd 降到 v5；也不要在 antd 6 上直接裝 Pro Flow / Pro Chat / Pro Editor。

設計契約：design.md 是機器可讀版本，寫頁面前先讀；本檔案的視覺表是摘要，衝突時以 design.md + 專案實際 antd 版本為準。

官方連結：ant.design · 設計價值觀 · 色彩 · 佈局 · 字型 · 社群精選 · CLI · For Agents · design.md。

官方 For Agents 規範（強制）

官方明確說明：當前版本可能包含破壞性變更，組件 API、慣例、檔案結構可能不同於訓練資料；寫程式碼前先讀規範，不要憑記憶寫 antd API。

寫任何 UI 之前：

讀 design.md 與 references/for-agents.md。
確認專案實際版本：antd info --version，或讀 package.json。

查組件 API 與可執行 Demo：

npx -y @ant-design/cli info <Component> --format json
npx -y @ant-design/cli demo <Component> <demo-name>
npx -y @ant-design/cli token <Component> --format json
npx -y @ant-design/cli semantic <Component> --format json

能安裝官方 skill 時，可執行 npx skills add ant-design/ant-design-cli；接入 MCP 請見 references/for-agents.md。
交付前盡量執行 npx -y @ant-design/cli lint ./src；再跑 pnpm typecheck && pnpm build。

除錯順序：antd env → antd doctor → antd info --version → antd lint。遷移順序：antd migrate → antd changelog → antd lint。沒有 CLI 時，用 https://ant.design/components/<name>.md 與本地 design.md 回退，並在交付中註明實際版本。

官方提示詞原文、完整命令表、MCP 配置與回退流程請見 references/for-agents.md。

CLI 貫穿生命週期：

階段	命令	目的
設計對齊	`npx -y @ant-design/cli design.md`	取得當前版本設計語言；與本技能 `design.md` 對照
選型/查 API	`info` / `demo` / `token` / `semantic`	先看真實 props、可執行 demo、組件 token 與語義 DOM
寫程式碼	讀 `references/components/<component>.md`	離線快照兜底；唯讀命中的 1–2 個
交付檢查	`lint` + `typecheck` + `build`	廢棄 API、型別、建置一起過
遷移	`migrate` → `changelog` → `lint`	v5→v6 或跨版本升級
診斷	`env` → `doctor` → `info --version` → `usage`	環境、版本、組件使用面排查

動效與程式碼品質（強制）

動效

寫任何過渡/入場/滾動效果前，讀 references/ant-motion.md。預設策略：

後台/工具/SaaS：只用 antd 內置 motion + CSS token；組件級 100/200/300ms，頁面級不超過 300ms；不做全螢幕轉場。
入口網站/官網/活動頁：可以用少量敘事型動效，頁面級 150/300/450/600ms；同一畫面只保留一條主要時間線。
Ant Motion 組件庫：rc-tween-one / rc-queue-anim / rc-scroll-anim / rc-banner-anim 均在 2022 年停止更新，peer 未宣告 React 19，且依賴 findDOMNode；不要預設裝進 antd 6 核心後台。確需行銷動效時鎖定版本、做真實瀏覽器驗證，並準備 CSS/IntersectionObserver 降級。
必須支援 prefers-reduced-motion；不用動畫承載唯一資訊；不讓動畫阻塞輸入/路由/載入。

程式碼品質

寫程式碼前讀 references/code-quality.md。它把阿里巴巴前端規約的命名、TypeScript、React Hooks、可及性、工程規範，適配到 React 19 + antd 6：

strict + 不用 any 偷懶；不用無理由的 @ts-ignore / 非空斷言。
函式組件 + Hooks 頂層呼叫；依賴陣列完整；不用 effect 派生 state。
列表 key 穩定；非同步頁面五態齊全；危險操作確認；伺服器端資料不進全域 store。
顏色/間距/圓角來自 token；不覆蓋 .ant-* 深層結構；390px 無橫向溢出。
互動元素可鍵盤操作、有可見焦點和可讀名稱；對比度滿足 WCAG AA。
專案有 lint 時交付前跑 pnpm lint / pnpm stylelint；沒有 lint 時按 code-quality.md §11 手工審查，並在交付說明中註明「未配置 lint」。

可選接入官方 F2E 工具：

npx f2elint
# 選擇 React + TypeScript，按需啟用 ESLint / Stylelint / Prettier / lint-staged / commitlint

已有 ESLint/Stylelint 配置時不要覆蓋，先合併規則；F2E 文件中的 class component / ReactDOM.render 規則不適用於 React 19。

初始化自檢（進入既有專案先做）

技能內置 36 份 antd 6.7.0 中文組件文檔快照，位於 references/components/。專案 antd 版本可能不同，不得預設快照就是當前 API。

# 1) 對齊專案安裝的 antd 版本與快照
node <SKILL_DIR>/scripts/check-antd-docs.mjs <專案目錄>

# 2) 不一致時按專案版本重新整理（需要官方 CLI；網路/沙箱受限時可指定本地 CLI）
node <SKILL_DIR>/scripts/fetch-antd-docs.mjs --project <專案目錄>
# 或明確指定：--version 6.7.0

退出碼 0：版本一致且 36 個檔案大小/雜湊值完整。
退出碼 1：版本不一致或檔案被改動；按提示重新整理，或把專案 antd 對齊到快照版本。
退出碼 2：無法確定專案 antd 版本；先 pnpm install，或傳 --target。
CLI 在沙箱/CI 寫 HOME 失敗時，可設 ANTD_CLI_HOME=/tmp/antd-home；已有本地 CLI 時用 ANTD_CLI_BIN=/path/to/antd。
自檢通過後，讀 references/components/README.md 的索引，只開啟當前要寫的 1–2 個組件，不要全量載入。

組件復用閘門（強制，先於任何 UI 程式碼）

在寫 JSX 之前，必須依序完成：

掃描專案：執行 node <SKILL_DIR>/scripts/scan-ui.mjs <專案目錄>，查看已安裝 UI 依賴、src/components / src/layouts 已有組件、antd 使用頻次。
檢索現有組件：用工具搜尋 src/components、功能目錄、同類頁面；能復用就不要新寫。
查 antd：Table / Form / Modal / Drawer / Descriptions / Tree / Upload / Empty / Result 等是否已覆蓋；有 CLI 時先跑 antd info <Component> / antd demo <Component>，再按 references/component-reuse.md 的映射表選型。
查官方擴展：@ant-design/pro-components、@ant-design/charts、@ant-design/x、antd-mobile；再考慮成熟第三方。
最後才自訂：放到 src/components，使用 theme.useToken()，說明為什麼不能復用。

跳過 1–4 直接手寫下拉選單、表格、彈窗、開關、日期選擇器、toast 或空狀態，視為未完成。交付時必須寫一句「復用了什麼 / 新增了什麼自訂組件」。

詳細規則、組件映射與反模式請見 references/component-reuse.md。

工作流程

0. 初始化自檢

進入既有專案，先跑：

node <SKILL_DIR>/scripts/check-antd-docs.mjs <專案目錄>

不通過時先重新整理快照或對齊 antd 版本；不要帶著版本偏移寫組件 API。新建專案在 scaffold 後、安裝依賴完成時再跑一次。

1. 先對齊五件事

資訊不足時只問必要問題，不要盤問：

品牌名：用於 APP_NAME、登入頁、標題。
應用型態：中後台 / 入口網站 / 工具型 SaaS / 資料看板 / 文檔 / AI 工作台 / 專案看板 / 電商 / 客服 / 設定中心等。
業務物件與頁面：例如「訂單清單 + 訂單詳情 + 退款審批」。
角色與權限：至少區分管理員與一般成員；決定是否需要權限樹。
資料來源：先用記憶體 Mock，還是直接對接真實介面。

資訊足夠時直接開始，不要停在方案階段。

2. 定架構、資料模型與 React 狀態邊界

涉及真實後端、新領域物件或複雜互動時，先讀 references/fullstack-design.md；要設計/審查伺服器端時再讀 references/backend-design.md，再寫頁面。至少產出：

3–6 個核心實體：關係、唯一約束、租戶隔離、狀態機、審計欄位。
API 契約：清單/詳情/寫操作、分頁、錯誤碼、冪等、並發控制。
狀態歸屬：URL（篩選/分頁）、伺服器端快取、表單、局部 UI、全域工作階段各放什麼。
後端約束：伺服器端驗證、交易邊界、冪等鍵、樂觀鎖、審計表、錯誤不洩漏內部資訊。
Mock 簽章：先按真實介面形狀實現，後續只替換 service 內部。

沒有契約就直接寫 JSX，視為未完成。前端權限只做展示，伺服器端必須重新驗證；後端驗收按 backend-design.md §14 清單。

3. 選外殼與預設

先按 references/app-patterns/README.md 的四問選型態；唯讀命中的類型檔案 + _common.md，不要全量載入：

型態	預設 / 外殼	寬度	密度	頁面配方
中後台 / 營運	標準中台 · 側邊	流動	預設	清單 + 詳情 + 權限
入口網站 / 官網	入口網站 · 頂部	定寬 1200	寬鬆	首屏 + 能力 + CTA
工具型 SaaS	頂部 · 自訂	流動/定寬	緊湊	工作區 + 歷史 + 設定
資料看板 / 監控	資料密集 · 側邊/無殼	流動	緊湊	指標 + 圖表 + 排行榜
文檔 / 知識庫	入口網站 · 頂部	定寬	預設	左樹 + 正文 + 右目錄
專案 / 看板	標準中台 · 側邊	流動	緊湊	橫向看板列
AI 對話 / Copilot	頂部/無殼	定寬/流動	預設	會話 + 訊息串流 + 上下文
電商 / 商品	入口網站 · 頂部	定寬	預設	商品網格 + 詳情 + 結算
客服 / 工單	資料密集 · 側邊	流動	緊湊	佇列 + 會話 + 詳情
登入 / 引導	無殼	定寬 420/720	預設	表單 + Steps

一級模組 ≤ 5 個優先頂部導航；模組多、需要長期切換則側邊導航。不要把「所有應用」都做成側邊欄後台。完整 36 型態、佈局示意圖與組件選型請見 references/app-patterns/README.md。

按需讀取協議：

只在 README.md 的總表裡定位型態，不要先打開類型檔案。
讀一次 _common.md，確定外殼、寬度、密度與通用狀態。
只打開命中的 1 個類型檔案；混合型態最多 2 個，並說明組合理由。
需要程式碼骨架時再讀 page-recipes.md，不要從零發明。
不要在交付中聲稱讀過未打開的類型檔案。

4. 生成專案

# 把 <SKILL_DIR> 換成技能資源區塊裡的絕對路徑
node <SKILL_DIR>/scripts/scaffold.mjs <target-dir> --name "<品牌名>"
# 需要順便裝依賴時：
node <SKILL_DIR>/scripts/scaffold.mjs <target-dir> --name "<品牌名>" --install

腳本會複製模板、替換 APP_NAME、套件名稱與 localStorage 前綴。不要跳過腳本手工複製模板再逐檔案改名。

生成後先跑一次：

cd <target-dir>
pnpm typecheck
pnpm dev

用示範帳號 admin / admin123 登入，確認基線可用後再改業務。

5. 改品牌與資訊架構

品牌名：src/config/constants.ts 的 APP_NAME（腳手架已寫入）。
預設設計：src/config/design.ts 的 DEFAULT_APP_CONFIG 與 DESIGN_PRESETS。
選單：src/config/menu.tsx 的 siderMenuItems；快捷搜尋：同檔案 appPages。
路由：src/router/index.tsx，每條業務路由都要有 handle: { title: '頁面名' }。
登入示範帳號：src/services/auth.ts。

選單與路由必須同步：選單項 key 等於路由路徑，否則反白和跳轉會錯位。

6. 調整設計配置

預設配置與預設集中在 src/config/design.ts：

interface AppConfig {
  mode: 'light' | 'dark' | 'system';
  primaryColor: string;
  navLayout: 'side' | 'top';
  siderTheme: 'dark' | 'light';
  contentWidth: 'fluid' | 'fixed';
  density: 'compact' | 'default' | 'comfortable';
  borderRadius: number;
  grayMode: boolean;
}

改產品預設型態：改 DEFAULT_APP_CONFIG。
改推薦組合：改 DESIGN_PRESETS。
新增配置項：擴充 AppConfig → 加預設值 → 在 AppConfigContext 暴露 setter → 在 DesignDrawer 加控制項 → 在 App.tsx / 佈局中消費。
配置持久化在 localStorage（預設 nova-admin:design）。
如果產品不允許使用者改佈局，從 DesignDrawer 中移除對應 Segmented，而不是隱藏整個面板。

7. 實現業務頁面

按 references/page-recipes.md 的骨架寫，不要每次都重新發明：

清單頁 = PageContainer + 篩選 Card + 表格 Card（工具列、批次操作、分頁）。
新建/編輯 = 獨立 Modal 組件 + Form 驗證 + 服務層呼叫。
詳情頁 = Descriptions + Timeline + 狀態 Tag。
看板 = 指標卡 + 圖表 + 最近記錄；模板自帶無依賴 SVG 圖表。
權限 = 角色表格 + Tree 權限抽屜。
入口網站/工具頁 = 頂部導航 + 定寬內容；行銷區塊可自建，但仍用 antd Token 與組件。
組件 API 先查 references/components/README.md 或官方 CLI；唯讀當前組件，不憑記憶寫 props。
互動細節按 references/ux-scenarios.md 選場景：先覆蓋五態，再補批次、長時間任務、衝突、權限申請等。
動效按 references/ant-motion.md：後台預設只做組件級 100–300ms 回饋；不要逐行入場、視差或全螢幕轉場。
程式碼品質按 references/code-quality.md：型別、Hooks、可及性、錯誤處理、命名與檔案邊界一起過；不要先堆頁面再回頭修。
模板內置三個擴展示例：/welcome 入口網站/官網、/workspace/board 專案看板、/docs 文檔中心；可參考它們復用到 AI、電商、客服、CRM、HR、財務、IoT 等型態。

新增領域資料時，同時更新 src/types、src/services、src/pages；不寫死 mock 路徑。

常見問題

Q：為什麼有了 antd 6，還要用 ProComponents？

ProComponents 是 antd 的進階封裝，適用於 ProLayout / ProTable / ProForm 等常見中後台模式。

lzhbhlrPython/antd-admin-template

antd-admin-template 是什麼？

在你喜歡的 AI 中提問

說明文件