fable-dataviz

Fable DataViz

Turn data into a visual claim that is easy to read without changing what the data actually says.

Mission

A chart is an argument about magnitude, trend, distribution, relationship, uncertainty, or composition. The first job is to choose a visual encoding that matches that question. The second is to preserve statistical meaning. Styling comes after both.

A valid SVG with attractive colors can still be a bad visualization if it truncates axes deceptively, aggregates incompatible groups, hides missing data, implies causality from correlation, or invents precision the source does not support.

Activate When

• a metric/trend/distribution/comparison/relationship needs visual explanation;
• benchmark/eval results need charts or stat graphics;
• a report/artifact needs an evidence-backed visual;
• raw data must be transformed into SVG/chart code or a visual specification.

Do Not Activate When

• there is no actual data and the request would require inventing values;
• a plain table is more accurate/readable for a small lookup task;
• the core task is document structure rather than visual encoding (fable-artifact);
• the user requests an illustrative image rather than a data visualization.

Question Classification

Question	Useful first encoding	Typical misuse
Compare categories	bar/dot plot	pie with many similar slices
Trend over ordered time	line/area with careful baseline	unordered category line chart
Distribution	histogram/box/violin/dot	average-only bar
Relationship	scatter/bubble with scale caveats	dual-axis correlation theater
Part-to-whole	stacked bar/100% bar; limited pie	sum components that are not one whole
Ranking	sorted bar/dot	alphabetic order hiding rank
Single KPI + context	stat + baseline/change	giant number without denominator/timeframe
Uncertainty	interval/band/error bars	precise point with hidden variance

Protocol

Stage 1 — Establish data provenance and semantic contract

Record:

• source/dataset/version/time window;
• unit and denominator;
• category/time definitions;
• missing/null semantics;
• whether values are counts, rates, percentages, currency, estimates, or modeled outputs;
• uncertainty/precision available.

If source or metric meaning is ambiguous, stop and resolve it before rendering.

Stage 2 — State the visual question

Write one sentence: This chart should help the reader see ___.

If there are multiple unrelated questions, create separate views rather than forcing one overloaded chart.

Stage 3 — Validate transformations

Before plotting, explicitly define:

• filters;
• grouping/aggregation;
• normalization/denominator;
• sorting;
• date bucketing/time zone;
• handling of missing/outliers;
• derived metrics/calculations.

Check totals/ranges before and after transformation. Never silently drop records that change the claim.

Stage 4 — Choose encoding and scales

Use position/length for precise comparisons where possible. Choose linear/log/percentage scales based on metric semantics.

Baseline rules:

• bar length usually needs meaningful zero because length encodes magnitude;
• line/scatter axes may use non-zero domains if clearly labeled and not exaggerating the story;
• log scales require positive values and explicit labeling;
• dual axes are high-risk and need strong justification.

Stage 5 — Encode uncertainty and data quality

If estimates have intervals/variance/sample sizes, show or state them when material. Mark missing periods/categories rather than connecting them as if observed.

Do not show more decimal places than source precision justifies.

Stage 6 — Design for reading and accessibility

Prioritize:

• descriptive title stating metric/context;
• direct labels where they reduce legend decoding;
• readable typography/spacing;
• contrast and non-color cues;
• accessible title/description for SVG;
• responsive viewBox/appropriate container behavior;
• units and source note.

Do not rely on red/green or hue alone for meaning.

Stage 7 — Validate the rendered artifact

Check:

• chart renders without clipping/overlap;
• data coordinates match source values;
• axes/ticks/labels/legend are correct;
• small/large screens when responsive;
• light/dark theme if required;
• accessibility metadata;
• no transformation/render code silently changes ordering or values.

Stage 8 — Run a deception audit

Ask:

• would a reasonable reader infer a larger/smaller effect than raw data supports?
• is the denominator/time window obvious?
• are missing values hidden?
• does annotation imply causality not established?
• are categories incomparable due to different bases?

Fix the visual claim, not only the pixels.

Decision Rules

• Never invent data, labels, sample sizes, sources, or benchmark results.
• A percentage without denominator/base often needs contextualization before visualization.
• Avoid pie/donut when readers need precise comparison or categories are numerous.
• Do not downsample by simply dropping points when extrema/events matter; use a documented aggregation/sampling strategy.
• Missing values are not zero unless the domain explicitly defines them that way.
• Sort categories to support the question unless natural/order semantics require otherwise.
• Use zero baseline for bars by default; exceptions require an encoding where truncation is not misleading and must remain visible.
• Correlation chart/temporal coincidence does not justify causal annotation.
• If a chart cannot remain legible at target size, simplify/segment rather than shrink labels into illegibility.

Invariants

• Every plotted mark maps to source/transformation logic.
• Units, denominator, and timeframe remain truthful.
• Missing/uncertain data is not silently converted into certainty.
• Scale choices do not intentionally exaggerate magnitude.
• Accessibility does not depend on color alone.
• Rendered output can be traced back to source data and transformation steps.

Failure Taxonomy

Wrong chart question

Encoding answers composition while reader needs precise comparison. Re-select chart by analytical question.

Aggregation distortion

Grouping/normalization changes denominator or hides important subgroup behavior. Recompute and document transformation.

Scale deception

Axis/domain makes modest changes look extreme. Restore appropriate baseline/domain and labels.

Missing-data fiction

Null periods are plotted as zero/interpolated without justification. Mark gaps or document imputation.

Overplotting/crowding

Marks/labels overlap and conceal distribution. Aggregate, facet, sample responsibly, or change encoding.

Accessibility failure

Contrast/color-only meaning/text size prevents interpretation. Add non-color cues/direct labels/accessible metadata.

Source uncertainty

Metric meaning or provenance is unclear. Stop rendering and resolve source contract.

Anti-Patterns

• starting with "make it a donut" before understanding the question;
• truncating bar axes to dramatize change;
• dual axes used to manufacture correlation;
• treating missing values as zero;
• inventing sample data to make the chart look complete;
• downsampling away spikes without disclosure;
• 3D/perspective effects that distort area/length;
• rainbow palettes with no semantic reason;
• title like "Revenue" with no unit/timeframe;
• declaring a chart verified because SVG syntax parses.

Visualization Packet

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:

Completion Criteria

Visualization completes when:

• visual question and metric semantics are explicit;
• transformations are reproducible and totals/ranges checked;
• encoding/scale match the analytical task without distortion;
• missing/uncertain data is honest;
• artifact renders accessibly at target size/theme;
• source/data-to-mark traceability exists;
• no claim exceeds what the data supports.

Progressive Resources

• Deep guide: references/truthful-chart-selection-and-validation.md
• Existing design system: references/dataviz-design-system.md
• Example: examples/render-bar-chart.md