Charts Across Musewoods

Abstract

Musewoods charts are one analytical object. The same ChartSpec, the same data resolver, and the same D3 engine render inside Stories, Journals, Viewgraphs, and Groves; what changes between fields is editorial — the safe area, the figure wrapper, the caption tone, and how much interaction the reader is permitted. This article is the Journal-facing half of that contract: a working gallery of every chart type an author can place in a Journal figure, each one rendered through the real pipeline, with the Markdown that produces it and a short note on when to reach for it. Read straight through, it answers one question — what can I put in a Journal, what will it look like, and how do I write it?

Every figure below resolves its data through the shared ChartDataResolver from a logical dataset id. Nothing here fetches a URL or embeds a table in the prose. The datasets are small, illustrative fixtures kept under data/charts/; their numbers are invented to exercise the renderer, not to assert anything about the world.

The Journal Chart Grammar

A Journal chart is a blockquote directive whose body is a list of **Key:** value lines — the same authoring grammar Stories and Viewgraphs use. It joins the numbered figure sequence alongside Mermaid diagrams and images, and its static first frame carries the whole finding.

The complete anatomy of a chart block:

> [!chart]
> **Chart:** bar
> **Treatment:** wide
> **Interaction:** inspect
> **Title:** Where automated authority concentrates
> **Caption:** Exposure score by control surface, from the 2025 review.
> **Source:** Illustrative Musewoods data
> **Note:** Scores are relative, not absolute risk.
> **Alt:** Bar chart of exposure score by control surface; model decision authority is highest and rollback capability lowest.
> **Data:** authority-exposure
> **X:** dimension
> **Y:** exposure

Chart names the type. Data is a logical dataset id (or a /data/charts path) — never a URL, because logical identity belongs in the article and physical location is infrastructure. X, Y, Value, Series, Size, Label, and Group bind the dataset's columns to the chart's analytical roles; which of them a type needs is listed in the capability reference at the end. Title, Caption, Source, Note, and Alt are the figure apparatus; Alt is required, because a chart that only works on screen is not evidence. Treatment is inline or wide. Interaction is one of none, inspect, focus, compare, or explore, subject to the Journal policy described below. Optional refinements — Stack, Orientation, Sort, ValueFormat, Bins, X Title, Y Title — are shown with the charts that use them.

Comparison and Magnitude

These are the charts for the question how big, and how do these compare? They are the Journal's workhorses, and most of them read well inline.

> [!chart]
> **Chart:** bar
> **Treatment:** inline
> **Title:** ...
> **Alt:** ...
> **Data:** chart-gallery-throughput
> **X:** stage
> **Y:** value

Change and Time

These charts answer what happened over time, and how do the trajectories differ? A single trend reads well inline; anything with several series or labelled endpoints needs width.

> [!chart]
> **Chart:** line
> **Treatment:** wide
> **Interaction:** focus
> **Data:** chart-gallery-quarterly
> **X:** quarter
> **Y:** value
> **Series:** series

Distribution and Relationship

These charts answer how is this spread out? and how do two variables move together? Distributions can be compact; relationships with labelled points need room.

Composition and Hierarchy

These charts answer what are the parts of the whole, and how do they nest?

Flow

Interaction in a Journal

Interaction in a Journal is deliberately quieter than in a Viewgraph. The policy is a two-part gate: the chart family must implement the mode, and the Journal must permit it editorially. In practice that leaves four modes, and the first frame must already tell the story before any of them is used.

`inspect` is available on every chart type and needs no editorial justification. Hover, focus, or tap a mark and its precise value appears; the histogram, the throughput bar, and the heatmap above all use it. Nothing the reader needs to understand the figure is hidden behind it.

`focus` — isolating one series, path, branch, or slice while the rest fade to context — is available on the pointed, path, and hierarchical families: bar, dot, line, area, slope, scatter, bubble, pie, treemap, tree, and sankey. The multi-line, slope, scatter, tree, and sankey figures above demonstrate it. Use it when a chart legitimately carries several things at once and a reader will want to trace one of them.

`compare` — holding a small set of selections side by side — is available on the Cartesian families (bar, diverging bar, dot, line, area, slope, scatter, bubble). The dot plot above uses it. It suits a figure where the reader's job is to weigh two or three specific items against each other.

`explore` — descending into a structure the static frame cannot fully show — is permitted only on the treemap, and only where the hierarchy genuinely has depth worth opening. The treemap above declares it. It is the one mode that lets a Journal figure change what it is showing, and it should stay rare.

Histograms and heatmaps stop at inspect; pie, tree, and sankey stop at focus. Those are engine limits, not Journal policy, and the capability reference below records them.

Inline or Wide

inline renders the chart at the reading measure, in the column with the prose. wide grows the figure rightward to roughly the engine's full safe area without disturbing the text. The engine re-lays-out the chart for whichever size it is given — it is never a wide chart shrunk with CSS — so the choice is purely editorial.

Prefer inline for figures that read at a glance in a narrow column: a few-category bar chart, a single-series line or area, a small histogram, a small pie. Prefer wide whenever the figure needs horizontal room — long category labels, several series, endpoint labels, a second axis, a matrix, a hierarchy, or a flow. When in doubt, author inline first and widen only if the labels crowd; a Journal stays prose-led, and a chart that has taken over the page is usually the wrong chart rather than the wrong treatment.

Choosing a Chart

Capability Reference

The rows below mirror the registry the parser and validator read; a regression test keeps this table and the code in step. Fields are the **Key:** lines the type requires; best treatment is guidance, not a constraint.

Every registered Musewoods chart type is available in a Journal; the Journal does not withhold any family. What the Journal restrains is interaction depth, not the chart vocabulary. The Viewgraph-only settings a Journal has no equivalent for are the hero and interpretation layout treatments and the unrestricted explore grammar — a Journal keeps inline and wide, and gates explore to the treemap.

The First-Frame Rule

The static rendering is the whole finding. A reader looking at a printout, a screenshot, or a screen reader announcing the Alt text must reach the same conclusion as a reader who can hover for exact values. Interaction may add precision and exploration may test a structure, but neither may carry meaning that the first frame omits.

The first frame tells. Interaction reveals. Exploration tests.

A Journal chart earns its place when a specific data relationship is load-bearing for the sentence beside it. If the prose can carry the point on its own, the chart is decoration and should be cut. One figure, one analytical job, read in sequence with the argument — that is what keeps a gallery like this one a Journal rather than a dashboard.