Menu
Chart catalog organized by communication goal, CSAR evaluation loop for AI-generated charts, 5-visual rule, override decision framework, and living gallery references
Bundle plugin: installs the complete Visual Storytelling pipeline (brief, ingest, clean, select, deliver). See component SKILLs for detailed specs.
Data cleaning, profiling, transformation, and quality gates -- prepares raw data for visualization and analysis
Ingestion patterns for CSV, JSON, REST API, SQL, Excel, and Parquet -- guides an LLM through loading data from any common source
Render data dashboards as pure ASCII art in monospace text -- the cheapest, most portable delivery method. No rendering engine, no SVG, no browser. LLM-native output with predictable character geometry.
Render data dashboards as self-contained HTML files using Apache ECharts v6. Single file, zero build step, interactive charts with tooltips and data zoom. Declarative JSON option config optimized for AI generation.
Render data dashboards as static SVG panels embeddable in Markdown. Uses D3.js v7 mental model for scales, shapes, and axes. No runtime JS; output is pure SVG with inline styles for GitHub compatibility.
| type | skill |
| lifecycle | stable |
| inheritance | inheritable |
| name | visual-vocabulary |
| description | Chart catalog organized by communication goal, CSAR evaluation loop for AI-generated charts, 5-visual rule, override decision framework, and living gallery references |
| tier | standard |
| applyTo | **/*chart*,**/*visual*,**/*viz*,**/*dashboard*,**/*report* |
| currency | "2026-05-02T00:00:00.000Z" |
| lastReviewed | "2026-05-02T00:00:00.000Z" |
Pick the right chart for the story you want to tell, evaluate whether an AI-generated chart choice is correct, and know when to override.
This skill is the selection and evaluation layer. It delegates chart design (color, annotation, decluttering) to data-visualization and narrative arc (three-act structure, audience framing) to data-storytelling. Use this skill first to decide WHAT to show; use those skills to decide HOW to show it.
Show differences between items or groups.
| Chart | Best When | Avoid When |
|---|---|---|
| Horizontal bar | Ranking items; long category labels | More than 15 items (paginate or filter) |
| Grouped bar | Comparing 2-3 series across categories | More than 3 series (use small multiples) |
| Dot plot | Precise value comparison; tight ranges | Audience expects bars |
| Slope chart | Before/after comparison of ranked items | More than 10 items (too many crossing lines) |
| Radar | Multi-dimensional profile comparison | More than 7 axes; general audiences |
| Bullet chart | Actual vs. target with qualitative ranges | No clear target or benchmark |
Show trends, seasonality, or evolution.
| Chart | Best When | Avoid When |
|---|---|---|
| Line | Continuous data; up to 5 series | Categorical time (use bar) |
| Area | Emphasizing volume or magnitude of change | Multiple overlapping series (use stacked) |
| Stacked area | Part-to-whole composition changing over time | Need to compare individual series precisely |
| Sparkline | Inline trend context (KPI cards, tables) | Trend shape matters less than precise values |
| Step line | Discrete changes (pricing, policy, thresholds) | Continuous gradual change |
| Small multiples | Comparing trends across 6-20 categories | Fewer than 4 categories (use single line chart) |
Show part-to-whole relationships.
| Chart | Best When | Avoid When |
|---|---|---|
| Donut | 2-5 segments; one hero segment to highlight | More than 6 segments; comparing across groups |
| Stacked bar | Comparing composition across categories | More than 5 segments per bar |
| Waffle | Communicating percentages to general audiences | Precision matters (use table) |
| Treemap | Hierarchical part-to-whole with many items | Need to show change over time |
| Sunburst | Multi-level hierarchy exploration | Print or static context (needs interaction) |
| Waterfall | Showing additive/subtractive contributions | Non-sequential contributions |
Show spread, shape, or outliers.
| Chart | Best When | Avoid When |
|---|---|---|
| Histogram | Single variable distribution shape | Comparing distributions (use violin or ridgeline) |
| Box plot | Comparing distributions across groups | General audiences (unfamiliar format) |
| Violin | Distribution shape comparison across groups | Fewer than 3 groups (use histogram) |
| Ridgeline | Many distributions stacked for pattern scanning | Precision on individual values |
| Scatter | Two-variable distribution and outlier detection | Categorical data |
| Beeswarm | Small dataset; every point matters | More than 500 points (use density) |
Show correlation, causation, or connection.
| Chart | Best When | Avoid When |
|---|---|---|
| Scatter | Two continuous variables; outlier identification | Categorical variables |
| Bubble | Three variables (x, y, size) | More than 50 bubbles (overplotting) |
| Heatmap | Dense matrix relationships (correlation, time x category) | Fewer than 4x4 cells |
| Parallel coordinates | Multi-dimensional comparison (5+ variables) | General audiences |
| Network graph | Entity relationships, social connections | Hierarchical data (use tree) |
| Chord diagram | Bidirectional flows between categories | More than 10 categories |
Show movement, conversion, or paths.
| Chart | Best When | Avoid When |
|---|---|---|
| Sankey | Multi-stage flow with branching paths | Fewer than 3 stages (use stacked bar) |
| Funnel | Sequential drop-off (conversion, pipeline) | No sequential order |
| Gantt | Timeline with parallel activities | More than 30 tasks (filter or paginate) |
| Swimlane | Process flow with role/team assignments | Simple linear process |
Show variance from a reference point.
| Chart | Best When | Avoid When |
|---|---|---|
| Diverging bar | Above/below target or median | No clear reference point |
| Lollipop | Deviation from baseline; cleaner than bars | Audience expects standard bars |
| Line + reference | Trend deviation from target over time | Multiple baselines |
| Gauge | Single KPI vs. target (dashboards, KPI cards) | More than 3 gauges on a page |
When an AI tool generates a chart, evaluate before accepting. Adapted from the Copilot Design Automation framework:
| Step | Question | Action |
|---|---|---|
| Clarify | "What question am I answering?" | Write the question as a sentence before looking at the chart |
| Summarize | "The AI chose a [chart type]. Does it answer the question?" | Name the chart type and check it against Module 1 |
| Act | Accept, modify, or override | Accept if story-intent matches. Override if wrong goal group. Modify if right type but wrong emphasis |
| Reflect | "Why did I accept/override? What principle guided me?" | Document the rationale; builds judgment over time |
| AI Chose | But Your Goal Is | Override To | Rationale |
|---|---|---|---|
| Pie (8 slices) | Compare items | Horizontal bar, sorted | Pie with 8+ slices is unreadable |
| Clustered bar | Show trend | Line chart | Time series needs continuity |
| 3D column | Anything | 2D bar or line | 3D adds no information, distorts perception |
| Stacked bar | Compare individual series | Grouped bar or small multiples | Stacking hides individual values |
| Donut | Show precise values | Table with conditional formatting | Donut communicates rough proportion only |
| Line (20 series) | Compare trends | Small multiples or highlight 3 key series | Too many lines become spaghetti |
| Map | Compare values | Bar chart sorted by value | Maps encode position; bars encode length (more precise) |
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.
| Slot | Role | Typical Chart |
|---|---|---|
| 1-3 | KPI cards | Card, gauge, or sparkline |
| 4 | Hero chart | The main visual that carries the story |
| 5 | Supporting chart | A second angle on the same story |
A sixth visual is a table for drill-down, placed below the fold or on demand.
| Audience | Visuals | Time Budget | Design Priority |
|---|---|---|---|
| Executive | 3-5 | 30 seconds | KPIs first, hero chart, one action item |
| Manager | 5-8 | 2 minutes | Filters, comparison charts, trend lines |
| Analyst | 8-15 | Unlimited | Detail tables, drill-through, cross-filters |
| General | 3-4 | 1 minute | Annotated hero chart, simple narrative |
Lessons from building production SVG dashboards:
Every card in an SVG dashboard uses one function:
panel({ x, y, w, h, title, subtitle, color })
Constants: radius 16, fill #0f172a (dark slate), stroke #334155, title at y+32. One primitive, every card looks the same. Visual uniformity builds trust.
| Use | Hex | Name |
|---|---|---|
| Card background | #0f172a | Slate 950 |
| Card stroke | #334155 | Slate 700 |
| Primary text | #ffffff | White |
| Secondary text | #cbd5e1 | Slate 300 |
| Muted text | #94a3b8 | Slate 400 |
| Tertiary text | #64748b | Slate 500 |
| Positive/complete | #22c55e | Green 500 |
| Warning/pending | #f59e0b | Amber 500 |
| Error/critical | #ef4444 | Red 500 |
| Info/accent | #3b82f6 | Blue 500 |
| Purple accent | #8b5cf6 | Violet 500 |
| Anti-pattern | Fix |
|---|---|
| Pie arcs computed at wrong center coordinates | Calculate center from card y + card height, not absolute y |
| Incremental y-shifts corrupting multi-row layouts | Define each row's y from scratch (row N y = header + sum of previous row heights + gaps) |
| Labels bleeding outside card boundaries | Max y of any element = card y + card height - margin |
| Different font sizes per card | One title size (20px), one body size (13px), one muted size (11px) across all cards |
| Inline coordinate math | Define constants at the top: ROW_Y[], CARD_W, CARD_H, GAP |
Use these galleries to browse real examples when Module 1's table isn't enough. The galleries are the living source of truth; this skill is the decision framework.
| Gallery | URL | Organized By | Best For |
|---|---|---|---|
| FT Visual Vocabulary | https://ft-interactive.github.io/visual-vocabulary/ | Communication goal | Choosing chart type by what you want to say |
| From Data to Viz | https://www.data-to-viz.com/ | Data type and relationship | Choosing chart type by what your data looks like |
| Data Viz Catalogue | https://datavizcatalogue.com/ | Chart function | Understanding individual chart strengths/weaknesses |
| Vega-Lite Examples | https://vega.github.io/vega-lite/examples/ | Chart type | Declarative spec examples for programmatic generation |
| Storytelling with Data | https://community.storytellingwithdata.com/exercises | Story challenge | Real-world "makeover" exercises with before/after |
Run this algorithm when choosing charts for a dashboard or report:
1. Write the Big Idea sentence
(audience + action + evidence)
If you can't write it, the analysis isn't done.
2. List the 3-5 questions the dashboard 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 5)
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
(delegate to dashboard-design for layout patterns)
6. Design each chart:
(delegate to data-visualization for color,
annotation, decluttering)
data-visualization -- color theory, annotation patterns, decluttering rules. Use after this skill selects chart types.data-storytelling -- three-act narrative structure, audience-first framing, Big Idea worksheet. Use before this skill to define the story.dashboard-design -- layout patterns, KPI card design, filter architecture. Use after this skill to arrange the visuals.svg-dashboard-composition -- SVG composition mechanics, panel primitives, coordinate systems. Use when the output format is SVG.chart-interpretation -- reading and evaluating existing charts. The inverse of this skill.