Chart Vocabulary
Select chart types by analytical job—not visual novelty.
Shared Knowledge Gate
Before selecting chart encodings or types for consequential analysis, consult
scout-knowledge-base for
relevant prior decisions, failure modes, procedures, and gotchas. Read only
records whose signals or preconditions match the analysis, and treat them as
context rather than authority. If unavailable, state that once and continue with
the current evidence; do not create a local fallback while selecting a chart.
Chart selection matrix
| Task |
Prefer |
Avoid |
| Compare categories |
Bar, grouped bar, lollipop |
Pie with many slices |
| Compare values over time |
Line, area, slope, sparkline |
Unsorted bars for dense time series |
| Part-to-whole with few categories |
Donut, stacked bar |
Donut with many small categories |
| Show relationship |
Scatter, regression, connected scatter |
Dual-axis line charts |
| Show distribution |
Histogram, density, boxplot, violin |
Average-only bar charts |
| Show matrix intensity |
Heatmap |
3D surface charts |
| Show progress to target |
KPI card, bullet chart |
Gauge-like decoration |
| Explain additive drivers |
Waterfall |
Pie or stacked area |
| Show schedule or duration |
Gantt |
Calendar screenshots |
| Show geography |
Map, choropleth |
Map when location is not the point |
Flint encoding reminders
Common Flint channels:
| Chart type |
Required channels |
| Bar Chart |
x, y |
| Grouped Bar Chart |
x, y, group |
| Line Chart |
x, y; optional color, detail |
| Scatter Plot |
x, y; optional color, size, shape |
| Heatmap |
x, y, color |
| Histogram |
x; optional color |
| Donut Chart |
size, color |
| Waterfall Chart |
x, y; optional color |
| KPI Card |
metric, value; optional goal |
| Area Chart |
x, y; optional color |
| Lollipop Chart |
x, y; optional color |
Call list_chart_types when uncertain. Flint's available chart set is runtime-specific.
Semantic type guidance
Use semantic types to make intent explicit:
| Data meaning |
Example semantic type |
| Category labels |
Category |
| Dates, months, quarters |
Time |
| Counts and quantities |
Quantity |
| Money |
Currency |
| Percent values |
Percentage |
| Ratings or scores |
Score |
| Countries or regions |
Country, Region |
Review questions
Before rendering:
- What is the comparison?
- Is the visual sorted or sequenced correctly?
- Will the legend be readable?
- Are units explicit?
- Does the chosen chart type make the Big Idea easier to see?
Label strategy
Choose the label plan with the chart type. Do not bolt labels on after rendering.
| Visual shape |
Label strategy |
| Single-series vertical bar |
Value labels above bars only when there is headroom; otherwise inside with contrast text or omit. |
| Single-series horizontal bar |
Value labels outside the bar end when space allows; otherwise inside the bar with contrast text. |
| Grouped bar |
Prefer a legend and axis values; use tooltips or selective labels instead of labeling every bar. |
| Stacked bar |
Label totals or the most important segment only; labeling every segment usually collides. |
| Line |
Label endpoints or annotated inflection points; avoid labeling every point. |
| Heatmap or matrix |
Use theme-derived intensity plus optional direct values; ensure text contrast holds at the darkest and lightest cells. |
| KPI or gauge |
Make the primary number dominant; keep range labels and target markers secondary. |
| Small multiples or sparklines |
Label panel names and endpoints, not every point. |
Theme fit
When choosing a chart type for a themed gallery or dashboard:
- Prefer chart types that survive both brand palettes and colorblind-safe palettes.
- Avoid designs that depend on red-vs-green distinction unless there is also text, position, pattern, or sign.
- For table/matrix visuals, theme headers, heatmap cells, totals, row labels, borders, and helper text together.
- For custom Canvas/SVG renderers, theme all marks and helper text through shared tokens. A themed page with an unthemed custom chart is visually broken.
Anti-patterns
- Use a donut chart for more than five or six categories.
- Use a line chart for unordered categories.
- Use a heatmap when exact value comparison matters.
- Use color for categories when color should encode intensity.
- Use size and color together unless both encodings earn their complexity.
- Add value labels to dense, grouped, or stacked charts without proving that the labels do not overlap.
1---2name: chart-vocabulary-23description: Choose appropriate chart types and Flint encodings from the analytical task, data shape, and reader goal. Use when selecting among bar, line, scatter, heatmap, histogram, KPI, waterfall, area, donut, and other Flint chart templates.4---56# Chart Vocabulary78Select chart types by analytical job—not visual novelty.910## Shared Knowledge Gate1112Before selecting chart encodings or types for consequential analysis, consult13[`scout-knowledge-base`](../../skills/scout-knowledge-base/SKILL.md) for14relevant prior decisions, failure modes, procedures, and gotchas. Read only15records whose signals or preconditions match the analysis, and treat them as16context rather than authority. If unavailable, state that once and continue with17the current evidence; do not create a local fallback while selecting a chart.1819## Chart selection matrix2021| Task | Prefer | Avoid |22| --- | --- | --- |23| Compare categories | Bar, grouped bar, lollipop | Pie with many slices |24| Compare values over time | Line, area, slope, sparkline | Unsorted bars for dense time series |25| Part-to-whole with few categories | Donut, stacked bar | Donut with many small categories |26| Show relationship | Scatter, regression, connected scatter | Dual-axis line charts |27| Show distribution | Histogram, density, boxplot, violin | Average-only bar charts |28| Show matrix intensity | Heatmap | 3D surface charts |29| Show progress to target | KPI card, bullet chart | Gauge-like decoration |30| Explain additive drivers | Waterfall | Pie or stacked area |31| Show schedule or duration | Gantt | Calendar screenshots |32| Show geography | Map, choropleth | Map when location is not the point |3334## Flint encoding reminders3536Common Flint channels:3738| Chart type | Required channels |39| --- | --- |40| Bar Chart | `x`, `y` |41| Grouped Bar Chart | `x`, `y`, `group` |42| Line Chart | `x`, `y`; optional `color`, `detail` |43| Scatter Plot | `x`, `y`; optional `color`, `size`, `shape` |44| Heatmap | `x`, `y`, `color` |45| Histogram | `x`; optional `color` |46| Donut Chart | `size`, `color` |47| Waterfall Chart | `x`, `y`; optional `color` |48| KPI Card | `metric`, `value`; optional `goal` |49| Area Chart | `x`, `y`; optional `color` |50| Lollipop Chart | `x`, `y`; optional `color` |5152Call `list_chart_types` when uncertain. Flint's available chart set is runtime-specific.5354## Semantic type guidance5556Use semantic types to make intent explicit:5758| Data meaning | Example semantic type |59| --- | --- |60| Category labels | `Category` |61| Dates, months, quarters | `Time` |62| Counts and quantities | `Quantity` |63| Money | `Currency` |64| Percent values | `Percentage` |65| Ratings or scores | `Score` |66| Countries or regions | `Country`, `Region` |6768## Review questions6970Before rendering:71721. What is the comparison?732. Is the visual sorted or sequenced correctly?743. Will the legend be readable?754. Are units explicit?765. Does the chosen chart type make the Big Idea easier to see?7778## Label strategy7980Choose the label plan with the chart type. Do not bolt labels on after rendering.8182| Visual shape | Label strategy |83| --- | --- |84| Single-series vertical bar | Value labels above bars only when there is headroom; otherwise inside with contrast text or omit. |85| Single-series horizontal bar | Value labels outside the bar end when space allows; otherwise inside the bar with contrast text. |86| Grouped bar | Prefer a legend and axis values; use tooltips or selective labels instead of labeling every bar. |87| Stacked bar | Label totals or the most important segment only; labeling every segment usually collides. |88| Line | Label endpoints or annotated inflection points; avoid labeling every point. |89| Heatmap or matrix | Use theme-derived intensity plus optional direct values; ensure text contrast holds at the darkest and lightest cells. |90| KPI or gauge | Make the primary number dominant; keep range labels and target markers secondary. |91| Small multiples or sparklines | Label panel names and endpoints, not every point. |9293## Theme fit9495When choosing a chart type for a themed gallery or dashboard:9697- Prefer chart types that survive both brand palettes and colorblind-safe palettes.98- Avoid designs that depend on red-vs-green distinction unless there is also text, position, pattern, or sign.99- For table/matrix visuals, theme headers, heatmap cells, totals, row labels, borders, and helper text together.100- For custom Canvas/SVG renderers, theme all marks and helper text through shared tokens. A themed page with an unthemed custom chart is visually broken.101102## Anti-patterns103104- Use a donut chart for more than five or six categories.105- Use a line chart for unordered categories.106- Use a heatmap when exact value comparison matters.107- Use color for categories when color should encode intensity.108- Use size and color together unless both encodings earn their complexity.109- Add value labels to dense, grouped, or stacked charts without proving that the labels do not overlap.
fabioc-aloha