Axis

The axis grammar lives in one file directly under your plot's config (margins have their own file beside it):

plot_name
├── config
│   ├── axis                    => The axis grammar (this page)
│   ├── margins                 => Surface margins (own format)

An axis is a stack of lanes over one scale. Each non-empty line of the axis file is one lane: a filter that selects domain values, plus properties that say what to draw for them — marks, labels, a gridline, a shaded band. Months and years under a time axis are two lanes; a grid is a lane; a recession band is a lane.

The line grammar

<axis>[+] [domain] [selection] [key:value ...]

Two positional filter slots, like d3's domain/range split: the domain declares the axis's coordinate span, the selection picks values within it for this lane's furniture. One filter token is always the selection; the domain slot exists only in the two-token form:

x 2000:2030 ::5y  f:%Y      -- domain: 30 years; label every 5 across it
y 0:100 ::25      f:,.0f    -- domain 0-100, ticks every 25
x ::5y            f:%Y      -- selection only; domain stays at its default

• Lines are whitespace-tokenized. -- starts a comment. Blank lines are ignored. A lane dies only with its axis token: an invalid property is dropped while the rest of its line survives, and so is an invalid filter, whose slot falls back to auto. A half-typed key reports as one, so adding a property to a line never blanks the axis mid-keystroke.
• Values containing whitespace are quoted — '…' or "…", the opener naming the closer: f:"%b %Y", l:'Net flow'.
• Keys and axis tokens are case-insensitive; formats are case-sensitive. Category names match case-insensitively with spaces as underscores.
• The filter is optional and defaults to : (everything / auto).

Numbers are rail ordinals, not sides — a rail is a full axis, and there is no upper bound. The side is the e: property on each line (e:l|r on y, e:b|t on x; defaults left/bottom): lanes partition by (family, side) before any rail rule applies, so e:r on one line never moves another line's furniture, and ordinals count per side (y2 e:r is the second rail of the right side). Rails sharing a side stack visibly outward in ordinal order. The primary rail — the innermost rail of the default side, or of the only side present — owns the plot scale; every other rail inherits it (ruler-style stacking) or declares a numeric domain of its own — a reading rail that relabels the same pixels (°F beside °C) without ever re-windowing the plot.

Special forms: y e:r mirror duplicates the opposite side's innermost rail on this side (crossed-axis offsets swap, so outward space stays outward); x none owns the axis and renders nothing (suppresses the default axes, see Defaults); cut turns a lane's marks into holes instead of ink (see Cut lanes).

Cut lanes

cut makes the lane's marks paint holes through everything the plot has drawn below the lane — series, gridlines, chrome — instead of ink. A hole reads as the page background with no colour named, so a cut divider is correct in every theme, in dark mode, and over an unknown host page by construction, where a c:-painted line would need the right colour picked for each context.

Unlike none and mirror, cut is a mode, not a whole-lane claim: it is a bare keyword on an ordinary rail line, written anywhere among the filters (x cut ::2 and x ::2 cut are the same lane), and the lane's filters, slices and geometry properties compose exactly as on a painted lane — ta: makes a dashed hole, tw: sets its width, and the lane's labels still render normally. The shipped price/volume divider is one line:

y2 ts:-100% z:over cut tw:1   -- a full-bleed divider that cuts through

• By default the cut removes from the entire stack below the lane; z:over states that intent explicitly. An explicit z:under scopes the holes to bands and the under-plot gridlines only — legal, but nearly invisible since the series sits above it, and diagnosed as such.
• Mark colours (tc:, dc:, fill:) have no ink to colour on a cut lane and drop with a diagnostic; c: survives, since it still colours the lane's labels.
• cut is not amendable (a + x line drops it), does not combine with none or mirror, and is not supported on the frame o.

The domain

