--- type: ui-spec outputFor: [frontend] dependencies: [prd] --- # UI/UX 规范文档 ## 文档信息 - **功能名称**：{{FEATURE_NAME}} - **版本**：1.0 - **创建日期**：{{DATE}} - **作者**：UI Designer Agent ## 摘要 > 下游 Agent 请优先阅读本节，需要细节时再查阅完整文档。 - **设计风格**：[视觉风格定义] - **主色调**：[色值] - **核心组件**：[关键 UI 组件列表] - **响应式断点**：[Mobile / Tablet / Desktop] - **设计系统**：[是否使用现有 UI 库] --- ## 1. 设计概述 ### 1.1 设计理念 [描述核心设计理念和视觉风格] ### 1.2 设计原则 - **简洁**：[描述] - **一致**：[描述] - **可访问**：[描述] - **响应式**：[描述] --- ## 2. 用户流程 ### 2.1 主流程 ```mermaid flowchart TD A[入口] --> B[步骤 1] B --> C{决策点} C -->|选项 A| D[路径 A] C -->|选项 B| E[路径 B] D --> F[完成] E --> F ``` ### 2.2 流程说明 | 步骤 | 页面/组件 | 用户行为 | 系统响应 | |------|-----------|----------|----------| | 1 | [页面名] | [行为描述] | [响应描述] | | 2 | [页面名] | [行为描述] | [响应描述] | --- ## 3. 设计令牌 ### 3.1 颜色系统 #### 主色调 | 名称 | 色值 | 用途 | |------|------|------| | Primary | #{{PRIMARY_COLOR}} | 主要操作、链接 | | Primary Light | #{{PRIMARY_LIGHT}} | 悬停状态 | | Primary Dark | #{{PRIMARY_DARK}} | 按下状态 | #### 语义色 | 名称 | 色值 | 用途 | |------|------|------| | Success | #22C55E | 成功状态 | | Warning | #F59E0B | 警告状态 | | Error | #EF4444 | 错误状态 | | Info | #3B82F6 | 信息提示 | #### 中性色 | 名称 | 色值 | 用途 | |------|------|------| | Gray 50 | #F9FAFB | 背景色 | | Gray 100 | #F3F4F6 | 卡片背景 | | Gray 300 | #D1D5DB | 边框 | | Gray 500 | #6B7280 | 辅助文字 | | Gray 700 | #374151 | 正文文字 | | Gray 900 | #111827 | 标题文字 | ### 3.2 暗色模式 #### 语义映射 | 语义名称 | 亮色值 | 暗色值 | 用途 | |----------|--------|--------|------| | --color-bg | #FFFFFF | #1A1A2E | 页面背景 | | --color-surface | #F9FAFB | #16213E | 卡片/面板背景 | | --color-text | #111827 | #E2E8F0 | 正文文字 | | --color-text-secondary | #6B7280 | #94A3B8 | 辅助文字 | | --color-border | #D1D5DB | #334155 | 边框 | | --color-shadow | rgba(0,0,0,0.1) | rgba(0,0,0,0.4) | 阴影 | #### 主题切换机制 1. **系统偏好**：`prefers-color-scheme: dark` 作为默认 2. **手动切换**：`` 属性覆盖 3. **持久化**：`localStorage.setItem('theme', 'dark'|'light'|'system')` #### CSS 实现 ```css :root { --color-bg: #FFFFFF; --color-surface: #F9FAFB; --color-text: #111827; --color-border: #D1D5DB; } [data-theme="dark"], @media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { --color-bg: #1A1A2E; --color-surface: #16213E; --color-text: #E2E8F0; --color-border: #334155; } } ``` #### 暗色模式无障碍 - 暗色背景上文字对比度仍需满足 ≥ 4.5:1 - 避免纯黑 (#000) 背景，减少视觉疲劳 - 暗色模式下阴影使用更深的 rgba 值 - 图标/插画需提供暗色适配版本或使用 `currentColor` ### 3.3 排版系统 | 名称 | 大小 | 行高 | 字重 | 用途 | |------|------|------|------|------| | H1 | 36px | 1.2 | 700 | 页面标题 | | H2 | 30px | 1.3 | 600 | 区块标题 | | H3 | 24px | 1.4 | 600 | 子标题 | | H4 | 20px | 1.4 | 500 | 小标题 | | Body | 16px | 1.5 | 400 | 正文 | | Small | 14px | 1.5 | 400 | 辅助文字 | | Caption | 12px | 1.4 | 400 | 注释 | **字体族**： - 英文：Inter / -apple-system / system-ui - 中文：PingFang SC / Microsoft YaHei ### 3.4 间距系统 基础单位：8px | 名称 | 值 | 用途 | |------|-----|------| | spacing-1 | 4px | 紧凑间距 | | spacing-2 | 8px | 小间距 | | spacing-3 | 12px | 默认间距 | | spacing-4 | 16px | 中等间距 | | spacing-5 | 20px | 较大间距 | | spacing-6 | 24px | 大间距 | | spacing-8 | 32px | 区块间距 | | spacing-10 | 40px | 大区块间距 | ### 3.5 圆角 | 名称 | 值 | 用途 | |------|-----|------| | rounded-sm | 4px | 小元素 | | rounded-md | 6px | 按钮、输入框 | | rounded-lg | 8px | 卡片 | | rounded-xl | 12px | 模态框 | | rounded-full | 9999px | 圆形 | ### 3.6 阴影 | 名称 | 值 | 用途 | |------|-----|------| | shadow-sm | 0 1px 2px rgba(0,0,0,0.05) | 微弱阴影 | | shadow-md | 0 4px 6px rgba(0,0,0,0.1) | 悬浮元素 | | shadow-lg | 0 10px 15px rgba(0,0,0,0.1) | 卡片 | | shadow-xl | 0 20px 25px rgba(0,0,0,0.15) | 模态框 | --- ## 4. 页面规范 ### 4.1 页面：{{PAGE_NAME}} #### 布局结构 ``` +----------------------------------+ | Header (64px) | +----------------------------------+ | Sidebar | | | (240px) | Main Content | | | (flex-1) | | | | +----------------------------------+ | Footer (48px) | +----------------------------------+ ``` #### 响应式断点 | 断点 | 宽度 | 布局调整 | |------|------|----------| | 移动端 | < 768px | 侧边栏收起，单列布局 | | 平板 | 768-1024px | 侧边栏可折叠 | | 桌面 | > 1024px | 完整布局 | #### 组件清单 | 组件 | 位置 | 说明 | |------|------|------| | [组件名] | [位置] | [说明] | --- ## 5. 组件规范 ### 5.1 按钮 Button #### 变体 | 变体 | 用途 | 样式 | |------|------|------| | Primary | 主要操作 | 实色背景 | | Secondary | 次要操作 | 描边 | | Ghost | 第三操作 | 无边框 | | Danger | 危险操作 | 红色 | #### 尺寸 | 尺寸 | 高度 | 内边距 | 字号 | |------|------|--------|------| | Small | 32px | 12px 16px | 14px | | Medium | 40px | 12px 20px | 16px | | Large | 48px | 16px 24px | 18px | #### 状态 | 状态 | 变化 | |------|------| | Default | 默认样式 | | Hover | 亮度 +5% | | Active | 亮度 -5% | | Disabled | 透明度 50%，禁止点击 | | Loading | 显示加载动画 | ### 5.2 输入框 Input #### 变体 | 变体 | 用途 | |------|------| | Text | 文本输入 | | Password | 密码输入 | | Search | 搜索框 | | Textarea | 多行文本 | #### 状态 | 状态 | 边框颜色 | 说明 | |------|----------|------| | Default | Gray 300 | 默认 | | Focus | Primary | 聚焦 | | Error | Error | 错误 | | Disabled | Gray 200 | 禁用 | ### 5.3 卡片 Card ``` +----------------------------------+ | [图片区域] (可选) | +----------------------------------+ | 标题 | | 描述文字... | +----------------------------------+ | [操作区域] (可选) | +----------------------------------+ ``` **样式**： - 背景：White - 边框：1px solid Gray 200 - 圆角：rounded-lg - 阴影：shadow-md --- ## 6. 动效规范 ### 6.1 过渡时长 | 名称 | 时长 | 用途 | |------|------|------| | fast | 150ms | 按钮状态 | | normal | 250ms | 展开/收起 | | slow | 350ms | 页面切换 | ### 6.2 缓动函数 | 名称 | 值 | 用途 | |------|-----|------| | ease-out | cubic-bezier(0, 0, 0.2, 1) | 进入 | | ease-in | cubic-bezier(0.4, 0, 1, 1) | 退出 | | ease-in-out | cubic-bezier(0.4, 0, 0.2, 1) | 状态变化 | --- ## 7. 无障碍要求 ### 7.1 对比度 - 正文文字/背景：≥ 4.5:1 - 大文字/背景：≥ 3:1 - UI 元素：≥ 3:1 ### 7.2 键盘导航 - 所有交互元素可通过 Tab 访问 - 逻辑 Tab 顺序 - 可见焦点指示器 ### 7.3 屏幕阅读器 - 所有图片有 alt 文本 - 表单有正确标签 - 错误信息可访问 --- ## 变更记录 | 版本 | 日期 | 作者 | 变更内容 | |------|------|------|----------| | 1.0 | {{DATE}} | UI Designer Agent | 初始版本 |