Core concepts
A template is one component that lays out a whole page from a title, figures and chart specs. It can be written as JSX or as one JSON document.
An atom draws one chart. A molecule combines a few atoms. A template arranges molecules and atoms into a whole page and handles the layout at narrow widths. It takes all of its content as props, so a complete page can be one JSON document written by a person, a CMS or a model.
A one-page summary. It has a headline that states the main finding with its number, a deck, a row of three or four key figures, one hero chart with a takeaway callout, two smaller supporting exhibits, a short list of actions and a source note.
A long article read by scrolling. It has a headline, then an ordered list of blocks in a reading column, then a source note. The blocks are prose, figures, charts with a callout, scrolly sequences, pull quotes, stat rows, small multiples and chapter breaks. Exhibits can be wider than the column.
A recurring report. It has a masthead with the report name and period, a headline that states the main change, a KPI grid with changes and sparklines, a ranked list beside one or two trend charts, an optional comparison table, short notes and a source note.
The catalogue has 20 templates in two groups. 10 are report-style page layouts, covered on this page. 10 are infographics: each draws one designed poster on a painted ground. The infographics guide covers those.
Pick the template that matches what the reader needs from the page. Each template page has a "use when" and an "avoid when" that names the alternative.
| type | What it is | Built from |
|---|---|---|
| comparison-brief | A compared with B on one page. It has a headline that states the result, the headline figures mirrored either side of their labels, one hero exhibit that shows both sides, paired exhibits on a shared scale, a verdict callout and a source note. | atoms only |
| data-explorer | A set of linked charts over one shared dataset that filter each other. It has a headline, a sentence of instructions with filter chips, a row of figures that recompute from the filtered rows, two to four charts and an optional detail table. It opens on selections the author chooses. | Filter chips, Stat row, Linked charts |
| executive-brief | A one-page summary. It has a headline that states the main finding with its number, a deck, a row of three or four key figures, one hero chart with a takeaway callout, two smaller supporting exhibits, a short list of actions and a source note. | Stat row, Chart with callout |
| explainer | A vertical infographic in one narrow column. It opens with a big number or a proportion statement (hook), then the hero exhibit, then numbered sections with one exhibit each, a conclusion with an optional link, and sources. | Proportion statement |
| report-page | A section of an analytical report laid out as a document. It has a title block, a summary, numbered findings, then method, limitations and sources. Each finding has one exhibit, an observation and a separately labelled interpretation with a confidence rating and a caveat. | atoms only |
| scorecard | A recurring report. It has a masthead with the report name and period, a headline that states the main change, a KPI grid with changes and sparklines, a ranked list beside one or two trend charts, an optional comparison table, short notes and a source note. | KPI grid, Ranked list, Comparison table |
| social-card | A graphic that states one fact, at a fixed aspect ratio (1:1, 4:5, 16:9 or 9:16). It has a kicker, a headline, one exhibit, a source and a credit, painted on the theme surface. A button downloads the whole card as a PNG. | atoms only |
| story-deck | A sequence of full-frame cards (title, stat, chart, quote, closing) that the reader swipes or steps through. Each card states one fact. It has an optional fixed aspect ratio, a keyboard-accessible pager and a stacked layout for print. | atoms only |
| timeline-story | A story told in date order. It has a headline, one overview exhibit of the whole period (a timeline chart or an annotated line), dated chapters along a rail, a closing paragraph and a source note. Each chapter has a short text and an optional small exhibit. | Annotated timeline |
| visual-essay | A long article read by scrolling. It has a headline, then an ordered list of blocks in a reading column, then a source note. The blocks are prose, figures, charts with a callout, scrolly sequences, pull quotes, stat rows, small multiples and chapter breaks. Exhibits can be wider than the column. | Chart with callout, Scrolly chart, Small multiple grid, Stat row |
Choose an infographic instead when the piece is one image with little text that is shared as a picture.
This is an executive brief. Open the JSON tab to see the document that produces the whole page.
Support review · Q3
The triage rota began in July. The weekend median was 6.2 hours in September.
Support operations
Median hours to first reply, by month, 2025
Median hours to first reply, September 2025
Share of tickets by channel, September 2025
The weekend median was 6.2 hours in September.
Support · October
The overall median was 1.8 hours in September.
import { ExecutiveBrief, registerAll } from "insightcharts";
// The slot props below are JSON specs. This makes their `type` names resolvable.
registerAll();
export function Example() {
return (
<ExecutiveBrief
kicker="Support review · Q3"
title="Median first reply time fell from 4.1 hours in June to 1.8 hours in September 2025"
deck="The triage rota began in July. The weekend median was 6.2 hours in September."
byline="Support operations"
date="2025-10-06"
figures={[
{
value: "1.8 h",
label: "Median first reply, September",
delta: "−2.3 h",
deltaLabel: "vs June",
upIsGood: false,
},
{
value: 0.92,
format: "percent",
label: "Tickets answered within a day",
delta: "+11 pts",
deltaLabel: "vs June",
},
{ value: 4.6, label: "Satisfaction, out of 5", context: "4.1 in June" },
]}
hero={{
type: "line-chart",
data: [
{ month: "Apr", hours: 4.3 },
{ month: "May", hours: 4.2 },
{ month: "Jun", hours: 4.1 },
{ month: "Jul", hours: 2.9 },
{ month: "Aug", hours: 2.1 },
{ month: "Sep", hours: 1.8 },
],
x: "month",
y: "hours",
format: "{value} h",
zero: true,
title: "Median first reply time fell from 4.3 hours in April to 1.8 hours in September",
subtitle: "Median hours to first reply, by month, 2025",
annotations: [
{ type: "line", axis: "x", value: "Jul", label: "Triage rota begins" },
],
}}
takeaway={{
lead: "The median fell 2.3 hours in three months",
body: "The triage rota began in July. The median was 4.1 hours in June.",
}}
supporting={[
{
type: "bar-chart",
data: [
{ day: "Weekdays", hours: 1.4 },
{ day: "Weekends", hours: 6.2 },
],
x: "day",
y: "hours",
format: "{value} h",
highlight: "Weekends",
title: "Weekend median first reply was 6.2 hours in September",
subtitle: "Median hours to first reply, September 2025",
},
{
type: "bar-chart",
data: [
{ channel: "Chat", share: 48 },
{ channel: "Email", share: 39 },
{ channel: "Phone", share: 13 },
],
x: "channel",
y: "share",
format: "{value}%",
orientation: "horizontal",
title: "Chat was 48% of tickets in September",
subtitle: "Share of tickets by channel, September 2025",
},
]}
actions={[
{
title: "Extend the rota to weekends",
text: "The weekend median was 6.2 hours in September.",
owner: "Support · October",
},
{
title: "Report the weekend median separately",
text: "The overall median was 1.8 hours in September.",
},
]}
sources={["Helpdesk export"]}
period="April to September 2025"
note="Illustrative data"
/>
);
}{
"type": "executive-brief",
"kicker": "Support review · Q3",
"title": "Median first reply time fell from 4.1 hours in June to 1.8 hours in September 2025",
"deck": "The triage rota began in July. The weekend median was 6.2 hours in September.",
"byline": "Support operations",
"date": "2025-10-06",
"figures": [
{
"value": "1.8 h",
"label": "Median first reply, September",
"delta": "−2.3 h",
"deltaLabel": "vs June",
"upIsGood": false
},
{
"value": 0.92,
"format": "percent",
"label": "Tickets answered within a day",
"delta": "+11 pts",
"deltaLabel": "vs June"
},
{ "value": 4.6, "label": "Satisfaction, out of 5", "context": "4.1 in June" }
],
"hero": {
"type": "line-chart",
"data": [
{ "month": "Apr", "hours": 4.3 },
{ "month": "May", "hours": 4.2 },
{ "month": "Jun", "hours": 4.1 },
{ "month": "Jul", "hours": 2.9 },
{ "month": "Aug", "hours": 2.1 },
{ "month": "Sep", "hours": 1.8 }
],
"x": "month",
"y": "hours",
"format": "{value} h",
"zero": true,
"title": "Median first reply time fell from 4.3 hours in April to 1.8 hours in September",
"subtitle": "Median hours to first reply, by month, 2025",
"annotations": [
{ "type": "line", "axis": "x", "value": "Jul", "label": "Triage rota begins" }
]
},
"takeaway": {
"lead": "The median fell 2.3 hours in three months",
"body": "The triage rota began in July. The median was 4.1 hours in June."
},
"supporting": [
{
"type": "bar-chart",
"data": [
{ "day": "Weekdays", "hours": 1.4 },
{ "day": "Weekends", "hours": 6.2 }
],
"x": "day",
"y": "hours",
"format": "{value} h",
"highlight": "Weekends",
"title": "Weekend median first reply was 6.2 hours in September",
"subtitle": "Median hours to first reply, September 2025"
},
{
"type": "bar-chart",
"data": [
{ "channel": "Chat", "share": 48 },
{ "channel": "Email", "share": 39 },
{ "channel": "Phone", "share": 13 }
],
"x": "channel",
"y": "share",
"format": "{value}%",
"orientation": "horizontal",
"title": "Chat was 48% of tickets in September",
"subtitle": "Share of tickets by channel, September 2025"
}
],
"actions": [
{
"title": "Extend the rota to weekends",
"text": "The weekend median was 6.2 hours in September.",
"owner": "Support · October"
},
{
"title": "Report the weekend median separately",
"text": "The overall median was 1.8 hours in September."
}
],
"sources": ["Helpdesk export"],
"period": "April to September 2025",
"note": "Illustrative data"
}Render with import { Insight } from "insightcharts" and <Insight spec={spec} />. Nested specs resolve by name; nothing else to import.
Reading the spec from the top:
type names the template.title, kicker, deck, byline, date are the masthead. The title is one plain statement of the main fact, with its number and period.figures is plain data: three or four objects with the props of big number. The template renders them with a stat row.hero and each entry of supporting are slots: their values are chart specs, each with its own type. A slot takes any component. The template sets a height when the spec does not.takeaway is the callout beside the hero. lead is a short statement in bold and body is one or two sentences under it.actions are numbered recommendations, as strings or { title, text, owner }.sources, period, method, note become the closing source note.The spec contains no functions, so it can be stored, sent over the network and validated.
From JSON, render the spec with Insight. It resolves the template and every nested spec by name.
import { Insight } from "insightcharts";
export function Brief({ spec }) {
return <Insight spec={spec} />;
}In a server component you can load the spec and pass it straight through; it is serialisable.
import { Insight } from "insightcharts";
export default async function Page({ params }) {
const { id } = await params;
const spec = await fetch(`https://example.com/briefs/${id}.json`).then((r) => r.json());
return <Insight spec={spec} />;
}From JSX, import the template by name. Slots take React elements or specs. If you pass specs, call registerAll() once so their type names resolve (see nested specs); if you pass elements, you do not need it.
import { BarChart, ExecutiveBrief, LineChart } from "insightcharts";
<ExecutiveBrief
title="Median first reply time fell from 4.1 hours in June to 1.8 hours in September 2025"
figures={[{ value: "1.8 h", label: "Median first reply, September" }]}
hero={<LineChart data={monthly} x="month" y="hours" title="Median hours to first reply, by month" />}
supporting={[<BarChart key="days" data={byDay} x="day" y="hours" title="Median hours to first reply, weekdays and weekends" />]}
sources={["Helpdesk export"]}
/>Templates use the same prop names for the same content, so content can be moved from one template to another. Most report-style templates have these props:
| Prop | Purpose |
|---|---|
title | The result of the comparison, as one plain sentence with the number in it. |
kicker | Small label above the title. |
deck | One-sentence standfirst. |
byline | Author line. |
date | Publication date. |
sources | Where the data comes from, shown in the closing source note. Entries with a url are linked. |
period | The period the data covers. |
method | How the numbers were produced: definitions, adjustments, exclusions. |
note | Caveats the reader should know, e.g. "Illustrative data". |
credit | Who made the piece. |
level | Heading level of the title; section headings follow one level down. |
maxWidth | Widest the piece may get. It is centred in wider containers. |
theme | Theme override, passed on to everything inside. |
mode | Colour mode, passed on to everything inside. |
theme and mode are passed on to everything inside, so one prop changes the theme of the whole page. A preset that is designed for its own surface needs that surface behind the template; see presets and their surfaces.
Layout follows the width of the template's container, not the viewport: a template in a 400 pixel column lays out as it would on a phone. maxWidth limits the width and centres the template in a wider container.
A chart spec in a slot takes data the way any chart does: inline rows, CSV text, or a URL the browser fetches. In a stored spec, a URL keeps the document small, and the data is fetched each time the page loads.
{
"type": "bar-chart",
"data": "/data/energy.csv",
"transform": [{ "type": "filter", "field": "year", "op": "==", "value": 2024 }],
"x": "source",
"y": "twh"
}Templates that filter several charts together, such as data explorer, take one data prop themselves and share it with the charts inside; those chart specs leave data out. See data for every accepted shape and transform.
Three templates show a sequence of blocks, chapters or cards. Visual essay takes an ordered blocks array, where each block has a kind (prose, figure, callout, scrolly, quote, stats, multiples, break) and a bare chart spec counts as a figure. Timeline story takes dated chapters. Story deck takes cards to step or swipe through.
{
"type": "visual-essay",
"title": "Solar generation rose from 720 TWh in 2020 to 1,960 TWh in 2024",
"blocks": [
{ "kind": "prose", "text": "Hydro generated 3,900 TWh in 2024. Wind generated 2,640 TWh." },
{ "kind": "figure", "chart": { "type": "line-chart", "data": "/data/energy.csv", "transform": [{ "type": "aggregate", "groupBy": ["year", "source"], "measures": { "twh": { "op": "sum", "field": "twh" } } }], "x": "year", "y": "twh", "series": "source" } },
{ "kind": "quote", "quote": "Asia added 790 TWh of solar generation between 2020 and 2024.", "attribution": "Grid planner" }
]
}A scrolly block pins its chart while the steps scroll past, with the same rules as Scrolly: no ancestor of the template may clip overflow.
A template spec is a good thing to ask a model for. The template has already fixed the layout, so the model only writes the titles, figures and chart specs.
/llms/executive-brief.md. The page lists every prop and includes a complete example./schema/insight-spec.json.Insight. An unknown type anywhere in the tree renders an inline alert naming the valid ones, which you can send back to the model.See for AI agents for the other files published for agents.
A template is too large for the preview box used for atoms. On each template page the preview scrolls inside its frame, Expand shows it at full height in place, and Full screen opens it alone at /templates/<name>/preview, for example the executive brief. The width, theme and mode controls work in all three.
An infographic page has a different toolbar. The theme menu lists the eight poster themes, a Download PNG button saves the poster, and there is no light and dark switch because a poster paints its own ground.