fable-dataviz

Fable DataViz

将数据转化为易于理解的可视化表达，同时不改变数据实际表达的含义。

使命

图表是对幅度、趋势、分布、关系、不确定性或构成的论证。首先要选择与问题相匹配的视觉编码，其次要保留统计含义。完成这两步后再进行样式设计。

即使 SVG 有效、配色美观，也可能不是好的可视化：例如，误导性地截断坐标轴、汇总不兼容的组别、隐藏缺失数据、将相关性暗示为因果关系，或凭空赋予数据源不支持的精度。

在以下情况启用

• 需要通过可视化解释指标／趋势／分布／比较／关系；
• 需要为基准测试／评估结果制作图表或统计图形；
• 报告／产物需要有证据支持的可视化；
• 需要将原始数据转换为 SVG／图表代码或可视化规范。

在以下情况不要启用

• 没有实际数据，且请求需要编造数值；
• 对于简单的小型查询任务，纯表格更准确／易读；
• 核心任务是文档结构，而非视觉编码（fable-artifact）；
• 用户请求的是说明性图像，而非数据可视化。

问题分类

问题	首选的实用编码	常见误用
比较类别	条形图／点图	使用许多相似扇区的饼图
展示有序时间趋势	折线图／面积图，并谨慎处理基线	将无序类别绘制成折线图
展示分布	直方图／箱线图／小提琴图／点图	只展示平均值的条形图
展示关系	散点图／气泡图，并说明尺度注意事项	双轴相关性表演
展示部分与整体的关系	堆叠条形图／100% 条形图；有限使用饼图	将并不构成同一整体的部分相加
排名	排序后的条形图／点图	按字母顺序排列，掩盖排名
单个关键指标及背景	统计值 + 基线／变化	没有分母／时间范围的巨大数字
不确定性	区间／带状区域／误差线	隐藏方差，却只显示精确点值

协议

阶段 1 — 确定数据来源及语义约定

记录：

• 来源／数据集／版本／时间窗口；
• 单位和分母；
• 类别／时间定义；
• 缺失值／空值语义；
• 数值属于计数、比率、百分比、货币、估算值还是建模输出；
• 可用的不确定性／精度信息。

如果来源或指标含义不明确，应先暂停并厘清，再进行渲染。

阶段 2 — 明确可视化问题

用一句话写明：This chart should help the reader see ___。

如果存在多个互不相关的问题，应创建独立视图，而不是强行塞进一张过载图表。

阶段 3 — 验证转换

绘图前，明确规定：

• 筛选条件；
• 分组／聚合方式；
• 归一化／分母；
• 排序方式；
• 日期分桶／时区；
• 缺失值／异常值处理方式；
• 衍生指标／计算方式。

检查转换前后的总量／范围。绝不静默丢弃会改变论点的记录。

阶段 4 — 选择编码和尺度

在可行的情况下，使用位置／长度进行精确比较。根据指标语义选择线性／对数／百分比尺度。

基线规则：

• 条形长度通常需要有意义的零点，因为长度用于编码幅度；
• 折线图／散点图的坐标轴可以使用非零范围，但必须清晰标注，且不能夸大趋势；
• 对数尺度要求数值为正，并且必须明确标注；
• 双轴风险较高，必须有充分理由。

阶段 5 — 编码不确定性和数据质量

如果估算值带有区间／方差／样本量，且这些信息很重要，应予以展示或说明。应标记缺失的时间段／类别，不要将其连接起来，仿佛数据已实际观测到。

不要展示超出数据源精度所支持的小数位数。

阶段 6 — 兼顾可读性与无障碍设计

优先考虑：

• 能说明指标和背景的描述性标题；
• 能减少对图例解读需求的直接标签；
• 易读的字体排版和间距；
• 对比度和非颜色线索；
• SVG 的无障碍标题和描述；
• 响应式 viewBox／合适的容器行为；
• 单位和来源说明。

不要仅依靠红绿或色相来表达含义。

阶段 7 — 验证渲染结果

检查：

