# 设计规范（UI / 视觉）

> hs-data 前端的视觉与交互定稿。**本文是设计决策的唯一权威来源**;`apps/web/src/index.css` 是实现来源(CSS 变量),改样式先看本文、再动 CSS,二者保持一致。
> 风格已锁定,非经讨论不随意更改(`CLAUDE.md` 第 1、3 条)。

| 项 | 内容 |
|----|----|
| 文档版本 | v1.0 |
| 文档状态 | 已定稿 |
| 更新日期 | 2026-06-24 |

## 修订记录

| 版本 | 日期 | 修订内容 |
|------|------|----------|
| v1.0 | 2026-06-24 | 初版:锁定 shadcn + Tailwind v4 + 神策风 mint 主题、布局、漏斗图、控件、抗抖 |

---

## 1. 技术与来源

- UI 栈:**shadcn/ui(radix-nova/neutral 起手)+ Tailwind CSS v4**,图表用 **ECharts**(见 `docs/02` §1)。
- 配色取自**神策数据**官网(sensorsdata.cn)实际 CSS:主色 mint `#04CB94`、文本 `#1F2D3D`、底 `#F9FAFC`、弱化文本 `#99A9BF`、强调淡 mint `#DEFFF6`、错误 `#EF4444`。
- 组件源码拷贝在 `apps/web/src/components/ui/`,可改;主题变量在 `apps/web/src/index.css`。

## 2. 色板(关键 token)

> 完整值见 `src/index.css` 的 `:root`。以下为决策锚点(OKLCH / 对应 hex)。

| 角色 | token | 值 | 用途 |
|----|----|----|----|
| 页底色 | `--background` | `oklch(0.985 0.003 247)` ≈ `#F9FAFC` | 主内容区,微蓝白(**非纯白**) |
| 文本 | `--foreground` | `oklch(0.27 0.035 261)` ≈ `#1F2D3D` | 标题 / 正文 |
| 卡片 | `--card` | 纯白 | 浮在底色上 |
| 主色 | `--primary` | `oklch(0.71 0.16 168)` = `#04CB94` | 按钮 / 选中 / focus / logo / 漏斗末层 |
| 弱化文本 | `--muted-foreground` | `oklch(0.68 0.025 247)` ≈ `#99A9BF` | caption / 辅助 |
| 强调淡底 | `--accent` | `oklch(0.96 0.045 162)` ≈ `#DEFFF6` | 选中 / hover 淡 mint |
| 错误 | `--destructive` | `oklch(0.63 0.22 27)` ≈ `#EF4444` | 错误态 |
| 描边 | `--border` | `oklch(0.92 0.008 247)` | 分隔线 / 边框 |
| 圆角 | `--radius` | `0.625rem` | 全局基准 |

暗色(`.dark`)变量已备但**默认不启用**(`index.html` 不挂 `dark` 类)。

## 3. 布局(三段式 + 单一滚动区)

- **顶栏**:白(`bg-card`)+ 底部细线;左 mint logo 图标 + 标题「hs-data · 数据服务平台」,右 mint dot + `MVP`。
- **侧栏**:浅 slate-100(`--sidebar`,**有色不刺眼**,比主区沉一档);宽 `w-56`,可纵向滚动。
  - **三级导航树**(`NavTree.tsx`,IA 见 `docs/01` §2):L1 能力域(加粗 + 图标 + 展开箭头 ▸/▾)→ L2 分析模块 → L3 报表;L2/L3 用**左侧竖引导线**(`border-l border-sidebar-border`)+ 缩进,层级一眼可分。
  - **展开/折叠**(对齐主流后台):点 L1/L2 分组手动展开/折叠(不跳转);多个可同时展开;进入某页自动展开其所在分支,不折叠其它已展开分支。叶子才跳转。
  - hover/激活:淡 mint 底(`--sidebar-accent`)+ mint-700 文字;**叶子精确激活强高亮(mint pill)**,父分组在路径内仅文字变 mint。
  - **5 个 L1(模块名统一四字)**:行为分析 `/behavior`、指标体系 `/metrics`、画像体系 `/profile`、数据看板 `/dashboards`、营销触达 `/marketing`。MVP 可用页:`/behavior/funnel/group`(拼团漏斗);`/` 重定向至此。
  - 设计取舍(内部工具非 SaaS):指标体系只取消费面;不设独立"实时"域(并入数据看板);画像为多实体(用户/商家/产品);不设数据治理/工作台门面。
