Ant Design Skill

核心用法

Ant Design Skill 是面向 React 前端开发的实用设计技能，专注于使用 Ant Design v5（antd）快速构建一致、美观的用户界面。其核心定位是“非丑陋的默认方案”——在不需要重度定制的前提下，通过标准化模式产出专业级 UI。

技术栈前提：React + Ant Design v5+（基于 CSS-in-JS 的 Design Tokens 体系）。若检测到 v4（Less 变量），需暂停并确认版本。

标准开发流程：
1. 确认版本：锁定 antd v5+ 以使用 Token 体系
2. 选择页面模式：CRUD 列表、向导（Steps）、设置页、Dashboard
3. 搭建布局骨架：Layout + Sider + Header + Content + Menu
4. 构建核心交互：表单（Form + 验证规则）、表格（Table + 服务端分页）、弹层（Modal/Drawer）
5. 完善反馈机制：message、notification、Modal.confirm
6. 应用主题令牌：通过 ConfigProvider 全局配置或组件级覆盖
7. 验证三态：空状态、加载状态、错误状态 + 移动端适配（360px 基准）

关键模式：

• 表单：垂直布局 + Form.useForm() 管理编辑流，内置验证优先
• 表格：左标识、中属性、右操作列；强制 rowKey；服务端分页
• 主题：theme.defaultAlgorithm/darkAlgorithm + 精简 Token 集合，避免过度定制

显著优点

• 开箱即用的规范性：沉淀了 CRUD、Dashboard、Wizard 等高频场景的成熟模式，减少设计决策负担
• Token 体系现代化：v5 的 Design Tokens 支持算法化主题（明暗切换）、组件级细粒度覆盖，告别 Less 变量时代
• 可复制的心智模型：Layout/Form/Table/Modal 等模式提供“脑内代码片段”，提升开发效率
• 生态完备：配套 README、protocols（LLM-first 契约）、tokens 手册、components 食谱、examples 示例库、starter 脚手架

潜在缺点与局限性

• 版本锁定风险：v5 Token 体系与 v4 不兼容，遗留项目迁移成本高
• 设计灵活性边界：强调“非丑陋的默认”而非“高度定制”，强视觉品牌需求可能受限
• AntD 生态依赖：组件库体积、样式侵入性、升级节奏完全绑定 antd 官方
• 移动端深度适配有限：仅要求“360px 布局 sanity”，复杂移动端交互需额外方案

适合人群

• 中后台前端开发者：需快速交付管理后台、数据密集型界面
• 全栈工程师：React 技术栈，追求 UI 一致性而不愿投入设计资源
• LLM 辅助编程场景：protocols 目录支持“描述即代码”的确定性生成

常规风险

• 版本误判：未确认 antd 版本即应用 Token 配置，导致样式失效
• 主题过度定制：覆盖过多组件级样式，维护成本激增，违背技能初衷
• 表格性能：大数据量时未启用服务端分页/虚拟滚动，引发渲染卡顿
• 表单验证冗余：自定义验证替代内置规则，增加代码复杂度与测试负担

核心用法

本 Skill 专为使用 React + Ant Design v5 技术栈的前端开发者设计，提供系统化的 UI 构建指南。使用时遵循既定工作流：先确认技术栈版本（确保 v5+ 以支持 Design Token），选择页面模式（CRUD 列表、向导、设置页、仪表盘），搭建 Layout 骨架（Sider + Header + Content），再实现核心交互组件（Form、Table、Modal/Drawer），最后添加反馈循环（message、notification）并通过 ConfigProvider 应用主题令牌。

组件模式涵盖四大场景：Layout 布局推荐使用可折叠 Sider 与 Header 顶部操作栏；表单设计坚持纵向布局与内置验证规则；表格 CRUD 遵循「左标识、中属性、右操作」列排序；弹窗与抽屉根据表单长度选择——短表单用 Modal，长表单或需保留上下文时用 Drawer。主题系统基于 v5 的 CSS-in-JS 方案，通过 ConfigProvider 全局配置 token（colorPrimary、borderRadius 等）并支持组件级细粒度覆盖，同时内置 darkAlgorithm 实现一键暗色模式。

显著优点

1. 权威性与成熟度：背靠阿里巴巴开源的 Ant Design——企业级 UI 组件库的事实标准，拥有 55k+ GitHub Stars 和广泛的业界验证。

2. 设计一致性：Design Token 机制确保颜色、圆角、间距等视觉变量全局可控，告别「每页不同色」的维护噩梦。

3. 开发效率：提供可直接复制的 CRUD、Settings、Wizard 页面模板，将常见企业场景的开发时间从数小时缩短至分钟级。

4. 可访问性基础：Ant Design 组件内置 ARIA 属性与键盘导航支持，Skill 中的模式建议进一步引导无障碍最佳实践。

潜在缺点与局限性

• 技术栈锁定：仅适用于 React + Ant Design 项目，Vue/Angular 开发者无法直接使用，技术迁移成本较高。

• 版本依赖严格：假设 v5+ 环境，若项目停留在 v4（Less 变量方案），部分 Theme Token 语法不兼容，需手动降级处理。

• 设计灵活性边界：Ant Design 的「企业级审美」偏向稳重保守，追求高度定制化视觉风格（如激进的品牌色、非标准组件形态）时可能遭遇瓶颈。

• 移动端局限：虽支持响应式布局，但组件库主要针对桌面端设计，复杂移动端交互（手势滑动、底部栏导航）需额外适配。

适合的目标群体

• 中后台产品开发团队：需要快速交付管理后台、数据看板、配置中心的工程师与前端负责人。

• 设计-开发协作型团队：设计师提供 Ant Design 视觉稿后，开发者可直接套用 Skill 中的组件模式，减少沟通损耗。

• Ant Design 初学者：希望系统学习 v5 Token 系统与最佳实践，避免踩坑「自定义 CSS 覆盖导致升级断裂」等经典问题。

使用风险

| 风险类型 | 说明 | 缓解建议 |

|---------|------|---------|

| **性能风险** | Table 大数据量时未配置虚拟滚动可能导致渲染卡顿 | 遵循 Skill 建议启用 server-side pagination，必要时配合 react-window |

| **主题升级风险** | 过度使用组件级 token 覆盖可能造成维护负担 | Skill 明确建议「设置少量全局 token，仅在必要时组件级覆盖」 |

| **依赖版本风险** | Ant Design 大版本升级（v5→v6）可能引入 Breaking Changes | 定期关注官方 changelog，避免锁定过旧版本 |

| **无障碍遗漏** | Skill 未详尽覆盖 ARIA 属性配置细节 | 生产环境建议结合 axe-core 等工具二次检测 |

总体而言，本 Skill 作为纯文档型指导资源，无运行时代码注入、无网络请求、无用户数据收集，安全风险极低，可放心集成至开发工作流。