Create Static Viz

Create or refresh a static visualization

Joins the three halves of a static-viz refresh that are otherwise separate: getting the data into ETL at a current vintage, drawing it in an viz://static step whose SVG a designer can actually pick up, and getting that SVG into the Charts file.

Model check: the session context names the running model. On Fable, recommend re-running on Opus (or Sonnet for a mechanical re-render) before starting, and continue only on the user's say-so — same rule as /owid-staff:create-figma-chart.

Paired skill — an update here may oblige an update there, and the reverse. /owid-staff:create-figma-chart owns everything that happens inside Figma, and this skill hands off to it at Step 7. The two share a contract that lives half in each file, so when you change something on this list, check the other skill in the same session and update it too — or state explicitly that you checked and no change was needed. Neither side may drift silently; a stale cross-skill fact is how a later run re-derives geometry by trial and error. That skill now lives in owid/skills-private (the owid-staff plugin, auto-installed here via .claude/settings.json); invoke it as /owid-staff:create-figma-chart.

Shared fact	Owner	Consumed by
Template geometry — node ids, sizes, band top, footer starts	TEMPLATES.md	both
The content box and the band a chart is fitted into	TEMPLATES.md	both
Node naming (gids) this step emits, and frame proportions	this skill	that skill's Steps 1/3/7–8
Which text slots this step fills vs. leaves to the template	this skill	that skill's Step 6
Type and palette — this step sets neither	that skill	this skill defers to it
The design vocabulary (per chart type, labeling, colors)	that skill's GUIDELINES.md	both
The sketch dir ai/static-viz-sketches/<slug>/, what its SVG carries, and the Figma handoff docstring section that records the page	this skill (reference/SKETCHING.md)	that skill's sketch mode, local-SVG route
The sketch marker — page … [sketch], frame <slug>--sketch; no sketch carries the bare website slug	that skill	this skill reports it
Finalize mode as the re-entry point once a sketch is promoted	that skill	this skill's Sketch mode, §8

The asymmetry worth remembering: this skill owns the data, the geometry and the proportions; that one owns the type and the palette. A change that crosses that line belongs in both files. In particular, if you change what the step emits — node naming, frame proportions, which text slots it fills — check whether that skill's Step 1/3/7 notes on local SVGs still hold.

Its GUIDELINES.md is where the visual vocabulary this skill defers to actually lives — the per-chart-type rules, direct labeling in place of legends, the OWID palette, the annotation and reference-line conventions. Read the section for your chart type before choosing a form or deciding what to label: the point is not to style anything here, it is to avoid emitting a structure the Figma pass then has to undo (a legend that should have been direct labels, a category count that cannot be labeled in place). That file also indexes the design team's DI Chart Library (pltrHXyVLg2XaNq4AvxPaK, read-only) — 288 finished charts on 2026-10-01, filed by chart type (dumbbell plots now have a page of their own; GUIDELINES.md keeps the current per-page counts), which is the closest thing to precedent for whatever you are about to draw.

Two companions in this directory:

• TEMPLATES.md — the static-chart template geometry, measured off the Charts file. Read it before laying anything out; don't re-derive it through MCP calls.
• scripts/verify_static_viz.py — mechanical check that the emitted files honor the Figma handoff contract. Run it before showing anyone the chart.

The step-by-step detail lives in reference/ and is read at that step:

Size budget, enforced by --structure: this spine under 34 KB, TEMPLATES.md under 25 KB. (Raised from 30 KB on 2026-09-17 to land Sketch mode and its contract rows, and to 34 KB on 2026-10-05 to land the published-original handoff in Step 7 — the spine sat 11 bytes under 33 KB. The discipline is unchanged.) Both are read on every run, so a paragraph added here costs every future viz — new detail belongs in the reference file for its step. After editing any doc in this skill:

.venv/bin/python .claude/skills/create-static-viz/scripts/verify_docs.py --structure
# and after moving text between files, prove nothing was dropped:
.venv/bin/python .claude/skills/create-static-viz/scripts/verify_docs.py --against <ref>

When you do make a Figma MCP call, batch it. A call costs twice — the network hop to the hosted connector and the model turn around it. The hop is environment-specific and the cloud is the faster side of it: get_screenshot 7.8–9.9 s from a sandbox against 12.5–20.5 s locally, use_figma 0.70 s against 3.5–5.8 s. The turn is not environmental — it tracks the work in it, and identical light probes measured 2.8 s in a sandbox against 3.7 s locally. (A ~12 s cloud turn was claimed here once; it came from turns doing real chart work, so it is the heavy-turn cost either side.) Either way, a handful issued one at a time is the difference between seconds and minutes. Batching pays about the same in both: the connector serves concurrent calls — eight screenshots in one message measured 4.1× faster than serially, and ten reps of a fixed six-call probe a side put it at ≈4.0× in both environments (4.00× cloud, 3.84× local, six in flight every time) — and admits about four or five at once, so put independent calls in one message, 4–6 at a time. A batch's wall is first call + rate × (n−1) — measured at 9.2 s + 0.75 s per extra screenshot in a cloud session and 11.7 s + 2.1 s locally — and that marginal cost is the stopping rule. Those are screenshots; batching use_figma never compresses its calls (one plugin context per file) and pays only by collecting turn gaps — still worth it, and worth more in the cloud, where the cheap call makes the turn 80% of the cost rather than 46%. Reads always; writes only when they target different pages. If the Figma tools arrive deferred — a harness setting, not an environment — load the ones you need in a single ToolSearch, taking the prefix from your own session's tool list rather than assuming one; skip that where they are already loaded. /owid-staff:create-figma-chart → Round-trip budget has the full rule and the list of what is genuinely serial.

