1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
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)),)
```
|
