hs-data/docs/04-设计规范.md

设计规范（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。