The domain slot is a single stepless range (a:b, _, or :); endpoints are literals, value tokens, or _ (data-anchored). It is axis-level (last declaration wins; all rails of a family share rail 1's plot domain), and declaring one replaces the default — the zero-config domain is the data extent, zero-clamped on value axes, so y i:x : gives a terminal-style data-tight scale and y 50:200 : is the zoom. Data outside the domain clips; a domain wider than the data is legal and central (projection space). Selections can never re-window a chart — only domains can.

Bars and areas truncate at the window edge: under a domain that excludes zero the base rests on the edge instead of projecting toward raw zero, so y _ : over strictly positive data gives truncated bars.

Selections

A selection is a comma-separated union of atoms, written in the axis's own domain units — numbers on value axes, dates on time axes, category names or positions on categorical axes.

Steps are numbers on value axes, frequencies on time axes (s, min, h, d, w, m, q, y, with multiples like 15min, 6h, 2w, and 2q, and anchors like y@oct for fiscal years or w@mon for week start), and integer positions on categorical axes (0:_:5 = every 5th category; negatives count from the end, so 0:_:5,-1 adds the last).

sp: controls the spacing independently of the ticks. Use the matching period spacing when each second, minute, hour, or week should occupy one equal-width slot (including empty periods between data points):

x s f:%H:%M:%S sp:s
x min f:%H:%M sp:min
x h f:"%b %d %H:%M" sp:h
x w f:"%b %d" sp:w

Value tokens stand in for data-derived values anywhere a value can appear: i (min), x (max), e (median), a (mean), f (first row), l (last row), _ (contextual endpoint). y i,x labels only the data extremes.

Filters select from your data, not from the calendar. A monthly filter over business-day data snaps to real rows and never emits a weekend tick; periods with no data emit nothing.

Wide domains and sparse data

Period selections partition the domain; each boundary snaps to a real row when its period contains one. Dataless periods inside the data still emit nothing (a daily filter never ticks a weekend), but periods entirely outside the data extent emit their calendar boundaries — so x 2000:2030 ::5y f:%Y stays labelled across an axis far wider than the data. Range amends pair with this: + x i:x tx:b emphasizes the labels where the data actually lives, and x x:_ fill:gray-100 shades from the data max to the domain end.

Properties

Line-local unless marked axis-level (last one wins across the axis). Prefixes name the thing (t tick, tl tick label, d domain, l the axis's own label); suffixes name the property (size, width, color, dash-array, position, format, overflow, rotation, backing, extent). c: and tx: are generic: they style whatever the line draws.

Labels

Labels have two positioning dimensions. tlp: moves text along the domain; tls: moves it across the axis:

y   ::20  ts:-100% c:gray-200          -- gridlines
y2  e:r ::20  f:,.0f  ts:0  tls:in,3  tlp:end
--  labels on the right, inside the plot, sitting just above their line

Labels placed inside the plot get an automatic background plate so they stay legible over gridlines and bars (tlb:0 disables it). The first and last labels of a lane snap inward automatically when centring would hang past the plot edge; an explicit tlp: opts out.

Every line with a format and tls:out claims the next label row outward, so two label lanes make a two-row axis:

x m   f:%b
x y   f:%Y  tlp:start
--   Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
--   2026

Amending a lane

An axis token with + edits labels inside the previous label lane's row instead of opening a new one. Where the base lane has a label at the selected value the amend overrides it; elsewhere it inserts. Within an amend filter, f and l mean the base lane's first and last label:

x   y  f:'%y  tlp:start
+ x f  f:%Y            -- first year in full: 2019 20 21 22

y   0:_:200  f:,.0f  ts:0
+ y l  f:"{$,.0f} billion"   -- unit on the top label only

+ x 2020,2024  tx:b    -- no format: just bold those two labels

Use : to match the base lane's complete rendered set, then a second positional token to slice those results. Negative positions count from the end:

y 160:240 ~5 f:$,.0f ts:0
+ y : -1 c:red-500 f:"{$,.0f} per share"

Titles

l: sets the axis title, lp: places it. lp:top (the y default) renders a horizontal unit line above the labels; start/mid/end run along the axis:

y  l:"Percent of GDP"  lp:top
x  l:"GDP per capita →"  lp:end

The title takes the labels grammar's letters as satellites — the same keys place a data label, a strip label and a title, so you learn them once:

y  l:"Streamflow"  lp:mid lr:-90      -- the classic vertical y title
y  l:"Index"  lp:mid lr:-90 le:r      -- ...docked on the right edge
y  l:"per capita"  lp:end li:in       -- overlaid inside the plot
y  l:"Price"  le:tl li:in lm:5        -- inside the top-left corner
x  l:"Month"  le:t lm:6               -- above the plot, 6px off

Marks, gridlines and paint order

A gridline is a tick that crosses the plot: ts:-100%. When two lines of the same axis put a mark at the same value, the later line's mark replaces the earlier one — restyle a single gridline by overpainting it:

y ::25  ts:-100%  c:gray-200
y 0     ts:-100%  c:gray-500     -- the zero line wins

Paint order is fixed: bands, then gridlines, then your data, then z:over gridlines, then ticks, domain lines and the frame, then labels and titles.

Bands

fill: shades the filtered interval(s) of the domain across the plot:

x 2020-02:2020-04,2022-06:2022-10  fill:gray-100,gray-800   -- two bands
y 2:3        fill:green-100,green-900                       -- a target range
x ::10y      fill:gray-100                                  -- alternating decades

Explicit ranges shade exactly those spans; stepped filters shade alternating periods (zebra). Bands paint below everything and never widen the window.

Defaults

An empty axis file behaves as this implicit program — a sketch, not a paste-able file: ~auto stands in for the automatically chosen tick count, whereas in a real file ~ always takes a number (~5):

x :      f:auto  an:0     ts:6  dw:1
y ~auto  f:auto  an:edge  ts:6  dw:1

Touch an axis, own it: your first line for an axis replaces that axis's defaults entirely — x m f:%b gives month labels and nothing else on x; add dw:1 back if you want the domain line. Other axes keep their defaults. f:auto keeps the automatic format while you change placement or style.

Examples

FT-style index chart:

y   60:140 ::20      ts:-100%  c:#ccc1b7
y   100              ts:-100%  c:#66605c        -- index base line
y2  e:r ::20        f:,.0f  ts:0  tls:in,3  tlp:end
y2  l:"Index, 2019 = 100"  lp:top
x   q                f:%b  ts:3
x   y                f:'%y  tlp:start
+ x f                f:%Y
x   2020-02:2020-04  fill:#e8dcd2

Fiscal-year briefing chart:

y   -8:_ ::4   f:,.0f  ts:0  tx:600,2xl
y   0          ts:-100%  c:inverse
y   l:"Percent of GDP"  lp:top
x   2000:2036:4y@oct  f:%fy  tx:600,2xl
x   2026-10    ts:-100%  ta:6,3  c:gray-500
x   2026-10:_  fill:gray-100

Extremes-only minimal axis:

y  i,x   f:,.1f  ts:4  dw:1  de:data
x  f,l   f:"%b %Y"  ts:0

Log decades:

y  1:_ ::*10  f:,.0f  sc:log

Rankings, best on top:

y  1:10 ::1  f:,.0f  dir:rev

Margins

Explicit plot margins live in their own file, config/margins — see the

margins page. What an axis author needs to know: an explicit margin is exact and doubles as the wrap budget for tlo:w labels; unstated sides are auto, the measured autocompute.