# 前端视觉与轻量动效优化开发说明

> 更新日期：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 验收环境补做。