chart-vocabulary

Pick the right chart for the story you want to tell, evaluate whether an AI-suggested chart is correct, and know when to override.

This skill is the selection and evaluation reference. It sits upstream of the plugin's other chart skills:

flint-chart §0.2 (Question → family → chart) is a compact router pointing into this catalog; when a decision needs more than the router's ~7 rows, read this file. When picking a chart to hand-author rather than render via Flint, this catalog is still the reference — the delivery skill differs, the taxonomy does not.

When to Use

• Choosing chart types for a dashboard, report, book figure, or data story
• Evaluating an AI-generated visualization (Copilot / ChatGPT / any tool that auto-selects chart types)
• Reviewing another agent's or teammate's chart choices for story-intent alignment
• Sanity-checking a dashboard's density (5-visual rule)
• Teaching a heir the chart taxonomy without them reading FT's catalog end to end

Module 1: Chart Catalog by Communication Goal

Seven communication goals. Pick the goal first, then the chart. Never pick the chart first.

Comparison

Show differences between items or groups.

Change Over Time

Show trends, seasonality, or evolution.

Proportion

Show part-to-whole relationships.

Distribution

Show spread, shape, or outliers.

Relationship

Show correlation, causation, or connection.

Flow and Process

Show movement, conversion, or paths.

Deviation

Show variance from a reference point.

Module 2: The CSAR Evaluation Loop

Module 1.5: Storytelling Technique Router

Choose a technique because it solves a reading problem, not because it makes the chart look authored.

Theme choice follows technique and audience. It cannot repair a wrong chart family or unsupported claim.

When an AI tool generates a chart, evaluate before accepting. Compose with render-verify's Prose-coupling check for a two-layer safety net: CSAR asks did it pick the right chart family; render-verify asks did it render the right message.

Override Decision Table

Module 3: The 5-Visual Rule

Executive dashboards that work follow this constraint:

No more than 5 visuals per page. Each visual answers a different question. If you need more, you need a second page, not a denser layout.

Count the visuals, do not eyeball them, when the page is machine-readable. For an HTML or docs-shell dashboard, count chart containers per page from the DOM or the page manifest and assert the count is ≤5. In the browser console: document.querySelectorAll('canvas, svg, .chart, .chart-container, [data-chart]').length (narrow the selector to the page's chart-container convention so decorative SVGs do not inflate the count). A screenshot scanned by eye is not a count.

A sixth visual is a table for drill-down, placed below the fold or on demand.

Composition by Audience

Module 4: Living Gallery References

Use these galleries to browse real examples when Module 1's tables aren't enough. The galleries are the living source of truth; this skill is the decision framework.

When to consult a gallery

• Module 1 suggests 2+ chart types and you cannot decide
• The story intent doesn't fit any standard goal group
• You need to see a real example of a chart type before committing
• Stakeholder needs visual evidence that the chart type works for their data

Module 5: Chart Selection Decision Tree

Run this algorithm when choosing charts for a dashboard, report, or book figure:

1. Write the Big Idea sentence (audience + action + evidence)
   → delegate to chart-big-idea; if you can't write it, the analysis isn't done

2. List the 3-5 questions the artifact must answer
   Each question becomes one visual

3. For each question:
   a. Identify the communication goal (Module 1 header)
   b. Check the chart catalog table
   c. Filter by data shape and audience
   d. If AI generated a chart, run CSAR (Module 2)
   e. If still unsure, consult a gallery (Module 4)

4. Apply the 5-Visual Rule (Module 3)
   Cut the weakest visual if over budget

5. Arrange by narrative flow:
   KPIs → Hero chart → Supporting → Detail

6. Author + render:
   → statistical charts: flint-chart (Vega-Lite / ECharts / Chart.js via Flint MCP)
   → structural / hand-authored SVG: figure-generator + print-svg-style-guide
   → AI-generated illustration: separately configured host image tool (not bundled by ONE)
   → no renderer available (terminal, log, PR, context window): ascii-chart

7. Verify: render-verify (Prose-coupling + failure catalog)

Attribution

The chart catalog (Module 1), CSAR loop (Module 2), 5-visual rule (Module 3), gallery references (Module 4), and selection tree (Module 5) are adapted from an earlier visual-vocabulary curriculum, absorbed into this plugin in 2026. Its ASCII delivery lives here as ascii-chart. Its SVG composition patterns (panel primitive, pie sizing, dark-slate palette) are covered by print-svg-style-guide and figure-generator, with print-legibility math and semantic palette colors, so they are not duplicated here.

FT Visual Vocabulary, Data-to-Viz, Data Viz Catalog, Vega-Lite examples, and Storytelling with Data are cited under their published URLs; this skill is a decision framework built on top of those galleries, not a replacement for them.

Would Revise If

Revisit if:

• The 5-visual rule is contradicted by a working dashboard that ships more visuals without density complaints (rule too strict)
• One of the five galleries in Module 4 retires or moves; the URL check fails
• A heir installs chart-vocabulary and visual-vocabulary from the Mall on the same brain and reports confusion about which is canonical (the absorption story isn't landing)