113 lines
4.0 KiB
Markdown
113 lines
4.0 KiB
Markdown
# 前端视觉与轻量动效优化开发说明
|
||
|
||
> 更新日期：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. 动效性能边界
|
||
|
||
允许的常规动效：
|
||
|
||
```text
|
||
opacity
|
||
transform: translate / scale / rotate
|
||
background-color
|
||
border-color
|
||
color
|
||
box-shadow
|
||
```
|
||
|
||
默认禁止：
|
||
|
||
```text
|
||
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-*`
|
||
- `--shadow-*`
|
||
- `--radius-*`
|
||
- `--motion-*`
|
||
|
||
主题 CSS 不应给通配选择器增加动画，不应重新启用高成本滤镜，也不应覆盖 `prefers-reduced-motion` 的降级规则。若主题需要完全静态的界面，可把三个 `--motion-*` Token 设置为接近 0ms。
|
||
|
||
## 6. 验证
|
||
|
||
新增 `styles/motion.spec.ts`，防止全局样式重新引入 `transition: all`、高成本模糊滤镜或布局型页面入场动画。
|
||
|
||
当前验证结果：
|
||
|
||
```text
|
||
pnpm test 7 files / 17 tests passed
|
||
pnpm build passed
|
||
git diff --check passed
|
||
```
|
||
|
||
生产构建仍有已有的大 Chunk 警告，主要来自 Milkdown、CodeMirror、KaTeX 和 Shiki；本轮样式及动效未增加 JavaScript 动画库或运行时依赖。
|
||
|
||
本轮已完成样式静态检查、自动化测试和生产构建。由于本机内置浏览器运行资源路径缺失，亮色/暗色主题的人工页面巡检需在 PR 验收环境补做。
|