418 lines
17 KiB
Markdown
418 lines
17 KiB
Markdown
# EPEEKit 交互体验指南
|
||
|
||
> 设计语言：**青绿山水 · 科技幽谷**
|
||
> 核心意境：深山幽谷中的科技圣地 — 自然的宁静与数字的精密共存
|
||
> 更新日期：2026-04-16
|
||
|
||
## 实现状态说明
|
||
|
||
每个特性标注实现状态：
|
||
- ✅ **已实现** — 代码完整落地，与文档描述一致
|
||
- 🔶 **基本实现** — 核心功能已落地，细节有微小偏差（不影响体验）
|
||
- ⬜ **未实现** — 仅有文档描述，无对应代码
|
||
|
||
---
|
||
|
||
## 1. 设计哲学
|
||
|
||
每一次交互都是一次"与山水对话"：
|
||
|
||
| 操作 | 意象 | 动效语言 | 状态 |
|
||
|------|------|----------|------|
|
||
| 发送消息 | 投石入水 | 按钮弹缩 → 气泡飞入 → 涟漪扩散 | ✅ |
|
||
| AI 回复 | 云雾凝聚 | 模糊→清晰 → 文字逐行显现 | ✅ |
|
||
| 收藏图片 | 萤火点亮 | 星标亮起 → 金色粒子飘散 | ✅ |
|
||
| 滚动浏览 | 穿行雾中 | 内容在雾气边缘隐现 | ✅ |
|
||
| 等待加载 | 溪水潺潺 | 石青流光 + 水波纹脉冲 | ✅ |
|
||
| 图片揭示 | 水墨晕染 | clip-path 圆形从中心扩展 | ✅ |
|
||
| 会话切换 | 翻山越岭 | 内容滑出/滑入 | ✅ |
|
||
|
||
科技感不通过赛博朋克的锐利线条传递，而是通过"精密点阵 × 自然粒子"的融合 —
|
||
就像在深山中发现了一座用水晶和苔藓构建的数据中心。
|
||
|
||
---
|
||
|
||
## 2. 色彩体系 ✅
|
||
|
||
### 主色调
|
||
|
||
| 语义 | 变量名 | 色值 | 色彩隐喻 | 状态 |
|
||
|------|--------|------|---------|------|
|
||
| 背景主色 | `--bg-primary` | `#0C1210` | 深山暗处 | ✅ |
|
||
| 背景次级 | `--bg-secondary` | `#131E1A` | 苔藓暗绿 / 山石基底 | ✅ |
|
||
| 背景三级 | `--bg-tertiary` | `#1C2A24` | 松烟绿 / 远山中层 | ✅ |
|
||
| 卡片表面 | `--bg-card` | `rgba(16, 30, 24, 0.65)` | 半透明山岩 | ✅ |
|
||
| 主高亮色 | `--accent` | `#4DB8A4` | 石青绿 — 千里江山图的石青 | ✅ |
|
||
| 高亮 hover | `--accent-hover` | `#6CD4BE` | 石青亮态 | ✅ |
|
||
| 辅助高亮 | `--accent-secondary` | `#3A8FB7` | 石绿蓝 — 千里江山图的石绿 | ✅ |
|
||
| 热门/警告 | `--hot` | `#C4654A` | 赭石红 — 点景人物/宫殿暖色 | ✅ |
|
||
| 文字主色 | `--text-primary` | `#E0E8E2` | 微泛绿的月白 | ✅ |
|
||
| 文字次级 | `--text-secondary` | `#7A9485` | 青灰绿 | ✅ |
|
||
| 边框色 | `--border` | `rgba(77, 184, 164, 0.12)` | 石青半透明 | ✅ |
|
||
| 发光边框 | `--border-glow` | `rgba(77, 184, 164, 0.25)` | 石青发光态 | ✅ |
|
||
| 雾气基础 | `--mist` | `rgba(77, 184, 164, 0.06)` | 云雾底色 | ✅ |
|
||
| 赭金点缀 | `--gold` | `#B8935A` | 收藏星标等极少量暖色 | ✅ |
|
||
|
||
### 色彩来源
|
||
|
||
石青（`#4DB8A4`）和石绿蓝（`#3A8FB7`）取自《千里江山图》中使用的矿物质颜料色，
|
||
经现代演绎降低饱和度，在深色 UI 中不过于刺眼。
|
||
赭石红（`#C4654A`）来源于画中点景人物和宫殿使用的暖色颜料。
|
||
|
||
**实现文件**: `globals.css` `:root` 第 4-18 行
|
||
|
||
---
|
||
|
||
## 3. 信息层级体系
|
||
|
||
### 3.1 排版重量体系（7 级） ✅
|
||
|
||
| 层级 | CSS 类 | 大小 | 字重 | 字间距 | 视觉手段 | 状态 |
|
||
|------|--------|------|------|--------|----------|------|
|
||
| Display | `.typo-display` | 32px | 300 | -0.02em | 石青→石绿蓝渐变填色 | ✅ |
|
||
| H1 | `.typo-h1` | 24px | 700 | -0.01em | 底部石青细线装饰 | ✅ |
|
||
| H2 | `.typo-h2` | 18px | 600 | 0 | 左侧 3px 石青竖线标记 | ✅ |
|
||
| Body | 默认 | 14px | 400 | 0.01em | 标准 | ✅ |
|
||
| Body Strong | `.typo-strong` | 14px | 600 | 0 | 石青色 | ✅ |
|
||
| Caption | `.typo-caption` | 12px | 400 | 0.02em | text-secondary | ✅ |
|
||
| Micro | `.typo-micro` | 11px | 600 | 0.04em | 大写 + 加宽字间距 | ✅ |
|
||
|
||
关键区分手段：Display 使用渐变文字而非纯色，H1 与 H2 各有独立视觉标记（底线 vs 竖线），
|
||
不仅靠字号大小区分层级。
|
||
|
||
**实现文件**: `globals.css` 第 33-102 行
|
||
**使用位置**: `typo-display`（欢迎页/登录页）、`typo-h1`（ProfileModal 用户名）、`typo-h2`（Gallery 详情标题）、`typo-strong`（侧栏/Gallery 区域标题、ProfileModal 记忆标题）、`typo-caption`（时间戳/记忆条数）、`typo-micro`（标签/分组标签/New 标记）
|
||
|
||
### 3.2 表面层级系统（Surface Elevation） ✅
|
||
|
||
4 级表面，每升一级 backdrop-blur +8px、border 亮度 +0.06、box-shadow 扩展 +4px：
|
||
|
||
| 层级 | CSS 类 | 用途 | 隐喻 | 状态 |
|
||
|------|--------|------|------|------|
|
||
| Surface-0 | — | 页面背景 `#0C1210` | 深渊 | ✅ |
|
||
| Surface-1 | `.surface-1` | 侧栏/主区域 | 山脚（bg-secondary + 微弱内发光） | ✅ |
|
||
| Surface-2 | `.surface-2` | 卡片/消息气泡 | 山腰（glass-panel + 更强模糊 + 微上移阴影） | ✅ |
|
||
| Surface-3 | `.surface-3` | 弹窗/下拉/tooltip | 山顶（强模糊 + 明显阴影 + 更亮边框） | ✅ |
|
||
|
||
**实现文件**: `globals.css` 第 106-133 行
|
||
**使用位置**: 侧栏（surface-1）、消息气泡/回到底部按钮（surface-2）、下拉菜单/弹窗（surface-3）
|
||
|
||
> 注：文档定义的 `.glass-panel` 与 `.surface-2` 视觉上等价，实际组件统一使用 surface-* 系列。`glass-panel` 保留为兼容。
|
||
|
||
### 3.3 用户消息 vs 助手消息 ✅
|
||
|
||
| 维度 | 用户消息 | 助手消息 | 状态 |
|
||
|------|----------|----------|------|
|
||
| 对齐 | 右对齐 | 左对齐 | ✅ |
|
||
| 背景 | 石青渐变（accent/8 → accent/15） | glass-panel（Surface-2） | ✅ |
|
||
| 圆角 | 左上方切角（几何感） | 标准圆角 | ✅ |
|
||
| 边框 | 无 | 左侧 2px 石青竖线（山泉流水） | ✅ |
|
||
| 入场动画 | 投石入水（从下方飞入） | 云雾凝聚（blur 消散） | ✅ |
|
||
|
||
**实现文件**: `chat-messages.tsx` 第 69-74 行、`globals.css` `.user-bubble` 类
|
||
|
||
---
|
||
|
||
## 4. 科技质感
|
||
|
||
### 4.1 环境粒子（Ambient Particles） ✅
|
||
|
||
背景云雾之上叠加"深山萤火"粒子层：
|
||
|
||
- 数量：15-20 个小光点
|
||
- 颜色：石青色，opacity 0.15-0.3
|
||
- 行为：缓慢随机漂浮 + 偶尔闪烁（opacity 脉冲）
|
||
- 实现：React 组件 + useMemo 随机化 + CSS animation
|
||
- 空态时粒子增多至 ~28 个，营造"未探索的深山"感
|
||
|
||
**实现文件**: `components/ui/ambient-particles.tsx`
|
||
**接入位置**: `page.tsx`（首页，count 根据空态切换）、`login/page.tsx`、`gallery/page.tsx`
|
||
|
||
### 4.2 网格底纹（Subtle Grid） ✅
|
||
|
||
Surface-0 背景叠加极淡的点阵网格（opacity: 0.03），
|
||
几乎不可见但传递"精密、数字化"的潜意识感知，与云雾层形成"自然 × 科技"张力。
|
||
|
||
**实现文件**: `globals.css` `body::before` 第 136-145 行
|
||
|
||
### 4.3 数据流光（Data Stream） ✅
|
||
|
||
AI 思考/生成时，输入栏上方出现一条横向流光：
|
||
|
||
- 石青色光带从左向右流动，高度 2px
|
||
- 思考时慢速、生成图片时加速
|
||
- 意象：山间溪流 / 数据脉搏
|
||
|
||
**实现文件**: `components/ui/data-stream.tsx`、`globals.css` `.data-stream` / `-slow` / `-fast`
|
||
**接入位置**: `chat-input.tsx` 第 202 行
|
||
|
||
---
|
||
|
||
## 5. 微交互图鉴
|
||
|
||
所有微交互使用 framer-motion 实现，统一动画参数定义在 `motion-presets.ts` 中。
|
||
|
||
### 5.1 发送消息 — "投石入水" ✅
|
||
|
||
1. 发送按钮 `scale(0.85)` → spring 弹回（`sendBounce`）
|
||
2. 消息气泡从输入栏位置飞入对话区（translateY + opacity）
|
||
3. 到达目标位置时涟漪扩散（`RippleLayer` 石青色圆环 scale + fade out）
|
||
4. 输入栏清空后边框发光脉冲一次（水面恢复平静）
|
||
|
||
**实现文件**: `chat-input.tsx`（sendBounce + useRipple）、`ripple-effect.tsx`、`motion-presets.ts`
|
||
|
||
### 5.2 AI 回复 — "云雾凝聚" ✅
|
||
|
||
1. 消息气泡 `blur(8px)` → `blur(0)` 凝聚显现
|
||
2. 文字逐行显示时 opacity 阶梯（新行更亮，旧行渐稳）
|
||
3. 图片结果：石青色模糊占位 → blur 消散 + scale 1.02→1.0（拨开云雾）
|
||
|
||
**实现文件**: `motion-presets.ts` `assistantEnter`、`chat-messages.tsx` `StreamingLines` 组件
|
||
|
||
### 5.3 收藏图片 — "萤火点亮" ✅
|
||
|
||
1. 星标 outline → filled，赭金色
|
||
2. 点击瞬间散出 5-7 个微小金色粒子（萤火被惊起）
|
||
3. 粒子向四周飘散并淡出（stagger + random 偏移）
|
||
|
||
**实现文件**: `components/ui/firefly-burst.tsx`、`image-grid.tsx` `FavoriteButton`
|
||
|
||
### 5.4 图片加载 — "水墨晕染" ✅
|
||
|
||
1. 占位：石青渐变块 + 呼吸脉冲（`.stone-placeholder`）
|
||
2. 加载完成：`clip-path: circle()` 从中心扩展到全图（水墨滴入纸面）
|
||
|
||
**实现文件**: `globals.css` `.stone-placeholder`、`motion-presets.ts` `inkReveal`、`image-grid.tsx` `ImageReveal`
|
||
|
||
### 5.5 输入框 — "水面感应" ✅
|
||
|
||
- 空态：底部淡石青线
|
||
- 获焦：边框从中心向两端扩展点亮（水面波纹展开）
|
||
- 输入时：边框亮度随文字长度微增（蓄力）
|
||
- 可发送态：发送按钮缓慢脉冲发光（准备就绪）
|
||
|
||
**实现文件**: `globals.css` `.water-focus-line` / `.water-focus-active`、`chat-input.tsx` boxShadow 联动
|
||
|
||
### 5.6 Hover 状态 ✅
|
||
|
||
- 按钮：`translateY(-1px)` + shadow 加深（浮起感）
|
||
- 卡片：border-glow + 底部向上内发光渐变
|
||
- 侧栏会话项：左侧 2px 石青竖线 slide-in
|
||
|
||
**实现文件**: `globals.css` `.btn-hover-lift`（第 466-472 行）、`.neon-border`（第 195-204 行）、`.session-hover-line`（第 474-493 行）
|
||
|
||
### 5.7 滚动到底部 — "落叶归根" ✅
|
||
|
||
- 形状：水滴形（椭圆切割 border-radius）
|
||
- 出现：spring 从下方弹入
|
||
- 石青半透明背景 + 雾气边框
|
||
|
||
**实现文件**: `page.tsx` scroll-btn、`motion-presets.ts` `scrollBtnEnter`
|
||
|
||
### 5.8 会话切换 — "翻山越岭" ✅
|
||
|
||
- 当前对话向上/向下滑出
|
||
- 新对话从对应方向滑入
|
||
- 过渡 250ms ease-out
|
||
- 使用 `AnimatePresence mode="wait"` + `sessionSlide` 变体
|
||
|
||
**实现文件**: `page.tsx` AnimatePresence 包裹聊天内容区、`motion-presets.ts` `sessionSlide`
|
||
|
||
---
|
||
|
||
## 6. 状态与反馈
|
||
|
||
### 6.1 Loading 体系 ✅
|
||
|
||
| 场景 | 表现 | 状态 |
|
||
|------|------|------|
|
||
| 骨架屏 | shimmer 渐变（bg-tertiary → bg-secondary），左→右扫描 | ✅ |
|
||
| 内联加载 | 三个石青圆点"水波纹"式依次涌起（scale Y 变化） | ✅ |
|
||
| 全屏加载 | 中心放射状云雾凝聚（涟漪环 + 核心光点 + 呼吸脉冲） | ✅ |
|
||
| AI 生成中 | 数据流光（输入栏上方 2px 流动光带） | ✅ |
|
||
|
||
**实现文件**: `globals.css` `.skeleton-shimmer`、`.wave-dot`、`.mist-loader`、`.data-stream`
|
||
**接入位置**: `image-grid.tsx`、`chat-messages.tsx`、`app-context.tsx`、`chat-input.tsx`
|
||
|
||
### 6.2 空态设计 ✅
|
||
|
||
- Display 级渐变文字欢迎语
|
||
- "快速开始"建议卡片（stagger 入场）
|
||
- 萤火粒子增多营造氛围
|
||
|
||
**实现文件**: `page.tsx` isEmptyState 分支
|
||
|
||
### 6.3 Error 状态 ✅
|
||
|
||
- 赭石红色调但保持优雅（非大红色块）
|
||
- 微弱横向震动（translateX ±2px，2 次）
|
||
- 自动消失时向上飘散淡出（`errorFloat` 变体 + 4s 定时清除）
|
||
|
||
**实现文件**: `globals.css` `.error-shake`、`motion-presets.ts` `errorFloat`、`login/page.tsx`
|
||
|
||
---
|
||
|
||
## 7. 动效语言
|
||
|
||
### 7.1 时序原则 ✅
|
||
|
||
| 类别 | 时长 | 缓动 |
|
||
|------|------|------|
|
||
| 即时反馈（hover/press） | 150-200ms | ease |
|
||
| 状态过渡（展开/折叠） | 250ms | ease-in-out |
|
||
| 云烟效果（淡入/淡出） | 400-600ms | ease |
|
||
| 环境动效（背景漂移） | 45-60s | ease-in-out infinite |
|
||
| Spring 物理（弹缩） | stiffness: 400, damping: 25 | spring |
|
||
|
||
### 7.2 编排原则 ✅
|
||
|
||
- **先快后慢**：触发瞬间最快，收尾最慢（模拟自然物理）
|
||
- **层次递进**：多元素入场使用 stagger（50-80ms 间隔），从近到远
|
||
- **克制优先**：微交互幅度小（1-3px 位移、0.95-1.05 缩放），避免分散注意力
|
||
- **自然衰减**：所有粒子效果都应以 opacity → 0 结束，不突兀消失
|
||
|
||
### 7.3 统一动画参数（motion-presets.ts） ✅
|
||
|
||
```typescript
|
||
// Spring 物理参数
|
||
spring: { stiffness: 400, damping: 25 }
|
||
springGentle: { stiffness: 200, damping: 20 }
|
||
|
||
// 入场动画
|
||
fadeIn: { opacity: [0, 1], transition: { duration: 0.2 } }
|
||
slideUp: { opacity: [0, 1], y: [8, 0], transition: { duration: 0.2 } }
|
||
mistReveal: { filter: ["blur(8px)", "blur(0px)"], opacity: [0, 1], duration: 0.4 }
|
||
|
||
// 按钮反馈
|
||
buttonTap: { scale: 0.85 }
|
||
sendBounce: { scale: [1, 0.85, 1.05, 1], transition: { duration: 0.3 } }
|
||
|
||
// 涟漪/粒子
|
||
ripple: { scale: [0, 2.5], opacity: [0.4, 0], duration: 0.6 }
|
||
sparkle: { scale: [0, 1, 0], opacity: [0, 1, 0], duration: 0.8 }
|
||
|
||
// 会话切换
|
||
sessionSlide: { enter → center → exit, y ±30, duration: 0.25 }
|
||
|
||
// Error 飘散
|
||
errorFloat: { exit → opacity: 0, y: -12, duration: 0.5 }
|
||
```
|
||
|
||
**实现文件**: `components/ui/motion-presets.ts`
|
||
|
||
---
|
||
|
||
## 8. 视觉效果
|
||
|
||
### 8.1 山雾玻璃面板 ✅
|
||
|
||
```css
|
||
.glass-panel {
|
||
background:
|
||
linear-gradient(165deg, rgba(16, 30, 24, 0.15) 0%, transparent 50%),
|
||
rgba(16, 30, 24, 0.55);
|
||
backdrop-filter: blur(24px) saturate(1.1);
|
||
border: 1px solid var(--border);
|
||
}
|
||
```
|
||
|
||
**实现文件**: `globals.css` 第 185-192 行（定义）
|
||
> 注：组件统一使用 `.surface-2`（等价视觉），`.glass-panel` 保留为兼容别名。
|
||
|
||
### 8.2 云烟缭绕边框 ✅
|
||
|
||
选中态组件的动态边框：
|
||
- 常态：石青微弱均匀静态发光
|
||
- hover：conic-gradient 6s 缓慢旋转（40-50% 宽弧段），模拟云烟缭绕
|
||
- 移开：opacity 600ms 平滑淡散
|
||
|
||
**实现文件**: `globals.css` `.glow-border` + `@property --glow-angle` + `mistSpin`（第 206-285 行）
|
||
**使用位置**: `top-nav.tsx` 活跃 Tab、`session-list.tsx` 当前会话
|
||
|
||
### 8.3 山雾背景 ✅
|
||
|
||
多层缓慢漂移云雾（远景层 60s / 近景层 45s），
|
||
两层不同速率和方向模拟远山/近山视差。
|
||
|
||
**实现文件**: `globals.css` `.fog-layer-far` / `.fog-layer-near`（第 162-182 行）
|
||
**挂载位置**: `ambient-particles.tsx` 组件内渲染两个雾层 div
|
||
|
||
### 8.4 雾气滚动边缘 ✅
|
||
|
||
主要滚动区域顶底渐变遮罩（36px 渐变区域），内容消失在云雾中。
|
||
|
||
**实现文件**: `globals.css` `.fog-scroll`（第 288-303 行）
|
||
**使用位置**: `page.tsx` 对话滚动区、`session-list.tsx` 会话列表
|
||
|
||
---
|
||
|
||
## 9. 布局架构
|
||
|
||
### 整体结构 ✅
|
||
|
||
```
|
||
┌───────────────────────────────────────────────────────┐
|
||
│ Top Nav (56px) — Surface-1 + 毛玻璃 │
|
||
├──────────┬────────────────────────────────────────────┤
|
||
│ 侧边栏 │ 主内容区（对话 / 资源库） │
|
||
│ (280px) │ (flex-1) │
|
||
│ Surface-1 │ ┌──────────────────────────────────────┐ │
|
||
│ 会话列表 │ │ 对话消息 / 图片网格 │ │
|
||
│ 标签筛选 │ │ (fog-scroll 雾气边缘) │ │
|
||
│ │ └──────────────────────────────────────┘ │
|
||
│ │ 数据流光条（AI 活动时可见） │
|
||
│ │ 输入区 — 水面感应 │
|
||
└──────────┴────────────────────────────────────────────┘
|
||
```
|
||
|
||
**实现文件**: `page.tsx`（首页布局）
|
||
|
||
### 间距系统 ✅
|
||
|
||
- 面板间间距：0（紧贴，用边框分隔）
|
||
- 卡片网格间距：16px
|
||
- 内容区内边距：20px
|
||
- 面板内边距：16px
|
||
|
||
### 响应式断点 ✅
|
||
|
||
| 断点 | 布局 |
|
||
|------|------|
|
||
| ≥768px (md) | 双栏：侧边栏(280px) + 主内容区(flex-1) |
|
||
| <768px | 单栏：侧边栏为固定抽屉 + 主内容区全宽 |
|
||
|
||
**实现文件**: `sidebar.tsx`（md 断点切换固定/内联）、`app-context.tsx`（`window.innerWidth < 768` 初始折叠）
|
||
|
||
---
|
||
|
||
## 10. 技术实现
|
||
|
||
### 依赖
|
||
|
||
- `framer-motion`：微交互动画引擎（spring 物理、stagger、AnimatePresence）
|
||
- `tailwindcss v4`：工具类样式
|
||
- CSS 自定义属性：设计 token
|
||
- CSS `@property`：可动画角度属性（云烟边框）
|
||
|
||
### 文件结构
|
||
|
||
```
|
||
src/
|
||
├── components/ui/
|
||
│ ├── ambient-particles.tsx — 环境萤火粒子 ✅
|
||
│ ├── data-stream.tsx — 数据流光条 ✅
|
||
│ ├── ripple-effect.tsx — 涟漪效果 ✅
|
||
│ ├── firefly-burst.tsx — 萤火粒子爆发 ✅
|
||
│ └── motion-presets.ts — 统一动画参数 ✅
|
||
├── app/globals.css — 设计 token + 工具类 ✅
|
||
└── ...existing components — 集成微交互
|
||
```
|
||
|
||
### 性能约束
|
||
|
||
- 环境粒子使用 React + CSS animation，不引入 Canvas
|
||
- 所有动画使用 transform/opacity，避免触发 layout
|
||
- 粒子总数不超过 30 个
|
||
- 背景动效使用 `will-change: transform` 提示 GPU 加速
|
||
- framer-motion 使用 `layout` 动画时限制在必要组件
|