Data visualisation design

This skill helps you decide what a chart should say, choose the view that proves it, build it cleanly, and check it before it reaches anyone. The design rules apply to any tool. The bundled scripts add automated checks and finishing helpers for matplotlib.

The one rule everything else follows from: pick the representation that lets this reader answer this question accurately, with the context they need and the least effort. A chart that looks good but makes the comparison hard, or that leaves a false impression, has failed.

Rules here have different strengths. Some are arithmetic (bubble area must be proportional to the value). Some are strong defaults (bars start at zero). Some are heuristics (keep categorical colours few). When you break a default, have a reason you could say out loud to the reader.

Workflow

Work through these steps in order. They are quick for a simple chart. Go back a step when something does not fit. A legend that is hard to read often means too many categories. A total that looks impossible often means a bad join. A title the chart does not prove means the wrong view.

1. Write the brief

Finish this sentence before choosing a chart:

For [reader], this chart should make it easy to see [comparison or pattern], so that they can [decision or understanding].

"Visualise the dataset" is not a brief. If the user has not said what the chart is for, infer the most likely question from the data and say which question you chose. Note where the chart will be seen (slide, report, web page, phone), because that sets its size, font sizes and how much text fits. If nobody says, assume a web page.

Decide whether the chart is exploratory (you are looking for what is there, so show distributions and exceptions) or explanatory (the reader should get one supported finding, so edit hard and label directly).

2. Profile and check the data

A chart cannot fix a wrong number. Print a quick profile first: columns and types, distinct values of the key columns, the date range, and missing values per column. Then confirm:

• Grain. What does one row represent? What will one mark represent?
• Rows that are not entities. Totals, regions, groups, "Other" and "Unknown" rows mixed in with real entities. Find them before ranking or summing.
• Scale type of each variable. Nominal, ordinal, interval or ratio. A numeric ID is still a label. This decides which channels, palettes and baselines are valid.
• Aggregation and denominator. Is each value a count, sum, mean, share or rate, and a share of what? Do not let the library aggregate silently.
• Missing values and the latest period. Missing is not zero. The most recent period is often incomplete or provisional.
• Units and order. Thousands or millions, 0 to 1 or 0 to 100. Dates sorted as dates, ordinal levels in their real order.

Read references/data-and-preparation.md for the details, and whenever the task involves joins, reshaping, outliers, percentages, or time, map, hierarchy or network data.

3. Write the headline, then choose the evidence

Write the finding as one sentence with a number before writing chart code, and compute the numbers you will quote. Then choose the view that lets the reader check that sentence at a glance. This is the step that most separates a good chart from a merely tidy one.

• Pick the measure the headline is about: level, absolute change, percent change, index, share, or per-person rate. They can point in different directions.
• Make the evidence match the claim. "Largest" needs every item ranked on one scale. "Grew fastest" needs the change itself for every item, not just the levels. "Overtook" needs both lines and the crossing. "Slowing" needs the growth rate.
• Superlatives (most, fastest, first, only, record) claim something about every item, so every item must be visible in that measure.
• Use a second panel when the headline makes a second claim the first view cannot prove: levels plus ranked change, share plus total, level plus growth rate.
• Series of very different sizes squash the small ones into a band. Index them, use a log scale, use small multiples or add a panel, depending on the question.

Read references/claims-and-evidence.md before choosing the form for any explanatory chart.

4. Choose the form

Most questions are a comparison, a composition (what the whole is made of), a relationship or a distribution. Use the chart chooser below. If the reader needs exact values, a table may beat any chart. A single number with context can beat a gauge.

5. Encode the key comparison with the strongest channel

People judge some visual properties much more accurately than others. From most to least precise for quantities:

1. Position on a common scale
2. Position on separate but identical scales (small multiples)
3. Length
4. Angle and slope
5. Area
6. Volume, colour lightness and colour saturation

Put the most important comparison on position or length. Use hue and shape for categories, never for amounts. Use area and colour intensity for patterns where rough reading is enough. Read references/encoding-and-perception.md when a mapping is not obvious, when there are more than three variables, or when layout and grouping matter.

6. Choose colour by meaning

• Unordered categories: distinct hues (qualitative palette).
• Ordered or numeric low to high: one ramp that gets steadily lighter or darker (sequential palette).
• Two directions around a meaningful midpoint: two ramps meeting at a neutral centre (diverging palette).
• One thing matters: grey for context and one accent colour for the focus. This is the right default for most explanatory charts.

Keep the same colour for the same category in every chart. Never let colour be the only cue for something essential. Read references/colour.md for palette choice, accessibility and legends, and run scripts/check_palette.py on any custom palette.

7. Write the text, within a budget

• Title: the finding from step 3, one line.
• Subtitle: what is plotted (measure, unit, scope, period), one line.
• Labels: label lines and bars directly. Use a legend only when direct labels would collide.
• Annotations: at most two, for the things the reader must not miss.
• Footer: a note only if it changes the reading, then the source.

Everything else (methods, definitions, extra numbers) goes in your reply, not on the chart. Match wording to evidence: "rose after" is not "rose because of". Read references/layout-and-typography.md for sizes, the type scale, label placement and number formats, and references/explanation-and-honesty.md when the chart supports a claim someone will act on.

