# Choosing a form

First write down the one fact the chart should show, with its number. Then pick the form that shows that fact most directly.

## Decision table

Generated from each component's metadata. Use only names in this table.

| The data's job | Component | Level | Use it when | Pick something else when |
|---|---|---|---|---|
| State one number or one fact | [big-number](https://insightcharts.dev/llms/big-number.md) | atom | A single headline figure, or a row of three or four key numbers. Always give it context: a comparison, a denominator or a period. | Showing a number with no comparison; using a gauge or a one-slice donut for the same job. |
| State one number or one fact | [data-table](https://insightcharts.dev/llms/data-table.md) | atom | When readers need to look up exact values, or compare a handful of entities across several measures with different units. Sort it by the column the caption refers to and highlight the row it names. | Showing a trend or a single comparison (use `line-chart` or `bar-chart`); more than about 7 columns or 30 rows without `maxHeight`. |
| State one number or one fact | [delta](https://insightcharts.dev/llms/delta.md) | atom | Next to a figure, in a sentence, a table cell or a tile, to say how much it changed and against what. Set `upIsGood: false` for measures where a fall is the good news (churn, emissions, wait times). | Standing alone as the main figure (use `big-number` or `stat-tile`, which include a delta). Do not omit the baseline label unless the surrounding text names it. |
| State one number or one fact | [icon-stat](https://insightcharts.dev/llms/icon-stat.md) | atom | A single proportion that is easier to read as people or units than as a percentage: 1 in 4, 3 in 10, 37 of 100. Round to a small denominator first. | Comparing several proportions (use `bar-chart`), precise percentages (use `big-number`), or fractions that need more than 100 units. |
| State one number or one fact | [legend-key](https://insightcharts.dev/llms/legend-key.md) | atom | When several charts (small multiples, a map and a bar chart, a dashboard row) share one colour encoding, show the key once above them and turn their own legends off. | A single chart: its built-in legend or, better, direct labels already do this. Do not list more than eight categories. |
| State one number or one fact | [progress-meter](https://insightcharts.dev/llms/progress-meter.md) | atom | Progress toward a goal, a quota or a capacity: funds raised, budget spent, share of a target reached. Stack several with `size: "sm"` to compare progress across a few items. | Comparing more than a handful of items (use `bar-chart`), anything without a meaningful end point (use `big-number`), or a gauge dial. |
| State one number or one fact | [stat-tile](https://insightcharts.dev/llms/stat-tile.md) | atom | Dashboard grids and KPI rows of three to six figures, each needing its own change indicator or sparkline. Give every tile a delta or a context line. | The single number a story leads with (use `big-number` with `size: "hero"`). Do not put a full chart with axes in the trend slot. |
| Compare values across categories | [arrow-chart](https://insightcharts.dev/llms/arrow-chart.md) | atom | Shifts between two moments across up to about 25 categories when some rise and some fall: swings between elections, before / after a policy. | When both levels matter more than the direction (use dumbbell-chart); more than two points in time (use slope-chart or line-chart); a single value per category (use bar-chart). |
| Compare values across categories | [bar-chart](https://insightcharts.dev/llms/bar-chart.md) | atom | Ranking or comparing up to about 20 categories; grouped for a few series, stacked when the total and its composition both matter. | Change over many time points (use line-chart); two values per category (use dumbbell-chart); more than about 5 stacked segments. |
| Compare values across categories | [bullet-chart](https://insightcharts.dev/llms/bullet-chart.md) | atom | Progress against a target or budget for one to about 10 measures, including measures in different units (`scale: "independent"`); a compact scorecard instead of a row of gauges. | No target or thresholds to compare with (use bar-chart); a single share of a whole (use progress-meter); change over time (use line-chart). |
| Compare values across categories | [diverging-bar-chart](https://insightcharts.dev/llms/diverging-bar-chart.md) | atom | Values that can be above or below zero (net change, balance, deviation from average); survey scales where the split between the two sides matters; two opposed groups back to back. | Values that are all positive (use bar-chart); parts that do not have a natural two-sided order (use a stacked bar-chart); change between two dates (use arrow-chart or dumbbell-chart). |
| Compare values across categories | [dumbbell-chart](https://insightcharts.dev/llms/dumbbell-chart.md) | atom | Before / after or group A / group B across up to about 20 categories, when the size of the difference is what the reader needs. | A single value per category (use lollipop-chart or bar-chart); when the direction of change matters more than the two levels (use arrow-chart); more than two points in time (use slope-chart or line-chart). |
| Compare values across categories | [heatmap](https://insightcharts.dev/llms/heatmap.md) | atom | Finding patterns across two dimensions at once: hour by weekday, cohort by month, product by region. Good when there are too many series for lines or bars and the overall pattern matters more than exact values. | Precise comparison of a few values (use bar-chart); a single series over time (use line-chart); a daily value across a year (use calendar-heatmap). |
| Compare values across categories | [lollipop-chart](https://insightcharts.dev/llms/lollipop-chart.md) | atom | Rankings of 8 to 30 categories where bars would be too heavy; dot plot mode when the values sit far from zero and the differences between them matter, or to compare a few series per row. | Fewer than about 6 categories or part-to-whole stacks (use bar-chart); exactly two values per row where the difference between them matters (use dumbbell-chart); change over time (use line-chart). |
| Compare values across categories | [pictogram-chart](https://insightcharts.dev/llms/pictogram-chart.md) | atom | A few categories (2 to 6) of countable things, people, homes, vehicles, where making the quantity concrete matters more than reading precise values. | More than about 8 categories or values that need precise comparison (use bar-chart); a share of one whole (use waffle-chart); values that would need more than about 60 icons in a row (raise `unit`, or use bar-chart). |
| Show change over time | [area-chart](https://insightcharts.dev/llms/area-chart.md) | atom | A volume or cumulative quantity over time where the filled magnitude matters; stacked when the total and its composition both matter; percent when only the mix matters; stream for the changing mix of many series over a long period. | Comparing the trajectories of several series against each other (use line-chart: only the bottom band of a stack has a flat baseline); a few time points (use bar-chart with stack); more than about 6 bands. |
| Show change over time | [bump-chart](https://insightcharts.dev/llms/bump-chart.md) | atom | League tables over 3 to about 15 periods for up to about 12 entities, when the order and the changes in rank are what matter and the underlying values differ too much (or too little) to share an axis. | When the size of the values matters (use line-chart); only two periods (use slope-chart); a single ranking (use bar-chart or lollipop-chart). |
| Show change over time | [calendar-heatmap](https://insightcharts.dev/llms/calendar-heatmap.md) | atom | Daily data over months or years where weekly rhythm, seasonality, streaks and gaps matter: activity, sales, incidents, habits. | Reading the trend or exact values (use line-chart); fewer than about three months of days (use bar-chart); a non-daily grain such as hour by weekday (use heatmap). |
| Show change over time | [line-chart](https://insightcharts.dev/llms/line-chart.md) | atom | Trends over time with roughly 5 or more points; comparing the trajectories of a few series; one highlighted series against many context series. | Unordered categories (use bar-chart); only two time points (use slope-chart); more than about 6 equally important lines (use small-multiples). |
| Show change over time | [radial-bar-chart](https://insightcharts.dev/llms/radial-bar-chart.md) | atom | Only when the dimension is cyclical and the wrap-around matters: activity by hour of day, seasonality by month, wind by compass direction. The first category is placed at 12 o'clock. | Any dimension that does not wrap around: categories, rankings, years (use bar-chart); precise comparison of values, since bars further out look bigger (use bar-chart or line-chart); more than about 3 stacked series. |
| Show change over time | [slope-chart](https://insightcharts.dev/llms/slope-chart.md) | atom | Before / after for 3 to about 15 entities when the change in level and in ordering both matter; pair with `highlight` to emphasise one line. | Five or more time points (use line-chart); when only the ordering matters (use bump-chart); when only the size of each gap matters (use dumbbell-chart or arrow-chart). |
| Show change over time | [small-multiples](https://insightcharts.dev/llms/small-multiples.md) | atom | The same measure for 4 to about 24 entities when one chart would have too many overlapping lines; pair with `highlight` to pick out one panel, or `context` to show every other line faintly behind each. | Three or fewer series (use line-chart with direct labels); when exact comparison between two entities matters most (use line-chart with `highlight`); a single value per entity (use bar-chart). |
| Show change over time | [sparkline](https://insightcharts.dev/llms/sparkline.md) | atom | Showing the recent history of a number inside a stat tile, a table cell or a sentence, where the shape of the trend matters and exact values do not. | Anything the reader must read values from or compare across series (use line-chart); fewer than about 5 points (state the change in words or use big-number with a delta). |
| Show change over time | [timeline-chart](https://insightcharts.dev/llms/timeline-chart.md) | atom | When things happened and how long they lasted: project phases, terms of office, product launches, the sequence of events in a story. Mix spans (start and end) with point milestones (start only). | A measured value changing over time (use line-chart, with annotations for the events); more than about 40 items (filter, or split into several timelines); durations to be compared precisely with no interest in when (use bar-chart). |
| Show how values are spread | [beeswarm-chart](https://insightcharts.dev/llms/beeswarm-chart.md) | atom | Showing a distribution while keeping every individual visible: 30 to about 2,000 named things (countries, players, schools), optionally in a few rows by group, with one or two highlighted. | More than about 2,000 rows or when only the summary matters (use histogram or box-plot); many groups with few rows each (use strip-plot); two numeric measures (use scatter-chart). |
| Show how values are spread | [box-plot](https://insightcharts.dev/llms/box-plot.md) | atom | Comparing the centre and spread of a numeric value across several groups, especially with many rows per group and an audience comfortable with quartiles. | A general audience or fewer than about 20 rows per group (use strip-plot or beeswarm-chart, which show the observations themselves); one group whose shape matters, such as two peaks, which a box hides (use histogram). |
| Show how values are spread | [histogram](https://insightcharts.dev/llms/histogram.md) | atom | Showing the shape of a distribution for one numeric variable with roughly 50 rows or more: its centre, spread, skew, gaps and multiple peaks. | Comparing distributions across several groups (use box-plot or beeswarm-chart); under about 50 rows, where every observation can be shown (use strip-plot or beeswarm-chart); counts by category (use bar-chart). |
| Show how values are spread | [strip-plot](https://insightcharts.dev/llms/strip-plot.md) | atom | Comparing the spread and clustering of a numeric value across 2 to about 15 categories when there are few enough observations to show each one; many rows with few to a few hundred observations each. | A single group where the shape matters (use histogram or beeswarm-chart); when individual points must be identifiable or coloured (use beeswarm-chart); when only quartiles matter (use box-plot). |
| Show how a total divides | [donut-chart](https://insightcharts.dev/llms/donut-chart.md) | atom | A simple composition with one dominant part, or one part the title is about, where the total itself is worth printing in the centre. | More than 5 categories or parts of similar size that must be ranked (use bar-chart); a single figure (use big-number); composition compared across groups or time (use bar-chart with stack "percent"); a compact card (use segmented-bar). |
| Show how a total divides | [segmented-bar](https://insightcharts.dev/llms/segmented-bar.md) | atom | A compact part-to-whole for cards, table cells and stat rows: budget split, device mix, vote share. The legend carries names in block order. | Comparing compositions across several groups (use bar-chart with stack "percent"); more than about 6 parts or many slivers (use bar-chart); when the reader should count units (use waffle-chart). |
| Show how a total divides | [treemap](https://insightcharts.dev/llms/treemap.md) | atom | Many parts (10 to 100) of very different sizes, or a two-level hierarchy, where the reader needs the largest parts rather than exact comparison: budgets, market capitalisation, export baskets. | Fewer than about 6 parts or values that need precise comparison (use bar-chart); 2 to 5 parts (use donut-chart or segmented-bar); values that can be negative (use bar-chart); change over time (use line-chart). |
| Show how a total divides | [waffle-chart](https://insightcharts.dev/llms/waffle-chart.md) | atom | One share ("37 in every 100") or a handful of categories that add up to a whole, where the reader should be able to count the units. | Comparing shares across several groups (use bar-chart with stack "percent"); more than about 6 categories or shares under 1% (use bar-chart); a compact inline part-to-whole (use segmented-bar). |
| Show how two measures relate | [scatter-chart](https://insightcharts.dev/llms/scatter-chart.md) | atom | Showing whether and how two measures move together, spotting clusters and outliers, and placing named entities in a two-dimensional space (with quadrant lines via `annotations`). | A measure over time (use line-chart); one numeric measure by category (use beeswarm-chart or strip-plot); fewer than about 8 points (use bar-chart or a table); more than 4 colour groups (facet with small-multiples). |
| Show movement between stages or groups | [funnel-chart](https://insightcharts.dev/llms/funnel-chart.md) | atom | A strict sequence where each stage is a subset of the one before: sign-up flows, hiring pipelines, sales stages, applications to admissions. 3 to 7 stages. | Stages that are not sequential subsets, or categories with no order (use bar-chart); flows that split to several destinations (use sankey-chart); conversion tracked over time (use line-chart). |
| Show movement between stages or groups | [sankey-chart](https://insightcharts.dev/llms/sankey-chart.md) | atom | Where things come from and where they go: energy from fuel to end use, budget from revenue to spending, users from channel to outcome. Works best with 2 to 4 stages and up to about 20 nodes. | A single sequence of steps with drop-off (use funnel-chart); comparing a few totals (use bar-chart); flows that loop back (cycles cannot be drawn and are dropped); more than about 40 links. |
| Show values by place | [choropleth-map](https://insightcharts.dev/llms/choropleth-map.md) | atom | A rate, share or per-capita figure that varies by place, where the geographic pattern (a north-south divide, a cluster) is what the reader needs to see. Use a diverging scale for change or for values either side of a meaningful midpoint. | Raw counts, which mostly map population (normalise first, or use bar-chart); ranking regions precisely (use bar-chart); a handful of regions with no spatial pattern (use bar-chart); regions so different in size that small ones vanish (use a tile-grid GeoJSON). |
| Draw a poster graphic | [arc-diagram](https://insightcharts.dev/llms/arc-diagram.md) | atom | Connections among up to about 20 entities that have a meaningful order (stops on a line, chapters, age groups, teams by size): trips between stations, trade between neighbours, characters sharing scenes. | Flows with a direction through stages (use sankey-chart); one source splitting into parts (use fan-flow); a full matrix of every pair where exact values matter (use heatmap); more than about 20 entities or 60 connections (use heatmap). |
| Draw a poster graphic | [block-bar](https://insightcharts.dev/llms/block-bar.md) | atom | A short series or ranking that should read as a bold graphic with no axis: ticket sales in each of six years, two paired measures in five regions. Add `detail` for a second small figure above each bar and `marker` for an event between two bars. | More than 12 bars, more than two series or stacked parts (use bar-chart); negative values (use diverging-bar-chart); a long time series (use line-chart); values that differ by more than about 50 times, where the short bars vanish (use proportional-area). |
| Draw a poster graphic | [bubble-network](https://insightcharts.dev/llms/bubble-network.md) | atom | Showing which of up to about 12 named things are connected, and how big each is: trade blocs, route maps between hubs, partnerships, shared ownership. Give `x` and `y` to place the circles by hand, for example roughly geographically. | Flows with magnitudes between stages (use sankey-chart); more than about 12 circles or a dense web of links (use heatmap as a matrix, or data-table); comparison of the sizes alone (use bar-chart or circle-pack). |
| Draw a poster graphic | [bubble-scale](https://insightcharts.dev/llms/bubble-scale.md) | atom | A poster answer to "where does each one sit on this scale, and how big is it": 5 to about 40 named things with a rate or score (the scale) and a magnitude (the area), such as import dependency against share of demand. | Two measures that should be read against each other on two axes (use scatter-chart); one measure only (use beeswarm-chart or strip-plot); precise comparison of the sizes (use bar-chart); more than about 60 rows (use beeswarm-chart). |
| Draw a poster graphic | [circle-pack](https://insightcharts.dev/llms/circle-pack.md) | atom | A poster view of 5 to about 60 parts of very different sizes where the reader should see the largest ones and their rough proportions at once: budgets by programme, emissions by source, users by product. One level of grouping is supported. | Values that need precise comparison (use bar-chart, where bars share a baseline); parts that must visibly add up to a whole (use treemap or waffle-chart); more than about 80 parts (use treemap); negative values (use diverging-bar-chart). |
| Draw a poster graphic | [curve-rank](https://insightcharts.dev/llms/curve-rank.md) | atom | Two different measures of the same 4 to about 15 entities, when the point is how standing on one relates to standing on the other: price against sales, staff against output, cost against usage. Each side has its own scale, stated in its heading. | The same measure at two moments (use slope-chart); ranks across many periods (use bump-chart); more than about 15 entities or a statistical relationship (use scatter-chart); exact comparison on one measure (use bar-chart). |
| Draw a poster graphic | [fan-flow](https://insightcharts.dev/llms/fan-flow.md) | atom | One total divided among 4 to about 14 destinations (or collected from that many origins, with `direction: "in"`) when the picture of the split is the point: where a budget goes, what a day's water is used for, which sources feed one total. | Flows with more than one stage or several sources (use sankey-chart); precise comparison of the parts (use bar-chart); 2 to 4 parts (use segmented-bar or donut-chart); values that can be negative (use bar-chart). |
| Draw a poster graphic | [glyph-table](https://insightcharts.dev/llms/glyph-table.md) | atom | Comparing 3 to about 12 entities across 2 to 5 measures with different units, when the table should read as a graphic: profiles of products, cities, teams or species. Pair it with curve-rank by passing both the same `order`. | Looking up many exact values, sorting, or more than about 12 rows (use data-table); one measure across entities (use bar-chart or pictogram-chart); a trend over time (use line-chart or small-multiples). |
| Draw a poster graphic | [icon-array-grid](https://insightcharts.dev/llms/icon-array-grid.md) | atom | Counts of up to about 150 in 4 to 24 categories, especially rates per 100 or per 1,000: cars per 100 households in 12 districts. Set `total` so every tile shows the same full array with the uncounted icons as ghosts. | Counts in the thousands (use unit-blocks); two to six categories where one row of icons each is enough (use pictogram-chart); values that need precise comparison or ranking (use block-bar or bar-chart); one share of one whole (use waffle-chart). |
| Draw a poster graphic | [nested-shares](https://insightcharts.dev/llms/nested-shares.md) | atom | How much of one whole something was at 2 to 8 dates or in 2 to 8 categories, when the growth of a share is the point: bicycles made 4% of trips in 2005 and 27% in 2025. | Shares that are parts of each other and should add up (use waffle-chart or treemap); more than 8 items or precise reading of a trend (use line-chart); shares within a point or two of each other, where outlines coincide (use block-bar). |
| Draw a poster graphic | [orbit-chart](https://insightcharts.dev/llms/orbit-chart.md) | atom | A designed alternative to a table for 6 to about 40 named things grouped by distance, level or era from one centre: suppliers by tier, moons by planet-distance band, releases by decade, stakeholders by closeness. One item can be highlighted. | A numeric distance that must be read exactly (use strip-plot or scatter-chart); comparison of the dot values (use bar-chart); more than about 6 rings or 40 items (use data-table); hierarchy with sizes that add up (use treemap or circle-pack). |
| Draw a poster graphic | [pill-rank](https://insightcharts.dev/llms/pill-rank.md) | atom | A poster ranking of 4 to about 20 named things where the order and the overall silhouette matter more than fine differences: top cities, largest employers, league tables, with one row highlighted and optional reference rows set apart below. | Precise comparison of values (use bar-chart, where bars share a baseline); negative values (use diverging-bar-chart); change in rank over time (use bump-chart); more than about 25 rows (use data-table). |
| Draw a poster graphic | [proportional-area](https://insightcharts.dev/llms/proportional-area.md) | atom | A few quantities that differ a lot (2 times to 100 times), where the reader should feel the difference in size: lake areas, budgets, market sizes. Nest them to show one quantity inside another. | Values within about 30% of each other, where areas look the same (use block-bar or bar-chart); more than 8 values (use treemap or bar-chart); parts of one whole (use treemap or waffle-chart); negative values. |
| Draw a poster graphic | [radial-spokes](https://insightcharts.dev/llms/radial-spokes.md) | atom | A poster of 4 to 12 effects, causes or attributes of one subject, which sits in the centre as an icon or a short label: what a household's energy goes on, the side effects of one drug, the scores of one product. | Precise comparison or a ranking (use bar-chart or pill-rank); a dimension that is a cycle, such as hours or months (use radial-bar-chart); more than 12 rows (use bar-chart); several subjects compared on the same attributes (use small-multiples or heatmap). |
| Draw a poster graphic | [ribbon-chart](https://insightcharts.dev/llms/ribbon-chart.md) | atom | 4 to 8 entities over 4 to 10 periods when both the size of each and the changing order matter, and the graphic should read as one flowing form: market shares, harvests, medal tables, budget lines. | Totals that matter more than order, or a smooth centred stream of many periods (use area-chart, which has stacked and stream modes); rank alone (use bump-chart); more than 8 entities or 10 periods (use line-chart or small-multiples); values that can be negative (use line-chart). |
| Draw a poster graphic | [scale-ladder](https://insightcharts.dev/llms/scale-ladder.md) | atom | Answering how deep, how high, how hot, how old or how far each of 4 to about 20 things is on one shared scale, when the reader needs the positions themselves: depths, altitudes, temperatures, ages, distances. Use `zones` to name ranges along the scale. | Comparing sizes rather than positions (use bar-chart or lollipop-chart); events with start and end dates (use timeline-chart); a distribution of many unnamed values (use strip-plot or histogram). |
| Draw a poster graphic | [shape-fill](https://insightcharts.dev/llms/shape-fill.md) | atom | One to six shares of a full amount where the object itself says what is measured: how full a reservoir is, how charged a fleet is, what share of homes have a heat pump. | The fill height only approximates the share, because an irregular silhouette holds less area at its narrow end, so the number must always stay printed; for values to be compared precisely use block-bar or bar-chart, for a counted share use waffle-chart, for a compact inline meter use progress-meter. |
| Draw a poster graphic | [stat-circles](https://insightcharts.dev/llms/stat-circles.md) | atom | The poster way to show two to six related magnitudes whose rough proportion is the point: kilograms per person in three countries, the same quantity in three years, a total and its parts set side by side. | More than six values or values that need precise comparison (use bar-chart); a single number (use big-number); many circles of one whole (use circle-pack); values close together, where areas look the same (use bar-chart or dumbbell-chart). |
| Draw a poster graphic | [unit-blocks](https://insightcharts.dev/llms/unit-blocks.md) | atom | Large counts of people or things in 2 to 12 groups, where the reader should see the crowd itself: 20,350 marathon finishers by age group, one figure per 10 runners. | Precise comparison of close values (use block-bar or bar-chart); fewer than about 30 icons per group (use pictogram-chart or icon-array-grid); shares of one whole (use waffle-chart). |
| Draw a poster graphic | [poster](https://insightcharts.dev/llms/poster.md) | molecule | Use it as the outer frame of any infographic: one dominant graphic with a few supporting panels, on a painted ground. Give it a poster theme (`noir`, `magenta`, `dusk`, `paper`, `ocean`, `forest`, `blueprint`, `sunrise`) and put a chart or figure spec in each panel. Put the one fact in `title` and keep panel headings short. It reflows to one column under 600px. | Long reading text or more than about six panels (use `report-page` or `visual-essay`). A single fact at a fixed social size (use `social-card`). Charts that need axes, gridlines and dense labels to be read, because a poster ground suits large flat marks with their values printed on them. |
| Lay out a whole poster | [atlas-poster](https://insightcharts.dev/llms/atlas-poster.md) | template | Use it when one subject has many small facts of different kinds (shares, places, a trend, a change, a ranking, a map) and none of them should dominate: a crop, an industry, a service, a country's internet. Fill at least eight regions. Give every panel a short heading that states its one number. Every region is optional, and each band shares its width among the panels that are present. | One dominant fact or graphic (use `count-poster`, `flow-poster` or `ranking-poster`). The same measures across several entities (use `matrix-poster`). Fewer than six panels (use `poster` and place them yourself). A phone-first piece: the spread becomes one long column under 600px. |
| Lay out a whole poster | [count-poster](https://insightcharts.dev/llms/count-poster.md) | template | Use it when the subject is a large count of people or things in 2 to 6 groups and the reader should see the crowd: pupils by stage, trees planted by species, vehicles built by model. Give `hero` the groups and `reference` one to three quantities to compare them with. Both bands use the same `unit`, `icon` and icon size, so their areas compare. State the total in the title. | Counts under a few hundred (use `pictogram-chart` in a `poster`). Shares of one whole as the main point (use `waffle-chart` or `treemap`). A ranking of many named things (use `ranking-poster`). A flow from sources to destinations (use `flow-poster`). |
| Lay out a whole poster | [flow-poster](https://insightcharts.dev/llms/flow-poster.md) | template | Use it when one producer leads and the reader should follow its output: ports and the buyers of one port's catch, regions and the users of one region's electricity, terminals and the routes out of the largest. Give `producers` 4 to 10 rows, `flow` 4 to 12 destinations of the leading producer, and `scale` the same destinations with a share (position) and a size. Keep the destination names identical in `flow` and `scale` so `linked` can join them. | Flows through more than one stage or between many sources and many destinations (use `sankey-chart` in a `poster`). A count of people or things (use `count-poster`). Many measures of the same entities (use `matrix-poster`). |
| Lay out a whole poster | [matrix-poster](https://insightcharts.dev/llms/matrix-poster.md) | template | Use it for profiles of a handful of comparable things with measures in different units: cities, species, products, stations, teams. Pass one row per entity with every measure in it. Put the two measures whose relationship matters in `curve` and the rest in `columns`, choosing a counted glyph (`dots`, `blocks`, `icons`) for small whole numbers, `ring` for shares, `bar` or `circle` for magnitudes. Leave `highlight` out to give every entity its own colour, derived from the theme when its palette is smaller than the number of entities; set it to draw one or two entities in colour and the rest in grey. | One measure across entities (use `pill-rank` or `bar-chart`). More than 12 entities (use `data-table` or `heatmap`). A subject with a total and its parts (use `ranking-poster` or `flow-poster`). A phone-first piece: the table stacks into cards under 600px and the poster becomes long. |
| Lay out a whole poster | [network-poster](https://insightcharts.dev/llms/network-poster.md) | template | Use it when the connections between 5 to about 20 named things are the subject: ferry crossings between harbours, joint papers between institutes, freight between rail yards. Give `hero` one row per connection and the `order` the entities sit in, `map` the entities with a size and optional hand-placed `x` and `y`, and `rank` one measure of each entity. With `linked`, a click on an entity in any of the three highlights it in the other two. | A flow from sources to destinations in one direction (use `flow-poster` or `sankey-chart`). More than about 20 entities or 40 connections, because the arcs cover each other. Entities with no meaningful order and few links (use `bubble-network` in a `poster`). Parts of one subject (use `radial-poster`). |
| Lay out a whole poster | [profile-poster](https://insightcharts.dev/llms/profile-poster.md) | template | Use it for a fact sheet about one named thing: a vehicle, a reservoir, a building, a machine, a species. Give `portrait` one row with the share that defines the subject and the `icon` that stands for it, `figures` the numbers a reader should take away, `scale` the subject among 4 to 10 reference points, and `table` the subject beside 2 to 6 peers. Highlight the subject in `scale` and `table`. On a sheet at least 960px wide the silhouette, the figures and the scale stand in three columns. | Several subjects of equal weight (use `glyph-table` in a `poster`, or `ranking-poster`). A subject whose parts are the point (use `radial-poster`). A subject with no defining share: leave `portrait` to a full spec such as `stat-circles`, or use `scale-poster` when the scale is the whole subject. Change over time (use `timeline-poster`). |
| Lay out a whole poster | [radial-poster](https://insightcharts.dev/llms/radial-poster.md) | template | Use it when the poster is about the 4 to 12 parts, causes, effects or scores of one thing: what a household's water goes on, the species one tree supports, where one home's energy goes. Give `hero` the spokes and an `icon` for the centre, state the total in the title, and use `figures` for the two to four numbers a reader should take away. | Parts of a whole that must be compared precisely (use `bar-chart` in a `poster`). Positions on one scale (use `scale-poster`). Change over time (use `timeline-poster`). Connections between many things (use `network-poster`). Large counts shown as crowds (use `count-poster`). |
| Lay out a whole poster | [ranking-poster](https://insightcharts.dev/llms/ranking-poster.md) | template | Use it for a profile of one event, place or organisation that has a headline total, two ways to split it, a ranking of 6 to 12 named things and a few supporting magnitudes: a festival, a race, a nature reserve, a library service. Put the total in the title and repeat it as the first figure. Highlight the ranking row the heading is about. | A subject whose point is a count of people or things (use `count-poster`). Several entities compared on the same measures (use `matrix-poster`). Eight or more small graphics on one subject (use `atlas-poster`). A ranking alone (use `pill-rank` in a `poster`). |
| Lay out a whole poster | [scale-poster](https://insightcharts.dev/llms/scale-poster.md) | template | Use it when the positions of 6 to about 16 named things on one scale are the whole subject: depths, altitudes, temperatures, distances, ages. Give the scale's rows and zones in `scale`, up to five `figures` with the scale position each belongs to, and optionally a `side` graphic of two to four magnitudes. Beside the scale the figures line up with their positions; under 760px they move below it. | Comparing sizes rather than positions (use `ranking-poster` or `count-poster`); change over time (use `timeline-poster`); more than about 16 items, because the labels run together; several unrelated graphics (use `poster` and lay the panels out yourself). |
| Lay out a whole poster | [timeline-poster](https://insightcharts.dev/llms/timeline-poster.md) | template | Use it when the subject is how 4 to 8 named things grew, shrank and changed places over 4 to 10 periods: electricity by source, library loans by format, commuters by mode. Give `hero` the periods and entities, `milestones` the dated numbers a reader should take away, `bars` one measure of the whole at each period and `shares` one share at a few dates. State the latest value in the title. | A single series over time (use `line-chart` or `area-chart` in a `poster`). Events with start and end dates (use `timeline-chart` or the `timeline-story` template). More than 8 entities or 10 periods, because the bands get too thin to label. Positions on one scale (use `scale-poster`). Parts of one subject at one date (use `radial-poster`). |
| State something in words | [callout](https://insightcharts.dev/llms/callout.md) | atom | Beside or under a chart, to state its main fact in words, with the number. Also for a caveat the reader must not miss (`negative`). | Long narration (use `prose`), a featured number (use `big-number` or `stat-tile`), or more than one callout per chart. |
| State something in words | [headline](https://insightcharts.dev/llms/headline.md) | atom | At the top of a data story (`page`), at the start of each chapter (`section`), or as the heading of a tile (`card`). Write the title as one plain fact with its number. Write the deck as a second plain sentence. | Titling a single chart: charts carry their own `title` and `subtitle`. For numbered chapters use `step-marker`. |
| State something in words | [prose](https://insightcharts.dev/llms/prose.md) | atom | To say what a chart showed and introduce the next one. Use two or three short paragraphs at a time. | A single statement of fact (use `callout`), a quotation (use `pull-quote`), or sourcing and method notes (use `source-note`). |
| State something in words | [pull-quote](https://insightcharts.dev/llms/pull-quote.md) | atom | To quote a person on a finding the charts have already shown, or to break up a long run of charts. One per section at most. | Restating a number (use `big-number`) or the main fact of a chart (use `callout`). Never quote without attribution. |
| State something in words | [source-note](https://insightcharts.dev/llms/source-note.md) | atom | Once, at the end of a story or dashboard, to say where every number came from and how it was produced. | Sourcing a single chart: use that chart's own `source` and `note` props so the citation travels with its export. |
| State something in words | [step-marker](https://insightcharts.dev/llms/step-marker.md) | atom | When a piece has three to seven ordered chapters or steps. Open each one with a marker so the reader can see the position in the sequence. | Unordered sections (use `headline` with `size: "section"`), or numbering a list of items inside a paragraph. |
| Arrange several pieces | [before-after](https://insightcharts.dev/llms/before-after.md) | molecule | A single measure at two moments or under two conditions: before and after a policy, control and treatment, last year and this. The change is computed from the two values unless you state it. | More than two states (use `line-chart` or `slope-chart`); many entities each with a before and after (use `dumbbell-chart` or `arrow-chart`); two unrelated figures (use `stat-row`). |
| Arrange several pieces | [chart-callout](https://insightcharts.dev/llms/chart-callout.md) | molecule | Whenever a chart needs its meaning stated in words next to it: the standard chart-plus-interpretation unit of a report. The chart's title states the main fact with its number. The callout adds a second fact, a cause or a caveat in plain words. | Repeating the chart title in the callout; long narration (put `prose` before the chart instead); a chart that is already a small tile (the callout would outweigh it). |
| Arrange several pieces | [chart-tabs](https://insightcharts.dev/llms/chart-tabs.md) | molecule | The same entities under two to five measures or scalings where each view changes the reading: total / per capita / change, absolute / share, linear / log. Give the frame a plain label as its title. Each view's `subtitle` names its measure. | Hiding the most important view behind a tab (show it first, or show both with `small-multiple-grid`); unrelated charts (give each its own figure); more than five views. |
| Arrange several pieces | [comparison-table](https://insightcharts.dev/llms/comparison-table.md) | molecule | Comparing five to twenty entities on a level, a trend and a change at once: countries, products, teams. Readers look up their row. The sparkline and delta show how the value changed. | Plain lookups with no series (use `data-table`); one measure ranked (use `ranked-list` or `bar-chart`); trends the reader must compare precisely (use `small-multiples`). Each sparkline has its own scale, so it shows the direction of change and cannot be used to compare levels between rows. |
| Arrange several pieces | [filter-chips](https://insightcharts.dev/llms/filter-chips.md) | molecule | Inside any `<InsightData>` whose charts use `select`: put it above the charts so readers can see what is filtered, drop one value, or clear everything. `linked-charts` already includes it. | Outside `<InsightData>` it renders nothing unless you pass `selections` yourself. It is not a filter builder: selections are made by clicking marks in the charts. |
| Arrange several pieces | [kpi-grid](https://insightcharts.dev/llms/kpi-grid.md) | molecule | The top of a dashboard or a monthly report: three to eight metrics tracked over the same periods. Pass one table with a column per metric. | Figures without a series behind them (use `stat-row`); comparing the metrics with each other on one scale (use `line-chart` or `small-multiples`); more than eight cards. |
| Arrange several pieces | [linked-charts](https://insightcharts.dev/llms/linked-charts.md) | molecule | Exploration of one table along several dimensions: by region, by category and over time. Pass row-level data once; each chart aggregates it with its own `transform`, sets `select: true` and omits `data`. | A report that states one fixed fact (use `chart-callout` or `scrolly-chart`); charts over unrelated datasets (they cannot filter each other); more than four charts. |
| Arrange several pieces | [metric-breakdown](https://insightcharts.dev/llms/metric-breakdown.md) | molecule | A total that the reader will immediately want split: a budget by department, revenue by product line, emissions by sector. Two to six parts that add up to the number above them. | Parts that do not sum to the headline; more than about six parts (use `bar-chart`); composition compared across groups or over time (use `bar-chart` with `stack: "percent"` or `area-chart`). |
| Arrange several pieces | [ranked-list](https://insightcharts.dev/llms/ranked-list.md) | molecule | A top-N list where the names matter as much as the values: league tables, best and worst performers, leaderboards with a movement column. It keeps long names readable and works in a narrow column. | Precise visual comparison of many values or more than about 15 rows (use `bar-chart`); several measures per entity (use `data-table` or `comparison-table`); rank changing over time (use `bump-chart`). |
| Arrange several pieces | [small-multiple-grid](https://insightcharts.dev/llms/small-multiple-grid.md) | molecule | Faceting a chart form the `small-multiples` atom does not draw: stacked bars, scatter plots, donuts, waffles, dumbbells, histograms. Also when each panel should be a full chart with its own tooltip and axis. | Line, area or bar facets that must share one value scale: use the `small-multiples` atom, which draws every panel in one chart on a common axis. Here each panel scales to its own rows unless the spec fixes the axis (for example `option: { xAxis: { max: 70 } }`), so say so in the subtitle or fix it. More than about twelve panels. |
| Arrange several pieces | [stat-row](https://insightcharts.dev/llms/stat-row.md) | molecule | The opening summary of a report or dashboard: the two to five most important numbers. Give every figure a delta or a context line, and order them by importance. | More than five figures (use `kpi-grid`), a single lead number (use `big-number` with `size: "hero"`), or figures that need their history shown (use `kpi-grid`, or `variant: "tiles"` with a `trend`). |
| Arrange several pieces | [trend-card](https://insightcharts.dev/llms/trend-card.md) | molecule | A metric whose recent history matters as much as its level: users, revenue, response time. Pass the series and field names; the figure, the change and the sparkline all come from the same rows, so they cannot disagree. | A number with no history (use `big-number` or `stat-tile`); several metrics from one dataset (use `kpi-grid`); a series the reader must read values from (use `line-chart`). |
| Arrange several pieces | [comparison-brief](https://insightcharts.dev/llms/comparison-brief.md) | template | Use it for two things a reader has to choose between or compare, such as two countries, two products or a before and an after. Write the result with its number in the headline. Put the four or five most important measures in `figures`. Use a two-series line, dumbbell, slope or `before-after` as the hero. In each pair, use the same chart form and the same scale for both sides. The `subject` side takes the accent colour everywhere and the other side stays grey. | Three or more things (use a `comparison-table` or `small-multiple-grid` inside a `report-page`). One thing over time with nothing to compare it with (use `timeline-story`). Paired charts on different scales, because readers compare bar lengths across the pair. |
| Arrange several pieces | [executive-brief](https://insightcharts.dev/llms/executive-brief.md) | template | Use it when a decision-maker will spend about a minute on the page. State the main finding with its number and period in the headline. The headline and the hero chart should be enough for a reader who stops there. The figures, supporting exhibits and actions add detail. Use one accent colour for the subject (`highlight`) and leave everything else grey. Mark the cause on the hero as an annotation. The proportions suit a printed page. | More than one hero or more than three supporting exhibits (use `report-page`). A recurring set of numbers with no single finding (use `scorecard`). A story told in several steps (use `visual-essay`). |
| Arrange several pieces | [report-page](https://insightcharts.dev/llms/report-page.md) | template | Use it for readers who will check the reasoning, as in evaluations, research notes, audits and experiment write-ups. State the main finding with its number in the title. Put all the main findings and the recommendation in the summary. Write each finding title as one fact with its number, and give it an exhibit that shows that fact. Put what the data shows in `observation` and what you infer from it in `interpretation`. End with method, limitations and sources. | A decision-maker who wants only the result (use `executive-brief`). A general audience (use `explainer` or `visual-essay`). Findings without an exhibit. Put those in the summary. |
| Arrange several pieces | [scorecard](https://insightcharts.dev/llms/scorecard.md) | template | Use it for weekly or monthly numbers. Keep the layout the same in every edition so readers know where each number is. Change the headline each edition to state the main change with its number. The headline and the KPI row should be enough for a reader who stops there. The ranking, trends and notes add detail. Highlight the one row or series the headline is about and leave the rest grey. | A one-off finding (use `executive-brief`). Readers who need to filter the data themselves (use `data-explorer`). More than six KPIs. |
| Arrange several pieces | [social-card](https://insightcharts.dev/llms/social-card.md) | template | Use it for one finding that will be shared in a feed, a slide or a chat thread with no text around it. State the fact with its number in the headline. Use one simple exhibit, such as one highlighted bar, one line or one number. Put the source and your name on the card, because it will be shared without the page. Use 1:1 or 4:5 for feeds, 16:9 for slides and link previews, 9:16 for stories. | More than one fact or more than one exhibit (use `story-deck` for a sequence, `executive-brief` for a page). Charts that need a legend, small labels or hovering to read, because a shared image is not interactive. An exhibit with its own `title`, because the card's headline is the title. |
| Show a sequence of steps | [annotated-timeline](https://insightcharts.dev/llms/annotated-timeline.md) | molecule | Telling how something unfolded when the events matter more than a continuous measure: a policy history, an incident, a product's milestones. Four to eight events; give a figure only to the ones where a number changed. | Events that should be read against a time scale, with gaps and overlaps to scale (use `timeline-chart`); a continuous series with a few annotated moments (use `line-chart` with `annotations`); ordered steps that are not dated (use `section` with `step`). |
| Show a sequence of steps | [hero-figure](https://insightcharts.dev/llms/hero-figure.md) | molecule | At the very top of a data story or a one-page report. The headline states the main fact with its number. The chart shows that fact. | Giving the chart its own `title` (the headline is the title; use the chart's `subtitle` for the measure). A second hero on the same page: later sections use `section` or `chart-callout`. |
| Show a sequence of steps | [proportion-statement](https://insightcharts.dev/llms/proportion-statement.md) | molecule | One proportion that is easier to read as a count of people or units than as a percentage. Round to a small whole first: 1 in 4 with icons, 37 in every 100 with a waffle. | Several shares side by side (use `bar-chart`, or `waffle-chart` with categories); a precise percentage where the decimals matter (use `big-number`); totals above 100. |
| Show a sequence of steps | [quote-figure](https://insightcharts.dev/llms/quote-figure.md) | molecule | A quotation shown next to the number it refers to: an interview finding with its survey figure, an executive's statement with the metric. One per section. | A quote with no evidence (use `pull-quote`); a figure that needs axes to read (use `chart-callout` and put the quote in prose); unattributed quotations. |
| Show a sequence of steps | [scrolly-chart](https://insightcharts.dev/llms/scrolly-chart.md) | molecule | Walking a reader through one chart in stages: show everything, highlight the subject, change the measure, add the annotation. Make ONE change per step (the highlight, the data or the encoding) so the reader can see what changed. | Steps that change several things at once, or that swap to an unrelated chart (start a new `section` instead). More than about seven steps. A fact that one view can show (use `chart-callout`). In documents that will be printed or embedded in a short frame, set `scrollMode: "steps"`. |
| Show a sequence of steps | [section](https://insightcharts.dev/llms/section.md) | molecule | The building block of a longer piece. Each section states one fact with its number in the title, explains it in a paragraph and shows it in one to three exhibits. Use `step` when the sections are read in order. | The opening of a piece (use `hero-figure`); a single chart with one callout (use `chart-callout` directly); more than three exhibits in one section (split it). |
| Show a sequence of steps | [data-explorer](https://insightcharts.dev/llms/data-explorer.md) | template | Use it when readers will want to filter the data themselves after seeing the main finding. State the finding with its number in the headline. Set `initialSelections` so the piece opens on the view the headline describes. Use the figures and the `finding` callout to give the numbers for that view. Keep to one dataset and two to four small, plain charts. Readers click the charts to filter, so keep them all the same size. | A fixed message that needs no exploration (use `executive-brief` or `visual-essay`). Charts over unrelated datasets, which cannot filter each other. More than four charts or five figures. |
| Show a sequence of steps | [explainer](https://insightcharts.dev/llms/explainer.md) | template | Use it to explain one subject to a general audience in a single narrow column. The column also works as a tall image or on a phone screen. State the main finding with its number in the headline and repeat the main number in `hook`. Make the hero exhibit the largest thing on the page. Give each numbered section one heading, one exhibit and one sentence with its main number. Write each section so it can be read without the others. Keep one accent colour on the subject (`highlight`) throughout. | Findings that need caveats and separate interpretation (use `report-page`). A chart that has to change step by step (use `visual-essay` with a scrolly block). More than five sections, because readers stop before the end. |
| Show a sequence of steps | [story-deck](https://insightcharts.dev/llms/story-deck.md) | template | Use it for a short sequence read on a phone, such as a “year in review”. Each card should be readable in a couple of seconds. State the main fact with its number on the title card. Put one fact on each later card, as a number or as one chart with one highlighted mark under a headline that states the fact. Use five to ten cards. End with a closing card and the sources. Charts in cards should have few data points and direct labels, with no legend. | Findings that need two exhibits in view at once (use `executive-brief`). A single shareable image (use `social-card`). Dense charts or long paragraphs, because a card has little room. One chart that changes step by step (use `scrolly-chart` in `steps` mode). |
| Show a sequence of steps | [timeline-story](https://insightcharts.dev/llms/timeline-story.md) | template | Use it when the reader needs the events in date order to understand a change. State the change over the whole period in the headline, with the numbers and dates. Mark the main events on the overview exhibit as annotations. Give each chapter one event. Add a small figure to a chapter only when it has a number to show. Mark the two or three most important events with `emphasis`. | Events with no measure that runs through the period (use a plain `annotated-timeline`). A comparison of two states with nothing in between (use `comparison-brief`). More than eight chapters. Merge minor events into the text of the chapter before or after. |
| Show a sequence of steps | [visual-essay](https://insightcharts.dev/llms/visual-essay.md) | template | Use it for a finding that takes several charts and some text to explain. State the main finding with its number in the headline. Put the main figure within the first screen. Alternate text and charts, with two or three short paragraphs before each exhibit. In a scrolly block change one thing per step, such as the highlight, the year or an annotation. Use one accent colour for the subject in every chart. | A summary for someone who will not scroll (use `executive-brief`). Reference material read out of order (use `report-page`). More than one or two scrolly blocks. Use one only where the chart changes between steps. |

When two forms fit, use the simpler one. When nothing fits, use a sentence with a `big-number`.

## Poster primitives

The rows above with the job "Draw a poster graphic" are the poster primitives. They are for panels of a `poster` and for the regions of the infographic templates. Each prints names and values on or beside large flat marks and has no axes by default. Use the ordinary chart for a report page and the primitive for a poster.

| The data's job | Primitive | Ordinary chart for a report page |
|---|---|---|
| Count people or things in 2 to 12 groups, in the thousands | `unit-blocks` | `pictogram-chart` |
| Compare counts of up to about 150 in 4 to 24 categories | `icon-array-grid` | `pictogram-chart` |
| Compare 2 to 8 quantities that differ by 2 to 100 times | `proportional-area` | `bar-chart` |
| State 2 to 6 related magnitudes with the number set large | `stat-circles` | `stat-row` |
| Show 5 to about 60 parts of very different sizes | `circle-pack` | `treemap` |
| Show one share at 2 to 8 dates, or 2 to 8 shares of one whole | `nested-shares` | `waffle-chart` |
| Show 1 to 6 percentages as a filled silhouette | `shape-fill` | `icon-stat` |
| Compare a short series or ranking of 3 to 12 values | `block-bar` | `bar-chart` |
| Rank 4 to about 20 named things | `pill-rank` | `bar-chart`, `ranked-list` |
| Relate two measures of the same 4 to about 15 entities | `curve-rank` | `slope-chart`, `scatter-chart` |
| Show size and changing rank of 4 to 8 entities over 4 to 10 periods | `ribbon-chart` | `bump-chart`, `area-chart` |
| Place 4 to about 20 things on one scale (depth, height, age) | `scale-ladder` | `strip-plot` |
| Place 5 to about 40 things on one scale with a magnitude as area | `bubble-scale` | `beeswarm-chart` |
| Show 4 to 12 attributes of one subject | `radial-spokes` | `bar-chart` |
| Group 6 to about 40 named things by level or period round a centre | `orbit-chart` | `comparison-table` |
| Split one total among 4 to about 14 destinations | `fan-flow` | `sankey-chart` |
| Show connections among up to about 20 ordered entities | `arc-diagram` | `sankey-chart` |
| Show which of up to about 12 things are connected, with sizes | `bubble-network` | `sankey-chart` |
| Compare 3 to about 12 entities on 2 to 5 measures with different units | `glyph-table` | `comparison-table` |

A whole poster is an infographic template (the job "Lay out a whole poster") or the `poster` molecule. See the infographics guide.

## Writing titles and text

These rules apply to every `title`, `subtitle`, deck, callout, annotation label and story step. They are hard requirements.

Write one plain statement of fact, the way a person would say it out loud, with the real numbers and the period in it.

| Write this | Not this |
|---|---|
| Monthly churn fell from 4.2% to 2.1% in 2024 | Churn halved after the March onboarding revamp, and the gain has held for six months |
| Renewables supplied 98% of Norway's electricity in 2023 | Norway runs almost entirely on renewable electricity |
| Acme had 266 active teams in December 2024, 2.4 times Globex | Acme pulled away from the pack in late 2023 |
| Solar's share rose from 2.7% to 5.5% between 2019 and 2023 | Solar is closing the gap with wind |
| Households wasted 631 million tonnes of food in 2022 | It is not a rich-country habit |

- One clause. Do not add a second half joined with a comma, "and", "but", "while", "yet", a semicolon, a colon or a dash that adds a twist, a consequence or a follow-up. If there are two facts, write two sentences or put the second in the subtitle.
- Put the number in. Write "fell from 4.2% to 2.1%", not "halved". Write "98%", not "almost entirely". Write "3 of 12", not "a handful".
- Take every number from the data. Never invent a figure, a cause or an event that the data does not show.
- No metaphor, idiom or figure of speech. Do not write "pulled away from the pack", "closing the gap", "tells the story", "the long tail" or "did the work".
- No teasing. Do not point at something the reader has to work out, such as "one hospital explains most of it" or "here is where it goes".
- No dramatic verbs (soared, plunged, surged, skyrocketed, slashed). No staged contrast ("not X, but Y").
- No rhetorical questions, no groups of three for rhythm, no sign-off lines.
- A plain label is always acceptable when there is no single fact to state: "Monthly churn, 2024".
- Subtitles name the measure, unit, population and period. Sources name the source.

## Design rules

The components enforce some of these. You are responsible for the others.

1. **State one fact in the title.** `title` is one plain statement with its number and period, or a plain label. Put the measure, unit, population and period in `subtitle`.
2. **Highlight one series.** Set `highlight` to the one or two entities the title is about. The other series are drawn in grey. Do not colour every series when the title is about one of them.
3. **Label marks directly.** Charts label line ends and bar tips where they can and show a legend only for two or more series. Do not add a legend for something that is already labelled.
4. **Use few annotations.** `annotations` mark a date, a threshold or a single value: a `line` at a target or a date, a `band` over a period, a `point` label on one value. Use two or three per chart at most.
5. **Start bars and areas at zero.** Bars and filled areas start at zero, and the components do this for you. Lines and dots may use a value axis that does not start at zero. If you rebase or use a log scale, say so in the subtitle.
6. **No dual axes, no gauges, no pie with more than 5 slices.** Two measures get two charts (or an index). A single figure is a `big-number`. Many parts become a ranked bar chart with the smallest folded into "Other" (the `top` transform does this).
7. **Change one thing per scroll step.** In a `Scrolly` story each step changes one thing: the data, the highlight or the encoding.
8. **Do not rely on tooltips.** The chart must be readable without hovering. Touch screens and exported images have no hover.
9. **Always give a source.** Pass `source`. Use `note` for method caveats, and say when data is illustrative.
10. **Give a big number context.** Add a comparison, a denominator or a period with `context`, `delta` and `deltaLabel` on `big-number`. Write "31.7%, up from 19% in 2010", not "31.7%" alone.

## How colour is assigned

You do not pick colours per series. The theme assigns them:

- Identity (which entity): the categorical palette, in stable entity order. More than 8 entities should be folded or split into small multiples.
- Emphasis: `highlight`. The first highlighted entity takes the accent colour, others take the next categorical colours, and the remaining series take the context grey.
- Magnitude and polarity: sequential and diverging ramps from the theme.
- Good or bad: `positive` and `negative`, always with a second cue such as an arrow or sign.

To change colours, change the theme (see the theming guide), not individual charts.

## Checklist

- Is the title one clause that states one fact with its number and period, or a plain label?
- Can every number in the text be found in or computed from the data?
- Is exactly one thing highlighted?
- Can it be read with no hover, at 380px wide, and in dark mode?
- Is there a `subtitle` naming the measure and a `source`?
- Would a sentence or a `big-number` show the same fact?