The Grammar of Graphics Assembles

R, Python, SQL… and Now TYPST

Mickaël CANOUIL, Ph.D.

2026-06-30

Issue 01Origin Story

Every hero starts with a problem nobody else will fix.

The Dark Past

• Different fonts between prose and figure.
• Different colour palettes: slide theme vs. plot theme.
• Two render passes, document and figure compiled separately.
• No shared layout, so figure margins are guesswork.

Gribouille

#figure(
  plot(data: penguins, ...),
  caption: [Figure 1.],
)

R / Python + import

ggplot(penguins) + ...
ggsave("fig.svg")

#image("fig.svg")

The scars every figure carried, workflow after workflow.

The Spark

Before the powers, the ordinary day job.

With Typst Render I can render any Typst content straight into Quarto.

But, why do I still need to use R or Python to draw a plot?

What if one engine compiled the figure and the prose?

The Spark

• I wanted a plot from a CSV: no kernel, no session, no heavy dependencies.
• Typst was already compiling diagrams for me. Why not the plot too?

A grammar of graphics… inside a database?

Why not inside a document compiler.

Last year, ggsql brought the grammar into SQL.

Gribouille was born of necessity, not ambition.

Issue 02The Graphing API

Wilkinson’s grammar, native to Typst.

data + aes()

#import "@preview/gribouille:0.4.1": *

#plot(
  data: penguins,
  mapping: aes(x: "bill-len", y: "bill-dep"),
  layers: (geom-blank(),),
  labels: labels(x: "Bill Length (mm)", y: "Bill Depth (mm)"),
  theme: theme-comic(),
  width: auto,
  height: auto,
)

One line to import. No R session, no Python environment.
It is a Typst Universe package.

+ geom-point()

layers: (geom-point(size: 2pt),),

+ aes(fill = “species”)

mapping: aes(x: "bill-len", y: "bill-dep", fill: "species"),
scales: (scale-fill-discrete(palette: comic-colours),),

+ facet-wrap(“species”)

facet: facet-wrap("species"),

compose()

compose(
  defer(plot, ...)),
  defer(plot, ...)),
  columns: 2,
  labels: labels(title: comic-title("Palmer Penguins: Morphometrics")),
  collect: ("fill",),
)

Typst has no lazy evaluation, so defer() captures the plot spec without rendering it yet.

annotate(“typst”, …)

annotate(
  "typst", ...,
  label: [#box(inset: 8pt, fill: rgb("#ffd60a"), stroke: 2pt + rgb("#0b0b0b"))[_Typical_ Chinstrap]],
  anchor: "west",
  size: 14pt,
  clip: false
),

Pure Typst content — no new API needed.

Issue 03Faithful, and Not

Same grammar, different runtime.

Adherence vs. Departure

Faithful to ggplot2

• aes() mapping.
• Layered geom* / stat*.
• scale*, facet*, coord*.
• guides(), theme*.
• Layers stack in draw order.

Departs by necessity

• kebab-case: geom-point, stat-identity.
• No + operator: one plot() call with named args (layers, scales, facet).
• Marker body is fill, outline is colour.
• labels() not labs(); avoid abbreviations.

ish

The vocabulary is stable. The question was never “what should the API look like?” It was “how do I wire it to Typst?”

The Pipeline

The departures are not arbitrary. They reflect how Typst works.

• Typst has no objects. Every construct — plot(), aes(), geom-*, scale-* — builds a spec dict.
• render.typ walks a fixed pipeline:

Each stage receives dicts, transforms them, passes dicts forward. The final stage emits a CeTZ canvas.

Payoff: One Engine

The figure stops being a tourist.

The integration an SVG import can never close

Figure and prose are compiled by the same engine, in one pass. Switch the document theme and the figures follow. Annotate, caption, and cross-reference the plot like any other element.

Same Engine!

Typst

Issue 04Built With AI, 2026

Porting a grammar with agentic tools.

Timeline

Manual first. AI later, once it was safe to.

Plan, then hand-build

• Grammar and theme API design.
• cetz as the drawing layer.
• Core written and reviewed by hand.
• Tests, snapshots, docs, until the architecture was safe to automate on.

Then accelerate

• LLMs with proper guardrails.
• Heavy Human review.
• v0.1.0: May 20.
• v0.2.0: June 1.
• v0.3.0: June 14.
• v0.4.0: June 22.
• v0.4.1: June 23 (current).

Really!

v0.4.1

Earn the Right to Automate

1. Hand-build

Core grammar coded, edited, and reviewed manually. No AI on an unstable foundation.

2. Harden

Tests, snapshots, documentation: the guardrails that make change safe.

3. Accelerate

Only then bring in LLMs, to speed up well-bounded work.

What carried, what didn’t

Stable vocabulary ported cleanly, a good LLM target.
AI stumbled on Typst’s no-lazy-eval model, cetz primitives, and scale/stat edge cases.
Human review caught it.

manual

guardrails

Issue 05Where It Stands

v0.4.1

Rising Out of the Shadows

What Ships, What Doesn’t

• Geoms: point, line, bar, col, area, boxplot, ribbon, histogram, contour, hex, tile, text, smooth, rug …
• Scales: continuous, discrete, manual; brewer, viridis, okabe-ito, gradient; size, alpha, shape …
• Themes: grey, minimal, classic, bw, void, linedraw, light, dark.

Not there (yet)

• Static output only.
• Performance at scale not benchmarked.
• Not all geoms/stats ported: maps and complex stat pipelines (WASM possible).

Where to Help

Feedback is welcome:

• Bug reports: the test suite is young, edge cases are still being found as I use Gribouille, e.g., m.canouil.dev/tidytuesday
• Documentation examples: a lot of dummy examples, but a few “real” examples.

Gribouille is an unfunded spare-time project, and parts of the API are still settling.
Pull requests are not being accepted for now.

Links

Gribouille is a scribble today.
The grammar is stable enough to build on.

• Typst Universe — @preview/gribouille:0.4.1
• Docs — m.canouil.dev/gribouille
• GitHub — github.com/mcanouil/gribouille
• This talk — https://m.canouil.dev/2026-ggplot2-extenders-gribouille/
• TidyTuesday — m.canouil.dev/tidytuesday

v0.4.1

Thank you.