| name | ant-design-skill |
| description | 基于 Ant Design 生成企业级中后台界面与业务组件。适用于管理后台、企业管理系统（ERP/CRM）、运维控制台、数据看板等产品场景；覆盖导航布局（SideLayout/TopLayout/MixedLayout）、查询筛选（QueryFilter）、表单（基础表单、分步表单、嵌入表单、筛选表单、登录表单）、表格（AntD Table / ProTable）、列表（AntD List / ProList）、详情展示与描述列表（Descriptions / ProDescriptions）、图表（Ant Design Charts）、指标卡、Design Token 与 ConfigProvider。用户提到 antd、Ant Design、ProComponents、ProTable、ProForm、中后台页面、管理后台、管理系统、数据看板、表格页、列表页、表单页、详情页、筛选查询、批量操作、操作列、详情展示、图表看板、指标卡、页面说明提示条、侧边栏收起、Design Token、ConfigProvider 或主题 token 时使用本 Skill；即使用户未明确说 Ant Design，也应在上述中后台场景使用。 |
Ant Design 企业级中后台设计 Skill
概述
本 Skill 基于 Ant Design 设计规范，提供企业级中后台产品的完整界面生成能力，包括：
- 全局样式：统一的 Design Token（颜色、字体、间距、阴影等）
- 导航框架：侧边导航、顶部导航、混合导航三种布局模板
- 业务组件：表单、表格、列表、描述列表、图表等组件的设计规范与代码模板
适用于构建功能复杂、信息层级较深的企业级管理后台产品。
Skill 覆盖范围与模板优先级
本 Skill 是对 Ant Design / ProComponents 中后台常用场景的精选产品化落地规范，不替代官方全量组件文档。生成时按以下优先级判断：
- 已覆盖场景优先 Skill：凡需求命中
references/ 或 scripts/ 中明确列出的组件类型 / 页面类型，优先遵循本 Skill 的选型、模板、结构、间距、容器与交互规则。
- 有代码模板时必须模板起步：凡
scripts/ 中已提供模板的场景，必须以对应模板复制改造为起点，只替换业务字段、数据、文案、图表配置与提交逻辑；保留模板的页面结构、关键 className、Design Token、间距节奏和交互分区。
- 有 reference 无模板时按规范生成：若场景在
references/ 中已有规则但没有完整模板，按对应 reference 生成，再结合 Ant Design / ProComponents 原生 API 实现。
- 未覆盖能力回到官方原生：若组件或低频能力未出现在
references/ / scripts/ 覆盖范围内，可参考 Ant Design / ProComponents 官方原生用法实现；视觉仍须继承本 Skill 的全局 token、布局密度、间距、圆角与投影，不得引入与现有体系冲突的局部样式。
- 官方文档只补 API，不覆盖 Skill 结构：官方文档用于确认组件能力、props 与版本差异；对本 Skill 已覆盖的场景，最终结构和视觉规则以本 Skill 模板与 reference 为准。
全局优先级只决定“从哪里起步”；各组件 reference 中的单独规则仍然有效，用于约束高风险结构（如分步表单 stepsDom、表格/列表卡内部间距、描述列表长文本操作位、图表 tooltip 层级等）。
分段阅读指引
本 Skill 与配套 references/、global-style.css 体量较大，禁止一次性通读全文。按任务类型按需加载：
按任务选读
| 任务 | 先读（SKILL.md 章节） | 再读规范 | 再读模板 | global-style.css 按需段 |
|---|
| 页面布局 / 导航布局 | 快速指引 → 文件索引、导航布局选择 | references/layout.md 对应布局章节；含页面说明提示条时读 §页面说明提示条 | scripts/layout/ 中 1 个 模板 | Navigation 组件区；页面说明提示条样式 |
| 表单页面 | 业务组件生成流程 → 生成表单页面 | references/components_Form.md 对应表单类型；多步骤 / 长流程先读 §分步表单选型 | scripts/form/ 中 1 个 模板 | Form 组件区（分步 / 嵌入 / 筛选表单样式） |
| 表格页面 | 列表页顶部筛选选型、生成表格页面 | references/components_Table.md 对应场景 | scripts/table/ 中 1 个 模板 | Table + Toolbar 组件区 |
| 列表页面 | 生成列表页面 | references/components_List.md 对应列表类型 | scripts/list/ 中 1 个 模板 | List + Toolbar 组件区 |
| 详情页 / 信息展示 | 生成描述列表页面 | references/components_DescriptionList.md 对应类型 | scripts/description-list/ 中 1 个 模板 | Descriptions 组件区 |
| 图表 / 指标卡 | 业务组件生成流程 → 生成图表页面 | references/components_Chart.md 图表模块与指标卡规则 | 官方 Ant Design Charts 文档 | 共性层 Token + Navigation 页面区块间距 |
| Design Token 集成 | Design Token 集成 | — | — | 共性层 Token |
global-style.css 结构速查（按需检索）
| 段落 | 检索关键词 | 何时读 |
|---|
| 共性层 Token | :root、--color-*、--space-*、--shadow | 查变量名或验收硬编码 |
| 模板工具类 | .ds-text-main、.ds-page-inline-alert | 页面说明提示条 / 批量提示条正文样式 |
| Navigation | --nav-*、SideLayout、TopLayout、MixedLayout | 实现 / 修改导航布局 |
| Table / List / Toolbar | Table、List、Toolbar | 表格、列表、筛选与工具栏 |
| Descriptions / Card List | Descriptions、Card List | 描述列表与卡片列表 |
| Form | .horizontal-steps-form、.vertical-steps-form、.embed-form-content | 分步 / 嵌入 / 筛选表单 |
| Global | Button、Badge、z-index | ConfigProvider 协同与浮层层级 |
组件命名：SKILL、references、scripts 模板标题统一使用 references 中的规范名称（如「支持展开的列表」，勿简称「展开列表」）。
技术栈
本 Skill 输出物为 React 19 + TypeScript 5.x 的 .tsx 组件，仅依赖社区开源生态，不引入任何私有/内部组件库，可直接用于对外项目。
核心依赖
| 类别 | 包 | 版本 | 说明 |
|---|
| UI 组件库 | antd | ^6.0.0 | 基础组件 + Design Token 主题系统 |
| 业务组件 | @ant-design/pro-components | ^2.7.0 | ProLayout / ProTable / ProForm / ProList / ProDescriptions |
| 图标 | @ant-design/icons | ^6.0.0 | 与 antd 6.x 生态适配 |
| 框架 | react / react-dom | ^19.0.0 | 模板基于 React Hooks |
| 语言 | typescript | ^5.0.0 | 输出代码禁止使用 any |
按需依赖
| 场景 | 包 | 版本 | 说明 |
|---|
| 图表页面 | @ant-design/charts | ^2.0.0 | 仅当页面需要折线图、柱状图、饼状图等图表模块时引入；具体图表 API 以对应版本官方文档为准 |
工程脚手架（二选一）
- Vite + React Router：轻量灵活，社区主流，推荐中小型项目；新项目优先使用当前稳定主版本
- Ant Design Pro（Umi 4）：开箱即用，约定式路由，推荐标准中后台
运行环境
- Node.js
>= 18
- 包管理器：pnpm
>= 8 / npm >= 9 / yarn >= 1.22
最小起步
pnpm create vite my-admin --template react-ts
pnpm add antd @ant-design/icons @ant-design/pro-components \
react-router-dom @tanstack/react-query axios
pnpm add @ant-design/charts@^2.0.0
pnpm dlx create-umi@latest
如安装 @ant-design/pro-components 时出现 peer dependency 提示，可在本地预览或验证场景使用 npm install --legacy-peer-deps 继续安装；安装后必须启动本地预览，检查 ProForm / ProTable / ProList / ProDescriptions / StatisticCard 等页面是否正常渲染与交互。若运行报错，优先修正具体 API 或样式问题，不得因此降级 antd 或替换 Skill 模板组件。
快速指引
文件索引
规范文档（references/）
| 类别 | 文件 | 说明 |
|---|
| 布局规范 | references/layout.md | 页面框架、主内容区、区块间距、页面说明提示条、侧边导航、顶部导航、混合导航的详细规范 |
| 表单规范 | references/components_Form.md | 基础表单、分步表单、嵌入表单、筛选表单、登录表单 |
| 表格规范 | references/components_Table.md | 基础表格、可筛选排序表格、嵌套表格、批量操作表格、拖拽排序表格、带工具栏表格 |
| 列表规范 | references/components_List.md | 基础列表、编辑列表、带工具栏的列表、支持展开的列表、支持选中的列表、查询列表、竖排样式列表、卡片列表 |
| 描述列表规范 | references/components_DescriptionList.md | 基础描述列表、可编辑描述列表、分组卡片描述列表 |
| 图表规范 | references/components_Chart.md | 基础图表引用、图表与指标卡共性规则、指标卡规范入口 |
代码模板（scripts/）
导航布局（规范见 references/layout.md）
| 布局类型 | 文件 | 说明 |
|---|
| 侧边导航 | scripts/layout/SideLayout.tsx | 功能模块较多、信息层级较深的复杂系统 |
| 顶部导航 | scripts/layout/TopLayout.tsx | 菜单项较少（≤9 个）的轻量级工具平台 |
| 混合导航 | scripts/layout/MixedLayout.tsx | 功能复杂、包含多个独立业务子系统的超大型平台 |
表单（规范见 references/components_Form.md）
| 场景 | 文件 | 说明 |
|---|
| 基础表单 | scripts/form/01-BasicForm.tsx | 单列垂直布局，字段较少的录入场景 |
| 横向分步表单 | scripts/form/02-HorizontalStepsForm.tsx | 长流程拆解为多个有序步骤（横向步骤条） |
| 竖向分步表单 | scripts/form/03-VerticalStepsForm.tsx | 步骤较多（≥4 步）的竖向步骤条；含 5 步示例、暂存草稿与终态汇总 |
| 嵌入模式表单 | scripts/form/04-EmbedForm.tsx | 内容量大、可明确分类的配置型表单（窄容器 / 区块较少） |
| 筛选表单 | scripts/form/05-QueryFilter.tsx | 列表页顶部查询筛选，支持展开收起 |
| 登录表单 | scripts/form/06-LoginForm.tsx | 登录场景专用布局 |
表格（规范见 references/components_Table.md）
| 场景 | 文件 | 说明 |
|---|
| 基础表格 | scripts/table/01-BasicTable.tsx | 仅展示数据，无排序筛选 |
| 可筛选排序表格 | scripts/table/02-FilterSortTable.tsx | 单列或多列排序、筛选 |
| 嵌套表格 | scripts/table/03-NestedTable.tsx | 行内展开关联子数据 |
| 批量操作表格 | scripts/table/04-BatchTable.tsx | 勾选多行执行批量操作 |
| 拖拽排序表格 | scripts/table/05-DragSortTable.tsx | 拖拽调整行顺序 |
| 带工具栏表格 | scripts/table/06-ToolbarTable.tsx | Tab 切换、筛选、按钮等组合 toolbar |
列表（规范见 references/components_List.md）
| 场景 | 文件 | 说明 |
|---|
| 基础列表 | scripts/list/01-BasicList.tsx | 标题、描述、状态、标签与操作 |
| 编辑列表 | scripts/list/02-EditList.tsx | 浏览时即时修改列表属性 |
| 带工具栏的列表 | scripts/list/03-ToolbarList.tsx | Tab 分组、搜索、筛选、新建等 |
| 支持展开的列表 | scripts/list/04-ExpandableList.tsx | 收起展开渐进呈现更多信息 |
| 支持选中的列表 | scripts/list/05-SelectableList.tsx | 批量选中与批量操作 |
| 查询列表 | scripts/list/06-QueryList.tsx | 筛选条件一次性提交查询 |
| 竖排样式列表 | scripts/list/07-VerticalList.tsx | 图片 + 文本等展示型信息 |
| 卡片列表 | scripts/list/08-CardList.tsx | 网格卡片布局；标题、状态 / 分类 Tag 与右侧操作须使用模板局部的可收缩标题组 + 独立操作区 |
描述列表（规范见 references/components_DescriptionList.md）
| 场景 | 文件 | 说明 |
|---|
| 基础描述列表 | scripts/description-list/01-BasicDescriptions.tsx | 详情页结构化字段只读展示 |
| 可编辑描述列表 | scripts/description-list/02-EditableDescriptions.tsx | 查阅同时即时修改、保存字段 |
| 分组卡片描述列表 | scripts/description-list/03-GroupedCardDescriptions.tsx | 多个语义分组独立展示 |
图表 / 指标卡（规范见 references/components_Chart.md）
| 场景 | 文件 | 说明 |
|---|
| 基础图表 | scripts/charts/00-OnlyChartsBlock.tsx | 折线图、柱状图、饼图等纯图表页面区块；不展示核心指标数值 |
| 基础指标卡 | scripts/charts/01-BasicStatisticCard.tsx | 单个核心指标，可附带趋势图或辅助信息 |
| 同级指标卡 | scripts/charts/02-IconStatisticCard.tsx | 多个同级核心指标横向并排 |
| 总分指标卡 | scripts/charts/03-TotalStatisticCard.tsx | 总量与分项占比关系展示 |
| 嵌套指标卡 | scripts/charts/04-NestedStatisticCard.tsx | 多个独立指标卡按同级 Grid 排列，单卡内展示数值与 mini chart |
| 页签联动指标卡 | scripts/charts/05-TabsStatisticCard.tsx | 多维指标通过页签切换查看 |
设计系统
| 文件 | 说明 |
|---|
references/global-style.css | 完整的 Design Token CSS 变量定义 |
导航布局选择
| 布局 | 适用场景 | 模板文件 |
|---|
| 侧边导航 (SideLayout) | 功能模块较多、信息层级较深（3级及以上）的企业级管理后台；高频操作的生产力工具（ERP、CRM、运维平台） | scripts/layout/SideLayout.tsx |
| 顶部导航 (TopLayout) | 菜单项较少（≤9 个一级菜单）的轻量级工具平台；主导航菜单水平分布于页面顶部 | scripts/layout/TopLayout.tsx |
| 混合导航 (MixedLayout) | 功能极其复杂、包含多个独立业务子系统的超大型平台；多任务流并行、需要频繁在不同大类业务间切换 | scripts/layout/MixedLayout.tsx |
使用流程
快速开始
当用户需要创建一个中后台页面时，按照以下流程操作：
- 判断需求是否命中 Skill 覆盖范围与模板优先级；已覆盖场景优先走本 Skill。
- 判断交付边界：0 到 1 新建中后台应用 / 平台 / 系统时默认生成导航布局与主内容区；在已有项目中新增页面时先复用现有 Layout / 导航 / 路由壳，只生成内容区。若已有项目没有导航且需求属于管理后台 / 平台级页面，应补充导航壳；用户明确要求单页 demo、局部组件或嵌入模块时不强制生成导航。
- 需要生成导航时，按 导航布局选择 确定且仅确定一种布局：SideLayout、TopLayout 或 MixedLayout。
- 按页面目标选择业务组件：列表/表格、表单、详情描述列表、图表/指标卡，必要时先做顶部筛选选型。
- 按 按任务选读 读取对应 reference 与模板；有模板时复制模板起步，无模板时按 reference + 官方原生 API 实现。
- 替换业务字段、数据、文案与提交逻辑，保留模板结构、关键
className、Design Token 和交互分区。
- 按 Design Token 集成 接入
global-style.css 并完成自测验收。
导航布局生成流程
- 读取
references/layout.md 对应布局章节与「布局生成强约束与验收清单」。
- 从
scripts/layout/SideLayout.tsx、TopLayout.tsx 或 MixedLayout.tsx 复制唯一匹配的模板。
- 仅替换 Logo、产品名称、菜单文本、菜单数量、用户信息和内容区业务内容。
- 保留导航 DOM 结构、CSS token、hover / active / collapsed 状态；SideLayout / MixedLayout 必须保留独立可见的侧边栏收起触发器，收起态只隐藏品牌文字不隐藏 Logo。
- 顶部导航一级菜单必须保留模板
.menu-item 选中态（文字加深 + 字重 500，无背景），禁止改为 Tab / 胶囊 / Segmented 样式；完整禁止项见 layout.md §顶部一级菜单规范。
- TopLayout / MixedLayout 顶部品牌区后不得生成竖向分割线；禁止给
.brand-name、.logo-section、.header-left、.topbar-left 添加 border-right、伪元素竖线或右侧 box-shadow。混合导航的侧边栏右边界必须从顶栏下方开始，不得穿过顶栏品牌区。
- TopLayout / MixedLayout 顶导搜索必须保留模板中的
Input.nav-search 结构；搜索建议、最近访问、跨业务候选等增强能力使用 Popover / Dropdown 浮层扩展，不得替换为 AutoComplete、Select 或 Input.Search。
业务组件生成流程
列表页顶部筛选选型（通用，与导航无关）
凡在任意导航框架（侧边 / 顶部 / 混合）下实现「列表或表格 + 顶部查询区」，均须先按本表选型，再实现具体组件。完整说明见 references/components_Table.md「列表页顶部筛选：QueryFilter vs 单行工具栏」。
| 判断条件 | 推荐方案 | 规范 / 模板 |
|---|
| 筛选项 ≤4 个，且可在一行内清晰展示（含查询/重置） | 单行工具栏 | components_Table.md → 工具栏布局 / 工具栏与表格间距 |
| 筛选项 ≥5 个，或需要展开收起 | 搜索卡承载 QueryFilter | components_Form.md §5；scripts/form/05-QueryFilter.tsx |
选型优先级：先判断能否单行展示；能则用单行工具栏，勿在仅 3～4 个筛选项时默认 QueryFilter（易导致按钮独占一行、控件过宽）。
生成表单页面
输入：需要创建一个新增用户的表单页面
输出：完整的表单组件代码
操作步骤：
- 根据表单复杂度选择类型（基础表单 / 分步表单 / 嵌入表单）
- 读取
references/components_Form.md 中对应组件的规范和模板
- 复制代码模板
- 替换字段定义、表单验证规则、提交逻辑
生成表格页面
输入：需要一个支持排序、筛选、批量操作的表格页面
输出：完整的表格组件代码
操作步骤：
- 若含顶部筛选，先按 列表页顶部筛选选型 确定单行工具栏或搜索卡承载 QueryFilter
- 读取
references/components_Table.md 中对应场景（如筛选排序、批量操作、拖拽排序等）
- 复制代码模板
- 配置列定义（columns）、排序/筛选逻辑、操作列
- 禁止在工具栏与表格之间插入汇总条；轻量统计放
PageHeader extra，见 components_Table.md §工具栏与表格之间禁止插入汇总条
- 表格卡内部遵循
components_Table.md §表格卡内部垂直节奏与§表格卡头部表达：左右对齐线 24px；卡内标题 / 工具栏 / Tab / Table / 分页之间统一 16px；表格卡左上角必须有简单标题、带左侧标题的单行工具栏或结果分类 Tab，禁止只有空白 padding 后直接进入表头，也禁止搜索框 / 筛选框作为卡片左上角唯一内容；只有确有分类切换时才使用 Tab
- ProTable 作为表格卡内容时，外层必须使用
ds-page-card ds-table-card-padded ds-pro-table-card；若使用 toolbar.menu.type: 'tab'，再叠加 ds-table-card-with-tabs，避免 ProTable 默认 ListToolBar / ProCard body padding 与外层卡片 padding 叠加
- Table / List 分页写法必须二选一：内置分页只使用组件自带
pagination，不得传入 ds-table-pagination / ds-list-pagination 等外置分页容器 class；外置分页必须关闭内置 pagination，并用 ds-table-pagination / ds-list-pagination 包裹 Pagination。同一段 16px 间距只允许一个来源承担，禁止 margin 与 padding 叠加成 32px；若使用 Table 内置分页，外层表格卡仍必须保留 padding-block-end: var(--padding)
- 检查表头与表体单行展示：短枚举列、可排序列须预留标题与图标宽度；名称 / 标识 / 负责人 / 操作列须设置合理宽度、
ellipsis / Tooltip 或 whiteSpace: 'nowrap'；禁止在 render 中手写纵向多行结构导致名称、负责人、操作链接换行。
- 检查操作列与横向溢出：操作列不得固定套用 120 / 160，须按文案分档设置宽度（2 个 2 字操作 ≥160px，含 3-4 字操作 ≥180-200px，两个 4 字操作 ≥200px），并统一用
Space + table-action-cell + whiteSpace: 'nowrap' 包裹。列数 ≥ 6、存在长文本列 + 日期 / 时间列 + 操作列，或操作列含 3-4 字操作时，必须检查列宽总和；仅当列宽总和超过容器，或已出现表头换行、操作列贴边 / 溢出、内容被裁切时，才设置 scroll={{ x: ... }}。启用 scroll.x 后，操作列建议 fixed: 'right'；未启用横向滚动时，不默认固定列。禁止压缩列宽、换行或裁切操作链接。
生成列表页面
输入：需要一个项目管理列表，支持编辑和删除
输出：完整的列表组件代码
操作步骤：
- 读取
references/components_List.md 中"编辑列表"
- 复制代码模板
- 配置数据源、列定义、操作处理函数
- 列表卡内部遵循
components_List.md §列表卡内部留白，与表格卡共用「左右对齐线 24px、卡内工具栏 / Tab / List / 分页之间 16px」规则；列表卡左上角必须有列表结果标题、当前结果标题或结果分类 Tab，禁止搜索框 / 筛选框作为卡片左上角唯一内容
- 外置分页列表必须使用
className="ds-list-pagination" 或等价 padding: var(--padding) 0；若使用 List / ProList 内置分页，不得再套外置分页容器或重复写 padding-top；无分页列表必须保留 16px 底部收口（.ds-list-bottom-spacer 或全局兜底），禁止最后一条列表项贴到卡片底部
- 带右侧图片 / 缩略图的列表项必须使用
components_List.md §列表条目内部布局：图片作为 media / extra 时相对整条列表项上下居中，外层用 .ds-list-item-media，内层固定尺寸图盒用 .ds-list-item-media-box，禁止贴顶或贴底
生成图表页面
输入：需要一个数据看板，包含核心指标、趋势图和明细表
输出：遵循页面布局规范的图表模块组合方案与必要代码引用说明
操作步骤：
- 读取
references/components_Chart.md 中"图表与指标卡共性规则"与 §图表实现分层
- 基础图表能力引用
@ant-design/charts@^2.0.0 对应版本官方文档，不在 Skill 内复制具体图表配置；完整图表（OnlyCharts、页签关联区、图表 Grid）使用 Charts 实现，指标卡 mini chart（56–96px）优先使用 SVG sparkline（见 01 / 04 模板），禁止 <img> 或文字占位
- 先确定页面结构：标题区、筛选区、指标卡、主图表、辅助图表、明细表格
- 图表模块间距、容器留白和页面背景遵循
references/layout.md
- 如涉及指标卡，先按
references/components_Chart.md 中 2–6 节的指标卡类型选取合适形态；基础图表区块与指标卡分类需保持边界清晰
- 多个同级指标须先按
components_Chart.md §同级指标组图表选型判断：优先指标卡 Grid、小型趋势图或单个多 series 主图；禁止多个全宽主图表纵向堆在一个大 Card 中
- 同级指标卡必须复用
scripts/charts/02-IconStatisticCard.tsx 的 StatisticCard.statistic 结构；不得在同一组中混用普通 Card + div/span 手写主数值，避免核心数字字号和上下留白不一致；默认示例可展示 4 张，但真实生成必须按指标数量自适应：1–2 张靠左不拉满，3–4 张按实际数量等分，5 张及以上最多 4 列换行，窄屏单列
- 总分指标卡必须按
components_Chart.md §总分指标卡处理：总值和每个分值都是同级指标单元，单元总数为 1 + 分项数量，每个单元等宽；必须使用 ds-total-statistic-card + ds-total-statistic-grid + ds-total-statistic-cell 专用结构，所有单元用 minmax(0, 1fr) 等分且 box-sizing: border-box / min-width: 0 / max-width: 100% 防止长金额或 padding 撑出卡片；禁止生成“左侧总值区 + 右侧分项区”的非等分结构，分割线如有必须挂在同级单元边界并随内容区高度伸展
- 指标卡内嵌迷你图表：须按
components_Chart.md §指标卡内嵌迷你图表处理容器对齐与 plot padding；配色按 §指标卡内嵌迷你图表配色（通用）执行——每个指标单元绑定一个语义主色，同一枚迷你图内线条 / 柱体 / 面积 / 点 / 环必须同源同色族，禁止线用一种语义色、主体填充又用另一套默认色；有填充区域的类型（如面积图）使用同色渐变且方向为上浅下深（SVG 默认 stopOpacity 0.08 → 0.22）；模板默认 SVG sparkline，不在指标卡内引入 Charts 完整配置；若需要坐标轴 / 图例 / 完整 tooltip，升级为独立图表区块
- 完整图表面积填充：
@ant-design/charts Area / Column 等有填充区域的类型，须使用 G2 l(角度) 0:rgba(...) 1:rgba(...) 写法（模板默认 l(270)、8% → 22%）；禁止在 style.fill 中使用 CSS color-mix() 或 linear-gradient()，否则 Canvas 无法解析、面积区不渲染
- 涉及 hover tooltip 的图表，必须按
components_Chart.md §图表 Tooltip 浮层规则处理：优先使用当前 Charts 版本支持的 API 将 tooltip 挂到 document.body / overlay 容器，层级高于导航基础层，且不得被图表容器 overflow 裁切
- 嵌套指标卡必须按
components_Chart.md §嵌套指标卡处理：多个嵌套指标卡不得使用 StatisticCard.Group、Divider 或外层白色容器合并，必须像同级指标卡一样使用局部 Grid / Flex 直接落在页面画布上；默认示例可展示 4 张，但真实生成必须按指标数量自适应：1–2 张靠左不拉满，3–4 张等分，5 张及以上最多 4 列换行，窄屏单列；单卡内部使用 statistic + chart，chart 只作为 56–96px（推荐 72px，最大 120px）的 mini chart，优先使用同色面积填充的趋势图且每张卡须绑定独立 semanticColor，禁止生成多个全宽监控图纵向列表
- 页签联动指标卡必须使用
ds-statistic-tabs 的 Tabs 选中态；active 项只保留贴在页签指标卡白色卡片底边的 2px 主色 ink bar，禁止主色文字 / 数值、整块浅色背景、描边或 .card-selected；各 Tab 等分均分（flex: 1），相邻 Tab 须清零 AntD 默认 margin-left（.ant-tabs-tab + .ant-tabs-tab），避免选中第二项及之后 Tab 时 ink bar 与总计项分割线之间出现空隙；Tabs nav 不保留底部分割线、默认 bottom margin、空 content holder / content / tabpane 高度或 .ant-pro-card-tabs 底部 padding；Tabs 卡片 body 横向 padding 建议为 0，由每个 .ds-statistic-tab-label 自己提供左右 24px 内边距，保证第一项总计标题距离整张卡片最左侧 24px，且在 active Tab 单元内也保持 24px 左内距；状态点属于辅助标识槽，不参与标题 / 主数值 / 状态 Tag 的 24px 文字对齐线，总计项不显示状态点，只有分项指标显示状态点，禁止直接用默认 Statistic.status 把标题向右挤；状态 Tag 必须与标题 / 主数值左对齐，不得与状态点对齐；关联展示内容在卡片外部作为独立区块，并由 .ds-page-shell / .ds-statistic-linked-content 保留 16px 区块间距，禁止在 tabs.children 中放业务内容；关联内容卡的标题、关联图表、表格或列表必须共享同一 24px 左右对齐线，优先把标题放在 body 内，避免 ProCard header/title 与 body padding 形成两套对齐线；关联图表使用 @ant-design/charts 随 activeKey 切换数据，禁止文字或灰色占位块
生成描述列表页面
输入：需要一个订单详情页，展示结构化字段并支持部分字段行内编辑
输出：完整的描述列表组件代码
描述列表选型（与导航布局无关，任意 SideLayout / TopLayout / MixedLayout 均适用）：
| 判断条件 | 推荐方案 | 规范 / 模板 |
|---|
| 单组字段，只读展示 | 基础描述列表 | references/components_DescriptionList.md §1；scripts/description-list/01-BasicDescriptions.tsx |
| 需行内编辑、保存、动态字段 | 可编辑描述列表 | references/components_DescriptionList.md §2；scripts/description-list/02-EditableDescriptions.tsx |
| 页面含 ≥2 个语义分组 | 分组卡片描述列表 | references/components_DescriptionList.md §3；scripts/description-list/03-GroupedCardDescriptions.tsx |
选型优先级：先判断分组数（≥2 组 → 分组卡片）；单组再判断是否需编辑（需编辑 → 可编辑，否则 → 基础）。
操作步骤：
- 按上表完成描述列表选型
- 读取
references/components_DescriptionList.md 对应 § 章节及「描述列表共性规则」
- 从
scripts/description-list/ 复制对应编号模板
- 配置
items / columns、值展示格式（Tag、金额、日期等）及操作 icon 对齐 class（.db-descriptions-value-row）
- 检查字段
label 保持单行展示，发生跨行时优先降低 column 或使用 .ds-descriptions / labelStyle 兜底
- 可编辑描述列表额外检查：编辑入口只由
editable 自动生成或由自定义逻辑手动接管二选一，禁止在 render 中叠加第二套编辑 icon / 按钮
常见使用场景
场景 1：快速搭建 CRUD 页面
布局：任意导航框架 + 顶部筛选（见通用选型） + 表格/列表
本场景是 Step 2（导航）+ Step 3（表格/列表 + 筛选）的组合示例；筛选选型不绑定侧边导航，顶部导航、混合导航下的列表页同样适用 列表页顶部筛选选型。
生成顺序：
- 按 Step 2 选择导航模板（SideLayout / TopLayout / MixedLayout 均可）
- 根据数据实体选择表格或列表组件
- 按通用筛选选型实现顶部查询区（单行工具栏或搜索卡承载 QueryFilter）
- 配置列定义、查询/重置及行内操作（编辑、删除等）
场景 2：创建配置类页面
布局：任意导航 + 嵌入表单（多区块分组）；区块较多时可按 §4 的宽面板扩展规则增强
生成顺序：
- 使用
components_Form.md §4 与 04-EmbedForm 作为基础模板
- 如区块 ≥4 或需要页内跳转，再按 §4「增强形态：宽面板」扩展布局；不另选独立模板
- 每个子区块一个
ProForm.Group；长 TextArea 标记 embed-form-field-full 整行；其余落单字段默认半宽
- PageHeader + 可选页面说明提示条 + 底部操作栏（重置 / 暂存 / 保存）；页面说明提示条默认不生成，仅在保存范围、字段联动或生效时机容易误解时添加
场景 3：创建多步骤表单页面
布局：任意导航 + 横向/竖向分步表单（嵌入现有后台，不单独拆应用）
生成顺序：
- 读取
components_Form.md §分步表单选型，确定横向（≤4 步）或竖向（≥4 步）
- 从
scripts/form/02-HorizontalStepsForm.tsx 或 03-VerticalStepsForm.tsx 复制模板（竖向 ≥4 步时必须用 03，含 5 步示例）；竖向分步表单必须以模板代码为起点，只替换步骤标题、字段、描述与提交逻辑，禁止从 AntD 裸 StepsForm 或自定义 Steps 重新拼装
- 页面结构固定为三层，禁止在
StepsForm 上方叠加进度 Card / 协作看板 / 待补材料清单：
PageShell（或布局主内容区）
├─ PageHeader（标题 + 可选「返回」）
├─ [可选] Alert（ds-page-inline-alert：仅在保存规则与步骤校验容易误解时生成）
└─ PagePanel（ds-page-card steps-form-page-card 白色表单区块）
└─ vertical-steps-form（≥5 步加 --five-steps）
└─ StepsForm
- 每步
stepProps.description 写明负责方（如「业务方 · 负责人」）；需中途保存时在 submitter.render 增加「暂存草稿」（不触发全量校验）
- 最后一步用
Descriptions 做信息汇总；汇总区与多方确认 Checkbox 必须使用 .steps-confirm-summary / .steps-confirm-checklist，保持 16px 间距；全局进度 / 缺件 / 处理方如需展示，放在列表页、详情页或工单中心，不在表单页重复
- 若表单从业务模块内进入（如新建、编辑、继续填写），须按
layout.md §嵌入现有后台：主内容区继承 处理：只生成主内容区，不重复生成全局导航或独立应用壳
验收清单：
通用实施原则
生成导航或业务组件时均须：
- 读取规范：导航见
references/layout.md；业务组件见对应 references/components_*.md
- 按模板实现：已覆盖且
scripts/ 提供模板的场景，从对应模板复制到用户工作区，禁止从零重写；未覆盖能力按官方原生 API 实现并继承全局视觉体系
- 样式引用：颜色、间距、圆角、阴影使用 CSS 变量，禁止硬编码色值
- 适配与验收：替换示例数据为业务数据；确保 Design Token 生效、交互符合规范
输出规则
- 禁止写入 Skill 目录：所有生成的代码必须写入用户工作区
- 资源引用：使用用户项目中的相对路径或公网占位图
- Design Token 优先：优先使用
global-style.css 中的变量，减少硬编码
- ConfigProvider 主题色：
theme.token / theme.components 传入具体 hex 色值，禁止传入 'var(--xxx)' 字符串
- 自测验收：
- 组件可正常渲染，无控制台报错
- 交互行为符合规范
- 无硬编码色值（除特殊场景）
- 无 TypeScript
any 类型
- 分步表单默认约束：生成
StepsForm 页面时，默认不生成表单区上方的进度 Card、待补材料清单、协作看板；步骤进度由 Steps 步骤条承担；需全局追踪时由列表/详情/工单页承担，见 components_Form.md §分步表单选型
- 页面标题唯一来源：导航布局只负责菜单与内容容器，业务主标题由页面层
PageHeader 负责；禁止布局层用 activeMenu 自动渲染标题后，页面层再写第二个标题
- 页面标题水平对齐：页面级
PageHeader / .ds-page-header 默认直接放在 .ds-page-shell 下，禁止设置 padding-inline；页面左右留白由布局层 <Content> / .content 唯一提供。只有 Card / 表格 / 列表等内容容器内部才使用 padding-inline: var(--nav-space-6)。
- 带面包屑的页面标题区：一级入口页默认不展示面包屑；面包屑只用于存在明确上级路径、下钻来源或返回语义的页面，例如详情页、编辑页、流程页、创建页，以及从对象详情或项目空间继续下钻出的列表 / 表格页。页面是否展示面包屑由信息架构层级决定，不由列表 / 表格 / 表单等组件形态决定。Layout / ProLayout / PageContainer 不得根据菜单层级、
activeMenu、pathname 或 route 自动生成全局面包屑；Breadcrumb 必须由业务页面显式声明。使用 ProLayout / PageContainer 生成一级入口页时须关闭默认面包屑，例如 breadcrumbRender={false}。使用面包屑时，标题行和下方业务卡片外缘必须共用 <Content> / .content 提供的 24px 页面左对齐线，禁止给 Breadcrumb / PageHeader 单独设置 padding-left、margin-left 或包进 Card。内容区顶部到面包屑的 24px 由 Content padding 提供；面包屑到标题行固定 var(--nav-space-2)（8px）；标题行到首个业务区块继续由 .ds-page-shell { gap: var(--nav-space-4) } 提供 16px。Breadcrumb 必须使用 / 分隔，AntD 写法固定 separator="/"。标题右侧如有全局操作、轻量统计或辅助说明，必须放在标题行右侧 ds-page-header-extra，与标题行同一行上下居中并靠右；不得放到面包屑行，也不得在标题与业务卡片之间单独插入汇总条。
- 侧边栏收起态用户区：收起态只保留 32px 头像，隐藏用户名和整个
.user-action-icons 容器；头像必须设置 flex: 0 0 32px / min-width: 32px 防止被 flex 压缩，.user-actions 收起态须 gap: 0。
- 侧边栏边界与间距：SideLayout / MixedLayout 中，除 24px 收起触发器允许向侧边栏右侧受控外露 12px 外，Logo、品牌名、菜单、分组标题、底部用户区（如有）均不得横向溢出；品牌名、菜单文本、用户名必须单行省略。侧边导航节奏固定为：顶部到首个分组 12px、分组标题高 40px、标题到菜单 0、菜单行 40px、分组之间 12px + 分割线 + 12px；如有固定底部用户区，最后一组到底部用户区避让 12px。
- 搜索卡 Card body 间距：
<Card className="ds-search-panel"> 的内边距必须作用到 .ant-card-body；禁止只在 Card 外层写 padding，禁止同时写 styles.body.padding 与 .ds-search-panel padding。搜索框到 Tab 的 16px 只由 .ds-search-tabs-row 承担，搜索行不得再写额外 marginBottom。
- 卡内顶部结果分类 Tab 与轻量工具栏分层：表格 / 列表卡顶部若是结果分类 Tab（如「全部 / 进行中 / 失败」），必须使用
ds-card-tab-strip + toolbar-tabs；首个 ds-card-tab-strip 若位于已有顶部 padding 的 ds-page-card / ds-table-card 容器内，顶部 16px 由容器 padding 承担，禁止再叠加 Tab Strip 顶部 padding、空占位块或 marginTop，避免 32px 顶距。纯 ds-list-card 壳层只承担水平 24px，顶部 16px 仍由内部 Tab Strip / Header 垂直 padding 承担。Tab 行高固定 32px，下方到 Table / List 内容保留 16px；选中态只保留主色文字和 ds-tab-count 弱主色数量，禁止灰色底线、AntD ink-bar、整块背景、描边或红 / 黄 / 绿 Badge。表格卡无结果分类时不要强行生成 Tab，使用 ds-card-title-row + ds-table-title 表达当前数据集名称；禁止卡片左上角只有空白 padding 后直接进入表头，也禁止搜索框 / 筛选框作为卡片左上角唯一内容。Tab 左侧展示结果分类，搜索 / 筛选 / 操作按钮在右侧且不得跨行；右侧控件放不下、字段 ≥5 个或需要展开收起时，必须上移为独立 ds-search-panel + QueryFilter。普通标题 + 搜索 / 少量筛选 / 结果级操作才使用 ds-card-toolbar ds-card-toolbar-inline，其中左侧必须是 ds-table-title 或当前结果标题；搜索卡 Tab 继续使用 ds-search-tabs，页签联动指标卡继续使用 ds-statistic-tabs，不要混用。
- 页面级白卡投影：页面业务容器（
ds-page-card、ds-search-panel、ds-list-card、ds-table-card、ds-statistic-card）统一白底、8px 圆角、var(--shadow) 轻投影并清除默认描边；AntD Card / ProCard 生成时优先 bordered={false}。对象选择卡 / 卡片列表项可用细描边表达交互状态，但不得替代页面级白卡投影。
- 页面级内容卡 padding 唯一来源：基础业务卡内容区固定上下
var(--padding)（16px）、左右 var(--nav-space-6)（24px），适用于通用 Card、列表卡、表格卡、指标卡、图表卡、描述分组卡和对象选择卡；不适用于表单内部字段布局、StepsForm 步骤条、嵌入表单弱分组、QueryFilter 字段栅格和 submitter。普通 div.ds-page-card 由外层承担；AntD Card / ProCard / StatisticCard 必须命中 .ant-card-body / .ant-pro-card-body；ds-list-card 的 Card body 必须清零，由壳层承担 24px 内容线。禁止 bodyStyle={{ padding: 24 }}、styles.body.padding: 24、toolbar / List item / Table wrapper 再次写水平 padding。Table 外框跟随卡片 24px 内容线，但首末列必须保留 var(--padding)（16px）单元格内部留白，避免表头 / 行内容文字贴边。ProTable 必须用 ds-pro-table-card 清掉内部 ProCard body / ListToolBar 默认 padding，避免与外层表格卡叠加。对象选择卡可保留描边状态，但 body padding 不例外。
- 搜索卡与 QueryFilter 分层：
ds-search-panel 是页面级筛选区容器，负责白卡外观、区块间距和 Card body padding；QueryFilter 是内部筛选表单组件，负责字段栅格、展开收起、查询 / 重置和提交行为。复杂筛选必须使用 <Card bordered={false} className="ds-search-panel"><QueryFilter ... /></Card>；禁止把 QueryFilter 当成独立白卡外壳，也禁止在复杂筛选场景用手写搜索卡字段替代 QueryFilter。筛选项 ≤4 且一行清晰时才使用卡内单行工具栏或轻量搜索卡字段。
- 弹窗 / 抽屉浮层结构：生成 Modal / Drawer 前必须先判断展示类还是操作类；浮层必须显式定义宽度档位、最大视口约束、滚动归属和操作按钮位置，详见
components_Form.md §弹窗 / 抽屉浮层容器。固定设计值须集中到局部常量或设计 token 映射中，禁止在 styles 和计算表达式里散落硬编码。普通业务 Modal 默认设置 centered，禁止依赖 AntD 默认 top: 100px 造成弹窗偏上；操作类 Modal 使用 header / body / footer 三段式，header 与 footer 有分割线，body 是唯一滚动区且 footer 固定可见；展示类 Modal 可不生成 footer。桌面 Drawer 默认使用左关闭 + 标题 + 右侧操作按钮的固定 header，body 单独滚动；禁止沿用右上角默认关闭、把按钮放进可滚动 body，或让底部按钮被内容挤出屏幕。
Design Token 集成（复制模板时必做）
从 Skill 复制 layout / form / list 模板到用户项目时，模板内的 import '../../references/global-style.css' 指向 Skill 仓库路径，在用户项目中不会自动生效。须按以下 checklist 集成：
| 步骤 | 操作 |
|---|
| 1. 复制 global-style.css | 将 Skill 的 references/global-style.css 复制到用户项目，建议 src/styles/global-style.css（或项目既有全局样式目录） |
| 2. 全局引入 | 在入口文件（如 src/main.tsx）添加 import './styles/global-style.css' |
| 3. 移除 Skill 路径 | 删除已复制模板中的 import '../../references/global-style.css'（或改为指向步骤 1 的实际相对路径） |
| 4. ConfigProvider | App 根节点包裹 antd ConfigProvider，theme.token.colorPrimary 等传入 hex（如 #1677ff）；borderRadius / borderRadiusLG 统一为 8（与 --border-radius-lg 一致），禁止 CSS 变量字符串 |
| 4b. ProLayout 间距（必做） | 使用 ProLayout / PageContainer 时，必须引入 global-style.css（清零 Pro 默认 40px padding）；建议在根节点叠加 ProConfigProvider，token.pageContainer.paddingInlinePageContainerContent: 0、paddingBlockPageContainerContent: 0 |
| 5. 验收 | 页面背景为 #f7f8fa；导航 hover/active 背景正常；ProCard / StatisticCard 圆角为 8px；控制台无 global-style.css 404；DevTools 检查 .ant-pro-layout-content / PageContainer 无 40px padding |
import './styles/global-style.css';
import { ConfigProvider } from 'antd';
import { ProConfigProvider } from '@ant-design/pro-components';
import App from './App';
root.render(
<ConfigProvider
theme={{
token: {
colorPrimary: '#1677ff',
borderRadius: 8,
borderRadiusLG: 8,
},
}}
>
<ProConfigProvider
token={{
pageContainer: {
paddingInlinePageContainerContent: 0,
paddingBlockPageContainerContent: 0,
},
}}
>
<App />
</ProConfigProvider>
</ConfigProvider>,
);
table 模板：scripts/table/ 多数文件未 inline import global-style.css，同样依赖步骤 2 的全局引入，否则 var(--padding) 等变量未定义。
