# 应用程序 UI 指南 ## 概述此技能提供了全面的 UI/UX 指南，用于使用 Ant Design、shadcn/ui 和一致的设计令牌在 React/Next.js 应用程序中构建组件。它确保所有新组件都与现有的设计系统相匹配，具有适当的颜色、间距、排版和交互模式。 ## 何时使用此技能在以下情况下触发该技能： * **创建 UI 组件**：表单、表格、模式、卡片、列表 * **添加需要 UI 元素的新功能** * **构建数据可视化**或仪表板 * **实现加载状态**或动画 * **设计组件**以匹配设计系统 * **用户要求构建/创建/添加**任何可视组件 ## 快速入门 ### 第 1 步：识别组件类型确定您要构建的内容： * **抽屉/侧面板** → 阅读`references/component-patterns.md`（抽屉模式部分）**[强制模式]** * **数据表** → 阅读 `references/codebase-patterns.md` （表部分） * **表单/模态** → 阅读 `references/codebase-patterns.md` （模态模式部分） * **卡片/网格** → 阅读 `references/codebase-patterns.md` （卡片模式部分） * **需要颜色/间距** → 阅读 `references/design-tokens.md` * **需要动画/加载** → 阅读 `references/animations.md` ### 第 2 步：遵循组件清单每个组件必须： * 以Ant Design组件为基础 * 应用一致的间距（8px、12px、16px、24px） * 使用主题标记（`token.colorText`、`token.colorBgContainer`） * 包含正确的 TypeScript 类型 * 处理加载状态（骨架、旋转或加载道具） * 使用 `message.success()` / `message.error()` 显示反馈 * 支持响应式设计 * 包括正确的错误处理 ### 第 3 步：应用核心设计令牌 **颜色：** * 品牌橙色：`#F79402`（主要品牌颜色） * 产品负责人：`#7C4DFF`（紫色） * 技术所有者：`#52c41a`（绿色） * 错误/逾期：`#ff4d4f`（红色） * 始终使用 `theme.useToken()` 来获取动态颜色 **间距：** * 小间隙：`8px` * 中等间隙：`12px` * 标准内边距：`16px` * 节边距：`24px` **排版：** * 表格单元格：`fontSize: 12` * 辅助文本：`fontSize: '11px'` * 强文本：`<强文本>` * 次要：`` ## 核心模式 ### 模式 1：数据表所有数据表应遵循以下结构：从“antd”导入{表、输入、选择、ConfigProvider、主题}；从“@ant-design/icons”导入 { SearchOutlined }；导出默认函数DataTable() { const { token } = theme.useToken(); 返回（

{/* 过滤行 */}

} style={{ flex: 1 }} allowedClear /> <选择样式={{ flex: 1 }} placeholder=“过滤器”allowClear />

{/* 具有自定义主题的表格 */} <表数据源={数据} 正在加载={正在加载} 行键=“id” 尺寸=“小” 分页={false} 滚动={{ y: 'calc(100vh - 220px)', x: '最大内容' }} />

）； } **关键细节：** * 使用`ConfigProvider`进行表格主题定制 * 设置 `fontSize: 12` 以便紧凑显示 * 使用 `scroll={{ y: 'calc(100vh - 220px)' }}` 进行正确滚动 * 始终包含 `rowKey="id"` * 为紧凑表设置 `size="small"` ### 模式 2：模态框形式标准形式模态模式：从“antd”导入{模态、表单、输入、按钮、消息}；导出默认函数 AddModal({ isOpen, onClose, onSuccess }) { const [form] = Form.useForm(); const [isSubmitting, setIsSubmitting] = useState(false); const handleSubmit = async () => { 尝试{ const 值 = 等待 form.validateFields(); setIsSubmitting(true); 等待 api.post('/endpoint', 值); message.success("创建成功"); form.resetFields(); onSuccess(); onClose(); } 捕获（错误）{ message.error(error.response?.data?.error || "创建失败"); }最后{ setIsSubmitting(假); } }; 返回（ <表单form={form}layout=“vertical”onFinish={handleSubmit}> <输入占位符=“输入姓名”/> ）； } **关键细节：** * 对输入上方的标签使用 `layout="vertical"` * 包含带有明确信息的验证规则 * 成功时重置表单：`form.resetFields()` * 显示反馈： `message.success()` / `message.error()` * 设置 `maskClosable={true}` 以获得更好的用户体验 ### 模式 3：可选择的卡片网格带选择的水平滚动卡：从“antd”导入{主题、版式、头像}； const { 文本 } = 版式； const { token } = theme.useToken(); {items.map((item) => { const isSelected = selectedId === item.id; 返回（

