YG-Soft/YG_FT
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
242407b676037e37ce2393c55055e926bea631b8
YG_FT/docs/superpowers/specs/2026-07-09-frontend-visual-refresh-design.md
wangjiming b4ff5db17b 第一次提交
2026-07-27 09:12:47 +08:00

12 KiB
Raw Blame History

前端视觉与样式系统重构设计

日期：2026-07-09 范围：frontend/ （Vue 3 + Element Plus + Pinia） 目标用户：内部数据/算法工程师，桌面端浏览器使用

背景与动机

当前前端已用 Element Plus + 自定义 SCSS 变量搭起一套"深色侧边栏 + 浅色内容区"的现代 B 端布局，但实际页面观感"乱"且有功能性瑕疵，根因不是设计语言本身有问题，而是设计系统没有真正落地：

  • 颜色散落硬编码（#1e293b、#475569、#909399、#1890ff、#67c23a…）
  • Element Plus 旧默认色与新主题色（#4f46e5）并存
  • 用了 FontAwesome 4.7.0（2017 年停止维护），大量 fa-cogs/fa-hdd-o 这种短横线后缀命名
  • 登录页（LoginView.vue）背景是纯色 #dbe0f9，与主应用玻璃拟态风格割裂
  • AppHeader.vue:189 引用了主题里不存在的 --warning-color 变量，导致回退到默认值
  • index.scss 内有 5+ 处 !important，说明覆盖策略不对
  • 装饰性动画（按钮悬停 translateY(-1px)、pulse 动画、过度渐变）增加视觉噪音

本次重构目标是收口样式系统，让"主题改一处，全站生效"，并消除明显观感问题。

范围与非范围

范围内

  1. 统一颜色变量系统（消除硬编码、补齐缺失变量）
  2. 图标库迁移：FA4 → Element Plus Icons（@element-plus/icons-vue，已与 Element Plus 同步）
  3. 重新设计登录页，与主应用视觉一致
  4. 修复 AppHeader.vue 的 --warning-color 缺失问题
  5. 整理 index.scss 的 !important 覆盖，改用更高特异性选择器
  6. 适度降低装饰性效果：移除按钮悬停位移、统一卡片阴影阶梯

非范围（本次不做）

  • 布局结构改动（保留 260px 侧边栏 + 60px 顶栏）
  • 深色模式切换
  • 任何业务逻辑修改
  • 移动端适配（当前项目无移动端需求）
  • web/ 静态版不动

方案选型

选定方案：方案 A — 克制重塑

保留现有"深色侧边栏 + 浅色内容区"骨架，做样式系统收口。

未选 方案 B（极简重做）：改动面太广，10+ 视图都要适配，回报/风险比差。 未选 方案 C（全深色科技感）：Element Plus 暗色需要大量单独调校，工作量与当前诉求不匹配。

设计

1. 颜色变量系统（src/styles/index.scss 重构）

目标：所有颜色、阴影、圆角都走 CSS 变量；后续改主题只改 :root 即可。

新增/补齐变量（src/styles/index.scss 顶部）：

