wecom_it_smart_desk/docs/01-产品文档/00-产品规划/PRD-REQ-通用-001-前端设计系统-v1.0.md

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 适用范围

• 所有使用 <el-table> 的视图（管理后台核心列表页）
• 后续扩展到 <el-dialog> / <el-tag> / <el-form> / <el-pagination> 等深色主题相关组件

4.7.2 el-table 三层覆盖规则

Element Plus 的 <el-table> 在 DOM 上有三层结构：

<td>                              ← td 层（外层）
  <div class="el-table__cell">    ← cell 层（内层 div）
    <!-- 文字 -->                  ← 内容
  </div>
</td>

核心规则：必须覆盖到 cell 层 + fixed-column 层，否则白底白字。

/* 主体单元格（普通 + 固定列）—— 必须在 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