aboutsummaryrefslogtreecommitdiff
path: root/2026/2026-05-17-gribouille/gribouille-skill/references
diff options
context:
space:
mode:
Diffstat (limited to '2026/2026-05-17-gribouille/gribouille-skill/references')
-rw-r--r--2026/2026-05-17-gribouille/gribouille-skill/references/geom-table.md139
-rw-r--r--2026/2026-05-17-gribouille/gribouille-skill/references/scale-table.md217
2 files changed, 356 insertions, 0 deletions
diff --git a/2026/2026-05-17-gribouille/gribouille-skill/references/geom-table.md b/2026/2026-05-17-gribouille/gribouille-skill/references/geom-table.md
new file mode 100644
index 0000000..5f2721e
--- /dev/null
+++ b/2026/2026-05-17-gribouille/gribouille-skill/references/geom-table.md
@@ -0,0 +1,139 @@
+# Gribouille Geom Reference
+
+Full parameter reference for every geom exported in `lib.typ`. All parameters verified against source code.
+
+Columns: **Geom** | **Primary aes channels** | **Key params** | **Best used when**
+
+---
+
+## Point / scatter family
+
+| Geom | Primary aes | Key params | Best used when |
+|---|---|---|---|
+| `geom-point` | x, y, colour, fill, shape, size, alpha | `size` (default auto), `stroke` (outline), `alpha`, `shape` | Scatter plots; discrete x vs continuous y |
+| `geom-jitter` | x, y, colour, fill, shape, size, alpha | `size`, `stroke: 0.5pt`, `fill`, `colour`, `alpha`, `shape`; position defaults to `"jitter"` | Overplotted categoricals; combine with `geom-boxplot` |
+| `geom-count` | x, y, colour, fill, shape | `size: 3pt`, `stroke: none`, `fill`, `colour`, `alpha`, `shape` | Overplotted integer grids; size encodes count |
+| `geom-dotplot` | x, fill | `bins: 30`, `binwidth`, `dotsize: 1.0`, `stackratio: 1.0`, `fill`, `colour`, `stroke`, `alpha` | Dot histogram; alternative to `geom-histogram` |
+| `geom-rug` | x, y, colour | `sides: "bl"` (b=bottom, l=left, t=top, r=right), `length: 0.15cm`, `stroke: 0.4pt`, `colour`, `alpha` | Marginal data density; stack with another geom |
+
+## Line / path family
+
+| Geom | Primary aes | Key params | Best used when |
+|---|---|---|---|
+| `geom-line` | x, y, colour, linetype, alpha | `stroke: 0.8pt`, `colour`, `alpha`, `linetype` | Time series; connected data sorted by x |
+| `geom-path` | x, y, colour, linetype | `stroke: 0.8pt`, `colour`, `alpha`, `linetype` | Lines connected in data-row order (not sorted by x) |
+| `geom-step` | x, y, colour, linetype | `direction: "hv"\|"vh"\|"mid"`, `stroke: 0.8pt`, `colour`, `alpha`, `linetype` | Step functions; ECDF; survival curves |
+| `geom-area` | x, y, fill, alpha | `colour`, `fill`, `stroke: none`, `alpha` | Area under a line; stacked areas |
+| `geom-ribbon` | x, ymin, ymax, fill | `colour`, `fill`, `stroke: none`, `alpha` | Confidence bands; prediction intervals; pair with `geom-line` |
+| `geom-freqpoly` | x, colour, linetype | `bins: 30`, `binwidth`, `stroke: 0.8pt`, `colour`, `alpha`, `linetype` | Overlapping distributions as lines; alternative to `geom-histogram` |
+
+## Bar / column family
+
+| Geom | Primary aes | Key params | Best used when |
+|---|---|---|---|
+| `geom-bar` | x, fill, colour, alpha | `width: 0.9`, `colour`, `fill`, `stroke: none`, `alpha`, `position: "stack"` | Count bars; map `x` only, gribouille counts automatically |
+| `geom-col` | x, y, fill, colour, alpha | `width: 0.9`, `colour`, `fill`, `stroke: none`, `alpha`, `position: "identity"` | Pre-aggregated bar values; map both `x` and `y` |
+| `geom-histogram` | x, fill, colour, alpha | `bins: 30`, `binwidth`, `width: 1.0`, `colour`, `fill`, `stroke: none`, `alpha`, `position: "stack"` | Continuous variable distribution; requires `x` mapping |
+
+## Distribution summary family
+
+| Geom | Primary aes | Key params | Best used when |
+|---|---|---|---|
+| `geom-boxplot` | x, y (or y alone), fill, colour | `width: 0.6`, `colour`, `fill`, `stroke: 0.6pt`, `alpha`, `outlier-size: 1.8pt`, `outlier-colour: auto`, `whisker-cap: 0.5` | Distribution summary by group |
+| `geom-errorbar` | x, ymin, ymax, colour | `width: 0.4` (cap span; number=data units, length=panel units), `stroke: 0.8pt`, `colour`, `alpha`, `linetype: "solid"` | Vertical error bars |
+| `geom-errorbarh` | y, xmin, xmax, colour | `height: 0.4` (cap span), `stroke: 0.8pt`, `colour`, `alpha`, `linetype: "solid"` | Horizontal error bars |
+| `geom-linerange` | x, ymin, ymax, colour | `stroke: 0.8pt`, `colour`, `alpha`, `linetype: "solid"` | Vertical range lines without caps |
+| `geom-crossbar` | x, y, ymin, ymax, fill, colour | `width: 0.6`, `colour`, `fill`, `stroke: 0.6pt`, `middle-stroke: 1.2pt`, `alpha` | Box without whiskers or outliers |
+| `geom-pointrange` | x, y, ymin, ymax, colour | `size: 2.5pt`, `stroke: 0.8pt`, `colour`, `fill`, `alpha`, `linetype: "solid"` | Point with range line |
+| `geom-smooth` | x, y, colour, fill | `method: "lm"` (only option in v1), `se: true` (show ribbon), `alpha: auto` (ribbon alpha), `level: 0.95` (CI level), `stroke: 1pt`, `colour`, `fill`, `linetype` | Fitted trend + optional confidence ribbon |
+| `geom-quantile` | x, y, colour, linetype | `quantiles: (0.25, 0.5, 0.75)`, `n-samples: 64`, `stroke: 0.6pt`, `colour`, `alpha`, `linetype`, `linewidth` | Quantile regression lines |
+
+## Annotation family
+
+| Geom | Primary aes | Key params | Best used when |
+|---|---|---|---|
+| `geom-text` | x, y, label, colour, alpha | `size: 8pt`, `colour`, `alpha`, `anchor: "center"` (CeTZ anchor), `dx: 0`, `dy: 0` | Data labels at point positions |
+| `geom-label` | x, y, label, colour, fill | `size: 8pt`, `colour`, `fill`, `stroke: 0.4pt`, `alpha`, `inset: 2pt`, `radius: 1pt`, `anchor: "center"`, `dx: 0`, `dy: 0` | Text with background box; callout labels |
+| `geom-typst` | x, y, label (Typst content) | `size: 10pt`, `colour`, `alpha`, `anchor: "center"`, `dx: 0`, `dy: 0`, `label: none` | Arbitrary Typst content at data coordinates |
+| `geom-hline` | yintercept | `yintercept` (scalar or array), `colour`, `stroke: 0.6pt`, `alpha`, `linetype: "solid"` | Horizontal reference line; does NOT inherit plot mapping |
+| `geom-vline` | xintercept | `xintercept` (scalar or array), `colour`, `stroke: 0.6pt`, `alpha`, `linetype: "solid"` | Vertical reference line; does NOT inherit plot mapping |
+| `geom-abline` | slope, intercept | `slope: 1`, `intercept: 0`, `colour`, `stroke: 0.6pt`, `alpha`, `linetype: "solid"` | Diagonal reference (y = a + bx); does NOT inherit plot mapping |
+| `geom-segment` | x, y, xend, yend, colour | `stroke: 0.8pt`, `colour`, `alpha`, `linetype: "solid"` | Line segments between two data points |
+| `geom-curve` | x, y, xend, yend, colour | `curvature: 0.5`, `angle: 90deg`, `n: 32`, `stroke: 0.8pt`, `colour`, `alpha`, `linetype: "solid"` | Curved connectors |
+| `geom-rect` | xmin, xmax, ymin, ymax, fill, colour | `colour`, `fill`, `stroke: none`, `alpha` | Shaded rectangular regions; highlight bands |
+| `geom-polygon` | x, y, fill, colour, group | `colour`, `fill`, `stroke: none`, `alpha` | Arbitrary filled polygons; map outlines |
+| `geom-blank` | — | `mapping: none`, `data: none` | Reserve plot area without drawing; useful for setting axis limits |
+
+## Group / density family
+
+| Geom | Primary aes | Key params | Best used when |
+|---|---|---|---|
+| `geom-mark` | colour, fill | `method: "rect"\|"circle"\|"ellipse"\|"hull"`, `expand: 0pt` (padding), `n: 64` (ellipse smoothness), `colour`, `fill`, `stroke: 0.5pt`, `alpha` | Group outlines; convex hull or enclosing shape per group |
+| `geom-ellipse` | x, y, colour, fill | `a: 1`, `b: 1` (semi-axes), `angle: 0`, `n: 64` (polygon segments), `colour`, `fill`, `stroke: none`, `alpha` | Manually sized ellipses at group centroids |
+
+## 2D density / grid family
+
+| Geom | Primary aes | Key params | Best used when |
+|---|---|---|---|
+| `geom-tile` | x, y, fill, colour | `width: 1`, `height: 1`, `colour`, `fill`, `stroke: none`, `alpha` | Heatmaps; requires pre-computed fill values |
+| `geom-bin-2d` | x, y, fill | `bins: 30`, `binwidth`, `colour`, `fill`, `stroke: none`, `alpha` | 2D histogram; bins both x and y |
+| `geom-hex` | x, y, fill | `bins: 30`, `binwidth`, `colour`, `fill`, `stroke: none`, `alpha` | Hexagonal binning; alternative to scatter for large N |
+| `geom-contour` | x, y, z, colour, linetype | (no user params beyond mapping) | Topographic contour lines on a regular grid |
+| `geom-contour-filled` | x, y, z, fill | (no user params beyond mapping) | Filled contour regions |
+
+## Specialised family
+
+| Geom | Primary aes | Key params | Best used when |
+|---|---|---|---|
+| `geom-spoke` | x, y, angle, radius | Fixed params: `angle: 0deg`, `radius: 1`, `stroke: 0.8pt`, `colour`, `alpha`, `linetype: "solid"` | Wind rose / directional vector field |
+| `geom-qq` | sample | `size`, `stroke: none`, `fill`, `colour`, `alpha`, `shape`, `distribution: "normal"` | Q-Q scatter plot |
+| `geom-qq-line` | sample | `stroke: 0.8pt`, `colour`, `alpha`, `linetype`, `distribution: "normal"` | Reference line for `geom-qq` |
+| `geom-function` | — | `fun` (callable `x => y`), `n: 101`, `xlim: none` (overrides x-domain), `stroke: 0.8pt`, `colour`, `alpha`, `linetype: "solid"`; does NOT inherit aes | Draw y = f(x) curve; no data needed |
+
+---
+
+## Stat helpers (used inside geoms via `stat:` param)
+
+Note: most geoms accept `stat: "identity"` (default) or a stat object. The common pattern is to use the geom's default stat.
+
+| Stat | Created by | Key params | Notes |
+|---|---|---|---|
+| `stat-bin(...)` | `geom-histogram` default | `bins: 30`, `binwidth: none` | Bin continuous x into counts |
+| `stat-count` | `geom-bar` default | — | Count rows per x level |
+| `stat-boxplot` | `geom-boxplot` default | — | Five-number summary per group |
+| `stat-smooth` | `geom-smooth` default | `method: "lm"`, `se: true`, `level: 0.95` | Fit linear model |
+| `stat-sum` | `geom-count` default | — | Count overlapping points |
+
+---
+
+## Position adjustments
+
+Pass these as the `position:` argument in geoms. String shortcuts (`"stack"`, `"dodge"`, `"fill"`, `"jitter"`, `"identity"`) also work.
+
+| Position | Key params | Notes |
+|---|---|---|
+| `position-stack()` | — | Stacked bars/areas |
+| `position-fill()` | — | 100% stacked bars |
+| `position-dodge(width: 0.9, padding: 0.1)` | `width`, `padding` | Side-by-side bars |
+| `position-jitter(width: 0.4, height: 0.4, seed: 0)` | `width`, `height`, `seed` | Jitter points |
+| `position-jitterdodge(...)` | `jitter.width`, `dodge.width` | Jitter within dodge |
+| `position-nudge(x: 0, y: 0)` | `x`, `y` | Offset text/labels |
+| `position-identity()` | — | No adjustment (default) |
+
+---
+
+## `geom-text` / `geom-label` anchor values
+
+Both `geom-text` and `geom-label` use CeTZ anchors, not ggplot2-style hjust/vjust:
+
+| Anchor | Meaning |
+|---|---|
+| `"center"` | Centred on point (default) |
+| `"north"` | Above point |
+| `"south"` | Below point |
+| `"east"` | Right of point |
+| `"west"` | Left of point |
+| `"north-east"` | Upper-right |
+| `"south-west"` | Lower-left |
+
+Use `dx` and `dy` (numbers in canvas units where 1 = 1cm, or Typst lengths) for fine offsets.
diff --git a/2026/2026-05-17-gribouille/gribouille-skill/references/scale-table.md b/2026/2026-05-17-gribouille/gribouille-skill/references/scale-table.md
new file mode 100644
index 0000000..dfed574
--- /dev/null
+++ b/2026/2026-05-17-gribouille/gribouille-skill/references/scale-table.md
@@ -0,0 +1,217 @@
+# Gribouille Scale Reference
+
+Full parameter reference for every scale family exported in `lib.typ`. All parameters verified against source code.
+
+Columns: **Scale** | **Aesthetic** | **Key params** | **When to use**
+
+---
+
+## Position scales — x axis
+
+| Scale | Aesthetic | Key params | When to use |
+|---|---|---|---|
+| `scale-x-continuous(name, limits, breaks, labels, transform: "identity", expand, secondary)` | x | `name`, `limits`, `breaks`, `labels`, `transform` | Override x axis ticks, labels, or limits |
+| `scale-x-log10(name, limits, breaks, labels)` | x | `name`, `breaks`, `labels` | Log₁₀ x axis; data must be positive |
+| `scale-x-sqrt(name, limits, breaks, labels)` | x | `name`, `breaks`, `labels` | Square-root x axis |
+| `scale-x-reverse(name, limits, breaks, labels)` | x | `name` | Reverse x direction |
+| `scale-x-binned(name, limits, n-breaks: 10, labels)` | x | `n-breaks`, `labels`, `limits` | Bin continuous x into discrete intervals |
+| `scale-x-discrete(name, limits, labels, expand)` | x | `limits` (reorder levels), `labels` | Force discrete x; reorder categories |
+| `scale-x-date(name, limits, breaks, labels, date-format, expand)` | x | `date-format` (Typst datetime.display pattern) | Date x axis; values as numeric days since 2000-01-01 or ISO-8601 strings |
+| `scale-x-datetime(...)` | x | same as `scale-x-date` | Datetime x axis |
+| `scale-x-time(...)` | x | same as `scale-x-date` | Time-of-day x axis |
+
+## Position scales — y axis
+
+| Scale | Aesthetic | Key params | When to use |
+|---|---|---|---|
+| `scale-y-continuous(name, limits, breaks, labels, transform: "identity", expand, secondary)` | y | same as `scale-x-continuous` | Override y axis |
+| `scale-y-log10(name, limits, breaks, labels)` | y | `name`, `breaks`, `labels` | Log₁₀ y axis |
+| `scale-y-sqrt(...)` | y | — | Square-root y axis |
+| `scale-y-reverse(...)` | y | — | Flip y direction |
+| `scale-y-binned(name, limits, n-breaks: 10, labels)` | y | `n-breaks`, `labels` | Bin continuous y |
+| `scale-y-discrete(name, limits, labels, expand)` | y | `limits`, `labels` | Force discrete y |
+| `scale-y-date(...)` | y | `date-format`, `limits`, `breaks` | Date y axis |
+| `scale-y-datetime(...)` | y | same | Datetime y axis |
+| `scale-y-time(...)` | y | same | Time-of-day y axis |
+
+---
+
+## Colour scales (discrete)
+
+| Scale | Aesthetic | Key params | When to use |
+|---|---|---|---|
+| `scale-colour-discrete(name, palette, limits, labels)` | colour | `palette` (array of colours or `auto`), `limits` | Custom discrete colour palette |
+| `scale-colour-manual(values, name, limits, labels)` | colour | `values` (array of colours or dict `level -> colour`) | Explicit named mapping |
+| `scale-colour-identity(name)` | colour | — | Colour column holds literal colour values |
+| `scale-colour-okabe-ito(name, limits, labels)` | colour | — | Colourblind-safe 8-colour discrete palette |
+| `scale-colour-hue(hue, chroma, luminance, name, limits, labels)` | colour | `hue` (range, e.g. `(15deg, 375deg)`), `chroma: 100`, `luminance: 65` | Hue-based palette; tune saturation |
+| `scale-colour-grey(start, end, name, limits, labels)` | colour | `start: 0.2`, `end: 0.8` (grey levels 0–1) | Greyscale discrete |
+| `scale-colour-brewer(palette, name, limits, labels)` | colour | `palette: "Set1"` (ColorBrewer palette name) | ColorBrewer palettes |
+
+## Colour scales (continuous)
+
+| Scale | Aesthetic | Key params | When to use |
+|---|---|---|---|
+| `scale-colour-continuous(name, palette, limits, breaks, labels)` | colour | `palette` (gradient or colour array) | Continuous colour from palette |
+| `scale-colour-gradient(low, high, name, limits, breaks, labels)` | colour | `low: rgb("#132B43")`, `high: rgb("#56B1F7")` | Simple two-colour gradient |
+| `scale-colour-gradient2(low, mid, high, midpoint, name, limits, breaks, labels)` | colour | `low`, `mid: white`, `high`, `midpoint: 0` | Diverging gradient centred at `midpoint` |
+| `scale-colour-gradientn(colours, name, limits, breaks, labels)` | colour | `colours` (array of 3+ colours) | Multi-stop gradient |
+| `scale-colour-distiller(palette, direction, name, limits, breaks, labels)` | colour | `palette: "Spectral"`, `direction: 1\|-1` | Brewer palettes interpolated to continuous |
+| `scale-colour-steps(low, high, n-breaks, name, limits, labels)` | colour | `low`, `high`, `n-breaks: 5` | Stepped two-colour gradient |
+| `scale-colour-steps2(low, mid, high, midpoint, n-breaks, name, limits, labels)` | colour | `low`, `mid: white`, `high`, `midpoint: 0`, `n-breaks: 5` | Stepped diverging gradient |
+| `scale-colour-stepsn(colours, n-breaks, name, limits, labels)` | colour | `colours`, `n-breaks: 5` | Stepped multi-stop gradient |
+| `scale-colour-fermenter(palette, n-breaks, direction, name, limits, labels)` | colour | `palette: "Spectral"`, `n-breaks: 5`, `direction: 1` | Brewer palettes cut into discrete bins |
+
+## Colour scales (viridis family)
+
+Supported `option` values: `"viridis"` (default), `"magma"`, `"plasma"`, `"inferno"`, `"cividis"`.
+
+| Scale | Aesthetic | Key params | When to use |
+|---|---|---|---|
+| `scale-colour-viridis-c(option, name, limits, breaks, labels)` | colour | `option: "viridis"` | Perceptually uniform continuous colour |
+| `scale-colour-viridis-d(option, name, limits, labels)` | colour | `option: "viridis"` | Perceptually uniform discrete colour |
+| `scale-colour-viridis-b(option, n-breaks, name, limits, labels)` | colour | `option: "viridis"`, `n-breaks: 5` | Perceptually uniform binned colour |
+
+## Fill scales
+
+Every colour scale above has an exact fill counterpart. Replace `colour` with `fill`:
+
+```
+scale-fill-discrete() scale-fill-continuous()
+scale-fill-manual() scale-fill-gradient()
+scale-fill-identity() scale-fill-gradient2()
+scale-fill-okabe-ito() scale-fill-gradientn()
+scale-fill-hue() scale-fill-brewer()
+scale-fill-grey() scale-fill-distiller()
+scale-fill-viridis-c() scale-fill-fermenter()
+scale-fill-viridis-d() scale-fill-steps()
+scale-fill-viridis-b() scale-fill-steps2()
+ scale-fill-stepsn()
+```
+
+---
+
+## Alpha scales
+
+| Scale | Aesthetic | Key params | When to use |
+|---|---|---|---|
+| `scale-alpha-continuous(name, range, limits, breaks, labels)` | alpha | `range: (0.1, 1)` | Map a continuous variable to transparency |
+| `scale-alpha-binned(n-breaks, range, name, limits, labels)` | alpha | `n-breaks: 4`, `range: (0.1, 1)` | Binned (stepped) alpha |
+| `scale-alpha-manual(values, name, limits, labels)` | alpha | `values` (array of 0–1 values) | Explicit alpha per level |
+| `scale-alpha-identity(name)` | alpha | — | Alpha column holds literal 0–1 values |
+
+---
+
+## Size scales
+
+| Scale | Aesthetic | Key params | When to use |
+|---|---|---|---|
+| `scale-size-continuous(name, range, limits, breaks, labels)` | size | `range: (1pt, 6pt)` | Map continuous var to point size |
+| `scale-radius(name, range, limits, breaks, labels)` | size | `range: (1pt, 6pt)` | Alias of `scale-size-continuous`; map to radius |
+| `scale-size-area(name, range, limits, breaks, labels)` | size | `range: (1pt, 6pt)` | Map to area (perceptually correct for magnitude) |
+| `scale-size-binned(n-breaks, range, name, limits, labels)` | size | `n-breaks: 4`, `range: (1pt, 6pt)` | Binned size scale |
+| `scale-size-binned-area(n-breaks, range, name, limits, labels)` | size | `n-breaks: 4`, `range: (1pt, 6pt)` | Binned area scale |
+| `scale-size-identity(name)` | size | — | Size column holds literal length values |
+| `scale-size-manual(values, name, limits, labels)` | size | `values` (array of lengths) | Explicit size per level |
+
+---
+
+## Linewidth scales
+
+| Scale | Aesthetic | Key params | When to use |
+|---|---|---|---|
+| `scale-linewidth-continuous(name, range, limits, breaks, labels)` | linewidth | `range: (0.4pt, 1.4pt)` | Map continuous var to line width |
+| `scale-linewidth-binned(n-breaks, range, name, limits, labels)` | linewidth | `n-breaks: 4`, `range: (0.4pt, 1.4pt)` | Binned linewidth |
+| `scale-linewidth-manual(values, name, limits, labels)` | linewidth | `values` (array of lengths) | Explicit linewidth per level |
+| `scale-linewidth-identity(name)` | linewidth | — | Linewidth column holds literal length values |
+
+---
+
+## Shape / linetype scales
+
+| Scale | Aesthetic | Key params | When to use |
+|---|---|---|---|
+| `scale-shape(name, palette, limits, labels)` | shape | `palette` (array of shape keywords or `auto`) | Discrete point shapes |
+| `scale-shape-manual(values, name, limits, labels)` | shape | `values` (array of shape keywords) | Explicit shape per level |
+| `scale-shape-identity(name)` | shape | — | Shape column holds literal keywords |
+| `scale-shape-binned(n-breaks, palette, name, limits, labels)` | shape | `n-breaks: 4`, `palette` | Binned shape scale |
+| `scale-linetype(name, palette, limits, labels)` | linetype | `palette` (array of dash keywords or `auto`) | Discrete line types |
+| `scale-linetype-manual(values, name, limits, labels)` | linetype | `values` (array of dash keywords) | Explicit linetype per level |
+| `scale-linetype-identity(name)` | linetype | — | Linetype column holds literal keywords |
+| `scale-linetype-binned(n-breaks, palette, name, limits, labels)` | linetype | `n-breaks: 4`, `palette` | Binned linetype scale (continuous var) |
+| `scale-linetype-continuous(name, palette, limits, labels)` | linetype | alias of `scale-linetype-binned(n-breaks: 4)` | Alias |
+| `scale-linetype-discrete(name, palette, limits, labels)` | linetype | alias of `scale-linetype()` | Alias |
+
+Shape keywords: `"circle"`, `"square"`, `"triangle"`, `"diamond"`, `"cross"`, `"x"`, `"star"`, `"triangle-down"`
+
+Linetype keywords: `"solid"`, `"dashed"`, `"dotted"`, `"dash-dotted"`, `"densely-dashed"`, `"loosely-dashed"`
+
+---
+
+## Format helpers (use in `labels:` parameter)
+
+| Function | Output example | Notes |
+|---|---|---|
+| `format-comma()` | 1,234,567 | Thousands separator; best for y-axis with large integers |
+| `format-percent()` | 12.3% | Multiply by 100 and append %; input should be 0–1 |
+| `format-scientific()` | 1.23×10⁴ | Scientific notation |
+| `format-currency()` | $1,234 | Dollar prefix + comma separator |
+| `format-number(digits: N)` | 3.14 | Fixed decimal places |
+| `format-lower()` | lowercase | Convert labels to lowercase |
+| `format-upper()` | UPPERCASE | Convert labels to uppercase |
+| `format-title()` | Title Case | Capitalise each word |
+| `format-wrap(width: N)` | wrapped text | Word-wrap long labels at N characters |
+
+---
+
+## Common patterns
+
+**Large y-axis numbers:**
+```typst
+scales: (scale-y-continuous(labels: format-comma()),)
+```
+
+**Log-log axes:**
+```typst
+scales: (scale-x-log10(), scale-y-log10(),)
+```
+
+**Custom discrete colour palette:**
+```typst
+scales: (
+ scale-colour-manual(
+ values: ("Setosa": rgb("#E69F00"), "Versicolor": rgb("#56B4E9"), "Virginica": rgb("#009E73")),
+ limits: ("Setosa", "Versicolor", "Virginica"),
+ ),
+)
+```
+
+**Colourblind-safe palette:**
+```typst
+scales: (scale-colour-okabe-ito(),)
+```
+
+**Viridis continuous fill for heatmap:**
+```typst
+scales: (scale-fill-viridis-c(option: "viridis"),)
+```
+
+**Diverging colour centred at zero:**
+```typst
+scales: (scale-colour-gradient2(low: blue, mid: white, high: red, midpoint: 0),)
+```
+
+**Reorder discrete x axis:**
+```typst
+scales: (scale-x-discrete(limits: ("small", "medium", "large")),)
+```
+
+**Date axis:**
+```typst
+scales: (scale-x-date(date-format: "[month repr:short] [year]"),)
+```
+
+**Size range for bubble chart:**
+```typst
+scales: (scale-size-area(range: (1pt, 12pt)),)
+```