8. Build it

For matplotlib, use the bundled helpers. They apply the type scale and canvas size for the destination, add a left-aligned title block and footer, place direct labels without collisions, space value labels evenly, and run the linter when saving.

import sys; sys.path.insert(0, "<this skill>/scripts")
import chartkit as ck

ck.apply_style("web")                     # slide, report, web, social, square
fig, ax = ck.figure()
for name, s in series.items():
    ax.plot(s.index, s.values, label=name, **ck.emphasis(name, focus="North"))
ck.label_lines(ax, focus="North", values=True)
ck.tidy(ax)
ck.finish(fig, "chart.png", title="...", subtitle="...", source="Source: ...", alt="...")

Other helpers: ck.bar_labels (value labels, with an optional second label), ck.grid (small multiples), ck.callout, ck.reference_line, ck.plain_log_ticks, ck.colours_for and ck.fmt (number formatting). For other libraries, apply the same specs by hand and read references/library-notes.md, because library defaults often change the meaning of a chart.

9. Lint, look, critique, fix

A first render is a draft. Before delivering:

1. Lint. Run python scripts/chartlint.py your_script.py (ck.finish does this for you). It finds overlapping and clipped text, small fonts, bars that do not start at zero, unequal bar widths, squashed series, too many colours, oversized legends, crowded pies, dual axes, rainbow or off-centre colour maps, and colour pairs that fail colour-vision checks. Fix every FAIL. Fix each WARN or be able to say why it does not apply.
2. Look. Open the saved image and view it at its real size. Never judge a chart from its code.
3. Critique as a sceptical reader. Cover the title: does the chart alone say what the title says? Is every number in the title visible? Where does the eye land first? Can every series that matters be read? Is there text that belongs in the reply?
4. Fix and render again, up to three rounds. Change the design, not just the styling, when the critique demands it.

The full critique questions and final review are in references/review-checklist.md.

10. Deliver

Give the image at the destination size, its alt text, and a short reply: the answer to the question, any choice that changes the reading (filters, exclusions, smoothing, scale), and the caveats you kept off the chart.

Chart chooser

Use this to get candidates, then read the named reference for the pitfalls of the form you pick. The files in the last column are in references/. "Few" and "many" are judgments, not thresholds.

Defaults that prevent most bad charts

Each of these exists because breaking it changes what the reader believes.

1. Bars start at zero. Bar length is the value. If small differences matter, use dots or a line, which can use a narrower range.
2. Bars in one chart have equal width. Otherwise area becomes a second, unintended encoding.
3. Size means area. For circles, radius must scale with the square root of the value. Doubling the radius shows four times the amount.
4. No decorative 3D. Perspective and occlusion change apparent sizes and add no data.
5. Avoid dual y-axes. Their scales can be tuned to show any relationship. Use two aligned panels or index both series.
6. Stack only disjoint parts of one whole. Never stack a total with its own subsets, or metrics with different meanings.
7. Sort categories by value unless they have a natural order (time, rank, age bands). Never sort a time axis or a histogram by height.
8. Connect points with a line only when the order between them is real and they belong to the same series.
9. Palette type follows data type. No rainbow for numeric data. No ramp for unordered categories.
10. Colour is never the only cue for anything essential. Add labels, shapes, line styles or position.
11. Say what was done to the data. Smoothing, binning, log scales, exclusions, imputation and normalisation all change the reading.
12. Show estimated values differently from observed ones. Forecasts, fits and imputed points need their own style and a label.
13. Plot the raw data before trusting a summary. Very different datasets can share the same mean, spread and correlation.
14. Remove what does not help reading (heavy frames, fills, shadows, redundant legends). Keep axes, units, reference lines and uncertainty.
15. The chart proves its title. Every number and comparison in the title can be read from the marks or labels.
16. Text has a budget. One-line title, one-line subtitle, at most two annotations, a short footer. The rest goes in the reply.
17. Ask two questions before finishing. Are the numbers right? What will a reasonable reader conclude at a glance? Both answers must be defensible.

Critiquing or fixing an existing chart

Read the chart as an encoding before judging its style: what question it answers, what one mark represents, which variable sits on which channel, what was aggregated or filtered, which comparison is easy and which needs angle, area or memory, and what impression it leaves. If you have the code, run it through scripts/chartlint.py. Then name the specific problem and the specific repair. Common symptoms, with the file in references/ to read:

references/worked-redesigns.md has before and after cases with numbers. Read it when you want a pattern to follow for a redesign.

Reference files

Read only what the task needs.

Scripts

All three need only Python 3. chartkit and chartlint also need matplotlib 3.7 or later.

python scripts/chartlint.py make_chart.py
python scripts/check_palette.py "#0072B2" "#D55E00" "#009E73" --background "#FFFFFF"
python scripts/check_palette.py "#f7fbff" "#6baed6" "#08306b" --type sequential

Both checkers report FAIL, WARN or NOTE and exit with status 1 on a failure. Their thresholds are heuristics: a warning is a prompt to look at the rendered chart, not a verdict.