# PRD - 前端设计系统 > **REQ编号**: REQ-通用-001 > **版本**: v1.1 > **优先级**: P1 > **阶段**: 中期（3-4个月） > **作者**: 宋献 > **日期**: 2026-07-19（v1.1 补充 2026-07-27） --- ## 一、问题陈述 **用户问题**： - H5、坐席、管理后台三端视觉风格割裂 - 缺乏统一的 Design Tokens - 品牌感弱，除绿色外没有独特视觉符号 **业务目标**： - 建立统一的 IT 智能服务台设计系统 - 三端视觉风格一致，提升产品辨识度 - 提升用户体验和品牌感知 --- ## 二、需求范围 ### 2.1 核心功能 | 功能 | 描述 | |------|------| | Design Tokens | 统一的色彩、字体、间距、圆角、阴影、动效 | | 组件规范 | 按钮、输入框、卡片、弹窗等组件规范 | | 图标库 | 统一使用 Lucide 图标库 | | 深色模式 | 完整的深色模式适配 | ### 2.2 非目标 - 不包含完整的设计系统文档网站 - 不包含组件库的实现（仅定义规范） --- ## 三、用户故事 | 角色 | 用户故事 | 验收标准 | |------|----------|---------| | 前端开发 | 有统一的 Design Tokens 可复用 | 三端使用统一的 CSS 变量 | | 设计师 | 有完整的组件规范文档 | 设计产出符合规范 | | 员工 | 三端视觉风格一致 | H5、坐席、后台看起来像同一产品 | --- ## 四、功能详情 ### 4.1 Design Tokens 定义 **色彩系统**： | Token | 值 | 用途 | |-------|-----|------| | --color-primary | #07C160 | 主色（企微绿） | | --color-primary-light | #E8F5E9 | 主色浅背景 | | --color-primary-dark | #056739 | 主色深色 | | --color-secondary | #3b82f6 | 辅助色-蓝 | | --color-accent | #FF9800 | 强调色-橙 | | --color-success | #10B981 | 成功 | | --color-warning | #F59E0B | 警告 | | --color-danger | #EF4444 | 危险 | | --color-info | #6B7280 | 信息 | **灰阶**： | Token | 值 | 用途 | |-------|-----|------| | --gray-50 | #F9FAFB | 页面背景 | | --gray-100 | #F3F4F6 | 卡片背景 | | ... | ... | ... | | --gray-900 | #111827 | 主标题 | **排版系统**： | Token | 值 | 用途 | |-------|-----|------| | --font-family | PingFang SC, Microsoft YaHei | 字体 | | --font-size-xs | 12px | 辅助文字 | | --font-size-sm | 13px | 标签 | | --font-size-base | 14px | 正文 | | --font-size-lg | 16px | 小标题 | | --font-size-xl | 20px | 页面标题 | | --font-size-2xl | 24px | 大标题 | **间距系统**（4px 基准）： - 4, 8, 12, 16, 20, 24, 32, 48, 64 **圆角系统**： | Token | 值 | 用途 | |-------|-----|------| | --radius-sm | 4px | 标签 | | --radius-md | 6px | 按钮 | | --radius-lg | 8px | 卡片 | | --radius-xl | 12px | 大组件 | | --radius-full | 999px | 圆形 | **阴影系统**： | Token | 值 | 用途 | |-------|-----|------| | --shadow-sm | 0 1px 2px rgba(0,0,0,0.04) | 悬浮态 | | --shadow-md | 0 2px 8px rgba(0,0,0,0.06) | 卡片 | | --shadow-lg | 0 4px 16px rgba(0,0,0,0.08) | 弹窗 | **动效系统**： | Token | 值 | 用途 | |-------|-----|------| | --duration-fast | 150ms | hover/press | | --duration-normal | 200ms | 展开/收起 | | --duration-slow | 300ms | 弹窗/过渡 | ### 4.2 组件规范 **按钮**： - 主按钮：主色填充，白色文字，6px 圆角 - 次按钮：边框主色，主色文字，透明背景 - 文字按钮：无背景，无边框，主色文字 **输入框**： - 默认：灰色边框，14px 圆角 - 聚焦：主色边框，显示阴影 - 错误：红色边框，显示错误提示 **卡片**： - 白色背景，8px 圆角，轻微阴影 - 可选：边框样式（细灰线） ### 4.3 图标规范 - 统一使用 Lucide 图标库 - 风格：线框风格（outline） - 尺寸：16px（辅助）、20px（常规）、24px（强调） --- ## 四、用户交互反馈规范（补充） > **补充日期**: 2026-07-24 > **补充原因**: 2026-07-24 H5选项交互消息重复Bug反思——产品设计文档中缺失「用户交互反馈」定义 ### 4.4 交互反馈设计原则 **核心原则**：所有涉及后端异步响应的用户操作，前端应优先通过**UI状态变化**反馈结果，而非**临时消息**。 | 场景 | 不推荐做法 | 推荐做法 | |------|-----------|---------| | 用户点击AI选项 | 立即显示一条"待确认"消息，等后端返回后删除或保留 | 按钮立即禁用 + 高亮选中态，静默发WS，等后端返回后再添加正式消息 | | 用户发送消息 | 本地先添加消息，等后端返回确认后再决定是否显示 | 按钮禁用 + 发送中状态，后端返回后添加正式消息 | | 用户上传文件 | 先显示"上传中..."的临时消息 | 进度条 + 按钮禁用，上传完成后显示正式消息 | ### 4.5 交互状态定义 每一种用户操作都应定义以下状态： | 状态 | 视觉表现 | 说明 | |------|---------|------| | **正常态** | 按钮可点击，无特殊样式 | 用户可以执行操作 | | **处理中态** | 按钮禁用 + 加载指示器 | 后端正在处理，不允许重复点击 | | **成功态** | 恢复正常，可能有短暂高亮反馈 | 操作成功完成 | | **失败态** | 按钮恢复可用 + 错误提示 | 操作失败，需要用户重试 | ### 4.6 消息添加时机原则 **技术设计原则**：前端不应在收到后端确认前添加消息到消息列表。 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 推荐的消息添加流程 │ ├─────────────────────────────────────────────────────────────────┤ │ 1. 用户触发操作（如点击选项） │ │ 2. 前端：UI状态变为「处理中」（按钮禁用） │ │ 3. 前端：发送请求到后端（WS或HTTP） │ │ 4. 后端：处理完成，返回确认消息 │ │ 5. 前端：收到后端确认后，添加到消息列表 │ │ 6. 前端：UI状态恢复「正常」或变为「成功」 │ └─────────────────────────────────────────────────────────────────┘ ``` **为什么这样设计**： 1. 避免消息ID不一致导致的重复显示问题 2. 用户通过UI状态变化就能感知操作已被接收，不需要"假消息"来确认 3. 后端失败时，前端只需要恢复UI状态，不需要处理消息的"撤回" ### 4.7 Element Plus 深色主题适配规范（v1.1 补充 2026-07-27） > **补充原因**：BUG-通用-001（管理后台 el-table 白底白字）暴露了设计系统在 Element Plus 落地时的具体应用规则缺失。本节明确设计 Tokens 在 Element Plus 组件上的覆盖要求。 #### 4.7.1 适用范围 - 所有使用 `` 的视图（管理后台核心列表页） - 后续扩展到 `` / `` / `` / `` 等深色主题相关组件 #### 4.7.2 el-table 三层覆盖规则 Element Plus 的 `` 在 DOM 上有三层结构： ``` ← td 层（外层）
← cell 层（内层 div） ← 内容
``` **核心规则**：必须覆盖到 **cell 层 + fixed-column 层**，否则白底白字。 ```css /* 主体单元格（普通 + 固定列）—— 必须在 cell 层覆盖 */ .el-table .el-table__body td, .el-table .el-table__body td.el-table__cell, .el-table .el-table__body td.el-table-fixed-column--left, .el-table .el-table__body td.el-table-fixed-column--right { background-color: var(--bg-secondary) !important; /* ⚠️ 必须 !important */ color: var(--text-primary); } /* 斑马纹行（偶数行） */ .el-table .el-table__row--striped td, ... { background-color: var(--bg-tertiary) !important; } /* hover 状态 */ .el-table .el-table__body tr:hover > td, ... { background-color: rgba(59, 130, 246, 0.15) !important; } ``` #### 4.7.3 实施原则 | 原则 | 说明 | |------|------| | **全局覆盖** | 在 `src/<前端项目>/src/styles/global.css` 统一配置，不在每个视图写 scoped 样式 | | **必须 !important** | Element Plus 固定列选择器优先级高，不加 !important 无法胜出 | | **覆盖完整 3 层** | td / td.el-table__cell / td.el-table-fixed-column--left/--right，缺一不可 | | **覆盖完整状态** | 普通 / 斑马纹 / hover，缺一就有半清半不清 | #### 4.7.4 验收清单（每个 el-table 视图必须通过） - [ ] 普通行（无 striped）背景深、文字浅 → 清晰 - [ ] 偶数行（striped）背景更深一档、文字浅 → 清晰 - [ ] 固定列（`fixed="left"` 或 `fixed="right"`）与同行普通列颜色一致 - [ ] hover 时整行变蓝透 → 文字仍可读 - [ ] 表格头（thead）背景与全站风格一致 - [ ] WCAG 对比度 ≥ 4.5:1 #### 4.7.5 教训（来自 BUG-通用-001） 1. **不要在视图里加 scoped `:deep()`**：治标，每个表都得改；scoped 选择器优先级也不够 2. **必须用 !important**：Element Plus 的 `.el-table-fixed-column--left/--right` 优先级很高 3. **3 层都要覆盖**：第 1 次只覆盖 td（用户反馈"半清半不清"），第 2 次加 cell（用户反馈"偶数行不清"），第 3 次加 !important + fixed-column 才彻底修复 4. **完整 Skill 沉淀**：`~/.workbuddy/skills/element-plus-dark-table/SKILL.md`（下次遇到可直接调用） #### 4.7.6 关联文档 - 缺陷单：`03-测试文档/05-缺陷单/BUG-通用-用户角色分配表格看不清-001.md` - 故障案例：`04-运维文档/部署运维/00-标准故障排查手册.md` CASE-20260727-02 - Skill：`~/.workbuddy/skills/element-plus-dark-table/SKILL.md` --- ## 五、指标设计 | 指标 | 目标 | 测量方式 | |------|------|---------| | 设计系统覆盖率 | 100% | 三端组件使用 Design Tokens 的比例 | | 三端视觉一致性 | ≥ 90% | 用户调研评分 | --- ## 六、技术方案 - 使用 CSS Custom Properties 实现 Design Tokens - 抽离为独立 CSS 文件，三端引入 - 深色模式通过 CSS 变量覆盖实现 --- ## 七、关联文档 - 技术文档: `02-技术文档/前端改造/前端改造建议-v1.1.md`