本提交为 .git 对象库损坏后的重建提交,内容等价于原先三个本地提交 (5e2fd4c2 / 57a53c98 / 5d7e1873)的累积结果,未做任何额外改动。 一、docs 结构整改(整改 #14) 根因:重构时新结构为 untracked 文件,执行 git stash(未带 -u)未纳入, 随后 git reset 拉回 HEAD 旧 tracked 树,导致旧树复活、新旧两棵目录 树并存于 docs/,共 791 文件、双分类体系冲突。 修复动作: - b2 同名异主题文件改名迁移保全 9 个 - C 类 39 个孤立文件按主题正确归类 - A/B1 类 222 个重复文件删除(新结构已有内容副本) - 9 个旧独有空目录删除 - 270 处内部引用按 verified 映射改写 - 整改记录 #14 登记于 04-运维文档/部署运维 结果:docs 791 → 569 文件,顶层仅规范 8 类 + 治理文件,单树恢复。 残留:约 20 处指向从未存在文件的陈旧死链,归入独立文档卫生任务。 二、compose 双目录对齐(消除踩坑 A) - docker-compose.yml:nginx 前端挂载全部由根目录 frontend-*/dist 改为 src/frontend-*/dist(h5 / agent / admin / terminal) - docker-compose.dev.yml:dev 服务 build context 与卷同步改 src/ - 效果:本地 docker compose up 不再把根目录 stale dist 挂回, 与线上一致,分叉隐患消除(已 docker compose config 校验通过) 防复发铁律: - 重构须提交;仓库修复须 git stash -u 或先 commit - 新结构须 git add 并提交,避免再次 untracked 复活 - H5 改动只动 src/frontend-h5/,禁改根目录遗留 frontend-*/
26 KiB
PRD - 前端设计系统
REQ编号: REQ-通用-001 版本: v1.2 状态: [待评审] 优先级: P1 阶段: 中期(3-4个月) 作者: 宋献 日期: 2026-08-06 变更类型: 视觉主题重定义(UI优化)
一、问题陈述
用户问题:
- H5、坐席、管理后台三端缺乏统一的基础设计语言
- 三端角色不同,但当前主题色和视觉表达未充分体现角色差异
- 员工端绿色同时承担品牌色、成功色、在线色和交互强调色,存在语义过载
- 缺乏分层 Design Tokens,组件容易直接写死颜色值
- 玻璃拟态、高光和多层阴影在部分场景中可能压过内容,并带来低端设备性能风险
业务目标:
- 建立统一的 IT 智能服务台设计系统
- 统一字体、间距、圆角、图标、交互状态和语义色
- 通过角色主题区分员工端、坐席端和管理端的使用心理与任务重点
- 员工端由企微绿调整为服务蓝主题;绿色回归成功、在线、已解决语义
- 提升三端可访问性、对比度、可维护性和品牌辨识度
设计原则:
- 同源而不雷同:三端共享基础设计语言,但允许角色主题不同。
- 语义优先:成功、警告、危险、信息等语义色跨三端保持一致,不被角色主题覆盖。
- 内容优先:装饰性玻璃、渐变和阴影不得降低文字、状态和主要操作的可见性。
- Token 优先:组件只引用语义 Token,不直接写死品牌色值。
- 降级可用:关闭
backdrop-filter或使用低端设备时,布局、对比度和交互仍必须成立。
二、需求范围
2.1 核心功能
| 功能 | 描述 |
|---|---|
| 基础 Design Tokens | 统一字体、字号、间距、圆角、阴影、动效和中性色 |
| 角色主题 Tokens | 员工端、坐席端、管理端分别注入角色主题色 |
| 语义色 Tokens | 成功、警告、危险、信息、AI 能力等语义跨三端固定 |
| 组件规范 | 按钮、输入框、卡片、弹窗、表格、标签、消息气泡等组件规范 |
| 图标库 | 统一使用 Lucide 图标库,业务图标不得混用 Emoji |
| 明暗主题 | 坐席端和管理端完整适配;员工端根据容器与企微环境适配 |
| 可访问性 | 颜色对比度、键盘焦点、非颜色区分和减少动态效果 |
| 渐进降级 | 玻璃、模糊和复杂阴影在不支持或低性能设备上可降级 |
2.2 非目标
- 不包含完整的设计系统文档网站
- 不包含组件库的实现(仅定义规范)
三、用户故事
| 角色 | 用户故事 | 验收标准 |
|---|---|---|
| 员工 | 我希望快速获得帮助,不需要学习复杂系统 | 员工端呈现可信、清晰、低压力的服务蓝主题;主要操作易识别 |
| 坐席 | 我需要同时处理多个会话并快速判断下一步 | 状态、优先级和当前任务层级清晰;装饰颜色不干扰处置判断 |
| 管理员 | 我需要监控、配置、审计并控制风险 | 管理端保持稳定、权威、可追溯;告警色只用于真实状态 |
| 前端开发 | 我需要可复用且含义稳定的 Design Tokens | 三端组件不直接写死角色品牌色;主题切换无需修改组件结构 |
| 产品/设计 | 我需要三端看起来属于同一产品,又能区分角色 | 字体、间距、圆角、图标和交互一致;主题色按角色有明确区分 |
| 无障碍用户 | 我不能只依赖颜色理解状态 | 关键状态同时具备文字、图标、形状或位置提示 |
四、功能详情
4.1 Design Tokens 定义
4.1.1 Token 分层模型
Design Tokens 必须分为三层,禁止继续用一个 --color-primary 同时承担品牌、角色和状态语义。
| 层级 | 作用 | 示例 | 变更频率 |
|---|---|---|---|
| 基础色板层 | 提供稳定、无业务语义的颜色阶梯 | --palette-blue-600 |
低 |
| 角色主题层 | 表达员工、坐席、管理员的角色特点 | --theme-accent |
中 |
| 语义用途层 | 组件实际消费的操作和状态含义 | --color-action-primary |
低 |
/* 基础色板层 */
--palette-blue-600: #1769E0;
--palette-cyan-600: #0E9FBA;
--palette-green-700: #15803D;
--palette-amber-700: #B45309;
--palette-red-700: #B42318;
/* 角色主题层:由各端根容器注入 */
--theme-accent: var(--palette-blue-600);
--theme-secondary: var(--palette-cyan-600);
--theme-accent-soft: #E7F0FF;
/* 语义用途层:业务组件只引用这一层 */
--color-action-primary: var(--theme-accent);
--color-focus-ring: var(--theme-accent);
--color-status-success: var(--palette-green-700);
--color-status-warning: var(--palette-amber-700);
--color-status-danger: var(--palette-red-700);
4.1.2 三端角色主题
| 端 | 角色心理 | 设计关键词 | 主色 | 辅助色 | 页面基底 |
|---|---|---|---|---|---|
| 员工端 | 快速得到帮助,不想学习复杂系统 | 可信、亲和、清晰、低压力 | 服务蓝 #1769E0 |
青蓝 #0E9FBA |
#F4F8FD |
| 坐席端 | 同时处理多个会话并快速决策 | 专注、实时、效率、协同 | 深海蓝 #155E75 |
冷青 #22A6B3 |
#F2F7F8 |
| 管理端 | 监控、配置、审计和风险控制 | 权威、稳定、克制、可追溯 | 靛蓝 #4F72D8 |
冷紫蓝 #7889D8 |
#0B1220 |
角色主题约束:
- 三端可以使用不同
--theme-accent,但字体、间距、圆角、图标、交互状态和语义色必须一致。 - 绿色不得继续作为员工端品牌主色,只表示成功、在线、已解决、恢复正常。
- 紫色仅用于 AI 能力或管理端辅助强调,不承担告警、成功或普通导航分组语义。
- 红、黄、绿只用于真实业务状态,不用于装饰性渐变和导航分组标题。
4.1.3 员工端服务蓝主题
[data-product="employee"] {
--theme-accent: #1769E0;
--theme-accent-hover: #1258BC;
--theme-accent-soft: #E7F0FF;
--theme-secondary: #0E9FBA;
--surface-page: #F4F8FD;
--surface-chat: #FFFFFF;
--surface-ai: #F3F8FF;
--border-subtle: #D8E6F7;
--text-primary: #172B4D;
--text-secondary: #5B6B82;
}
员工端工具栏决策:
- 生产默认采用扁平蓝色服务舱:稳定对比度、较低性能成本、清晰操作优先。
- 蓝色水晶玻璃可作为增强效果;必须提供不使用
backdrop-filter的降级样式。 - 禁止使用多色发光、紫粉渐变或超过两层的装饰性外阴影。
- 人工坐席头像使用蓝色主题描边;在线状态小圆点继续使用成功绿。
4.1.4 坐席端深海蓝主题
[data-product="agent"] {
--theme-accent: #155E75;
--theme-accent-hover: #0E7490;
--theme-accent-soft: #E5F5F7;
--theme-secondary: #22A6B3;
--surface-page: #F2F7F8;
--surface-panel: #FFFFFF;
--border-subtle: #D7E5E8;
}
- 当前会话使用主题浅底与左侧指示条,不仅依赖文字颜色。
- AI 推荐使用青色图标或标签;紫色不得扩散到 logo、版本标签和普通按钮。
- 完成节点用绿色、当前节点用主题蓝、判断节点用琥珀色。
- 会话优先级颜色不得同时承担头像、分类和品牌装饰用途。
4.1.5 管理端海军蓝主题
[data-product="admin"] {
--surface-page: #0B1220;
--surface-sidebar: #101A2C;
--surface-card: #152238;
--surface-hover: #1C2E49;
--theme-accent: #4F72D8;
--theme-accent-soft: rgba(79, 114, 216, 0.16);
--text-primary: #E8EEF8;
--text-secondary: #9AAAC0;
--border-subtle: rgba(154, 170, 192, 0.16);
}
- 默认维持深色控制台方向。
- 导航分组标题统一使用灰阶,禁止每个分组使用不同颜色。
- KPI 卡片不使用彩色渐变;语义色仅出现在数据、状态点或告警标签。
- 外部系统品牌色只出现在集成图标,不扩散至整张卡片。
4.1.6 语义色系统
| Token | 浅色主题 | 深色主题 | 用途 |
|---|---|---|---|
--color-status-success |
#15803D |
#4ADE80 |
成功、在线、已解决 |
--color-status-warning |
#B45309 |
#FBBF24 |
警告、等待、待审核 |
--color-status-danger |
#B42318 |
#F87171 |
故障、失败、阻断 |
--color-status-info |
#1769E0 |
#60A5FA |
信息、说明 |
--color-ai |
#0E7490 |
#67E8F9 |
AI 推荐、智能能力 |
使用规则:状态不能只通过颜色表达,必须同时提供文字、图标、形状或位置中的至少一种辅助信号。
4.1.7 中性色与表面色
角色主题不能替代中性色阶。中性色用于文字、背景、边框和组件层级,在三端保持同一明度逻辑。
| Token | 浅色值 | 深色值 | 用途 |
|---|---|---|---|
--palette-gray-50 |
#F9FAFB |
#0B1220 |
页面最浅背景/深色页面基底 |
--palette-gray-100 |
#F3F4F6 |
#101A2C |
次级背景/侧边栏 |
--palette-gray-200 |
#E5E7EB |
#152238 |
卡片、面板分层 |
--palette-gray-400 |
#9CA3AF |
#64748B |
辅助边框、禁用态 |
--palette-gray-600 |
#4B5563 |
#9AAAC0 |
辅助文字 |
--palette-gray-800 |
#1F2937 |
#E8EEF8 |
标题、正文 |
--palette-gray-900 |
#111827 |
#F3F6FA |
强调文字/深色高对比文字 |
| Token | 浅色主题 | 深色主题 | 用途 |
|---|---|---|---|
--surface-page |
#F6F8FB |
#0B1220 |
页面背景 |
--surface-panel |
#FFFFFF |
#152238 |
主面板、卡片 |
--surface-subtle |
#F1F4F8 |
#1C2E49 |
次级区域、悬停 |
--text-primary |
#172B4D |
#E8EEF8 |
标题、正文 |
--text-secondary |
#5B6B82 |
#9AAAC0 |
辅助文字 |
--border-subtle |
#DCE3EC |
rgba(154,170,192,0.16) |
边框、分隔 |
4.1.8 旧 Token 兼容映射
为避免三端主题迁移过程中出现未定义变量或样式瞬间失效,迁移期允许保留以下兼容别名。新组件不得继续使用旧别名;兼容别名在三端完成迁移并通过回归验收后移除。
| 旧 Token | 迁移映射 | 说明 |
|---|---|---|
--color-primary |
var(--theme-accent) |
角色主题主操作色 |
--color-primary-light |
var(--theme-accent-soft) |
主题浅背景 |
--color-primary-dark |
var(--theme-accent-hover) |
深色/悬停状态 |
--color-secondary |
var(--theme-secondary) |
辅助主题色 |
--color-success |
var(--color-status-success) |
成功/在线/已解决 |
--color-warning |
var(--color-status-warning) |
警告/等待 |
--color-danger |
var(--color-status-danger) |
危险/失败 |
--color-info |
var(--color-status-info) |
信息/说明 |
--bg-primary |
var(--surface-page) |
页面背景 |
--bg-secondary |
var(--surface-panel) |
面板/卡片 |
--bg-tertiary |
var(--surface-subtle) |
次级表面 |
迁移纪律:兼容映射只允许放在全局 Token 文件,不得在各个页面重复声明;每次删除旧别名前,必须完成全仓库检索和视觉回归。
排版系统:
| 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 组件规范
4.2.1 通用要求
- 组件只能消费语义用途层 Token,不得直接引用具体颜色值。
- 正常、悬停、按下、聚焦、禁用、处理中、成功、失败状态必须完整定义。
- 关键状态不得只依赖颜色,需同时提供文字、图标、形状或位置提示。
- 主要按钮、危险按钮和普通按钮必须有明确层级;同一区域原则上仅保留一个主要按钮。
4.2.2 按钮
- 主按钮:
--color-action-primary填充,使用通过对比度校验的前景色,6px 圆角。 - 次按钮:中性边框;悬停后使用
--theme-accent-soft,避免大面积主色描边。 - 文字按钮:无背景、无边框,仅用于低风险辅助操作。
- 危险按钮:只有执行删除、停用、强制中断等不可逆操作时使用危险色。
- 处理中:保留按钮宽度,显示加载状态并禁止重复提交。
4.2.3 输入框
- 默认:中性边框,8px 圆角;不使用 14px 以上的过度圆角。
- 聚焦:使用
--color-focus-ring,外环不得造成布局抖动。 - 错误:危险色边框 + 错误图标 + 明确错误文字。
- 禁用:降低表面和文字对比,但仍须保持文字可读。
4.2.4 卡片与面板
- 优先使用边框和表面明度建立层级,阴影只用于浮层、弹窗和拖拽态。
- 避免“卡片套卡片”;同一页面主要容器层级不超过三层。
- 员工端可适量使用半透明表面;坐席端和管理端优先使用稳定实色表面。
4.2.5 弹窗、抽屉与下拉层
- 弹窗用于需要用户确认或集中完成的任务,不用于承载可直接展示在页面上的普通信息。
- 弹窗、抽屉和下拉层必须具有明确的层级、关闭方式和焦点管理;打开后焦点进入容器,关闭后回到触发控件。
- 危险确认弹窗必须明确描述影响范围,并区分取消和确认按钮;确认按钮不得使用模糊文案。
- 下拉层优先使用实色表面和边框,不使用高透明度玻璃导致选项与背景混淆。
- 弹窗遮罩仅用于阻断背景交互,颜色和透明度不得降低弹窗正文对比度。
4.2.6 消息气泡
- 用户消息使用员工端主题主色;AI/坐席消息使用浅表面和清晰边框。
- 用户、AI、人工坐席除颜色外,还必须通过对齐方向、角色名称或头像进行区分。
- 成功、失败和系统提示不得伪装成普通聊天消息。
4.2.7 表格和数据列表
- 管理端、坐席端的表格优先保证密度、对齐和扫描效率。
- 表格斑马纹、悬停、选中和固定列必须使用统一表面 Token。
- 状态标签不得以整行高饱和底色表达,优先使用轻底标签和文字。
4.3 图标规范
- 统一使用 Lucide 图标库,线框风格(outline)。
- 尺寸:16px(辅助)、20px(常规)、24px(强调)。
- 图标颜色引用语义 Token 或角色主题 Token,不直接写十六进制值。
- 业务功能图标不得混用 Emoji;Emoji 仅允许作为用户主动输入的内容展示。
- 图标按钮必须同时提供可见 tooltip 或
aria-label。 - 装饰性 SVG 必须使用
aria-hidden="true",不得进入辅助阅读顺序。 - 人工坐席头像属于品牌/角色资产,不作为状态图标使用;在线状态必须独立显示。
4.4 用户交互反馈规范(2026-07-24 补充)
补充日期: 2026-07-24 补充原因: 2026-07-24 H5选项交互消息重复Bug反思——产品设计文档中缺失「用户交互反馈」定义
4.4.1 交互反馈设计原则
核心原则:所有涉及后端异步响应的用户操作,前端应优先通过UI状态变化反馈结果,而非临时消息。
| 场景 | 不推荐做法 | 推荐做法 |
|---|---|---|
| 用户点击AI选项 | 立即显示一条"待确认"消息,等后端返回后删除或保留 | 按钮立即禁用 + 高亮选中态,静默发WS,等后端返回后再添加正式消息 |
| 用户发送消息 | 本地先添加消息,等后端返回确认后再决定是否显示 | 按钮禁用 + 发送中状态,后端返回后添加正式消息 |
| 用户上传文件 | 先显示"上传中..."的临时消息 | 进度条 + 按钮禁用,上传完成后显示正式消息 |
4.4.2 交互状态定义
每一种用户操作都应定义以下状态:
| 状态 | 视觉表现 | 说明 |
|---|---|---|
| 正常态 | 按钮可点击,无特殊样式 | 用户可以执行操作 |
| 处理中态 | 按钮禁用 + 加载指示器 | 后端正在处理,不允许重复点击 |
| 成功态 | 恢复正常,可能有短暂高亮反馈 | 操作成功完成 |
| ���败态 | 按钮恢复可用 + 错误提示 | 操作失败,需要用户重试 |
4.4.3 消息添加时机原则
技术设计原则:前端不应在收到后端确认前添加消息到消息列表。
┌─────────────────────────────────────────────────────────────────┐
│ 推荐的消息添加流程 │
├─────────────────────────────────────────────────────────────────┤
│ 1. 用户触发操作(如点击选项) │
│ 2. 前端:UI状态变为「处理中」(按钮禁用) │
│ 3. 前端:发送请求到后端(WS或HTTP) │
│ 4. 后端:处理完成,返回确认消息 │
│ 5. 前端:收到后端确认后,添加到消息列表 │
│ 6. 前端:UI状态恢复「正常」或变为「成功」 │
└─────────────────────────────────────────────────────────────────┘
为什么这样设计:
- 避免消息ID不一致导致的重复显示问题
- 用户通过UI状态变化就能感知操作已被接收,不需要"假消息"来确认
- 后端失败时,前端只需要恢复UI状态,不需要处理消息的"撤回"
4.5 Element Plus 深色主题适配规范(v1.1 补充 2026-07-27)
补充原因:BUG-通用-001(管理后台 el-table 白底白字)暴露了设计系统在 Element Plus 落地时的具体应用规则缺失。本节明确设计 Tokens 在 Element Plus 组件上的覆盖要求。
4.5.1 适用范围
- 所有使用
<el-table>的视图(管理后台核心列表页) - 后续扩展到
<el-dialog>/<el-tag>/<el-form>/<el-pagination>等深色主题相关组件
4.5.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(--surface-panel) !important; /* ⚠️ 必须 !important */
color: var(--text-primary);
}
/* 斑马纹行(偶数行) */
.el-table .el-table__row--striped td, ... {
background-color: var(--surface-subtle) !important;
}
/* hover 状态 */
.el-table .el-table__body tr:hover > td, ... {
background-color: var(--theme-accent-soft) !important;
}
4.5.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.5.4 验收清单(每个 el-table 视图必须通过)
- 普通行(无 striped)背景深、文字浅 → 清晰
- 偶数行(striped)背景更深一档、文字浅 → 清晰
- 固定列(
fixed="left"或fixed="right")与同行普通列颜色一致 - hover 时整行变蓝透 → 文字仍可读
- 表格头(thead)背景与全站风格一致
- WCAG 对比度 ≥ 4.5:1
4.5.5 教训(来自 BUG-通用-001)
- 不要在视图里加 scoped
:deep():治标,每个表都得改;scoped 选择器优先级也不够 - 必须用 !important:Element Plus 的
.el-table-fixed-column--left/--right优先级很高 - 3 层都要覆盖:第 1 次只覆盖 td(用户反馈"半清半不清"),第 2 次加 cell(用户反馈"偶数行不清"),第 3 次加 !important + fixed-column 才彻底修复
- 完整 Skill 沉淀:
~/.workbuddy/skills/element-plus-dark-table/SKILL.md(下次遇到可直接调用)
4.5.6 关联文档
- 缺陷单:
03-测试文档/05-缺陷单/BUG-通用-用户角色分配表格看不清-001.md - 故障案例:
04-运维文档/部署运维/00-标准故障排查手册.mdCASE-20260727-02 - Skill:
~/.workbuddy/skills/element-plus-dark-table/SKILL.md
五、指标设计
| 指标 | 目标 | 测量方式 |
|---|---|---|
| 设计系统覆盖率 | ≥ 95% | 三端组件使用语义 Design Tokens 的比例;直接写死品牌色的组件数为 0 |
| 三端基础一致性 | ≥ 90% | 字体、间距、圆角、图标、交互状态抽样评审通过率 |
| 角色主题识别度 | ≥ 85% | 员工、坐席、管理员用户盲测端角色识别正确率 |
| WCAG 对比度 | 普通文字 ≥ 4.5:1;大文字 ≥ 3:1 | 自动化扫描 + 真实页面人工复核 |
| 员工端主要操作可发现性 | ≥ 90% | 首次使用者在 10 秒内找到发送、转人工、上传等主要入口的比例 |
| 玻璃效果降级成功率 | 100% | 关闭 backdrop-filter 或低端设备模拟后,布局、对比度和操作仍可用 |
| 设计主题迁移回归缺陷 | 0 个 P0/P1 | 三端视觉回归与关键路径测试 |
六、技术方案
- 使用 CSS Custom Properties 实现基础色板、角色主题和语义用途三层 Design Tokens。
- 抽离为共享 CSS Token 文件,三端通过根容器属性(如
[data-product="employee"])注入角色主题。 - 组件只引用语义用途层变量,例如
--color-action-primary、--color-status-success,禁止直接写死品牌色。 - 深色模式通过 CSS 变量覆盖实现;员工端需兼容企微容器和窄屏环境。
- 员工端玻璃效果必须提供
@supports not (backdrop-filter: blur(1px))降级规则,并保留实色表面和可读边框。 - 颜色对比度纳入 CI 或视觉回归检查;普通文字最低 4.5:1,大文字最低 3:1。
- Element Plus 组件继续采用全局样式覆盖,表格必须覆盖普通、斑马纹、hover 和 fixed-column 状态。
- 迁移顺序:Token 层 → 员工端核心会话 → 坐席工作台 → 管理后台 → 三端回归验收。
七、实施范围与验收标准
7.1 第一阶段:Token 重构
- 完成基础色板、角色主题、语义用途三层变量定义。
- 三端能够通过根容器切换主题,不修改组件结构。
- 全仓库检索,核心组件不再直接写死角色品牌色。
7.2 第二阶段:员工端主题迁移
- 员工端主色切换为服务蓝,绿色仅保留成功/在线/已解决语义。
- 消息气泡、输入区、工具栏、人工坐席描边、焦点环完成迁移。
- 蓝色服务舱在关闭
backdrop-filter后仍保持布局、对比度和可操作性。 - ≤480px 窄屏、深色环境或低性能设备完成降级验证。
7.3 第三阶段:坐席端与管理端迁移
- 坐席端完成深海蓝 + 冷青主题收敛,AI 推荐与优先级颜色职责分离。
- 管理端完成海军蓝 + 靛蓝主题收敛,导航分组不再使用装饰性多色。
- 管理端 el-table 普通、斑马纹、hover、fixed-column 状态清晰一致。
7.4 体验与无障碍验收
- 普通正文对比度 ≥ 4.5:1,大文字对比度 ≥ 3:1。
- 键盘可以访问所有主要操作,并显示可见焦点环。
- 关键状态不只依赖颜色表达。
prefers-reduced-motion: reduce下关闭非必要动效。- 视觉回归无 P0/P1 主题迁移缺陷。
八、关联文档
- 评审提案:
deliverables/视觉设计系统重定义提案-v1.0.md - 员工端原型:
01-产品文档/02-会话管理/原型-REQ-会话-001-工具栏统一设计v1.9.2-员工端主绿水晶玻璃版.html(待按主题拍板结果更新) - 坐席端原型:
01-产品文档/04-坐席工作台/原型-REQ-坐席-000-坐席工作台-v1.6.html(待按主题拍板结果更新) - 管理端原型:
01-产品文档/08-集成生态/原型-REQ-集成-000-管理后台-v1.1.html(待按主题拍板结果更新) - 技术文档:
02-技术文档/前端改造/前端改造建议-v1.1.md
变更记录
| 日期 | 版本 | 变更内容 | 变更人 | 变更原因 |
|---|---|---|---|---|
| 2026-07-19 | v1.0 | 初版建立前端设计系统 PRD | 宋献 | 统一三端视觉与组件规范 |
| 2026-07-24 | v1.1 | 补充异步交互反馈与消息添加时机原则 | 宋献 | 修复 H5 选项交互消息重复问题 |
| 2026-07-27 | v1.1 | 补充 Element Plus 深色主题表格三层覆盖规则 | 宋献 | 修复管理后台 el-table 可读性问题 |
| 2026-08-06 | v1.2 | 补充归档过程文档中遗漏的中性色阶、弹窗/抽屉/下拉层规范、旧 Token 兼容映射,并统一 Element Plus 表格示例变量 | 宋献 | 对比 v1.1.archive 过程文档后发现的实施完整性补充 |