# UI 设计规格：电子木鱼桌宠（禅意木质风）

- 配套预览：`wooden-fish-plugin/ui-design/wooden-fish-preview.html`（浏览器打开）
- 木鱼美术稿：`wooden-fish-plugin/ui-design/fish.svg`
- 版本：v0.1 设计稿（待确认）

---

## 1. 设计基调

禅意 + 木质：暖棕木色系、圆润轮廓、柔和阴影、克制的高光。像一件放在案头的小木器，而不是像素贴纸。

## 2. 设计令牌（Design Tokens）

| Token | 值 | 用途 |
|---|---|---|
| `wood-deep` | `#6B421A` | 最暗描边 / 纹理 |
| `wood-dark` | `#8A5A2B` | 底座、槌柄 |
| `wood-base` | `#B06F2F` | 鱼身主色 |
| `wood-mid` | `#C9884A` | 鱼身中色 |
| `wood-light` | `#D8A062` | 鱼身亮部 |
| `wood-hi` | `#EABD85` / `#F0CE9D` | 头部高光 |
| `accent` | `#D99A3D`（悬停 `#E8A75A`） | 数值强调、选中态 |
| `ink` | 主题自适应 | 主文字 |
| `muted` | 主题自适应（~62% 透明度） | 次要文字 |
| 圆角 | 卡片 12px / 角标 999px / 柱 3px | 柔和 |
| 阴影 | `0 6px 18px rgba(80,50,20,.18)` | 悬浮层次 |
| 字体 | `system-ui, -apple-system, "PingFang SC", sans-serif` | 中文优先 |
| 鱼默认尺寸 | 宽 96px（设置页内小木鱼 72px） | 不挡内容 |

深浅主题：浅色底 `#F7F2EA`（暖纸感），深色底 `#201C17`；所有透明色用「暖棕 alpha」而非纯灰，保证两套主题下都不发灰。

## 3. 悬浮木鱼（桌宠）

### 3.1 造型（鱼头朝左，禅意微笑）
- **鱼身**：圆胖椭圆体，上缘饱满、下缘略收；木色纵向渐变，深棕描边。
- **头部高光**：左上叠加浅色高光区 + 亮斑，制造木质反光。
- **大嘴缝**：一条贯穿中部的微弧线（微笑），深棕粗线 + 下唇浅阴影线。
- **半闭禅眼**：一道向下弯的短弧线，不点瞳孔——「半眯着眼挨敲」的禅意。
- **分叉小尾**：右侧扇形小尾，与身体同色系深一档。
- **底座木垫**：鱼身下一条圆角厚木垫，让鱼"坐"稳。
- **木槌**：右上方一柄圆头小槌，柄根部为转轴，常态斜立、敲击时下摆。

### 3.2 状态与反馈

| 状态 | 表现 | 参数 |
|---|---|---|
| 常态 idle | 静置 + 柔和投影 | drop-shadow |
| 悬停 hover | 轻微上浮（translateY -2px）、投影加深 | 0.15s ease |
| 敲击 knock | ① 鱼身晃动：rotate ±6° 短促两摆；② 木槌绕柄根**朝左下摆 38°**（逆时针，敲向鱼身）；③ 鱼身顶部浮现两道声波弧线（0.6s 淡出扩散）；④ 右上飘「+1」（0.9s 上浮渐隐） | 总时长 ~0.18s 主动画 |
| 拖动 drag | 正常跟随指针；移动 >5px 判定为拖动，不触发敲击；拖完位置悬停态解除 | pointer capture |

### 3.3 悬停提示（今日次数）
- 鼠标悬停木鱼时，木鱼**上方**浮现胶囊气泡「今天已敲 N 次」（深色半透明底 + 暖橙数字 + 小箭头），0.15s 淡入上移；移开鼠标或拖动时消失。不悬停时完全不打扰。
- 敲击后气泡内数字有 0.2s 缩放弹跳。

### 3.4 位置
- 默认右下角（距右 26px、距底 150px，避开输入框）；可拖动到任意位置；本次会话内记忆，刷新回默认。

## 4. 设置页看板（设置 → 电子木鱼）

```
┌──────────────────────────────────────────────┐
│ [小木鱼] 电子木鱼                              │
│          点一下小木鱼，积攒今日份安心            │
├──────────────────────────────────────────────┤
│  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
│  │ 今日敲击 │  │ 累计敲击 │  │ 连续天数 │        │
│  │   28    │  │  1,204  │  │    9    │        │
│  └─────────┘  └─────────┘  └─────────┘        │
├──────────────────────────────────────────────┤
│  近3个月  近6个月  近一年   （胶囊切换，选中橙色，默认6个月）│
│  一 · ▢▢▢▢▢▢▢ ▢▢▢▢▢▢▢ …   日历热力图，色深=次数，悬停显数值 │
│     3月    5月    7月    9月   （月份标签 + 周一/三/五）      │
├──────────────────────────────────────────────┤
│  🔔 悬浮木鱼：显示中            （开关）        │
└──────────────────────────────────────────────┘
```