:root {
  /* Element Plus 主色（已有） */
  --el-color-primary: #4f46e5;
  --el-color-primary-light-3: #818cf8;
  --el-color-primary-light-5: #a5b4fc;
  --el-color-primary-light-7: #c7d2fe;
  --el-color-primary-light-8: #e0e7ff;
  --el-color-primary-light-9: #eef2ff;
  --el-color-primary-dark-2: #4338ca;

  /* 状态色（已有） */
  --el-color-success: #10b981;
  --el-color-warning: #f59e0b;       /* 修复：之前未显式定义 */
  --el-color-danger: #ef4444;
  --el-color-info: #64748b;

  /* 项目别名（已有 + 新增） */
  --primary-color: var(--el-color-primary);
  --primary-hover: var(--el-color-primary-light-3);
  --success-color: var(--el-color-success);
  --warning-color: var(--el-color-warning);   /* 新增：修复 AppHeader 引用 */
  --danger-color: var(--el-color-danger);

  /* 圆角（已有） */
  --el-border-radius-base: 8px;
  --el-border-radius-small: 6px;
  --el-border-radius-round: 20px;

  /* ========== 新增：项目语义化变量 ========== */

  /* 文字 */
  --text-primary: #1e293b;            /* 替代硬编码 #1e293b */
  --text-secondary: #475569;          /* 替代 #475569 */
  --text-tertiary: #64748b;           /* 替代 #64748b */
  --text-placeholder: #94a3b8;        /* 替代 #94a3b8 */

  /* 背景 */
  --bg-page: #f8fafc;                 /* 替代 --el-bg-color-page */
  --bg-card: #ffffff;
  --bg-subtle: #f1f5f9;               /* 替代硬编码 #f1f5f9 */
  --bg-hover: #f8fafc;                /* 替代硬编码 #f8fafc */

  /* 边框 */
  --border-subtle: #e2e8f0;           /* 替代硬编码 #e2e8f0 */
  --border-base: #f1f5f9;             /* 替代硬编码 #f1f5f9 */

  /* 侧边栏（已有） */
  --sidebar-bg: #0f172a;
  --sidebar-text: #94a3b8;
  --sidebar-active-bg: rgba(79, 70, 229, 0.15);
  --sidebar-active-text: #ffffff;
  --sidebar-section-title: #64748b;

  /* 阴影（统一阶梯） */
  --shadow-sm: 0 1px 2px rgba(15, 23, 42, 0.04);
  --shadow-md: 0 2px 8px rgba(15, 23, 42, 0.06);   /* 替代 --card-shadow */
  --shadow-lg: 0 8px 24px rgba(15, 23, 42, 0.08);
  --shadow-dialog: 0 20px 40px rgba(15, 23, 42, 0.12);

  /* 尺寸 */
  --header-height: 60px;
  --sidebar-width: 260px;
  --content-padding-x: 32px;
  --content-padding-y: 32px;
}

改动原则：

  • 组件 SCSS 内的硬编码颜色全部替换为对应变量
  • 任何新增颜色需求都先在 :root 定义，再引用
  • 不再使用 !important；如确需覆盖，提升特异性（如 :deep(.el-button)）

2. 图标库迁移：FA4 → Element Plus Icons

为什么选 Element Plus Icons：

  • 零新增依赖成本（仅在 package.json 增加一行）
  • 与 Element Plus 组件视觉风格天然一致
  • 树摇友好，按需引入
  • SVG 渲染，可继承 currentColor 与 font-size，比 FA 字体图标更现代

实施：

  1. npm i @element-plus/icons-vue
  2. main.ts 全局注册常用图标（按需在组件内 import 也可）
  3. 替换规则（在每个 view/component 内做局部替换）：
FA4 类名 Element Plus 图标 用在哪
fa-cogs Setting 侧边栏"模型调优"
fa-line-chart TrendCharts 侧边栏"模型评测"
fa-server Monitor 侧边栏"模型推理"
fa-cube Box 侧边栏"模型管理"、Logo
fa-file-text Document 侧边栏"数据集"
fa-wrench Tools 侧边栏"其他工具"
fa-bar-chart DataAnalysis 侧边栏"平台性能"
fa-search Search 搜索框前缀
fa-plus Plus 新建按钮
fa-trash Delete 删除按钮
fa-arrow-left ArrowLeft 返回按钮
fa-microchip Cpu 性能监控
fa-database Files 内存监控（数据文件堆）
fa-hdd-o Box 磁盘监控（存储箱）
fa-sign-out SwitchButton 退出登录
fa-angle-down ArrowDown 下拉箭头
fa-user-circle-o User 个人中心
fa-cog Setting 系统设置
fa-stop-circle-o VideoPause 停止训练
fa-pencil Edit 编辑
fa-times Close 关闭
fa-globe Connection 网络流量
fa-info-circle InfoFilled 系统信息
fa-user-o User 登录页账号图标
fa-lock-o Lock 登录页密码图标
fa-sign-in Right 登录按钮

注意点：

  • 替换后调整图标尺寸（Element Plus Icons 用 size prop 或 CSS font-size）
  • 部分 FA4 类名（如 fa-file-text-o）在 FA5/FA6 已无 -o 后缀
  • main.ts 中删除 import '@/assets/font-awesome/css/font-awesome.min.css'
  • 删 src/assets/font-awesome/ 整个目录（字体文件 100+KB）

3. 登录页重新设计（LoginView.vue）

目标：与主应用保持一致的视觉语言，背景改用渐变 + 玻璃卡片。

