4.1 KiB
4.1 KiB
前端视觉与轻量动效优化开发说明
更新日期：2026-08-30 适用范围：全局 Design Token、App Shell、功能页、卡片、表单、弹窗和轻量交互动效
1. 目标
本轮优化不改变页面功能和前后端契约，主要解决原界面层级偏平、组件间距不统一、交互反馈不足的问题，同时为后续主题商店 CSS 注入保留稳定边界。
设计原则：
- 颜色、圆角、阴影、间距和速度继续使用 CSS 变量；
- 页面与弹窗动画只改变
opacity和transform； - 不使用背景模糊、连续粒子、视差、复杂 SVG 或大范围布局动画；
- 不使用
transition: all，只声明需要变化的属性； - 尊重系统
prefers-reduced-motion设置； - 主题只需覆盖现有 Token，不需要了解组件内部动画实现。
2. 全局视觉基线
更新 tokens.css：
- 调整四级圆角和阴影，使卡片、弹窗与导航层次更清楚；
- 调整标题栏、状态栏和双侧栏尺寸；
- 统一更短的运动时间与缓动曲线；
- 增加键盘
focus-visible焦点环； - 为 checkbox、radio 和 range 使用主题强调色；
- 窄窗口下收缩辅助侧栏与展开导航宽度；
- 在减少动态效果模式下，把动画和过渡缩短到近似即时完成。
更新 features.css：
- 功能页增加受控内容宽度、响应式留白和低强度主题渐变；
- 卡片增加边框、阴影与最多 2px 的悬浮位移；
- 按钮、输入框、Badge、空状态和通知统一交互反馈；
- 设置页导航改为分段式卡片导航；
- 弹窗与页面增加一次性淡入和轻微位移动画。
3. 页面与布局优化
3.1 App Shell
- 主侧栏增加明确的 Active 标记、悬浮反馈和宽度过渡；
- 辅助侧栏统一为次级 Surface，并改善标题与标签层级；
- 标题栏应用名改为轻量胶囊标识；
- 状态栏强化状态点和窄窗口降级；
- 命令面板增加轻量入场、圆角、阴影和列表反馈。
3.2 业务页面
- Search 结果卡片增加左侧强调线和统一内容宽度；
- Chat 增加消息容器、头像层级、Citation 悬浮反馈和 Composer 顶部阴影；
- Agent Tool 选择卡增加选中状态，Trace 使用轻量时间线；
- Task 完成按钮增加主题化状态反馈；
- Settings 行在悬浮时提供背景提示；
- Workspace 空状态与 Vault 入口增加清晰的层级和一次性入场动画。
4. 动效性能边界
允许的常规动效：
opacity
transform: translate / scale / rotate
background-color
border-color
color
box-shadow
默认禁止：
transition: all
backdrop-filter / filter 模糊
持续改变 width / height / margin / padding 的动画
无限循环的装饰动画
全屏高频渐变或粒子动画
状态栏 Spinner 和 AI Core 检查状态点属于有明确状态含义的循环动画，并会被 prefers-reduced-motion 全局规则降级。
5. 主题商店接入约定
自定义主题优先覆盖以下 Token：
--color-background-*--color-surface-*--color-text-*--color-accent-*--color-border-*--color-code-*--shadow-*--radius-*--motion-*
主题 CSS 不应给通配选择器增加动画，不应重新启用高成本滤镜，也不应覆盖 prefers-reduced-motion 的降级规则。若主题需要完全静态的界面，可把三个 --motion-* Token 设置为接近 0ms。
6. 验证
新增 styles/motion.spec.ts，防止全局样式重新引入 transition: all、高成本模糊滤镜或布局型页面入场动画，并约束 Markdown 表格与列表使用独立的高对比度主题变量。
当前验证结果：
pnpm test 9 files / 22 tests passed
pnpm build passed
git diff --check passed
生产构建仍有已有的大 Chunk 警告，主要来自 Milkdown、CodeMirror、KaTeX 和 Shiki；本轮样式及动效未增加 JavaScript 动画库或运行时依赖。
本轮已完成样式静态检查、自动化测试和生产构建。由于本机内置浏览器运行资源路径缺失，亮色/暗色主题的人工页面巡检需在 PR 验收环境补做。