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、路由与菜单；新增业务页面时，在 src/pages 下按功能目录组织。遇到通用交互（确认弹窗、文件上传、富文本、批量选择、草稿保存），先在项目里搜同类实现，不要去 npm 装新库。

8. 验收动效与可访问性

动效：确认回退方案不为空；关闭 prefers-reduced-motion 后主交互路径正常。
可访问性（WCAG AA）：色彩对比度、Tab 导航顺序、ARIA 标签、表单错误关联、焦点管理、自定义组件的角色与状态；通用组件（弹窗、下拉、树、表格）的 a11y 已在 antd 内实现，但对话框焦点、表单错误关联、自定义内容仍需手动处理。
不符合项记录在交付说明中，优先级 P1（阻塞操作）必须有修复路径。

9. 收尾检查

按 references/code-quality.md 最后一个清单逐项过，再跑一次完整构建：

pnpm typecheck && pnpm build

所有把关（代码质量、动效合规、可访问性、后端契约对齐、设计规则、场景覆盖）合并记录在交付说明中：列出了做了哪些、跳过了哪些（含原因），以及每个检查项的结论。

Ant Design Web 应用设计系统（中后台优先）