设计：

  • 背景：渐变 linear-gradient(135deg, #4f46e5 0%, #818cf8 50%, #c7d2fe 100%)
  • 卡片：白色，圆角 16px，阴影 var(--shadow-dialog)
  • Logo 区域：上下结构（Logo 48px → 标题 24px → 副标题 14px 灰色）
  • 表单：单项之间 20px 间距，输入框 44px 高，圆角 8px
  • 按钮：主色实心，44px 高，全宽
  • 选项行：flex 布局，记住密码左、忘记密码右
  • 整体居中，最大宽 420px

关键 CSS 改动：

  • 背景从 #dbe0f9 改为 linear-gradient(135deg, #4f46e5 0%, #818cf8 50%, #c7d2fe 100%)
  • 卡片圆角从 12px 提升到 16px
  • 阴影替换为 var(--shadow-dialog)
  • 所有内联颜色改用变量

4. 修复 AppHeader.vue 的 --warning-color 缺失

问题：AppHeader.vue:189 使用 var(--warning-color)，但 index.scss 里只定义了 --danger-color、--success-color，没有 --warning-color。

修复：在 :root 中新增 --warning-color: var(--el-color-warning);（已在第 1 节列入）。

5. 整理 index.scss 的 !important

现有 !important 用法（来自 index.scss）：

选择器 用途 现状
.el-card { border: none !important; ... } 去掉 EP 默认边框 提升为 .app-container .el-card 或全局加 :where() 重置
.el-tag { border: none !important; ... } 去掉 EP 默认边框 同上
.el-dialog { border-radius: 16px !important; ... } 圆角和阴影 同上

改写策略：

  • 用更高特异性选择器（如 body .el-card）替代 !important
  • 或用 CSS Layer (@layer reset, overrides, components) 控制优先级

本次采用：直接提高特异性，避免引入 CSS Layer 复杂度（属于项目既定风格之外的引入，需要权衡）。

6. 降低装饰性效果

调整清单：

  • index.scss 移除 .el-button:hover { transform: translateY(-1px); box-shadow: ...; } — 改为仅改变背景色
  • AppHeader.vue 移除 pulse 动画，改为静态红色
  • 侧边栏菜单图标的 transform: scale(1.1) 悬停动画保留（这是细节点缀，不算噪音）
  • 卡片悬停 transform 动效保留（仅在 DataTablePage 等列表卡片上，目前没有，不新增）
  • 顶栏 backdrop-filter: blur(12px) 保留（玻璃感是这个项目的风格语言）

实施步骤（落地顺序）

按风险从低到高，便于逐步验证：

  1. 步骤 1：扩展 src/styles/index.scss 变量（新增，不删除旧的）
  2. 步骤 2：安装 @element-plus/icons-vue，在 main.ts 注册
  3. 步骤 3：逐文件替换图标（按表格顺序）
  4. 步骤 4：逐文件替换硬编码颜色为变量
  5. 步骤 5：重新设计 LoginView.vue
  6. 步骤 6：删除 src/assets/font-awesome/ 目录和 main.ts 的 import
  7. 步骤 7：运行 npm run type-check 和 npm run build 验证

每步完成后截图（手动）确认未引入新问题。

验证标准

  • npm run type-check 通过
  • npm run build 通过
  • 浏览器控制台无 CSS 警告（无未定义变量）
  • 全站不再有 #1890ff、#67c23a、#e6a23c、#f56c6c 这类 EP 旧色硬编码（grep 验证）
  • 全站不再有 class="fa fa- 的引用（grep 验证）
  • 全站不再有 --warning-color 这类指向不存在变量的引用
  • grep -c "!important" src/styles/index.scss 数量从当前值下降 50% 以上
  • 登录页与主应用风格一致

风险与回退

  • 风险 1：Element Plus Icons 不覆盖某些冷门 FA 图标（如 fa-stop-circle-o 训练停止）
    • 应对：在替换前先做一次图标对照表，确认每个 FA 类名都有 EP 对应项；没有则保留 FA4（不删除 FA 资源），但推进用 EP 主流图标
  • 风险 2：CSS 变量替换漏掉某处导致视觉回退
    • 应对：分阶段提交，每阶段都跑 build；如有遗漏，EP 会回退到自身默认色
  • 风险 3：!important 整理引入新覆盖问题
    • 应对：整理前先 git diff 对比编译产物颜色变化，保留 git stash 能力

后续优化（不在本次范围）

  • 抽出 Design Token 文件（tokens.scss）做 Figma → Code 同步
  • 引入 UnoCSS 或 Windi CSS 做原子化样式（取决于团队接受度）
  • 给所有列表页加 skeleton 加载态
  • 暗色模式支持（需要先在 EP 主题层注册暗色）
Reference in New Issue View Git Blame Copy Permalink