• 图表渲染后没有裁切或重叠；
• 数据坐标与源数据值一致；
• 坐标轴／刻度／标签／图例正确；
• 响应式布局在小屏幕和大屏幕上均正常；
• 浅色／深色主题（如有要求）；
• 无障碍元数据；
• 没有转换／渲染代码在不提示的情况下改变顺序或数值。

阶段 8 — 进行误导性审查

思考：

• 合理的读者是否会推断出超出原始数据支持范围的更大／更小效应？
• 分母／时间窗口是否一目了然？
• 缺失值是否被隐藏？
• 注释是否暗示了未经证实的因果关系？
• 类别是否因基准不同而无法比较？

修正图表表达的主张，而不只是图像本身。

决策规则

• 绝不捏造数据、标签、样本量、来源或基准测试结果。
• 不注明分母／基数的百分比，在可视化前通常需要补充背景信息。
• 如果读者需要精确比较，或类别很多，应避免使用饼图／环形图。
• 极值／事件很重要时，不要简单丢弃数据点来降采样；应采用有文档记录的聚合／采样策略。
• 除非领域明确定义缺失值为零，否则缺失值不等于零。
• 除非自然／顺序语义另有要求，否则应按有助于回答问题的方式排列类别。
• 默认情况下，条形图应从零基线开始；如需例外，必须采用不会造成误导的编码方式，并保持截断清晰可见。
• 相关图／时间上的巧合不足以支持因果注释。
• 如果图表在目标尺寸下无法保持易读性，应简化／拆分图表，而不是将标签缩小到无法辨认。

不变原则

• 每个绘制标记都能对应到源数据／转换逻辑。
• 单位、分母和时间范围都应如实保留。
• 不得悄无声息地将缺失／不确定数据转化为确定信息。
• 不得刻意通过尺度选择夸大数值大小。
• 无障碍访问不得仅依赖颜色。
• 渲染结果可追溯到源数据和转换步骤。

失败类型

图表问题选择错误

编码方式呈现的是构成情况，而读者需要精确比较。应根据分析问题重新选择图表。

聚合失真

分组／标准化改变了分母，或掩盖了重要的子群体表现。应重新计算并记录转换过程。

尺度误导

坐标轴／数值范围让微小变化看起来很极端。应恢复合适的基线／数值范围并添加标签。

缺失数据虚构

空值期间未经解释就被绘制为零／插值结果。应标示间隙或记录估算方法。

点位过度绘制／拥挤

标记／标签重叠，掩盖了分布情况。应合理聚合、分面、采样，或更换编码方式。

无障碍设计失败

对比度不足、仅用颜色表达含义或文字太小，导致图表难以解读。应添加非颜色线索／直接标签／无障碍元数据。

来源不确定

指标含义或来源不明确。应停止渲染并明确数据来源约定。

反模式

• 还没弄清问题，就先说“做成环形图”；
• 截断条形图坐标轴来夸大变化；
• 使用双坐标轴来制造相关性；
• 将缺失值视为零；
• 捏造样本数据来让图表看起来完整；
• 不做说明就通过降采样抹去峰值；
• 使用会扭曲面积／长度的 3D／透视效果；
• 没有语义理由却使用彩虹配色；
• 标题仅为“收入”，却不注明单位／时间范围；
• 仅因 SVG 语法解析通过就宣称图表已验证。

可视化数据包

Question / intended takeaway:
Source + version/timeframe:
Metric definition / unit / denominator:
Transformations:
Missing/outlier/uncertainty handling:
Encoding + scale rationale:
Accessibility choices:
Rendered validation:
Deception audit:
Source note:

完成标准

可视化在满足以下条件时即为完成：

• 明确说明视觉问题和指标含义；
• 转换过程可复现，并已检查总数／范围；
• 编码／比例尺与分析任务相匹配，且未造成失真；
• 如实呈现缺失／不确定的数据；
• 在目标尺寸／主题下可访问地渲染；
• 可追溯源数据与图形标记之间的关系；
• 结论不超出数据所能支持的范围。

渐进式资源

• 深入指南：references/truthful-chart-selection-and-validation.md
• 现有设计系统：references/dataviz-design-system.md
• 示例：examples/render-bar-chart.md