- **页头**：72px 小木鱼（可点击敲击，复用同一套反馈）+ 标题两行。
- **统计卡片**：3 张等宽暖底圆角卡；数字 22px 加粗暖橙、千分位；标签 12px muted。数字变化有 0.2s 弹跳。
- **趋势日历热力图**（v1.1 替换柱状图）：周 × 天方格矩阵（列=周，行=周一~周日）；**格子自适应压缩**（列宽 `minmax(0,14px)` + `aspect-ratio:1/1`，一年视图自动压到 6.5–13px），**任何宽度都不出现横向滚动条**；5 档木色（0 次浅底格；1-3 / 4-8 / 9-15 / 16+）；顶部月份标签（允许溢出可见）、左侧周一/三/五；悬停 `YYYY-MM-DD · N 次` 气泡（**最后 8 列右锚**，避免撑出滚动）；今日描边；底部图例「少→多」+ 范围摘要行（`近 6 个月　共 N 次 · 有敲击 D 天 · 最长连续 S 天`）。
- **显示/隐藏开关**：一行左侧铃铛图标 + 文案；点击切换，悬浮木鱼即时显隐；**状态持久化**（localStorage，刷新/重启后保持）。

## 5. 动效总表（全部纯 CSS，无 JS 补间）

| 动效 | 时长/缓动 |
|---|---|
| 鱼身敲击晃动 | 0.18s ease（rotate ±6°） |
| 木槌下摆 | 0.12s ease（rotate -38°，朝左敲向鱼身） |
| 声波弧线 | 0.6s ease-out（淡出 + 上移扩散） |
| +1 飘字 | 0.9s ease-out（上浮 26px 渐隐，首帧放大 1.15） |
| 数字弹跳 | 0.2s cubic-bezier(.34,1.56,.64,1) |
| 卡片/角标入场 | 0.25s ease（fade + 上移 4px） |

## 6. 确认点

1. 木鱼造型（圆胖 / 微笑嘴 / 半闭眼 / 木槌）是否合意？
2. 敲击反馈（晃动 + 槌落 + 声波 + +1）够不够？
3. 设置页看板布局是否符合预期？
4. 颜色深浅主题是否都需要？（预览页可切换主题查看）

---

## 7. v1.1 变更（已实现并通过验证）

### 7.1 日历热力图（替换柱状图，2026-09-19 确认）

| 项 | 最终实现 |
|---|---|
| 形态 | 周 × 天方格矩阵：列 = 周，行 = 周一~周日 |
| 范围 | 近 3 个月（13 周）/ **近 6 个月（26 周，默认）** / 近一年（53 周） |
| **自适应压缩** | 列宽 `repeat(N, minmax(0, 14px))` + 方格 `width:100%; aspect-ratio:1/1`：3/6 月格子到 14px 上限，一年视图自动压缩（900px 宽下约 11.8px，700px 下约 8px） |
| **零横向滚动** | 容器 `overflow-x: clip; overflow-y: visible`（clip 不产生滚动容器，纵向 tooltip 仍可溢出）；关键：**tooltip 的绝对定位盒子会撑宽网格**（8px 小格居中气泡外溢 ~54px，`opacity:0` 也占位），故最后 8 列改为右对齐锚定（`nth-last-child(-n+56)`） |
| 配色 | 5 档木色 `--dsh-muyu-h0..h4`（浅：`rgba(120,90,60,.10)`/#F0DFC4/#E3C293/#D09A54/#B2702F；深色另一套），**按设计稿锁定不改** |
| 标签 | 顶部月份（`overflow:visible`，小格时仍可读）、左侧周一/三/五（与 7 行对齐）、底部图例「少→多」 |
| 交互 | 悬停 `YYYY-MM-DD · N 次`；今日描边（brand-primary）；未来日期透明且不显示 tooltip |
| 摘要行 | `近 6 个月　共 N 次 · 有敲击 D 天 · 最长连续 S 天` |
| 数据源 | Host `summary` 返回全量 `days` 映射（新增字段） |

**验证**：4 档窗口宽（620/700/900/1100）× 3 档范围 = 12 组组合，均 `pageScrollbar=false`、网格宽度精确等于容器宽。

### 7.2 主题适配（v1.1）

外壳（卡片、边框、文字、按钮、tooltip）改用 **0.1.5 官方主题 CSS 变量** `--dsw-alias-*`（`bg-layer-1` / `border-l1` / `label-primary` / `label-secondary` / `brand-primary` / `bg-overlay`），带硬编码回退值 → 自动跟随浅/深色与自定义主题（如 sakura）；**木鱼美术与热力色阶保持木质本色**（视觉识别不随主题漂移）。

### 7.3 持久化（v1.1）

`localStorage`（键 `dsh-wooden-fish:v1`）保存 `{ visible, left, top }`：拖动结束后写入，位置按视口钳制；刷新/重启后木鱼回到原位、显隐状态保持（修掉 v1.0 的两处限制）。