setSelectedId(isSelected ? null : item.id)} 风格={{ 弹性：1，最小宽度：'200px'，最大宽度：'280px'，填充：'12px'，光标：'指针'，边框半径：'8px'，边框：已选中？ '1px 实心 #F79400' : `1px 实心 ${token.colorBorder}`, 背景颜色： isSelected ？ token.colorFillSecondary : token.colorBgContainer, boxShadow: '0 1px 2px rgba(0, 0, 0, 0.04)', }} > {item.name} {/* 附加内容 */}

）； })} **关键细节：** * 选择状态：边框为品牌原色 * 细微阴影：`0 1px 2px rgba(0, 0, 0, 0.04)` * 边框半径：`8px` * 使用 `token.colorBorder` 表示未选中状态 ### 模式 4：加载状态始终显示加载反馈： // 表格加载 <表加载={isLoading} dataSource={data} /> // 卡加载骨架 {数据===未定义？（ <卡片加载样式={{ minWidth: '200px' }} /> ) : ( <卡>{内容} )} // 按钮加载 // 页面内容骨架 <骨架活动段落={{ rows: 4 }} /> ### 模式 5：有后备的头像 {用户.个人资料图片？（ <头像大小={24} src={getCachedAvatarUrl(user.profilePic)} /> ) : ( <头像尺寸={24} style={{ backgroundColor: getAvatarColor(user.name) }}> {user.name.charAt(0).toUpperCase()} )} ## 造型方法 ### 优先顺序 1. **Ant Design 道具**先（类型、大小、危险性等） 2. **颜色的主题标记** (`token.colorBgContainer`) 3. **布局和间距的行内样式** 4. **Tailwind** 很少（仅适用于实用程序类） ### 要做的 ✅ * 使用Ant Design组件作为基础 * 使用`theme.useToken()`作为颜色 * 应用一致的间距（8px、12px、16px、24px） * 包括各处的加载状态 * 通过消息显示用户反馈 * 优雅地处理错误 * 使用 TypeScript 类型 ### 不要这样做 ❌ * 不要使用 CSS-in-JS 库 * 不要创建自定义 CSS 文件 * 不要硬编码颜色（使用标记） * 不要跳过错误处理 * 不要忽视响应式设计 * 不要使用过多的阴影 ## 常见食谱 ### 状态标签 <标签颜色={status.color || "#d9d9d9"} style={{ borderRadius: "8px", fontSize: 12 }}> {状态.名称 || “未设置”} ### 可点击文本 router.push(`/path/${id}`)}> {标题} ### 逾期指标 {已逾期 && ( <工具提示标题={`自${date}以来已逾期`}>

)} ### 选择商品数量 <选择> {items.map(item => ( <选项键={item.id} 值={item.id}>

{项目.名称} {item.count} 项

))} ## 参考文件阅读这些文件以获取详细信息： 1. **[design-tokens.md]()** \- 颜色、间距、排版系统 2. **[codebase-patterns.md]()** \- 现有代码的真实模式 3. **[component-patterns.md]()** \- Ant Design 组件标准 4. **[styling-layout.md]()** \- 布局模式和响应式设计 5. **[animations.md]()** \- 加载指示器和过渡 ## 决策树 **建立新的东西？** 1. **它是一个表吗？** → 阅读 `codebase-patterns.md` 表部分 2. **它是一个表单吗？** → 阅读 `codebase-patterns.md` 模态模式部分 3. **它是卡片网格吗？** → 阅读 `codebase-patterns.md` 卡片模式部分 4. **需要特定颜色？** → 阅读 `design-tokens.md` 5. **需要加载动画？** → 阅读 `animations.md` **对于任何组件：** * 使用打字稿 * 处理加载状态 * 显示错误信息 * 使用主题标记 * 测试反应能力 ## 版式比例 // 强文本（表格标题、卡片标题）标题 // 常规文本（表格单元格、正文）内容 // 辅助文本（字幕、元数据）元数据 // 第三级文本（附加信息）信息 ## 页面布局标准全高页面布局：导出默认函数 Page() { 返回（ {/* 适当滚动的页面内容 */}

）； } ## 数据获取使用SWR来获取数据：从“swr”导入 useSWR；从“@/lib/axios”导入{fetcher}； const { 数据、错误、正在加载、变异 } = useSWR( '/api/端点', 获取器， { 重新验证焦点：假，重新验证重新连接：假， } ）； ## 最终清单在完成任何组件之前： * 以 Ant Design 为基础 * 应用颜色主题标记 * 具有一致的间距 * 包括加载状态 * 显示错误反馈 * 具有 TypeScript 类型 * 反应灵敏 * 匹配现有模式 * 对表格使用 `fontSize: 12` * 包括适当的验证

用户界面指南

包含技能