- **主区**:`--background` 微蓝白,`p-6`;白卡浮起,卡片带轻双层投影(`index.css` 的 `[data-slot="card"]`)。
- **反差原则**:顶(白)≠ 左(浅 slate),全程浅色低反差。**不用**深色侧栏(试过,弃:对比太狠、顶左同色死板)。

### 滚动模型(防加载抖动)— 不可回退
- 根容器 **`h-screen overflow-hidden`**:让 `<main>` 成为**唯一滚动区**,窗口(html)不滚动。
- `<main>` 带 **`overflow-auto [scrollbar-gutter:stable]`**:始终预留滚动条宽度,内容增高时滚动条不出现/消失 → **无横向抖动**。
- 加载骨架高度对齐真实内容(漏斗图 ~380 + 表格) → **无竖向跳动**。

## 4. 漏斗图(ECharts)

- 类型 funnel,块宽按**真实 UV 比例**(`minSize:'12%'` 保底尾巴)。
- 配色:**mint 单色渐变**,深→浅 5 阶 `#064E3B → #065F46 → #047857 → #10A37F → #04CB94`(对齐主色)。
- 块内白字加粗显示「步骤名 + UV」;转化率不在图上重复(右侧表格已有,避免拥挤)。
- tooltip:深底圆角 + 阴影,列出 UV / 转化率 / 流失率(`null` 显示 “—”)。

## 5. 控件与文案

- **时间控件**(漏斗页标题行右侧)—— **统一 segmented 控件** `TimePeriodSelect`,三选一:`📅 单日 YYYY-MM-DD ｜ 近 7 天 ｜ 近 30 天`。
  - **选中态 = mint 实色 + 白字**(`bg-primary`),由 React 状态直接驱动(`cn(SEG, on?ON:OFF)`),**不依赖 shadcn Tabs/Button 的 `data-active` 变体**——避免选中态在浅页上隐形。任一选中都同款 mint,给明确"当前在此周期"反馈。
  - 「单日」段点开日历(popover)可选历史日:默认昨日、**上限昨日**(T+1,今天/未来禁选)、历史不设下限;选日即进单日模式。
  - 教训:此前用 shadcn Tabs 默认选中态(白底+微阴影)+ Button variant,选中高亮在浅色页几乎不可见;改为自绘 segmented + 状态驱动后彻底解决。
- **快照/截至说明**(结果区底部小灰字):
  - 单日 → 「数据快照日:`YYYY-MM-DD`」。
  - 近 7/30 天 → 「数据截至 `YYYY-MM-DD`(近 7 天 / 近 30 天)」,点明窗口不含今天。
- **数据状态**:`ready` 出图表+表格;`missing` 出「数据缺失」空态(**不补零**);传输错误出 destructive Alert。
- **Mock 徽章**:虚线灰边 + amber 小 dot「Mock 模式」(低饱和,不抢主色)。
- 漏斗页副标题:「拼团漏斗:启动 → 曝光 → 拼团详情 → 下单 → 成功」。

## 6. 改样式的规矩

- 调色:改 `src/index.css` 的 `:root`(主色改 `--primary` + `--ring` + `--accent` 一组)。
- 漏斗图色:改 `FunnelChart.tsx` 的 `STEP_COLORS`。
- 布局滚动模型(§3 末)与抗抖骨架**不要回退**。
- 任何视觉大改先按 `docs/05` §7 讨论再动,落地后更新本文 + `CHANGELOG.md`。