What this skill does not decide: colors, fonts, background, the logo, and any visual treatment the template provides. Those are applied in Figma. The ETL step owns the data, the structure (which text slots exist, in what order), the proportions, and the axis conventions. Setting a cream background or a serif title in matplotlib is work that will be thrown away.

The project's rules

Policy, quoted from the parent issue (owid/owid-issues#2459, and identically in the earlier #2278). These are not this skill's inventions and are not negotiable here.

Scope. A refresh is either a data update plus light visual tweaks (the common case) or visual polish only (when the data is already current).

We should not do deep redesigns. Aim to reproduce the same visualization with the same broad design choices.

So the default is to rebuild the same chart, better — not to redesign it. When the existing design has a real defect — an encoding that misleads, overlapping translucent fills that produce a color meaning nothing, a caption that misstates what the data shows — a departure can be the right call. But it then stops being a refresh, and needs naming as such: say plainly that it exceeds the scope rule, say which defect justifies it, and get design sign-off on the departure rather than letting it pass as polish.

Quality bar.

• All numbers match the source.
• As much as possible, make visualizations reproducible so future updates are easier (and transparent).
• Design consistency: Marwa should sign off on every new static viz.
• Mobile: discuss with Marwa whether a mobile version is feasible; otherwise, make the desktop version as readable as possible on mobile.

The second line is why this skill exists: an viz://static step is the reproducibility requirement, met. The third is not optional — @mrwbkrm signs off on every one. The fourth means a mobile version is a question to ask, not a default to assume.

Pace. Work in progress stays at roughly one or two open child issues. Don't start a new refresh to avoid finishing one.

Author credit

The license line carries the credit, and who appears on it depends on how much changed:

"Whoever is doing the refresh" is the person running this skill — not a fixed name. Resolve it from git config user.name and confirm it at the Step 3 checkpoint, following the repo convention of crediting the human directing the work and asking when it is ambiguous. Never carry a name over from a previous run of this skill, or from the AUTHOR constant of another step you copied from.

The original author is not always recorded anywhere obvious; static_viz_popular.csv carries viz_authors / viz_authors_source, and the old image's own footer usually states it. When the call between the two rows is genuinely close, ask — it is someone's credit.

This is also a useful test of whether the scope rule above has been crossed. If the honest credit drops the original author, the design changed considerably, and that is the case needing the sign-off conversation rather than a quiet ship.

Inputs

Any one of:

• An old static viz — the image, its filename, or the page it appears on.
• An indicator — a catalogPath, or a description of one.
• A grapher chart — live URL, staging URL, admin edit URL, bare slug, or chart id.
• Just a description of the chart wanted, plus a source.
• A data file — CSV, Excel or parquet, for a sketch of a new viz: see Sketch mode below.
• "Sketch", "brainstorm" or "prototype" plus an indicator or chart — pull its data to a CSV first, then Sketch mode.

Optionally: the article or topic page the viz belongs to, and a reference page in the Charts file to work like (/owid-staff:create-figma-chart has a whole mode for that).

Sketch mode — a data file in, no ETL until the visuals settle

For a new static viz that starts from data rather than from an existing viz. The input decides the mode — a data file, or a sketch/brainstorm/prototype ask, is a sketch; say so in one line, with what it skips, and proceed. Read reference/SKETCHING.md and follow it instead of Steps 1–4. In short: scripts/new_sketch.py scaffolds ai/static-viz-sketches/<slug>/sketch.py (gitignored) in the exact shape of a viz://static step, around a copy of the data file; render it with .venv/bin/python, run the verifier and read the PNG as in Step 5, iterate (variants are extra LAYOUTS keys), hand the SVG to /owid-staff:create-figma-chart's sketch mode and iterate there too; once the visuals settle, scripts/promote_sketch.py turns the sketch into a real step. Skipped — say so to the user every time: the branch, worktree and PR, the DAG entry, Step 2's newer-data check, the tracker question, the review chain. Promotion runs all of them: Steps 1–2, then 5–9, plus that skill's finalize mode on the sketch frame. Not skipped: the verifier, reading the PNG, and offering promotion and finalize at the end of every sketch reply — people may not know the checks exist. A Data Insight image is not a static-viz sketch — it is sketched in that skill directly, from the grapher chart.

Step 1 — Resolve the input to data

Reuse the existing resolver rather than writing another one:

.venv/bin/python .claude/skills/edit-faust-metadata/scripts/resolve_target.py <reference> [--json] [--no-db]

It takes a live/staging/admin URL, a bare slug, a chart id, or an indicator catalogPath, reports the chart's variables with their catalogPaths, and names the candidate ETL step files — including a warning when the grapher catalogPath's version differs from what is on disk.

In a cloud session, run it with --no-db first — only the DB half is unavailable. Parse-only mode never calls read_sql, so it works in a sandbox: it identifies what the reference is, preserves the dimension query params, and names the candidate ETL step files for an indicator or MDim catalogPath. Do that before reaching for anything else. What --no-db cannot give you is the DB half — a bare slug stays chart-or-mdim (needs DB), and the chart's variables and their catalogPaths need MySQL.

For that half, don't wait on staging. A cloud sandbox has no MySQL and staging is on Tailscale, so the DB path reports "Staging server … is not reachable. Run etl pr first or wait for the staging build to finish" — which invites waiting for something that will never arrive here. Don't wait, and don't run etl pr for it. Fall back to the read-only routes in cloud-sandbox.md — https://ourworldindata.org/grapher/<slug>.config.json for a published chart, the public Datasette for variables and chart_dimensions — or ask the user to run the resolver locally and paste the output. This is a fallback for one environment, not a replacement: use the resolver with its DB wherever MySQL is reachable, since it does strictly more than the fallbacks do.

From an old static viz image, two routes, neither of which the popularity CSV can do alone:

1. The grapher static_viz table carries a grapherSlug column. That gives a slug, and the slug goes through the resolver above. Note this table is not mirrored to the public Datasette, so query a staging DB or the local dev DB (see /query-grapher-db) — which means a cloud session cannot reach it either, and the slug has to come from the user.
2. ai/static_viz_popularity/static_viz_popular.csv gives rank, the pages it appears on, views, authors and tags — useful context, but it has no slug or indicator column, so it cannot reach the data by itself.

If neither resolves it, ask. Guessing which dataset an old hand-drawn image was built from is how you rebuild the wrong chart.

The project tracks which viz is claimed, parked or already done in a shared tracker, and this skill deliberately does not read or write it — ask instead. If the user has not already said where this viz stands, ask before doing any work: a viz someone else is mid-way through, or one already finished, is worth an interruption rather than a duplicate.

Read reference/GOTCHAS.md → Data before you use a single column. Those checks are pre-flight, not post-mortem: a column whose name means something other than what it holds, an unasserted splice, a framing that stops holding partway through a series, and an over-claim repeated across the metadata each render as a plausible chart with nothing to grep for. They are how a run that raises no exception still publishes wrong numbers.

Then report what you found: which dataset, which version, and how many charts use it.

Step 2 — Check for newer data. Always, even when it is already in ETL

Two sides, and both are needed. The ETL side tells you whether a newer version in our catalog exists; only the producer side tells you whether newer data exists at all.

ETL side.

from etl.version_tracker import VersionTracker
df = VersionTracker().steps_df   # update_state, update_period_days, days_to_update, n_charts

update_state is one of Unknown / No updates known / Outdated / Minor update possible / Major update possible / Not yet used. Outdated means a newer version of that step already exists in the DAG — the viz is pointing at a stale vintage. Also read each garden dep's snapshot .dvc for date_published and date_accessed, and the garden .meta.yml for update_period_days.

Be clear about what this is: days_to_update is step version date + update_period_days, a proxy. VersionTracker's own docstring says so. It is DAG version arithmetic, not knowledge of the producer's release calendar.

Producer side — this is the part that needs the internet. Fetch the origin's url_main and search for the current release. Report what the producer publishes now against what the snapshot captured.

Version labels prove nothing. Producers replace the published file — and the codebook — without bumping a stated version and without a changelog. Compare the hosting platform's file-modification dates or hashes (an OSF API date_modified, an HTTP Last-Modified, a checksum) against the previous snapshot's date_accessed and md5. An unchanged version label is not evidence of unchanged data.

Two more traps worth carrying from /update-dataset:

• date_published and the year inside citation_full never update themselves. etl update clones the previous .dvc verbatim except date_accessed. Re-check both against the source.
• Producer prose can lag the producer's own tables. Trust the data over the landing page.

Then route, and never do the ingest or update inline:

"In ETL and current" is a real, reportable finding — say it rather than staying silent, so the user knows the check happened.

Step 3 — One checkpoint, before writing anything

Put the whole proposal in front of the user at once, and get an explicit go-ahead:

• the dataset and its vintage, plus what Step 2 found upstream
• what the viz shows, and how it differs from the image it replaces
• which template(s), and desktop and/or mobile
• the author credit and the license line — the templates leave Licensed under CC-BY by the author [Name of author]. Propose the name(s) per the Author credit rules above, resolving the refresher from git config user.name, and say which of the two cases you think applies — that is also the moment to say out loud if the design change looks big enough to have crossed the scope rule. Whether CC-BY is correct cannot be inferred either: a source under CC BY-NC-SA is not automatically redistributable as CC-BY, so ask rather than filling the slot.

This mirrors /owid-staff:create-figma-chart's single-checkpoint rule, for the same reason: everything after here is expensive to redo.