# HTML 看板视觉设计底线（Part C-12 / Part D / Part E 共用）

> **来源**：吸收 [xiaomingtx666/design-taste-skills](https://github.com/xiaomingtx666/design-taste-skills)（MIT）的「可执行设计底线」方法论——design-taste 通用美学底座 + design-html A 路径（数据应用），按观远 BI 的三个 HTML 场景定制。随 majia-guanyuan **V3.1.0**（2026-06-11）引入。
>
> **核心心法**（来自上游，与本 skill 的路由哲学同构）：**决策交给模型，底线交给文档**。配色、深浅色、布局风格由模型按业务自定；本文档只收录「模型容易做不到的执行红线」——每条都是命中即修的硬底线，不是审美建议。
>
> **何时读这里**：生成或修改任何观远 HTML 看板（C-12 模块 / Part D customChart / Part E SuperApp）的视觉层时；用户说"做好看点 / 太丑 / AI 味重 / 不够专业"时；C-12 §11 四层 API 验收过了之后做第五层视觉验收时。

---

## §0 适用场景与 scope

| 场景 | 载体 | 适用章节 |
|---|---|---|
| **C-12 HTML 应用看板** | 观远 Page 卡片 iframe 内的 HTML 模块 | §1–§8 全部 + §9 验收 |
| **Part D v7 HTML customChart** | 同上（v7 发布流水线产物，`charts/dashboard.{html,css,js}`） | 同上 |
| **Part E SuperApp** | 独立整页 React 应用 | Part E §10 设计纪律已覆盖 token / App Shell / design:lint；本文档补 §2 数值口径、§6 状态文案、§8 反 AI 味全表 |

**为什么 C-12/D 场景没有 App Shell 章节**：HTML 模块活在观远卡片 iframe 里——导航、selector、权限、刷新都是 Page 原生的。上游 design-html 的 sidebar/topbar 规则只适用于 Part E 这种独立整页应用（且 SuperApp 官方模板已自带）。C-12/D 的设计底线收敛到**模块内**。

---

## §1 模块第一视觉位 = 数据判断

- 每个 HTML 模块的第一视觉位必须是**数据判断**：KPI + 主图、异常队列、核心表格、健康度——不是大标题、不是装饰图形、不是"使用说明"。
- 模块标题（`<h2>`）只负责定位，一行带过；**小节标题写业务结论**（"交通枢纽店客单领先 23%"），不写"数据概览""趋势分析"这类空标签。
- 模块内文字层级 **≤ 3 层**（标题 / 数值或正文 / 辅助标注）。要第 4 层，先拆模块。
- 相邻层级字号差 **≥ 1.2 倍**——不要 13/14/15 这种看不出差别的假层级。
- 一个模块只有 **1 个主焦点**。两个同等抢眼的元素必须分主次：一个变大变重，另一个降级。
- 并列项（KPI、列表行动项、标签）控制在 **5–7 个**，超了就分组、排序、折叠。

## §2 KPI 与数值口径

- KPI 一行 **3–4 个**，不要 6–9 个同权重铺满当模块主体。KPI 只能辅助，模块主体必须是图表 / 表格 / 列表 / 行动队列。
- KPI 主值 **28–32px**（`html_base.css` 的 `.gd-kpi-value` 已按 28px 校准），特殊主判断上限 40px。
- 每个核心数字必须带：**单位、时间范围、对比基准**。涨跌色要可推断是"好坏"还是"方向"（跌价红色未必是坏事）。
- 数字一律 `font-variant-numeric: tabular-nums`（防刷新跳动）；数值列右对齐，单位与数字基线对齐。
- 不混用"万 / w / K / 千"；同一指标在 KPI、图表、表格里**单位、小数位、千分位一致**。
- mock / demo 数据也要业务连续——KPI、图表、表格、洞察不能互相打架；没有真实数据时明确标 sample，不伪装成真实经营结果。

## §3 图表真实性（硬底线）

- SVG 自绘（`GDHTML.lineSvg / scatterSvg / bar / stacked`）必须**真实数据驱动 + 有基线/刻度/单位标注**。**禁止用 CSS 高度条、渐变块、静态图片伪造图表**——这是返工项，不是扣分项。
- 需要 tooltip / legend / 缩放等复杂交互的图表走 `ECHARTS_LITE`（见 C-12 §3 决策表），不在 SDK 模式里手搓交互。
- 一个图只回答**一个业务问题**，不把所有维度塞进一张图。
- 占比类别 **> 5 个不用饼图**，改条形。
- 面积、长度、角度、颜色深浅必须与数据含义一致；**不用 3D、透视、阴影夸大差异**；不为美观牺牲比例、排序、基线、坐标。
- 图表标题写业务问题，不写"柱状图""折线图"。

## §4 表格

- 首列放主对象（门店 / 城市 / 商品），数值列右对齐 + `tabular-nums`（`.gd-table td.num` 已内置），状态列色彩语义明确（`.gd-tag.good/warn/bad`）。
- 行高 **36–44px**（`html_base.css` 已按 ~38px 校准），高密度场景仍可读，不压缩到贴边。
- 长数字、长店名、长 ID 要有截断 / 换行策略，不侵入相邻列。

## §5 视觉 token 硬上限（`html_base.css` 对照）

> 这套上限是「没有明确品牌系统时」的默认约束。客户有 VI / 设计系统时优先沿用客户的，但反 AI 味（§8）和验收（§9）照样要过。

| token | 硬上限 | 模板现状 |
|---|---|---|
| 圆角 | 卡片 / 面板 **≤ 8px**（pill 形态标签例外） | `.gd-tag` 10px 为 pill ✓，其余 ≤4px ✓ |
| 阴影 | `box-shadow` 模糊 **≤ 8px**；优先 1px 细边框 + surface 分层 | 模板无阴影 ✓ |
| 间距 | 固定刻度 **8 / 12 / 16 / 20 / 24 / 32**，不冒出 13、19、27 | ✓ |
| 字号 | 模块标题 16/600 · 分组标题 13–14 · 正文表格 13 · 标签 11–12 · KPI 主值 28–32 | V3.1.0 起校准 ✓ |
| 字距 | 普通文本 letter-spacing 为 0，不用负字距压缩 | ✓ |
| 色彩 | **状态色 / 数据色 / 强调色三层分离**，不同语义不混用同一 token；一个模块一个主 accent | `.gd-tag` 状态族与 `.gd-kpi` 强调线分离 ✓ |
| 深色 | 不用纯黑 `#000` 铺底，留 **2–3 级 surface**；避开霓虹紫蓝 | 模板为浅色系；深色另定 surface 再动手 |

间距归属（亲密性）：组内 1x、同级组间 2x、大区块间 3–4x；**标题到自己正文的距离必须小于它到上一组的距离**，否则归属读错。

对齐：一个模块主对齐轴 ≤ 2 条；卡片、图表、段落边缘落在同一条网格线上，不要每个容器各缩进各的。

## §6 状态意识（`safeCols` / `mountEmpty` 升级）

C-12 §4.3 已有 `GDHTML.safeCols + mountEmpty` 兜底——V3.1.0 起升级要求：**状态文案必须带业务上下文**，不只写"暂无数据"。

| 态 | 底线 | C-12 落法 |
|---|---|---|
| `empty` | 说明当前筛选为什么无数据 + 给下一步 | `mountEmpty("所选城市无低效门店，可放宽到全国或近 90 天")` |
| `error` | 说明失败对象，可判断数据停在何时 | dataView 缺失时报模块名 + dataView 名（现行做法保留），有时间戳就带上 |
| `loading` | 观远卡片 iframe 的 loading 由 BI 原生控制，模块内**不需要**自做骨架屏 | 不处理 ✓ |

六态全表（loading / empty / error / success / disabled / permission）用于 Part E SuperApp 场景——SuperApp 是完整应用，主任务不能只有成功态；文案同样必须带业务上下文（"指标服务超时，数据停留在 10:32，点此重试"，而不是"加载失败"）。

## §7 信息密度与垂直节奏（最容易翻车）

- 模块内容填满卡片高度但不堆死：上下密度均衡，**不要上半挤、下半空一大块**。
- 撑高度靠真正的视觉元素（图表、列表、表格）变大去填，**不是把行距和分隔线拉开充数**。
- 同类间距全模块一致：KPI 行间距、列表行距、小节间距各自统一，不要每处不同。
- 高密度靠**对齐 + 分组 + 留白**做层次，不靠堆色块、加边框、套容器。
- 边界（容器框）只在能减少误解时加，不为显高级给所有东西套框、不卡片套卡片。

## §8 反 AI 味红线（命中即重做）

| 失败信号 | BI 场景替代做法 |
|---|---|
| 紫蓝 / 粉紫渐变铺底，霓虹光晕、粒子、bokeh | 实色 surface、品牌色细线、干净留白 |
| 玻璃拟态卡片 + 半透明 blur 到处用 | 实色表面 + 1px 边框 + surface 分层 |
| 模块内再套 3–6 张等大卡片墙（图标+标题+两行文案） | 按重要性做主从布局：1 主图 + 辅助列表 / 对比表 |
| emoji 当图标系统；图标混粗线细线填充 | 统一一套 SVG（同尺寸同描边），或干脆不用图标 |
| 每个小节都有小号大写 eyebrow 或 01/02/03 编号 | 只在真正的序列处用；其他让标题直接承担语义 |
| 欢迎语 / "如何使用本页"卡占第一视觉位 | 数据判断顶上去（§1） |
| "立即体验 / 一键生成"营销 CTA 出现在工作台 | BI 模块只有业务动作：导出、下钻、标记、放宽筛选 |
| 大圆角 + 重阴影 + 细边框叠满所有容器 | 只选一种层级手段：边界 / 阴影 / 背景差 / 留白 |
| 假图表（CSS 高度条 / 渐变块 / 静态图） | 真数据驱动 SVG 或 ECHARTS_LITE（§3） |
| 图表无基线、无单位、颜色只为好看 | 恢复基线、单位、标注、真实比例 |
| 文案满是"赋能 / 重塑 / 极致 / 智能洞察" | 写具体对象、动作、结果（"华东 12 店连续 3 周负增长"） |

**渐变不是禁区**：同色系两端相近色相、透明度 ≤ 20%、服务焦点（关键数字 / 图表面积 / 强调区）、一屏最多 1–2 处——这四条都满足就可以用。紫蓝满屏渐变、多个高饱和光晕叠加、渐变盖过文字可读性——任一命中就删。

## §9 视觉验收（第五层，接 C-12 §11 四层之后）

API 验收通过 ≠ 看板做对了，更 ≠ 看板能看。**用 `guanvis screenshot` 出 PNG 做视觉验收**（服务端截图，比 Chrome 截图可靠，C-12 §11 的黑屏问题不存在）：

```bash
guanvis screenshot <pgId> -o /tmp/page-visual-check.png
```

逐项检查（任一不过就修，修完重截）：

- [ ] 每个 HTML 模块第一视觉位是数据判断，不是标题 / 装饰 / 欢迎语（§1）
- [ ] KPI ≤ 4 个一行、主值 28–32px、有单位和对比基准（§2）
- [ ] 图表有基线 / 刻度 / 单位；无 CSS 假图表；饼图类别 ≤ 5（§3）
- [ ] 数字列右对齐、`tabular-nums`；同一指标各处单位小数位一致（§2/§4）
- [ ] 无紫蓝渐变 / 玻璃拟态 / 卡片墙 / emoji 图标 / 营销 CTA（§8）
- [ ] **工艺四查**：无挤压（文字贴边、按钮换行、标题截断）、无重叠（标签互盖、长数字侵列）、无错位（基线不齐、数字列不右对齐、卡片不在同一网格）、无无效留白（大面积空白无视觉重心、模块间距大于模块自身）
- [ ] 模块密度均衡：撑满高度靠视觉元素，不靠空隙（§7）

**修复顺序**：先保证不挤压、不重叠 → 再修对齐 → 最后调留白和节奏。第一轮一个问题都没找到，就换更严格视角再查一遍。

## §10 与上游和兄弟章节的关系

- **上游四件套只吸收两件**：design-taste 通用底座 + design-html 的 A 路径（数据应用）。design-ppt / design-pdf / design-html B 路径（官网营销页）不吸收——majia-guanyuan 不做这些载体。唯一带过来的 B 路径意识：**BI 看板不做营销 hero、不写欢迎语**（已并入 §8）。
- **Part E §10 设计纪律**（SuperApp 官方模板自带 `npm run design:lint`）与本文档**同源同向**：单数字 ≤ 40px、圆角 ≤ 8px、阴影 ≤ 8px、三层 token、tabular-nums、禁紫蓝渐变——完全一致。SuperApp 场景：design:lint 机械自检打底 + 本文档 §2 / §6 / §8 人工补查（lint 查不出口径缺失和文案空洞）。
- **Part D 的奶白 `#faf7f2` + 暖蓝 `#2563eb` 主题**是一个符合本底线的具体取色方案（实色 surface、单 accent、克制）。新项目可以换色，token 上限不变。
- **模板包**：`templates/html-dashboard/charts/html_base.css` V3.1.0 起按 §5 校准（KPI 主值 28px + tabular-nums、表格行高 ~38px、状态文案样式族），新模块直接复用即自动达标大半。
