plot-io 0.1.0__tar.gz → 0.3.0__tar.gz

{plot_io-0.1.0 → plot_io-0.3.0}/API.md

@@ -22,28 +22,33 @@ Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
   in any order.
 * **Settings.** Every object takes its settings as keywords when created and in
   `set(**settings)`, which returns the object. `set(name=None)` goes back to the inherited
-  or default value. `get(name)` returns the resolved value. Unknown names and invalid
-  values raise `ValueError` naming the setting (with the nearest valid name).
+  or default value. `get(name)` returns the value as given (`"4.5pt"`, `"var(color)"`),
+  `resolve(name)` the final one (px, degrees, colors), and `explain(name)` where it comes
+  from ([values](#values)). Unknown names and invalid values raise `ValueError` naming
+  the setting (with the nearest valid name).
 * **Inheritance.** Settings marked *inherited* in the tables (font, line width, palette,
   alpha, `rasterize`, `simplify`) are looked up series → plot → figure → style.
 * **Defaults.** Every default is in one dict, `plot_io/defaults.py`'s `DEFAULTS`
-  (`pl.defaults()` returns a copy): bare names for inherited settings (font size 8 pt,
-  sans-serif, black text, line width 1, `simplify="auto"`, the palette, …), and
+  (`pl.defaults()` returns a copy): bare names for inherited settings (font size,
+  sans-serif, black text, line width, `simplify="auto"`, the palette, …), and
   `"Class.name"` for the settings of each class. A class without an entry uses its base
-  class's. Entries that are functions are called with the object (a plot title is
-  1.2 × the plot's font size). `None` mostly means "chosen when drawing", as each
-  setting's documentation says.
+  class's. Entries are plain data: a default that follows another setting is written
+  with units, `var()` or `calc()` (a legend's font is `"1em"`, a minor tick `"60%"` of the
+  tick length, a fill's opacity `"calc(0.3 * var(alpha))"`). `None` and `"auto"` mean
+  "chosen when drawing", as each setting's documentation says. `"XAxis.name"` and
+  `"YAxis.name"` give one axis its own default.
 * **Styles.** `Figure(style=…)` presets settings: a style name or a dict of settings,
   merged over the inherited defaults (`pl.THEME`). See [Styles](#styles).
 * **Entry points.** `pl.Figure()`, `pl.Plot()` and the series classes (`pl.Scatter()`, …)
   each create the levels above them: `pl.Scatter(x, y)` makes a plot (`.plot`) in a new
   figure (`.plot.figure`). `fig.plot(…)` is `pl.Plot(figure=fig, …)` and `p.scatter(…)` is
   `pl.Scatter(…, plot=p)`. Keywords that belong to a level above go to it:
-  `pl.Scatter(x, y, plot_width=4, title="T")`. A name present on several levels goes to
+  `pl.Scatter(x, y, width=300, title="T")`. A name present on several levels goes to
   the lowest.
-* **Units.** Font sizes, line widths, marker sizes and tick lengths are points. Figure
-  sizes, spacing, margins and colorbar sizes are in the figure's `unit` (inches by
-  default).
+* **Units.** Lengths take units (`"1.5in"`, `"0.5em"`, `"60%"`); bare numbers are CSS px
+  (1 px = 1/96 in = 0.75 pt), except slot widths (data units). See [values](#values).
+  Images are `dpi` pixels per inch: `dpi=96` gives one image pixel per px, the default 192
+  two. A dpi up to 16 is a multiple of 96: `dpi=2` is 192. PDF pages are sized in pt (× 0.75).
 * **Data.** Sequences (`None` = missing), `array.array`, or any buffer (numpy arrays are
   read without importing numpy). NaN or `None` values are missing: scatter skips them,
   line and fill break there, box ignores them, heatmap cells take `nan_color`.
@@ -52,10 +57,86 @@ Complete reference. Worked examples are in [EXAMPLES.md](EXAMPLES.md).
 * **Text.** Titles, axis labels and legend entries are strings or rich content: a list of
   strings and `pl.Span` (pdf_io's), e.g. `["Area (m", pl.Span("2",
   baseline_shift="super", font_scale=0.7), ")"]`.
+* **Named colors.** `"blue"`, `"blue 0.45"`, `"blue 45%"`: 28 scales (`red`, `orange`,
+  `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`,
+  `violet`, `purple`, `fuchsia`, `pink`, `rose`, `slate`, `gray`/`grey`, `zinc`, `neutral`,
+  `stone`, `taupe`, `mauve`, `mist`, `olive`, `black`, `white`), Tailwind CSS 4's OKLCh
+  shades 100–900 at levels 0.1–0.9, white at 0 and black at 1, interpolated in Oklab between
+  and gamut mapped into sRGB as CSS Color 4 specifies;
+  a bare name is level 0.5. They take precedence over CSS's names (`"red"` is `#fb2c36`,
+  not `#ff0000`); other CSS names (`"navy"`) keep their CSS values. `get()` returns the
+  name as given, `resolve()` the hex color.
+* **Colors.** Named colors (above), any color pdf_io accepts: CSS names, `"#rrggbb[aa]"`, CSS Color 4 functions
+  (`"rgb(…)"`, `"hsl(…)"`, `"hwb(…)"`, `"lab(…)"`, `"lch(…)"`, `"oklab(…)"`,
+  `"oklch(64.5% 0.246 16.439)"`, `"color(display-p3 1 0 0)"`, …; colors outside sRGB are
+  gamut mapped as browsers do), tuples, `CMYK` and `Spot`; and `"C0"`, `"C1"`, … for the
+  palette's colors.
+* **Fonts.** `font_family` is a CSS family list; weights (`font_weight`, `label_weight`,
+  `tick_label_weight`) are `normal`, `bold` or 1–1000, styles `normal`, `italic`,
+  `oblique` or `"oblique 10deg"`. With a variable font (pdf_io embeds the instance used),
+  the weight sets `wght`, the inherited `font_stretch` (`"condensed"`, `"87.5%"`) sets
+  `wdth`, the style `ital` or `slnt`, `font_optical_sizing="auto"` sets `opsz` from the
+  font size, and `font_variations` (`{"GRAD": 50}`) any axis:
+  `pl.Figure(font_family="Roboto Flex", font_stretch="85%", font_variations={"GRAD": 50})`.
 * **Enums.** Enum-like settings take strings; `pl.Marker`, `pl.LineStyle`,
   `pl.Orientation`, `pl.Scale`, `pl.Position`, `pl.Order` and `pl.Align` are `str` enums
   of the same values.
 
+### Values
+
+Every length, angle and number setting takes a value with a unit, a reference to another
+setting, or an expression:
+
+```python
+pl.Plot(width="3in", font_size="9pt", title="T")
+p.x_axis(tick_length="0.5em", minor_tick_length="50%", tick_rotation="0.125turn")
+p.bar(days, counts, width="20h")                   # a duration on a time axis
+p.errorbar(x, y, y_error=e, cap_length="0.2data")  # data units across the bar
+p.title(font_size="large", color="var(--accent)")
+p.legend(pad="calc(1em - 2px)")
+fig.set(vars={"accent": "#c00"})                   # custom variables, read by var(--name)
+```
+
+| Unit | Meaning |
+|---|---|
+| bare number | px (lengths), degrees (angles); data units for slot widths (`Bar`, `Box`, `Violin`, `Strip`, `Swarm` `width`) |
+| `px` `pt` `pc` `in` `cm` `mm` `Q` | absolute lengths |
+| `em` | the object's `font_size`; in a `font_size` setting, the parent's |
+| `rem` | the figure's `font_size` |
+| `%` | of the reference the setting's table entry names: another setting (`minor_tick_length`: of `tick_length`), the font size, the axes side (`tick_length`: across the axis), the slot, the box, the radius, the data range (`padding`) |
+| `data` | along a data axis: data units on linear axes, categories on category axes, seconds on time axes; an error on log, symlog and logit axes |
+| `ms` `s` `min` `h` `d` `w` | durations, as data units of time axes (a `timedelta` too) |
+| `fr` | a share of the room left by fixed tracks, in `Figure.widths`/`heights` |
+| `deg` `grad` `rad` `turn` | angles |
+| `xx-small` … `xx-large`, `smaller`, `larger` | font sizes: × 0.579 … 1.728 of `rem`; ÷/× 1.2 of the parent's |
+
+* **`var(name[, fallback])`** reads another setting of the object, resolved through the
+  usual inheritance; `var()` of the setting's own name reads the parent's value
+  (`alpha="calc(var(alpha) / 2)"`). `var(--name)` reads a custom variable: from the
+  nearest `vars` (figure or plot), else a `"--name"` key of the style. The fallback is used
+  when the value is unset. Loops raise. Text settings (titles, labels, names, formats)
+  never read `var()`.
+* **`calc()`** takes `+ - * /`, parentheses, numbers, dimensions with any unit and
+  `var()`: dimensions add to dimensions and multiply or divide by numbers.
+* **Layout.** `%` of the axes is exact with `reference="axes"` (the axes size is given)
+  and resolved inside the layout loop otherwise; it is known only while the figure is
+  drawn. `spacing`, `margin` and fixed `widths`/`heights` in `%` of the figure are solved
+  exactly when the figure size follows from its contents.
+* **Scaling.** `Figure.scaling` multiplies every absolute length (px and physical units)
+  wherever it is given: on objects, in styles, in `DEFAULTS`; not the figure size.
+  `em`, `rem` and font keywords follow `font_size`, which is scaled; `%`, `fr` and `data`
+  are not scaled.
+* **Reading.** `get(name)` returns the value as given, `resolve(name)` the final value
+  (`resolve(name, of=…)` for settings whose `%` reference the caller passes), and
+  `explain(name)` a trace:
+
+```
+>>> pl.Plot(style="matplotlib").x_axis.explain("tick_spacing")
+Axis.tick_spacing = (46.6667px, 33.3333px) ← ('calc(3.5 * var(tick_font_size))', 'calc(2.5 * var(tick_font_size))')  (default Axis.tick_spacing)
+  Axis.tick_font_size = 13.3333px ← '1em'  (default Axis.tick_font_size)
+    Axis.font_size = 13.3333px ← '10.0pt'  (inherited from Figure: style "matplotlib" font_size)
+```
+
 ## 2. Figures
 
 ```python
@@ -85,15 +166,29 @@ are names; `fig.plot()` gives 1, 2, 3, … skipping taken ids.
 
 ### Sizes and alignment
 
-* `plot_width` × `plot_height` (default 3 × 2.25 in) is one cell's aligned box; the
-  figure size follows. `width` × `height` fix the figure instead; giving both kinds for
-  one direction raises `ValueError`. `widths`/`heights` are column/row ratios.
-* `align="axes"` (default): axis lines line up. Each cell's axes are `plot_width` ×
-  `plot_height`; between columns the gutter holds the widest right margin before it, the
-  widest left margin after it and `spacing`. A plot spanning cells covers the gutters in
-  its span.
-* `align="borders"`: plot boxes (axes and decorations) line up; each cell's box is
-  `plot_width` × `plot_height`, and the axes are what the plot's own decorations leave.
+* `width` × `height` is the size of the box `reference` names:
+  * `"axes"` (default): each grid cell's axes rectangle; the figure size follows;
+  * `"plot"`: each cell's whole plot box (axes and decorations); the figure size follows;
+  * `"figure"`: the whole figure; the cells share what the decorations leave.
+
+  With only one of `width` and `height`, `aspect_ratio` (width / height, default 4/3)
+  gives the other; with neither, the default is 3 × 2.25 in (288 × 216 px). Giving all
+  three raises `ValueError`. Plots with a `data_ratio` (and pies) take the other side from
+  it when only `width` or only `height` is given. `widths`/`heights` are the columns' and
+  rows' ratios (numbers or `fr`), or fixed lengths (`["2in", "1fr", "1fr"]`) that the
+  ratios share the rest around; a plot spanning cells gets their sizes plus the gaps
+  between them.
+* `align="axes"` (default): axis lines line up. Between columns the gutter holds the
+  widest right margin before it, the widest left margin after it and `spacing`.
+* `align="borders"`: plot boxes (axes and decorations) line up, and each plot's axes are
+  what its own decorations leave.
+* `reference` and `align` combine:
+
+| `align` \ `reference` | `"axes"` | `"plot"` | `"figure"` |
+|---|---|---|---|
+| `"axes"` | each cell's axes are `width` | the widest plot box of a column (axes plus the column's largest margins) is `width`; the axes are what is left | the figure is `width`; the axes share what the gutters leave |
+| `"borders"` | a column's box is `width` plus the largest margins in it, so every axes rectangle is at least `width` | each cell's box is `width` | the figure is `width`; the boxes share what the gaps leave |
+
 * Columns (rows) holding only vertical (horizontal) colorbars are as wide as the bar,
   unless `widths` (`heights`) is given.
 * Margins come from the real text metrics of tick labels, axis labels, titles, outside
@@ -107,8 +202,8 @@ fig.title(text, **settings)        # None removes it
 ```
 
 A band at the top of the figure: the title's height (all lines, wrapped within its
-width) plus `pad`. With `plot_width`/`plot_height` the figure grows by the band; with a
-fixed `height` the plots shrink by it. `over="axes"` aligns it within the leftmost to
+width) plus `pad`. The figure grows by the band, except with `reference="figure"`, where
+the plots shrink by it. `over="axes"` aligns it within the leftmost to
 rightmost axes (a left-aligned title starts at the first y axis line), `"figure"` within
 the figure minus `margin`. Rich content styles a second line (`["Title\n",
 pl.Span("subtitle", font_size=7, font_weight="normal")]`). It is drawn last and is not
@@ -120,13 +215,18 @@ width.
 | Setting | Default | Meaning |
 |---|---|---|
 | `text` | — | Title text: a string or rich content; `\n` starts a line. |
-| `font_size` | 1.4 × the figure's font size | Font size (pt); default 1.4 × the base font size. |
-| `font_weight` | 'bold' | `bold` or `normal`. |
+| `font_size` | '1em' | Font size; default the base font size. Length; `%`: of the parent's font size. |
+| `font_weight` | 'bold' | `bold`, `normal` or a weight 1–1000. |
+| `font_style` | 'normal' | `normal`, `italic`, `oblique` or `"oblique 10deg"`. |
 | `align` | 'center' | Alignment. |
 | `over` | 'axes' | Width it is aligned and wrapped within: from the leftmost to the rightmost axes, or the whole figure. |
-| `pad` | 0.5 × the title's font size | Gap between the title and the plots (pt); default half the font size. |
-| `color` | The figure's text color | Text color. |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `pad` | '0.5em' | Gap between the title and the plots; default half the font size. Length. |
+| `color` | 'var(text_color)' | Text color. |
+| `rule_gap` | '0.5em' | Gap between the title and the figure's `title_rule`. Length; `%`: of the font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 <!-- /settings -->
 
 ### Shared axes
@@ -182,37 +282,39 @@ with outer labels only.
 | `cols` | — | Automatic arrangement: columns. |
 | `order` | 'auto' | Fill order of the automatic arrangement: `auto` (row by row with `cols`, column by column with `rows`), `row` or `col`. |
 | `align` | 'axes' | `axes`: axis lines line up across plots; `borders`: plot boxes line up. |
-| `widths` | — | Column width ratios. |
-| `heights` | — | Row height ratios. |
-| `plot_width` | 3 in, in the figure's unit | Width of one grid cell's aligned box (axes, or whole plot with `align="borders"`), in `unit`; default 3 in. |
-| `plot_height` | 2.25 in, in the figure's unit | Height of one grid cell's aligned box, in `unit`; default 2.25 in. |
-| `width` | — | Figure width in `unit` (instead of `plot_width`). |
-| `height` | — | Figure height in `unit` (instead of `plot_height`). |
-| `unit` | 'in' | Unit of the figure's sizes: `in`, `cm`, `mm` or `pt`. |
-| `spacing` | 10 pt, in the figure's unit | Minimum gap between neighbouring plots, in `unit`; default 10 pt. |
-| `margin` | 4 pt, in the figure's unit | Space around the figure, in `unit`; default 4 pt. |
-| `background` | — | Figure background; unset: none in PDF, `image_background` in images. |
-| `image_background` | 'white' | Background of PNG, JPEG and JPEG XL output when `background` is unset. |
-| `dpi` | 150.0 | Resolution of PNG, JPEG and JPEG XL output. |
-| `quality` | — | Quality (1–100), as pdf_io's: of JPEG and JPEG XL output, and of rasterized content in PDFs (stored as JPEG). Unset: pdf_io's defaults (JPEG 90; JPEG XL and PDF images lossless). |
+| `widths` | — | Column widths: ratios (numbers or `fr`) sharing the room left by fixed lengths (`"2in"`, `"30%"` of the figure width). |
+| `heights` | — | Row heights, as `widths`. |
+| `width` | '3in' | Width of the `reference` box: one cell's axes, one cell's plot, or the figure. Length. |
+| `height` | 'calc(var(width) / var(aspect_ratio))' | Height of the `reference` box. Length. |
+| `aspect_ratio` | 1.3333333333333333 | Width / height of the `reference` box (16:9 → `16 / 9`), when only one of `width` and `height` is given. |
+| `reference` | 'axes' | What `width` and `height` measure: `axes` (each grid cell's axes rectangle), `plot` (each cell's whole plot box) or `figure`. |
+| `spacing` | 13.0 | Minimum gap between neighbouring plots. Length. |
+| `margin` | 5.0 | Space around the figure. Length. |
+| `background` | — | Figure background; unset: transparent (white in JPEG, which has no transparency). |
+| `dpi` | 192.0 | Resolution of PNG, JPEG, JPEG XL and AVIF output: `96` gives one image pixel per px, the default `192` two; up to 16, a multiple of 96 (`2` is 192). |
+| `quality` | — | Quality (1–100), as pdf_io's: of JPEG, JPEG XL and AVIF output, and of rasterized content in PDFs (stored as JPEG). Unset: pdf_io's defaults (JPEG 90; JPEG XL, AVIF and PDF images lossless). |
 | `title_rule` | — | Color of a rule above the figure title, across its width (The Economist's red bar); default none. |
-| `title_rule_width` | 3.0 | Thickness of the title rule (pt). |
+| `title_rule_width` | 4.0 | Thickness of the title rule. Length. |
 | `share_x` | — | Plots sharing their x axis: `False`, `True`/`"all"`, `"col"` (same column span) or `"row"` (same row span). |
 | `share_y` | — | Plots sharing their y axis, as `share_x`. |
 | `share` | — | Both axes at once: as `share_x`, or `"grid"` (x per column, y per row); `share_x`/`share_y` override it. |
 | `label_outer` | — | Tick labels and axis titles of shared axes only on the outer plots (bottom of each column, left of each row); default `True` for groups from the figure's settings, `False` for plots paired with `share_x=plot`. |
 | `style` | — | A style name (`"ggplot2"`, …) or a dict of settings with an optional `"base"`; default: the session style (`set_style`, `use_style`), else `"default"`. |
+| `vars` | — | Custom variables, read by `var(--name)` in any setting here and below: `{"accent": "#c00"}`. |
 | `scaling` | 1.0 | Multiplies every font size, line width, marker size, tick length and pad of the style; default 1. |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 | `text_color` | inherited ('black') | Text color. |
-| `line_width` | inherited (1.0) | Default line width (pt). |
+| `line_width` | inherited (1.25) | Default line width. Length. |
 | `palette` | inherited (10 colors) | Colors of series without one. |
 | `alpha` | inherited (1.0) | Default opacity of series. |
 | `rasterize` | inherited (False) | `True` or a dpi: series drawn as images inside the PDF. |
 | `simplify` | inherited ('auto') | pdf_io's `simplify` for every series; default `"auto"`. |
 | `data` | inherited (None) | A table whose columns the series' data arguments name. |
-| `color_map` | inherited ('viridis') | Default color map (alias `cmap`): of heatmaps, contours and numbers given as colors. |
+| `color_map` | inherited ('rainbow_llhh') | Default color map (alias `cmap`): of heatmaps, contours and numbers given as colors. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
 | `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
 | `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
@@ -239,24 +341,28 @@ axes clip.
 | Setting | Default | Meaning |
 |---|---|---|
 | `spines` | 'bottom left' | Axis lines drawn: any of `left`, `bottom`, `right`, `top`, or `all`, `none`. |
-| `aspect` | — | Data aspect ratio: 1 makes one unit as long on both axes. |
+| `data_ratio` | — | Data aspect ratio: 1 makes one unit as long on both axes. |
 | `background` | — | Background color of the axes area. |
 | `border` | — | Color of a frame around the axes area (drawn under the axis lines); default none. |
-| `border_width` | 0.8 | Width of the frame (pt). |
+| `border_width` | 0.75 | Width of the frame. Length. |
 | `clip` | True | Clip series to the axes area. |
 | `axes` | True | Draw axes; `False` hides both axes, drops padding and fixes the aspect to 1 (set by pie charts). |
 | `share_x` | — | Another plot of the figure whose x axis this plot shares (groups chain); overrides the figure's `share_x`. |
 | `share_y` | — | Another plot whose y axis this plot shares. |
+| `vars` | — | Custom variables, read by `var(--name)` in any setting here and below: `{"accent": "#c00"}`. |
 | `share` | — | Another plot whose x and y axes this plot shares. |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 | `text_color` | inherited ('black') | Text color. |
-| `line_width` | inherited (1.0) | Default line width (pt). |
+| `line_width` | inherited (1.25) | Default line width. Length. |
 | `palette` | inherited (10 colors) | Colors of series without one. |
 | `alpha` | inherited (1.0) | Default opacity of series. |
 | `rasterize` | inherited (False) | `True` or a dpi: series drawn as images inside the PDF. |
 | `simplify` | inherited ('auto') | pdf_io's `simplify` for every series: `"auto"`, `True`, a dpi or `False`. |
-| `color_map` | inherited ('viridis') | Default color map (alias `cmap`): of heatmaps, contours and numbers given as colors. |
+| `color_map` | inherited ('rainbow_llhh') | Default color map (alias `cmap`): of heatmaps, contours and numbers given as colors. |
 | `data` | inherited (None) | A table (dict, pandas or polars data frame, numpy structured array): strings in the data arguments of series name its columns. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
 | `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
@@ -272,20 +378,24 @@ axes clip.
 | Setting | Default | Meaning |
 |---|---|---|
 | `text` | — | Title text: a string or rich content. |
-| `font_size` | 1.2 × the plot's font size | Font size (pt); default 1.2 × the base font size. |
-| `font_weight` | 'normal' | `normal` or `bold`. |
-| `color` | The plot's text color | Text color. |
+| `font_size` | '1em' | Font size; default the base font size. Length; `%`: of the parent's font size. |
+| `font_weight` | 'normal' | `normal`, `bold` or a weight 1–1000. |
+| `font_style` | 'normal' | `normal`, `italic`, `oblique` or `"oblique 10deg"`. |
+| `color` | 'var(text_color)' | Text color. |
 | `align` | 'center' | Alignment over the axes. |
-| `pad` | 4.0 | Gap above the axes (pt). |
+| `pad` | 5.0 | Gap above the axes. Length; `%`: of the axes height. |
 | `over` | 'axes' | Width the title is aligned within: the axes, or the axes and the y axis labels. |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 <!-- /settings -->
 
 ### Legend
 
 One entry per series with a `name`, drawn as the series draws itself (marker, line,
 swatch or box), or with `glyph="box"`, `"circle"` or `"line"` in the series color. At
-`top`, `bottom`, `outside top` and `outside bottom` entries are side by side unless
+`top`, `bottom`, `outside_top` and `outside_bottom` entries are side by side unless
 `orientation` or `columns` is set.
 
 **Size keys.** A series whose `size` goes through a `size_map` adds a size key to its
@@ -301,33 +411,40 @@ id=…, values=None, title=None)` places a key in its own grid area, as colorbar
 whole length), bars, histogram bins, boxes, violins, areas and fills (the area they cover),
 heatmaps, 2-D histograms and contours (the whole axes). Data are sampled beyond 50,000
 points and curves thinned to 4,096 vertices (twin plots' series included). The legend
-goes to the first of `top right`, `top left`, `bottom left`, `bottom right`, `top`,
-`bottom`, `center right`, `center left` whose box covers no marked cell; else to the free
+goes to the first of `top_right`, `top_left`, `bottom_left`, `bottom_right`, `top`,
+`bottom`, `center_right`, `center_left` whose box covers no marked cell; else to the free
 place (any position inside, one grid cell apart, covering no marked cell) nearest to a
-corner of the axes; else `outside right`, with room made in the layout, when every
+corner of the axes; else `outside_right`, with room made in the layout, when every
 candidate covers more than 2 % marked cells; else the candidate covering the fewest.
 
 <!-- settings:Legend -->
 | Setting | Default | Meaning |
 |---|---|---|
-| `position` | 'auto' | `auto`, `top right`, `top left`, `bottom right`, `bottom left`, `top`, `bottom`, `outside right`, `outside top`, `outside bottom` or `none`. |
+| `position` | 'auto' | `auto`, `top_right`, `top_left`, `bottom_right`, `bottom_left`, `top`, `bottom`, `outside_right`, `outside_top`, `outside_bottom` or `none`. |
 | `columns` | 1 | Number of columns. |
 | `frame` | False | Draw a frame and background. |
-| `title` | The `group` column name, when there is one | Legend title; default the `group` column name. |
-| `font_size` | The plot's font size | Font size (pt). |
-| `color` | The plot's text color | Text color. |
+| `title` | — | Legend title; default the `group` column name. |
+| `font_size` | '1em' | Font size. Length; `%`: of the parent's font size. |
+| `color` | 'var(text_color)' | Text color. |
 | `background` | 'white' | Background of a framed legend. |
 | `frame_color` | '#999999' | Frame color. |
-| `pad` | 4.0 | Gap to the axes (pt). |
-| `frame_width` | 0.5 | Frame line width (pt). |
-| `frame_radius` | 0.0 | Corner radius of the frame (pt). |
+| `pad` | 5.0 | Gap to the axes. Length. |
+| `frame_width` | 0.5 | Frame line width. Length. |
+| `frame_radius` | 0.0 | Corner radius of the frame. Length. |
 | `frame_alpha` | 1.0 | Opacity of the frame and background. |
 | `glyph_alpha` | — | Fill opacity of `box` and `circle` symbols, outlined in the opaque color; default: the series' own fill. |
 | `glyph` | 'series' | Entry symbol: as the series draws itself, or a filled `box`, a `circle` or a `line` in the series color. |
-| `orientation` | 'auto' | `horizontal`: entries side by side; `auto`: horizontal at `top`, `bottom`, `outside top` and `outside bottom`. |
-| `glyph_width` | 2.0 | Width of an entry's symbol, in font sizes. |
-| `row_height` | 1.35 | Height of an entry, in font sizes. |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `orientation` | 'auto' | `horizontal`: entries side by side; `auto`: horizontal at `top`, `bottom`, `outside_top` and `outside_bottom`. |
+| `glyph_length` | '2em' | Width of an entry's symbol. Length; `%`: of the font size. |
+| `row_height` | '1.35em' | Height of an entry. Length; `%`: of the font size. |
+| `glyph_gap` | '0.5em' | Gap between a symbol and its text. Length; `%`: of the font size. |
+| `column_gap` | '1em' | Gap between columns. Length; `%`: of the font size. |
+| `title_gap` | '0.3em' | Gap below the title. Length; `%`: of the font size. |
+| `inner_pad` | 'auto' | Space inside the box; `"auto"`: 0.5em with a frame, 0.15em without. Length; `%`: of the font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 <!-- /settings -->
 
 ### Decorations
@@ -338,7 +455,7 @@ are drawn among the series by `z`: spans under the series (`z=-1`), lines and te
 them (`z=1`).
 
 ```python
-p.hline(y, min=0, max=1, color="#4d4d4d", line_style="solid", ...)   # min/max: fractions of the axes width
+p.hline(y, min="0%", max="100%", color="#4d4d4d", line_style="solid", ...)  # min/max: data values or % of the axes
 p.vline(x, ...)
 p.axline((x0, y0), slope=None, point2=None, ...)                    # slope: linear axes only
 p.hspan(y0, y1, color="#e5e5e5", ...); p.vspan(x0, x1, ...)
@@ -357,10 +474,10 @@ HLine:
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | '#4d4d4d' | Line color. |
-| `line_width` | inherited (1.0) | Line width (pt). |
-| `line_style` | 'solid' | `solid`, `dashed`, `dotted`, `dashdot` or a dash list. |
-| `min` | 0.0 | Start, as a fraction of the axes width. |
-| `max` | 1.0 | End, as a fraction of the axes width. |
+| `line_width` | inherited (1.25) | Line width. Length. |
+| `line_style` | 'solid' | `solid`, `dashed`, `dotted`, `dashdot` or a dash list. Length. |
+| `min` | '0%' | Start: a data value, or `%` (or a length) from the start of the axes. Length; bare numbers: data units. |
+| `max` | '100%' | End: a data value, or `%` (or a length) from the start of the axes. Length; bare numbers: data units. |
 | `name` | — | Legend entry; unset: not in the legend. |
 | `alpha` | 1.0 | Opacity. |
 | `z` | 1.0 | Drawing order among the series (default 0). |
@@ -374,8 +491,8 @@ AxLine:
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | '#4d4d4d' | Line color. |
-| `line_width` | inherited (1.0) | Line width (pt). |
-| `line_style` | 'solid' | `solid`, `dashed`, `dotted`, `dashdot` or a dash list. |
+| `line_width` | inherited (1.25) | Line width. Length. |
+| `line_style` | 'solid' | `solid`, `dashed`, `dotted`, `dashdot` or a dash list. Length. |
 | `name` | — | Legend entry; unset: not in the legend. |
 | `alpha` | 1.0 | Opacity. |
 | `z` | 1.0 | Drawing order among the series (default 0). |
@@ -389,10 +506,10 @@ HSpan:
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | '#e5e5e5' | Fill color. |
-| `line_color` | — | Outline color; default none. |
-| `line_width` | 0.0 | Outline width (pt). |
-| `min` | 0.0 | Start, as a fraction of the axes width. |
-| `max` | 1.0 | End, as a fraction of the axes width. |
+| `edge_color` | — | Outline color; default none. |
+| `edge_width` | 0.0 | Outline width. Length. |
+| `min` | '0%' | Start: a data value, or `%` (or a length) from the start of the axes. Length; bare numbers: data units. |
+| `max` | '100%' | End: a data value, or `%` (or a length) from the start of the axes. Length; bare numbers: data units. |
 | `name` | — | Legend entry; unset: not in the legend. |
 | `alpha` | 1.0 | Opacity. |
 | `z` | -1.0 | Drawing order among the series (default 0). |
@@ -407,12 +524,16 @@ Text:
 |---|---|---|
 | `align` | 'left' | Horizontal alignment on the point. |
 | `valign` | 'baseline' | Vertical alignment on the point. |
-| `rotation` | 0.0 | Rotation (degrees, counterclockwise). |
+| `rotation` | 0.0 | Rotation (degrees, counterclockwise). Angle (bare: degrees). |
 | `coords` | 'data' | `data`, `axes` (0–1) or `figure` (0–1). |
-| `color` | The text color | Text color; default `text_color`. |
-| `font_size` | inherited (8.0) | Font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
-| `font_weight` | 'normal' | `normal` or `bold`. |
+| `color` | 'var(text_color)' | Text color; default `text_color`. |
+| `font_size` | inherited (11.0) | Font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `font_weight` | 'normal' | `normal`, `bold` or a weight 1–1000. |
+| `font_style` | 'normal' | `normal`, `italic`, `oblique` or `"oblique 10deg"`. |
 | `text_color` | inherited ('black') | Text color. |
 | `name` | — | Legend entry; unset: not in the legend. |
 | `alpha` | 1.0 | Opacity. |
@@ -426,12 +547,16 @@ Annotate:
 <!-- settings:Annotate -->
 | Setting | Default | Meaning |
 |---|---|---|
-| `rotation` | 0.0 | Rotation (degrees, counterclockwise). |
+| `rotation` | 0.0 | Rotation (degrees, counterclockwise). Angle (bare: degrees). |
 | `coords` | 'data' | `data`, `axes` (0–1) or `figure` (0–1). |
-| `color` | The text color | Text color; default `text_color`. |
-| `font_size` | inherited (8.0) | Font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
-| `font_weight` | 'normal' | `normal` or `bold`. |
+| `color` | 'var(text_color)' | Text color; default `text_color`. |
+| `font_size` | inherited (11.0) | Font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
+| `font_weight` | 'normal' | `normal`, `bold` or a weight 1–1000. |
+| `font_style` | 'normal' | `normal`, `italic`, `oblique` or `"oblique 10deg"`. |
 | `text_color` | inherited ('black') | Text color. |
 | `name` | — | Legend entry; unset: not in the legend. |
 | `alpha` | 1.0 | Opacity. |
@@ -440,13 +565,13 @@ Annotate:
 | `clip` | False | Clip to the axes area. |
 | `align` | 'center' | Horizontal alignment on `xytext`. |
 | `valign` | 'center' | Vertical alignment on `xytext`. |
-| `text_coords` | As `coords` | Coordinates of `xytext`: as `coords`, or `offset` (pt from `xy`, y up); default `coords`. |
+| `text_coords` | 'var(coords)' | Coordinates of `xytext`: as `coords`, or `offset` (px from `xy`, y up); default `coords`. |
 | `arrow` | True | Draw an arrow from the text to `xy`. |
 | `arrow_style` | '->' | `->` (open head), `-\|>` (filled head) or `-` (no head). |
-| `arrow_color` | The text's `color` | Arrow color; default the text color. |
-| `arrow_width` | 0.8 | Arrow line width (pt). |
-| `head_size` | 5.0 | Arrowhead length (pt). |
-| `shrink` | 2.0 | Gap left at both ends of the arrow (pt). |
+| `arrow_color` | 'var(color)' | Arrow color; default the text color. |
+| `arrow_width` | 0.75 | Arrow line width. Length. |
+| `head_length` | 7.0 | Arrowhead length. Length. |
+| `shrink` | 3.0 | Gap left at both ends of the arrow. Length. |
 <!-- /settings -->
 
 ## 4. Axes
@@ -551,60 +676,65 @@ or the plot's `spines` is set.
 | Setting | Default | Meaning |
 |---|---|---|
 | `label` | — | Axis title: a string or rich content. |
-| `label_size` | The axis font size | Font size of the label (pt); default: the base font size. |
+| `label_font_size` | '1em' | Font size of the label; default: the base font size. Length; `%`: of the font size. |
 | `scale` | — | `linear`, `log`, `log2`, `log10`, `sqrt`, `exp`, `symlog`, `logit`, `time` or `category`; default: `category` for categorical series, `time` for dates, else `linear`. |
 | `linthresh` | 1.0 | Half-width of the linear region of a `symlog` axis. |
 | `tz` | — | Time zone of a time axis (a `tzinfo`); default: the zone of the first aware date, else naive (UTC). |
 | `limits` | 'auto' | `"auto"`, `"lo/hi"` (`min`, `max`, numbers, `q:F`) or `(lo, hi)`. |
-| `padding` | 'auto' | Space added to automatic limits, as a fraction of the range; `"auto"`: `auto_padding`, or 0 on axes of series drawn to exact limits (box value axes, heatmaps, …) and in plots without axes. |
-| `auto_padding` | 0.05 | The fraction `padding="auto"` adds on each side. |
+| `padding` | 'auto' | Space added to automatic limits, as a fraction of the range; `"auto"`: `auto_padding`, or 0 on axes of series drawn to exact limits (box value axes, heatmaps, …) and in plots without axes. Length. |
+| `auto_padding` | '5%' | The fraction `padding="auto"` adds on each side. Length. |
 | `invert` | False | Reverse the axis. |
 | `ticks` | — | `False` (no ticks) or a list of tick values. |
 | `tick_labels` | — | Labels of `ticks`. |
 | `minor_ticks` | — | `True`, `False` or a list of values; default: on for log10. |
 | `tick_format` | 'auto' | Number format: `auto`, `percent`, `sci`, `eng`, `si`, `int`, a format string or a function. |
-| `tick_rotation` | 'auto' | Label rotation in degrees, or `"auto"` (45° when category labels overlap). |
+| `tick_rotation` | 'auto' | Label rotation in degrees, or `"auto"` (45° when category labels overlap). Angle (bare: degrees). |
 | `max_ticks` | 'auto' | Most major ticks; `"auto"`: one per `tick_spacing` of axis length, at least 2, at most `auto_max_ticks`. |
-| `tick_spacing` | (3.5, 2.5) | Space per automatic tick, in tick label font sizes, on horizontal and vertical axes. |
-| `time_tick_spacing` | (5.0, 2.5) | `tick_spacing` of time axes. |
+| `tick_spacing` | ('3em', '2em') | Space per automatic tick, in tick label font sizes, on horizontal and vertical axes. Length; `em` and `%`: of `tick_font_size`. |
+| `time_tick_spacing` | ('5em', '2.5em') | `tick_spacing` of time axes. Length; `em` and `%`: of `tick_font_size`. |
+| `tick_label_gap` | '0.6em' | Smallest gap between neighbouring tick labels side by side: fewer numeric ticks, or category labels rotated and thinned out, below it. Length; `em` and `%`: of `tick_font_size`. |
+| `category_label_spacing` | ('1.6em', '1.3em') | Distance between category labels: rotated (horizontal axes) and stacked (vertical axes); labels closer than it are thinned out. Length; `em` and `%`: of `tick_font_size`. |
 | `auto_max_ticks` | (10, 8) | Most automatic ticks on numeric and time axes. |
 | `sci_limits` | (-4, 5) | Exponents beyond which labels become mantissas × 10ᵏ. |
-| `tick_length` | 3.0 | Tick length (pt). |
-| `minor_tick_length` | 0.6 × `tick_length` | Minor tick length (pt); default 0.6 × `tick_length`. |
+| `tick_length` | 6.0 | Tick length. Length; `%`: of the axes side across the axis. |
+| `minor_tick_length` | '60%' | Minor tick length; default 0.6 × `tick_length`. Length; `%`: of `tick_length`. |
 | `tick_direction` | 'out' | `out`, `in` or `both`. |
-| `tick_width` | 0.6 | Tick line width (pt). |
-| `tick_size` | The axis font size | Font size of tick labels (pt). |
-| `tick_pad` | 2.0 | Gap between ticks and labels (pt). |
-| `label_pad` | 3.0 | Gap between tick labels and the label (pt). |
-| `color` | The text color | Color of the axis line, ticks and labels (the default of `line_color`, `tick_color`, `tick_label_color`, `label_color`). |
-| `line_color` | The axis `color` | Axis line color. |
-| `tick_color` | The axis `color` | Tick color. |
-| `tick_label_color` | The axis `color` | Tick label color. |
-| `label_color` | The axis `color` | Axis title color. |
-| `label_weight` | 'normal' | Axis title weight. |
-| `label_style` | 'normal' | Axis title style. |
-| `side` | `bottom` for x, `left` for y | Where the ticks, labels and axis line go: `bottom` or `top` (x axis), `left` or `right` (y axis). |
-| `tick_label_weight` | 'normal' | Tick label weight. |
+| `tick_width` | 0.75 | Tick line width. Length. |
+| `tick_font_size` | '1em' | Font size of tick labels. Length; `%`: of the font size. |
+| `tick_pad` | 3.0 | Gap between ticks and labels. Length; `%`: of the axes side across the axis. |
+| `label_pad` | 4.0 | Gap between tick labels and the label. Length; `%`: of the axes side across the axis. |
+| `color` | 'var(text_color)' | Color of the axis line, ticks and labels (the default of `line_color`, `tick_color`, `tick_label_color`, `label_color`). |
+| `line_color` | 'var(color)' | Axis line color. |
+| `tick_color` | 'var(color)' | Tick color. |
+| `tick_label_color` | 'var(color)' | Tick label color. |
+| `label_color` | 'var(color)' | Axis title color. |
+| `label_weight` | 'normal' | Axis title weight: `normal`, `bold` or 1–1000. |
+| `label_style` | 'normal' | Axis title style: `normal`, `italic`, `oblique` or `"oblique 10deg"`. |
+| `side` | x: 'bottom' / y: 'left' | Where the ticks, labels and axis line go: `bottom` or `top` (x axis), `left` or `right` (y axis). |
+| `tick_label_weight` | 'normal' | Tick label weight: `normal`, `bold` or 1–1000. |
 | `mirror` | False | Ticks also on the opposite side of the axes. |
-| `spine_offset` | 0.0 | Distance the axis line (with its ticks and labels) is moved away from the axes (pt). |
+| `spine_offset` | 0.0 | Distance the axis line (with its ticks and labels) is moved away from the axes. Length; `%`: of the axes side across the axis. |
 | `spine_trim` | False | Axis line from the first to the last major tick only. |
 | `include_zero` | False | Extend automatic limits to 0 (linear and sqrt scales), before padding and `nice`: `True`, or `"auto"` where a series on the axis asks for it (Vega-Lite's rule: scatter axes, the value axis of lines, areas and boxes). |
 | `zero_line` | False | A line across the plot at 0. |
-| `zero_line_color` | The axis `line_color` | Zero line color; default `line_color`. |
-| `zero_line_width` | The axis `line_width` | Zero line width (pt); default `line_width`. |
+| `zero_line_color` | 'var(line_color)' | Zero line color; default `line_color`. |
+| `zero_line_width` | 'var(line_width)' | Zero line width; default `line_width`. Length. |
 | `nice` | False | Extend automatic limits to the enclosing major ticks (linear and log scales). |
-| `line_width` | 0.8 | Axis line width (pt). |
+| `line_width` | 0.75 | Axis line width. Length. |
 | `grid` | False | Major grid lines across the plot. |
 | `grid_color` | '#dddddd' | Grid line color. |
-| `grid_width` | 0.5 | Grid line width (pt). |
-| `grid_style` | 'solid' | Grid line style or dash list. |
+| `grid_width` | 0.5 | Grid line width. Length. |
+| `grid_style` | 'solid' | Grid line style or dash list. Length. |
 | `minor_grid` | False | Minor grid lines: at the minor ticks, or halfway between major ticks on linear axes without minor ticks. |
-| `minor_grid_color` | `grid_color` | Minor grid color; default `grid_color`. |
-| `minor_grid_width` | 0.5 × `grid_width` | Minor grid width (pt); default half `grid_width`. |
-| `minor_grid_style` | `grid_style` | Minor grid style; default `grid_style`. |
+| `minor_grid_color` | 'var(grid_color)' | Minor grid color; default `grid_color`. |
+| `minor_grid_width` | '50%' | Minor grid width; default half `grid_width`. Length; `%`: of `grid_width`. |
+| `minor_grid_style` | 'var(grid_style)' | Minor grid style; default `grid_style`. Length. |
 | `visible` | True | Draw the axis (ticks, labels). |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 | `text_color` | inherited ('black') | Text color. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
 | `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
@@ -623,7 +753,8 @@ with several value sets (histograms, densities, areas, pies) take one per set.
 * **Category slots.** Box and violin series, bar series, and strip and swarm series form
   three dodge groups: the series of a group that have a category split its slot (`width`)
   side by side, in call order; `dodge=False` overlays a series; `gap` leaves part of each
-  share empty. Stacked bars count as one, and so do split violins.
+  share empty (`"10%"`). `width` is in data units (`0.8` is 80 % of a category) or `%` of
+  the slot: one category, or the smallest gap between numeric `positions`. Stacked bars count as one, and so do split violins.
 * **Stacking.** `stack=True` (bars, histograms, densities) puts a series on the previous
   stacked series of its kind in the plot, per category or bin; positive and negative
   values stack apart; `stack="normalize"` divides each position by its total.
@@ -642,7 +773,7 @@ p = pl.Plot(data=df); p.scatter("a", "b")       # data inherited by the plot's s
 `data` is any object returning a column for `data[name]`: a dict of sequences, a pandas
 or polars data frame, a numpy structured array. Columns are read through `__getitem__`
 (and `to_numpy()` when present); no table library is imported. With `data`, a string in
-a positional data argument or in `color`, `line_color`, `size`, `alpha`, `group`,
+a positional data argument or in `color`, `edge_color`, `size`, `alpha`, `group`,
 `order`, `x_error`, `y_error`, `weights`, `positions`, `x`, `y` or `labels` names a
 column. Positional arguments, `group`, `weights` and `positions` must be columns; in
 `color`, a color name that is no column stays a color (a column wins, with a warning if
@@ -679,28 +810,29 @@ member, and `order` sorts within each member.
 pl.Scatter(x, y, plot=None, **settings)
 ```
 
-`color`, `line_color`, `size`, `marker` take one value or one per point. Numbers per
-point in `color` and `line_color` are mapped through `color_map` (alias `cmap`; default:
+`color`, `edge_color`, `size`, `marker` take one value or one per point. Numbers per
+point in `color` and `edge_color` are mapped through `color_map` (alias `cmap`; default:
 the style's map); numbers in `size` are diameters, or values mapped through `size_map`
 (alias `smap`) when it is set. See [values](#values-in-color-and-size).
 
-* `size` is a diameter in points. With `size_basis="area"` (default) every shape has the
-  area of the circle of that diameter: a square of size 4 is drawn 3.54 pt wide.
+* `size` is a diameter (a length; per-point numbers are px). With `size_basis="area"` (default) every shape has the
+  area of the circle of that diameter: a square of size 4 is drawn 3.54 px wide.
 * Error bars: `x_error`/`y_error` take a value, a sequence, `(low, high)` sequences or
-  `ErrorBars(values, color=None, line_width=None, cap=3)`.
+  `ErrorBars(values, color=None, line_width=None, cap_length=None)` (cap: the series'
+  `cap_length`, else 4 px).
 
 <!-- settings:Scatter -->
 | Setting | Default | Meaning |
 |---|---|---|
 | `marker` | 'circle' | Marker name, `Path` or path data, or one per point. |
-| `size` | 4.0 | Marker size (pt): the diameter of the circle of equal area; one value or one per point; numbers per point are values to map when `size_map` is set; or `"density"`. |
+| `size` | 5.0 | Marker size: the diameter of the circle of equal area; one value or one per point; numbers per point are values to map when `size_map` is set; or `"density"`. Length. |
 | `color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
-| `line_color` | — | Outline: as the fill color. |
-| `line_width` | 0.5 | Outline width (pt). |
+| `edge_color` | — | Outline: as the fill color. |
+| `edge_width` | 0.5 | Outline width. Length. |
 | `filled` | True | `True`: filled with the color; `False`: hollow, outlined in the color; a number: filled at that opacity and outlined in the color. |
 | `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
-| `color_map` | inherited ('viridis') | How numbers in `color` become colors: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
-| `size_map` | — | How numbers in `size` become sizes: a `SizeMap` (alias `smap`); without it, numbers are sizes in pt. |
+| `color_map` | inherited ('rainbow_llhh') | How numbers in `color` become colors: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
+| `size_map` | — | How numbers in `size` become sizes: a `SizeMap` (alias `smap`); without it, numbers are sizes in px. |
 | `size_legend` | True | With a `size_map`: a size key in the legend (`True`), none (`False`), or the values to show (a list). |
 | `order` | — | Drawing order: `"density"` (densest drawn last), `"-density"`, or sort keys per point (ascending); default: call order. |
 | `alpha` | inherited (1.0) | Opacity, multiplying the colors' own; or `"density"` / a `Density`, mapped linearly to `alpha_range`. |
@@ -711,9 +843,12 @@ the style's map); numbers in `size` are diameters, or values mapped through `siz
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: pdf_io's `simplify`. |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
 | `text_color` | inherited ('black') | Text color. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 <!-- /settings -->
 
 ### Line
@@ -738,17 +873,17 @@ Named line styles scale with the width. Markers (`marker`, `marker_size`,
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | — | Line color; default: the next palette color. |
-| `line_width` | inherited (1.0) | Line width (pt). |
-| `line_style` | 'solid' | `solid`, `dashed`, `dotted`, `dashdot` or a dash list (pt); named styles scale with the width. |
+| `line_width` | inherited (1.25) | Line width. Length. |
+| `line_style` | 'solid' | `solid`, `dashed`, `dotted`, `dashdot` or a dash list; named styles scale with the width. Length. |
 | `interpolation` | 'linear' | How points are joined: `linear`, `step-pre`, `step-post`, `step-mid`, `monotone` (a curve that never overshoots) or `spline` (centripetal Catmull–Rom). |
 | `missing` | 'break' | Missing values: `break` the line there, or `skip` them and connect their neighbours. |
 | `cap` | 'butt' | Line cap. |
 | `join` | 'round' | Line join. |
 | `marker` | 'circle' | Marker name, `Path` or path data, or one per point. |
-| `marker_size` | 4.0 | Marker size (pt): the diameter of the circle of equal area; one value or one per point; numbers per point are values to map when `size_map` is set; or `"density"`. |
+| `marker_size` | 5.0 | Marker size: the diameter of the circle of equal area; one value or one per point; numbers per point are values to map when `size_map` is set; or `"density"`. Length. |
 | `marker_color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
-| `marker_line_color` | — | Outline: as the fill color. |
-| `marker_line_width` | 0.5 | Outline width (pt). |
+| `marker_edge_color` | — | Outline: as the fill color. |
+| `marker_edge_width` | 0.5 | Outline width. Length. |
 | `marker_filled` | True | `True`: filled with the color; `False`: hollow, outlined in the color; a number: filled at that opacity and outlined in the color. |
 | `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
 | `x_error` | — | Horizontal error bars at the points. |
@@ -759,9 +894,12 @@ Named line styles scale with the width. Markers (`marker`, `marker_size`,
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: pdf_io's `simplify`. |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
 | `text_color` | inherited ('black') | Text color. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 <!-- /settings -->
 
 ### Fill
@@ -778,9 +916,9 @@ x, y1 or y2 is), so a band with the settings of its line matches it. With
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | — | Fill color; default: the next palette color. |
-| `alpha` | 0.3 × the plot's alpha | Opacity; default 0.3. |
-| `line_color` | — | Outline color; default none. |
-| `line_width` | inherited (1.0) | Outline width (pt). |
+| `alpha` | 'calc(0.3 * var(alpha))' | Opacity; default 0.3. |
+| `edge_color` | — | Outline color; default none. |
+| `edge_width` | 'var(line_width)' | Outline width; default the line width. Length. |
 | `interpolation` | 'linear' | How points are joined: `linear`, `step-pre`, `step-post`, `step-mid`, `monotone` (a curve that never overshoots) or `spline` (centripetal Catmull–Rom). |
 | `missing` | 'break' | Missing values: `break` the line there, or `skip` them and connect their neighbours. |
 | `orientation` | 'vertical' | `vertical`: between y curves; `horizontal`: between x curves. |
@@ -788,9 +926,12 @@ x, y1 or y2 is), so a band with the settings of its line matches it. With
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: pdf_io's `simplify`. |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
 | `text_color` | inherited ('black') | Text color. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 <!-- /settings -->
 
 ### Box
@@ -811,30 +952,31 @@ category.
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | — | Box fill: a color, one per box (list or dict by category), or numbers per box (list or dict) mapped through `color_map`; default: the next palette color. |
-| `color_map` | inherited ('viridis') | How numbers in `color` become colors: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
-| `line_color` | 'black' | Box outline, whiskers, caps and median: a color, `"series"` (each box's own color) or `"auto"` (a grey 0.6 × as light as the series' lightest color, as seaborn). |
-| `whisker_color` | — | Whisker and cap color; default `line_color`. |
-| `whisker_style` | 'solid' | Whisker line style: `solid`, `dashed`, `dotted`, `dashdot` or a dash list (caps stay solid). |
-| `line_width` | 0.8 | Outline and whisker width (pt). |
-| `median_color` | — | Median line color; default `line_color`. |
-| `median_width` | 1.5 | Median line width (pt). |
-| `width` | 0.8 | Width of a category's slot (category units). |
-| `cap_width` | 0.5 | Whisker cap width, as a fraction of the box. |
+| `color_map` | inherited ('rainbow_llhh') | How numbers in `color` become colors: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
+| `edge_color` | 'black' | Box outline, whiskers, caps and median: a color, `"series"` (each box's own color) or `"auto"` (a grey 0.6 × as light as the series' lightest color, as seaborn). |
+| `whisker_color` | — | Whisker and cap color; default `edge_color`. |
+| `whisker_style` | 'solid' | Whisker line style: `solid`, `dashed`, `dotted`, `dashdot` or a dash list (caps stay solid). Length. |
+| `edge_width` | 0.75 | Outline width. Length. |
+| `whisker_width` | 'var(edge_width)' | Whisker and cap width; default `edge_width`. Length. |
+| `median_color` | — | Median line color; default `edge_color`. |
+| `median_width` | 1.5 | Median line width. Length. |
+| `width` | 0.8 | Width of a category's slot (category units). Length; bare numbers: data units. |
+| `cap_length` | '50%' | Whisker cap width (`%` of the box width). Length. |
 | `whiskers` | 1.5 | Whisker reach: a multiple of the IQR, `"range"`, or percentiles `(lo, hi)`. |
 | `outliers` | True | Draw points beyond the whiskers. |
 | `saturation` | 1.0 | Saturation of the box fills (1: the colors as given; seaborn uses 0.75). |
 | `mean` | False | Draw the mean as a marker. |
 | `mean_marker` | 'diamond' | Marker of the mean. |
-| `mean_color` | 'white' | Fill of the mean marker (outline: `line_color`). |
+| `mean_color` | 'white' | Fill of the mean marker (outline: `edge_color`). |
 | `orientation` | 'vertical' | `vertical` (categories on x) or `horizontal`. |
 | `dodge` | True | Box and violin series sharing a category share its slot side by side; `False` overlays them. |
-| `gap` | 0.1 | Fraction of each box's part of a shared slot left empty. |
+| `gap` | '10%' | Fraction of each box's part of a shared slot left empty. Length. |
 | `categories` | — | Category names of a list of arrays. |
 | `marker` | 'circle' | Marker name, `Path` or path data, or one per point. |
-| `marker_size` | 3.0 | Marker size (pt): the diameter of the circle of equal area; one value or one per point; numbers per point are values to map when `size_map` is set; or `"density"`. |
+| `marker_size` | 4.0 | Marker size: the diameter of the circle of equal area; one value or one per point; numbers per point are values to map when `size_map` is set; or `"density"`. Length. |
 | `marker_color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
-| `marker_line_color` | — | Outline: as the fill color. |
-| `marker_line_width` | 0.6 | Outline width (pt). |
+| `marker_edge_color` | — | Outline: as the fill color. |
+| `marker_edge_width` | 0.5 | Outline width. Length. |
 | `marker_filled` | True | `True`: filled with the color; `False`: hollow, outlined in the color; a number: filled at that opacity and outlined in the color. |
 | `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
 | `name` | — | Legend entry; unset: not in the legend. |
@@ -842,9 +984,12 @@ category.
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: pdf_io's `simplify`. |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
 | `text_color` | inherited ('black') | Text color. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 <!-- /settings -->
 
 ### Heatmap
@@ -865,7 +1010,7 @@ all cells), in black or white, whichever contrasts more (at most 2,500 cells unl
 <!-- settings:Heatmap -->
 | Setting | Default | Meaning |
 |---|---|---|
-| `color_map` | inherited ('viridis') | A `ColorMap`, a map name or a list of colors. |
+| `color_map` | inherited ('rainbow_llhh') | A `ColorMap`, a map name or a list of colors. |
 | `color_limits` | — | Override of the map's limits for this series. |
 | `color_scale` | — | Override of the map's scale. |
 | `mode` | 'image' | `image` (one image pixel per cell), `cells` (rectangles) or `smooth` (interpolated). |
@@ -873,16 +1018,19 @@ all cells), in black or white, whichever contrasts more (at most 2,500 cells unl
 | `origin` | 'top' | `top`: row 0 at the top (y axis inverted); `bottom`: at the bottom. |
 | `labels` | False | Write each cell's value (`"all"` above 2,500 cells). |
 | `label_format` | 'auto' | Number format of cell labels (`auto`: 3 significant digits, the same decimals for all cells). |
-| `label_size` | 0.9 × the font size | Font size of cell labels (pt). |
+| `label_font_size` | '0.9em' | Font size of cell labels. Length; `%`: of the font size. |
 | `colorbar` | False | Attach a colorbar to the plot. |
 | `name` | — | Legend entry; unset: not in the legend. |
 | `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: pdf_io's `simplify`. |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
 | `text_color` | inherited ('black') | Text color. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
 | `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
 | `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
@@ -903,18 +1051,19 @@ pl.Bar(x, height=None, plot=None, **settings)
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | — | Bar fill: a color, one per bar (list or dict by category), or numbers per bar (list or dict) mapped through `color_map`; default: the next palette color. |
-| `color_map` | inherited ('viridis') | How numbers in `color` become colors: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
-| `line_color` | — | Outline color; default none. |
-| `line_width` | 0.0 | Outline width (pt). |
-| `width` | 0.8 | Bar width: a category's slot (category units) or data units (a `timedelta` on time axes). |
+| `color_map` | inherited ('rainbow_llhh') | How numbers in `color` become colors: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
+| `edge_color` | — | Outline color; default none. |
+| `edge_width` | 0.0 | Outline width. Length. |
+| `width` | 0.8 | Bar width: a category's slot (category units) or data units (a `timedelta` on time axes). Length; bare numbers: data units. |
 | `bottom` | 0.0 | Base of the bars: a value or one per bar. |
 | `orientation` | 'vertical' | `vertical` (bars rise from the x axis) or `horizontal`. |
 | `stack` | False | `True`: on top of the previous stacked bars of the plot; `"normalize"`: stacks scaled to 1. |
 | `dodge` | True | Bar series sharing a category share its slot side by side; `False` overlays them. |
-| `gap` | 0.0 | Fraction of each bar's part of a shared slot left empty. |
+| `gap` | 0.0 | Fraction of each bar's part of a shared slot left empty. Length. |
 | `saturation` | 1.0 | Saturation of the fills (seaborn: 0.75). |
 | `error` | — | Error bars at the bar ends: a value, a sequence, `(low, high)` or `ErrorBars`. |
 | `error_color` | '#333333' | Error bar color. |
+| `error_width` | 0.75 | Error bar line width. Length. |
 | `labels` | False | Value labels: `True`/`"outside"`, `"inside"`, `"center"`. |
 | `label_format` | 'auto' | Number format of the labels. |
 | `name` | — | Legend entry; unset: not in the legend. |
@@ -922,9 +1071,12 @@ pl.Bar(x, height=None, plot=None, **settings)
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: pdf_io's `simplify`. |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
 | `text_color` | inherited ('black') | Text color. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
 | `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
 | `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
@@ -955,9 +1107,11 @@ pl.Hist(values, plot=None, **settings)
 | `stack` | False | Stack the sets (and other stacked histograms with the same bins). |
 | `dodge` | False | Put the sets side by side within each bin. |
 | `color` | — | Fill color, or one per set; default palette colors. |
-| `line_color` | — | Outline color (bars: default none; steps: the fill color). |
-| `line_width` | No outline on bars, 1 pt for step outlines | Outline width (pt); default 0 for bars, 1 for steps. |
-| `alpha` | 0.5 when several value sets overlap (neither stacked nor dodged), else the plot's | Opacity; default 1, 0.5 for overlaid sets. |
+| `edge_color` | — | Bar outline color; default none. |
+| `edge_width` | 0.0 | Bar outline width. Length. |
+| `line_color` | — | Step line color; default the fill color. |
+| `line_width` | inherited (1.25) | Step line width. Length. |
+| `alpha` | 'auto' | Opacity; `"auto"`: 0.5 for overlaid sets, else the plot's. |
 | `saturation` | 1.0 | Saturation of the fills. |
 | `labels` | False | Value labels on bars. |
 | `label_format` | 'auto' | Number format of the labels. |
@@ -965,9 +1119,12 @@ pl.Hist(values, plot=None, **settings)
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: pdf_io's `simplify`. |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
 | `text_color` | inherited ('black') | Text color. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
 | `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
 | `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
@@ -998,16 +1155,19 @@ A Gaussian kernel density of each set on a common grid of `grid` points, extendi
 | `orientation` | 'vertical' | `vertical` (values along x) or `horizontal`. |
 | `stack` | False | Stack the sets (seaborn's `multiple="stack"`). |
 | `color` | — | Color, or one per set; default palette colors. |
-| `alpha` | Fill opacity: 1 when stacked, 0.25 otherwise | Fill opacity; default 0.25 (1 when stacked). |
-| `line_width` | inherited (1.0) | Line width (pt). |
-| `line_style` | 'solid' | Line style. |
+| `alpha` | 'auto' | Fill opacity; `"auto"`: 0.25, 1 when stacked. |
+| `line_width` | inherited (1.25) | Line width. Length. |
+| `line_style` | 'solid' | Line style. Length. |
 | `name` | — | Legend entry; unset: not in the legend. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: pdf_io's `simplify`. |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
 | `text_color` | inherited ('black') | Text color. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 <!-- /settings -->
 
 ### Kde2d
@@ -1031,22 +1191,25 @@ labels, colorbar).
 |---|---|---|
 | `filled` | False | Fill the bands between levels. |
 | `lines` | True | Draw the iso-lines. |
-| `color_map` | inherited ('viridis') | Color map of the levels. |
+| `color_map` | inherited ('rainbow_llhh') | Color map of the levels. |
 | `colors` | — | Line color, or one per level, instead of the map. |
-| `line_width` | 0.8 | Line width (pt). |
-| `line_style` | 'solid' | Line style. |
+| `line_width` | 'calc(0.6 * var(line_width))' | Line width; default 0.6 × the plot's. Length. |
+| `line_style` | 'solid' | Line style. Length. |
 | `negative_style` | — | Line style of negative levels drawn with a single color (matplotlib: dashed). |
 | `alpha` | 1.0 | Opacity. |
 | `labels` | False | Write the level values on the lines. |
 | `label_format` | 'auto' | Number format of the labels. |
-| `label_size` | 0.8 × the font size | Label font size (pt). |
+| `label_font_size` | '0.8em' | Label font size. Length; `%`: of the font size. |
 | `name` | — | Legend entry; unset: not in the legend. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: pdf_io's `simplify`. |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
 | `text_color` | inherited ('black') | Text color. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
 | `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
 | `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
@@ -1079,16 +1242,19 @@ A step line through the sorted values of each set: `stat` `proportion`, `count`
 | `complementary` | False | Plot 1 − F (survival). |
 | `orientation` | 'vertical' | `vertical`: values along x; `horizontal`: along y. |
 | `color` | — | Line color, or one per set; default palette colors. |
-| `line_width` | inherited (1.0) | Line width (pt). |
-| `line_style` | 'solid' | Line style. |
+| `line_width` | inherited (1.25) | Line width. Length. |
+| `line_style` | 'solid' | Line style. Length. |
 | `name` | — | Legend entry; unset: not in the legend. |
 | `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: pdf_io's `simplify`. |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
 | `text_color` | inherited ('black') | Text color. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 <!-- /settings -->
 
 ### Violin
@@ -1103,12 +1269,12 @@ pl.Violin(values, positions=None, plot=None, **settings)
 | Setting | Default | Meaning |
 |---|---|---|
 | `color` | — | Fill: a color, one per violin (list or dict by category), or numbers per violin mapped through `color_map`; default the next palette color. |
-| `color_map` | inherited ('viridis') | How numbers in `color` become colors: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
-| `line_color` | '#333333' | Outline and inner color. |
-| `line_width` | 0.8 | Outline width (pt). |
+| `color_map` | inherited ('rainbow_llhh') | How numbers in `color` become colors: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
+| `edge_color` | '#333333' | Outline and inner color. |
+| `edge_width` | 0.75 | Outline width. Length. |
 | `saturation` | 1.0 | Saturation of the fills. |
 | `alpha` | 1.0 | Fill opacity. |
-| `width` | 0.8 | Width of a category's slot. |
+| `width` | 0.8 | Width of a category's slot. Length; bare numbers: data units. |
 | `bandwidth` | 'scott' | `scott`, `silverman` or a number. |
 | `adjust` | 1.0 | Factor applied to the bandwidth. |
 | `cut` | 2.0 | The density extends this many bandwidths past the data. |
@@ -1118,15 +1284,18 @@ pl.Violin(values, positions=None, plot=None, **settings)
 | `split` | False | Two violin series share each slot as facing halves. |
 | `orientation` | 'vertical' | `vertical` (categories on x) or `horizontal`. |
 | `dodge` | True | Violin and box series sharing a category share its slot side by side; `False` overlays them. |
-| `gap` | 0.1 | Fraction of each part of a shared slot left empty. |
+| `gap` | '10%' | Fraction of each part of a shared slot left empty. Length. |
 | `categories` | — | Category names of a list of arrays. |
 | `name` | — | Legend entry; unset: not in the legend. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: pdf_io's `simplify`. |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
 | `text_color` | inherited ('black') | Text color. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 <!-- /settings -->
 
 ### Strip and swarm
@@ -1136,27 +1305,27 @@ pl.Strip(values, positions=None, plot=None, **settings)
 pl.Swarm(values, positions=None, plot=None, **settings)
 ```
 
-Points of each category's values: `Strip` spreads them by uniform jitter (± `jitter` × the slot width, from `seed`), `Swarm` places them side by side without overlaps (points that do not fit go to the slot edge, with a warning). Marker settings as `Scatter`. `Swarm` takes the same settings as `Strip` except `jitter` and `seed`.
+Points of each category's values: `Strip` spreads them by uniform jitter (± `jitter`, `%` of the slot width, from `seed`), `Swarm` places them side by side without overlaps (points that do not fit go to the slot edge, with a warning). Marker settings as `Scatter`. `Swarm` takes the same settings as `Strip` except `jitter` and `seed`.
 
 <!-- settings:Strip -->
 | Setting | Default | Meaning |
 |---|---|---|
 | `marker` | 'circle' | Marker name, `Path` or path data, or one per point. |
-| `size` | 4.0 | Marker size (pt): the diameter of the circle of equal area; one value or one per point; numbers per point are values to map when `size_map` is set; or `"density"`. |
+| `size` | 5.0 | Marker size: the diameter of the circle of equal area; one value or one per point; numbers per point are values to map when `size_map` is set; or `"density"`. Length. |
 | `color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
-| `line_color` | — | Outline: as the fill color. |
-| `line_width` | 0.5 | Outline width (pt). |
+| `edge_color` | — | Outline: as the fill color. |
+| `edge_width` | 0.5 | Outline width. Length. |
 | `filled` | True | `True`: filled with the color; `False`: hollow, outlined in the color; a number: filled at that opacity and outlined in the color. |
 | `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
-| `color_map` | inherited ('viridis') | How numbers in `color` become colors: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
-| `size_map` | — | How numbers in `size` become sizes: a `SizeMap` (alias `smap`); without it, numbers are sizes in pt. |
+| `color_map` | inherited ('rainbow_llhh') | How numbers in `color` become colors: a `ColorMap`, a map name or colors (alias `cmap`); default: the style's. |
+| `size_map` | — | How numbers in `size` become sizes: a `SizeMap` (alias `smap`); without it, numbers are sizes in px. |
 | `size_legend` | True | With a `size_map`: a size key in the legend (`True`), none (`False`), or the values to show (a list). |
 | `orientation` | 'vertical' | `vertical` (categories on x) or `horizontal`. |
-| `width` | 0.8 | Width of a category's slot. |
+| `width` | 0.8 | Width of a category's slot. Length; bare numbers: data units. |
 | `dodge` | True | Point series sharing a category share its slot side by side; `False` overlays them. |
-| `gap` | 0.0 | Fraction of each part of a shared slot left empty. |
+| `gap` | 0.0 | Fraction of each part of a shared slot left empty. Length. |
 | `categories` | — | Category names of a list of arrays. |
-| `jitter` | 0.1 | Half-width of the jitter, as a fraction of the slot width. |
+| `jitter` | '10%' | Half-width of the jitter (`%` of the slot width). Length. |
 | `seed` | 0 | Seed of the jitter. |
 | `order` | — | Drawing order: `"density"` (densest drawn last), `"-density"`, or sort keys per point (ascending); default: call order. |
 | `alpha` | inherited (1.0) | Opacity, multiplying the colors' own; or `"density"` / a `Density`, mapped linearly to `alpha_range`. |
@@ -1165,9 +1334,12 @@ Points of each category's values: `Strip` spreads them by uniform jitter (± `ji
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: pdf_io's `simplify`. |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
 | `text_color` | inherited ('black') | Text color. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 <!-- /settings -->
 
 ### Area
@@ -1185,17 +1357,20 @@ Layers (rows of `ys`, or a dict `{name: values}`, one legend entry each) stacked
 | `stack` | True | Stack the layers; `False` overlays them from 0. |
 | `color` | — | A color, or one per layer; default palette colors. |
 | `alpha` | 0.85 | Opacity of the fills. |
-| `line_color` | — | Outline color of each layer's top; default none. |
-| `line_width` | inherited (1.0) | Outline width (pt). |
+| `edge_color` | — | Outline color of each layer's top; default none. |
+| `edge_width` | 'var(line_width)' | Outline width; default the line width. Length. |
 | `interpolation` | 'linear' | How points are joined: `linear`, `step-pre`, `step-post`, `step-mid`, `monotone` (a curve that never overshoots) or `spline` (centripetal Catmull–Rom). |
 | `missing` | 'break' | Missing values: `break` the line there, or `skip` them and connect their neighbours. |
 | `name` | — | Legend entry; unset: not in the legend. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: pdf_io's `simplify`. |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
 | `text_color` | inherited ('black') | Text color. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 <!-- /settings -->
 
 ### Errorbar
@@ -1210,15 +1385,15 @@ Error bars on their own (markers only with `marker=`); `y_error_style="band"` fi
 | Setting | Default | Meaning |
 |---|---|---|
 | `marker` | — | Marker at the points; default none. |
-| `marker_size` | 4.0 | Marker size (pt): the diameter of the circle of equal area; one value or one per point; numbers per point are values to map when `size_map` is set; or `"density"`. |
+| `marker_size` | 5.0 | Marker size: the diameter of the circle of equal area; one value or one per point; numbers per point are values to map when `size_map` is set; or `"density"`. Length. |
 | `marker_color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
-| `marker_line_color` | — | Outline: as the fill color. |
-| `marker_line_width` | 0.0 | Outline width (pt). |
+| `marker_edge_color` | — | Outline: as the fill color. |
+| `marker_edge_width` | 0.0 | Outline width. Length. |
 | `marker_filled` | True | `True`: filled with the color; `False`: hollow, outlined in the color; a number: filled at that opacity and outlined in the color. |
 | `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
 | `color` | — | Bar color; default: the next palette color. |
-| `line_width` | inherited (1.0) | Bar width (pt). |
-| `cap` | 3.0 | Cap width (pt); 0: no caps. |
+| `line_width` | inherited (1.25) | Bar width. Length. |
+| `cap_length` | 4.0 | Cap width (`data`: in data units across the bar); 0: no caps. Length. |
 | `x_error` | — | Horizontal errors. |
 | `y_error` | — | Vertical errors. |
 | `y_error_style` | 'bars' | `bars`, or `band`: a filled band between the y error ends (points sorted by x). |
@@ -1228,9 +1403,12 @@ Error bars on their own (markers only with `marker=`); `y_error_style="band"` fi
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: pdf_io's `simplify`. |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
 | `text_color` | inherited ('black') | Text color. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 <!-- /settings -->
 
 ### Stem
@@ -1245,26 +1423,29 @@ Stems from `baseline` to each value with a marker (lollipops), and a baseline li
 | Setting | Default | Meaning |
 |---|---|---|
 | `marker` | 'circle' | Marker name, `Path` or path data, or one per point. |
-| `marker_size` | 5.0 | Marker size (pt): the diameter of the circle of equal area; one value or one per point; numbers per point are values to map when `size_map` is set; or `"density"`. |
+| `marker_size` | 7.0 | Marker size: the diameter of the circle of equal area; one value or one per point; numbers per point are values to map when `size_map` is set; or `"density"`. Length. |
 | `marker_color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
-| `marker_line_color` | — | Outline: as the fill color. |
-| `marker_line_width` | 0.0 | Outline width (pt). |
+| `marker_edge_color` | — | Outline: as the fill color. |
+| `marker_edge_width` | 0.0 | Outline width. Length. |
 | `marker_filled` | True | `True`: filled with the color; `False`: hollow, outlined in the color; a number: filled at that opacity and outlined in the color. |
 | `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
 | `color` | — | Stem and marker color; default: the next palette color. |
-| `line_width` | inherited (1.0) | Stem width (pt). |
+| `line_width` | inherited (1.25) | Stem width. Length. |
 | `baseline` | 0.0 | Value the stems start from. |
 | `baseline_color` | '#4d4d4d' | Baseline color; `none`: no baseline. |
-| `baseline_width` | 0.8 | Baseline width (pt). |
+| `baseline_width` | 0.75 | Baseline width. Length. |
 | `orientation` | 'vertical' | `vertical` stems (values on y) or `horizontal`. |
 | `name` | — | Legend entry; unset: not in the legend. |
 | `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: pdf_io's `simplify`. |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
 | `text_color` | inherited ('black') | Text color. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 <!-- /settings -->
 
 ### Regression
@@ -1287,14 +1468,14 @@ A least-squares polynomial of `order` with the confidence band of the mean (Stud
 | `truncate` | True | Draw the fit over the data range only (`False`: over the axis range). |
 | `points` | 100 | Points of the fitted curve. |
 | `color` | — | Line, band and point color; default the next palette color. |
-| `line_width` | 1.5 | Line width (pt). |
-| `line_style` | 'solid' | Line style. |
+| `line_width` | 'calc(1.4 * var(line_width))' | Line width; default 1.4 × the plot's. Length. |
+| `line_style` | 'solid' | Line style or dash list. Length. |
 | `band_alpha` | 0.2 | Opacity of the band. |
 | `marker` | 'circle' | Marker name, `Path` or path data, or one per point. |
-| `marker_size` | 4.0 | Marker size (pt): the diameter of the circle of equal area; one value or one per point; numbers per point are values to map when `size_map` is set; or `"density"`. |
+| `marker_size` | 5.0 | Marker size: the diameter of the circle of equal area; one value or one per point; numbers per point are values to map when `size_map` is set; or `"density"`. Length. |
 | `marker_color` | — | Fill: a color, colors per point, numbers per point (mapped through `color_map`) or `"density"`. |
-| `marker_line_color` | — | Outline: as the fill color. |
-| `marker_line_width` | 0.0 | Outline width (pt). |
+| `marker_edge_color` | — | Outline: as the fill color. |
+| `marker_edge_width` | 0.0 | Outline width. Length. |
 | `marker_filled` | True | `True`: filled with the color; `False`: hollow, outlined in the color; a number: filled at that opacity and outlined in the color. |
 | `size_basis` | 'area' | `area`: shapes of the same size have the same area; `box`: size is the width of the shape's box. |
 | `name` | — | Legend entry; unset: not in the legend. |
@@ -1302,9 +1483,12 @@ A least-squares polynomial of `order` with the confidence band of the mean (Stud
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: pdf_io's `simplify`. |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
 | `text_color` | inherited ('black') | Text color. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 <!-- /settings -->
 
 ### Hist2d
@@ -1318,23 +1502,26 @@ Counts in rectangular bins (even on the axis scales), drawn as a heatmap with th
 <!-- settings:Hist2d -->
 | Setting | Default | Meaning |
 |---|---|---|
-| `color_map` | inherited ('viridis') | A `ColorMap`, a map name or a list of colors. |
+| `color_map` | inherited ('rainbow_llhh') | A `ColorMap`, a map name or a list of colors. |
 | `color_limits` | — | Override of the map's limits for this series. |
 | `color_scale` | — | Override of the map's scale. |
 | `mode` | 'image' | `image` (one image pixel per cell), `cells` (rectangles) or `smooth` (interpolated). |
 | `nan_color` | — | Color of missing cells; default: the map's `bad` (transparent). |
 | `labels` | False | Write each cell's value (`"all"` above 2,500 cells). |
 | `label_format` | 'auto' | Number format of cell labels (`auto`: 3 significant digits, the same decimals for all cells). |
-| `label_size` | 0.9 × the font size | Font size of cell labels (pt). |
+| `label_font_size` | '0.9em' | Font size of cell labels. Length; `%`: of the font size. |
 | `colorbar` | False | Attach a colorbar to the plot. |
 | `name` | — | Legend entry; unset: not in the legend. |
 | `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: pdf_io's `simplify`. |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
 | `text_color` | inherited ('black') | Text color. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
 | `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
 | `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
@@ -1367,20 +1554,23 @@ aspect (and the counts depend on it). Points outside the axes are not counted. C
 | `weights` | — | A weight per point (sums). |
 | `stat` | 'count' | `count`, `probability` or `percent`. |
 | `min_count` | 1.0 | Hexagons below this count are not drawn. |
-| `color_map` | inherited ('viridis') | A `ColorMap`, a map name or colors. |
+| `color_map` | inherited ('rainbow_llhh') | A `ColorMap`, a map name or colors. |
 | `color_limits` | — | Override of the map's limits. |
 | `color_scale` | — | Override of the map's scale. |
-| `line_color` | — | Hexagon outline color; default none. |
-| `line_width` | 0.0 | Outline width (pt). |
+| `edge_color` | — | Hexagon outline color; default none. |
+| `edge_width` | 0.0 | Outline width. Length. |
 | `colorbar` | False | Attach a colorbar to the plot. |
 | `name` | — | Legend entry; unset: not in the legend. |
 | `alpha` | inherited (1.0) | Opacity, multiplying the colors' own. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: pdf_io's `simplify`. |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
 | `text_color` | inherited ('black') | Text color. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 <!-- /settings -->
 
 ### Contour
@@ -1397,23 +1587,26 @@ Iso-lines (`lines`) and filled bands (`filled`) of a grid at nodes `x`/`y`. `lev
 | `levels` | 10 | A number of levels (nice values over the data) or the level values. |
 | `filled` | False | Fill the bands between levels. |
 | `lines` | True | Draw the iso-lines. |
-| `color_map` | inherited ('viridis') | Color map of the levels. |
+| `color_map` | inherited ('rainbow_llhh') | Color map of the levels. |
 | `colors` | — | Line color, or one per level, instead of the map. |
-| `line_width` | 0.8 | Line width (pt). |
-| `line_style` | 'solid' | Line style. |
+| `line_width` | 'calc(0.6 * var(line_width))' | Line width; default 0.6 × the plot's. Length. |
+| `line_style` | 'solid' | Line style. Length. |
 | `negative_style` | — | Line style of negative levels drawn with a single color (matplotlib: dashed). |
 | `alpha` | 1.0 | Opacity. |
 | `labels` | False | Write the level values on the lines. |
 | `label_format` | 'auto' | Number format of the labels. |
-| `label_size` | 0.8 × the font size | Label font size (pt). |
+| `label_font_size` | '0.8em' | Label font size. Length; `%`: of the font size. |
 | `colorbar` | False | Attach a colorbar to the plot. |
 | `name` | — | Legend entry; unset: not in the legend. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: pdf_io's `simplify`. |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
 | `text_color` | inherited ('black') | Text color. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
 | `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
 | `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
@@ -1428,31 +1621,35 @@ Iso-lines (`lines`) and filled bands (`filled`) of a grid at nodes `x`/`y`. `lev
 pl.Pie(values, plot=None, **settings)
 ```
 
-Wedges of `values` (a sequence or a dict `{label: value}`) from `start`, on a plot drawn without axes (`Plot.axes=False`, aspect 1). `hole` makes a donut, `explode` moves wedges out. Names go outside (pushed apart so that they do not overlap), inside, or into the legend (`label_position="none"`, the legend then outside right); `value_labels` writes percents or values inside, or outside with a leader line when a wedge is too thin.
+Wedges of `values` (a sequence or a dict `{label: value}`) from `start`, on a plot drawn without axes (`Plot.axes=False`, aspect 1). `hole` makes a donut (`"40%"` of the radius), `explode` moves wedges out (`%` of the radius, one value or one per wedge). Names go outside (pushed apart so that they do not overlap), inside, or into the legend (`label_position="none"`, the legend then outside right); `value_labels` writes percents or values inside, or outside with a leader line when a wedge is too thin.
 
 <!-- settings:Pie -->
 | Setting | Default | Meaning |
 |---|---|---|
 | `labels` | — | Wedge names (default: the dict's keys). |
 | `colors` | — | One color per wedge; default palette colors. |
-| `start` | 90.0 | Angle where the first wedge starts (degrees, 0: 3 o'clock, 90: 12 o'clock). |
+| `start` | 90.0 | Angle where the first wedge starts (degrees, 0: 3 o'clock, 90: 12 o'clock). Angle (bare: degrees). |
 | `counterclockwise` | True | Direction of the wedges. |
-| `hole` | 0.0 | Radius of the hole (fraction of the radius): a donut. |
-| `explode` | — | Offset of the wedges from the centre (fraction of the radius): one value or one per wedge. |
+| `hole` | 0.0 | Radius of the hole (`%` of the radius): a donut. Length. |
+| `explode` | — | Offset of the wedges from the centre (`%` of the radius): one value or one per wedge. Length. |
 | `sort` | False | Sort the wedges by decreasing value. |
 | `label_position` | 'outside' | Where the names go: `outside`, `inside` or `none` (in the legend instead). |
 | `value_labels` | False | Write each wedge's `percent` or `value` inside it (outside, with a leader line, when it does not fit). |
+| `label_spacing` | '1.25em' | Smallest distance between outside labels on a side. Length; `%`: of the font size. |
 | `label_format` | 'auto' | Number format of the value labels (percentages: of 100). |
-| `line_color` | 'white' | Wedge outline color; `none`: no outline. |
-| `line_width` | 1.0 | Wedge outline width (pt). |
+| `edge_color` | 'white' | Wedge outline color; `none`: no outline. |
+| `edge_width` | 1.25 | Wedge outline width. Length. |
 | `alpha` | 1.0 | Opacity. |
 | `name` | — | Legend entry; unset: not in the legend. |
 | `z` | — | Drawing order (higher on top); default: call order. |
 | `rasterize` | inherited (False) | `True` or a dpi: drawn as an image inside the PDF. |
 | `simplify` | inherited ('auto') | `"auto"`, `True`, a dpi or `False`: pdf_io's `simplify`. |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
 | `text_color` | inherited ('black') | Text color. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
 | `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
 | `minus` | inherited ('hyphen') | `hyphen` (`-`) or `minus` (U+2212, from an installed font). |
@@ -1479,17 +1676,20 @@ side, so axes stay aligned. A bar in its own area runs along the neighbouring ax
 | Setting | Default | Meaning |
 |---|---|---|
 | `position` | 'right' | Side of the plot an attached bar takes. |
-| `orientation` | `vertical` beside the axes or in a grid area, `horizontal` above or below them | Bar direction; default: vertical, or horizontal for bars attached at the top or bottom. |
-| `size` | 10 pt, in the figure's unit | Bar thickness, in the figure's unit; default 10 pt. |
-| `length` | 1.0 | Bar length as a fraction of the axes side (attached bars). |
-| `pad` | 8 pt, in the figure's unit | Gap between the axes and an attached bar, in the figure's unit. |
+| `orientation` | 'auto' | Bar direction; default: vertical, or horizontal for bars attached at the top or bottom. |
+| `thickness` | 13.0 | Bar thickness (`%` of the attached axes side across it). Length. |
+| `length` | '100%' | Bar length as a fraction of the axes side (attached bars). Length. |
+| `pad` | 11.0 | Gap between the axes and an attached bar. Length. |
 | `label` | — | Bar label: a string or rich content. |
 | `extend` | 'auto' | Triangular ends in the under/over colors: `auto` shows them when the limits clip the data. |
 | `frame` | False | Outline the bar. |
 | `frame_color` | '#666666' | Outline color. |
-| `frame_width` | 0.5 | Outline width (pt). |
-| `font_size` | inherited (8.0) | Base font size (pt). |
-| `font_family` | inherited ('sans-serif') | Font family. |
+| `frame_width` | 0.5 | Outline width. Length. |
+| `font_size` | inherited (11.0) | Base font size. Length; `%`: of the parent's font size. |
+| `font_family` | inherited ('SF Pro, Inter, Helvetica, Arial, sans-serif') | Font family. |
+| `font_stretch` | inherited ('normal') | Font width: `normal`, `condensed`, …, or a percentage (`"87.5%"`); the `wdth` axis of variable fonts. |
+| `font_variations` | inherited (None) | Variable font axes: `{"GRAD": 50}` or `'"GRAD" 50, "wght" 650'`. |
+| `font_optical_sizing` | inherited ('auto') | `auto`: a variable font's `opsz` axis follows the font size; `none`. |
 | `text_color` | inherited ('black') | Text color. |
 | `decimal_separator` | inherited ('.') | Decimal separator of numbers (`"."`). |
 | `thousands_separator` | inherited ('') | Thousands separator (`""`: none). |
@@ -1509,14 +1709,25 @@ default palette `pl.PALETTE` (`"okabe_ito"`) is Okabe–Ito's eight colorblind-s
 plus indigo and dark brown, chosen as the pair farthest from every other color (in Oklab)
 under normal and simulated protan, deutan and tritan vision.
 
-`palette` takes a list of colors, a registered name, or a function `n -> colors`, called
-with the number of series of the plot that take a palette color.
+`palette` takes a `pl.Palette`, a registered name (`"tab10"`; `"tab10_r"` reversed), a
+list of colors (or one comma-separated string: `"red, teal 0.7"`), or a function `n -> colors`, called with the number of series of the plot
+that take a palette color.
 
 ```python
-pl.register_palette(name, colors_or_function)
+pl.Palette(colors="okabe_ito", name=None)    # a name, colors, a Palette or n -> colors
+pl.register_palette(name, palette)           # a Palette, colors or a function
 pl.palette_names()
 ```
 
+| `Palette` | |
+|---|---|
+| `colors(n=None)` | the colors: all, or `n` (a list repeats, as series reuse it; a function is called with `n`) |
+| `len(p)`, `p[i]`, `p[a:b]`, `iter(p)` | lists only: count; a color (indices wrap); a sub-palette |
+| `reversed()`, `lighter(k=0.25)`, `darker(k=0.25)` | copies: reversed; each color moved by `k` toward white or black in Oklab |
+
+`ColorMap.to_palette(n)` samples a gradient into `n` colors, at the centers of `n` equal
+parts: `palette=pl.ColorMap("viridis").to_palette(5)` for ordered categories.
+
 | Palette | Colors |
 |---|---|
 | `okabe_ito` | plot_io's default (10) |
@@ -1533,33 +1744,55 @@ pl.palette_names()
 | `economist` | The Economist (ggthemes, pre-2017) (10) |
 | `fivethirtyeight` | matplotlib's fivethirtyeight style (6) |
 | `greys` | black to light grey (4) |
+| `set1`, `set2`, `set3`, `paired`, `accent`, `dark2`, `pastel1`, `pastel2` | ColorBrewer's qualitative schemes by Brewer (Apache-2.0) (8–12) |
+| `batlow`, `batlowk`, `batloww`, `devon`, `lajolla`, `bamako`, `davos`, `bilbao`, `nuuk`, `oslo`, `grayc`, `hawaii`, `lapaz`, `tokyo`, `buda`, `acton`, `turku`, `imola`, `glasgow`, `lipari`, `navia` | Crameri's categorical Scientific colour maps 8 (MIT): the first colors differ most (100) |
 
 ### Color maps
 
 ```python
-pl.ColorMap(colors="viridis", positions=None, limits="auto", scale="linear",
-            under=None, over=None, bad=None, space=None, name=None)
+pl.ColorMap(colors="rainbow_llhh", positions=None, limits="auto", scale="linear",
+            under=None, over=None, bad=None, space=None, name=None, interpolation=None,
+            widen_colors=1, widen_sides=1.0)
 pl.register_color_map(name, color_map)
 pl.color_map_names()
 ```
 
 | Member | |
 |---|---|
-| `colors` | a name (`viridis`, `magma`, `inferno`, `plasma`, `cividis`, `coolwarm`, `grey`, `rocket`, `mako`, `flare`, `crest`, `vlag`, `icefire`, `jet`, `parula`, `turbo`, `ylgnbu`, `blues`, `ggplot2`; `_r` reverses), a list of colors (evenly spaced or at `positions`), a `ColorMap` (copied) or a function `t -> color` |
+| `colors` | a name (`viridis`, `magma`, `inferno`, `plasma`, `cividis`, `coolwarm`, `grey`, `rocket`, `mako`, `flare`, `crest`, `vlag`, `icefire`, `jet`, `parula`, `turbo`, `ggplot2`, the rainbows, ColorBrewer's and Crameri's maps below, in any case (`"RdBu"`, `"batlowK"`); `_r` reverses), a list of colors (evenly spaced or at `positions`; or one string, comma-separated: `"violet 0.4, sky 0.4, green 0.4"`), a `ColorMap` (copied) or a function `t -> color` |
 | `limits`, `scale` | axis syntax, applied to the mapped values; `"auto"` covers every series using the map |
 | `under`, `over`, `bad` | colors below/above the limits (default: the end colors) and of missing values (default: transparent) |
-| `space` | `"oklab"` (default for color lists: perceptually even) or `"srgb"` (bundled maps, whose stops are already a dense perceptual sampling) |
+| `space` | interpolation between the colors: `"oklab"` (default, for every map: perceptually even) or `"srgb"` |
+| `interpolation` | `"linear"` (default): between neighboring colors; `"nearest"`: equal steps, one per color (`n` colors, `n` bins; with `positions`, each step starts at its position); `"smooth"`: a Bézier curve with the colors as control points, through the first and last only (no `positions`); `"spline"`: a monotone cubic curve through every color (PCHIP in Oklab: no overshoot between colors) |
+| `widen_colors`, `widen_sides` | each inner color of a list repeated `widen_colors` times, each end color `round(widen_sides × widen_colors)` times: wider bands around the colors |
 | `cm(t)`, `colors_at(ts)` | color at t ∈ [0, 1]; bulk colors (C) |
 | `reversed()`, `resampled(n)`, `truncated(lo, hi)`, `with_extremes(…)` | copies: reversed; n flat steps; a part stretched to [0, 1]; new extremes |
-| `to_pdf_io()` | the equivalent pdf_io color map (Oklab maps as 256 sRGB stops) |
+| `to_palette(n)` | a `Palette` of `n` colors sampled at the centers of `n` equal parts |
+| `to_pdf_io()` | the equivalent pdf_io color map (maps with fewer than 256 colors as 256 sRGB stops) |
 
 Bundled data: viridis, magma, inferno and plasma by van der Walt and Smith (CC0); cividis
 by Nuñez, Anderton and Renslow; coolwarm by Moreland; rocket, mako, flare, crest, vlag and
 icefire from seaborn by Waskom (BSD-3-Clause); jet from matplotlib; a parula-like map;
-turbo by Mikhailov (Google, Apache-2.0); YlGnBu and Blues from ColorBrewer by Brewer
-(Apache-2.0);
-`ggplot2` is ggplot2's continuous default (`#132B43` → `#56B1F7`, Oklab). The
-`color_map` setting (alias `cmap`; inherited, default `"viridis"`) is the map of heatmaps,
+turbo by Mikhailov (Google, Apache-2.0);
+the rainbows, built from named colors with `widen_colors=6, widen_sides=0.6` and
+`interpolation="smooth"` (violet, sky,
+green, yellow, orange, rose): `rainbow` (all at level 0.4), `rainbow_neutral` (0.5),
+`rainbow_l0hh` (from white, then levels 0.1 to 0.6), `rainbow_llhh` (0.16 to 0.6),
+`rainbow_llh` (0.16 to 0.4), `rainbow_hlh` (dark ends, light middle); diverging maps from
+named colors: `blue_white_red` (sky, white, rose), `blue_white_red_hc` (levels 0.6 at the
+ends), `blue_gray_red` (a gray 0.2 middle), `blue_gray_red_hc`;
+ColorBrewer's schemes by Brewer (Apache-2.0): sequential `blues`, `bugn`, `bupu`, `gnbu`,
+`greens`, `greys`, `oranges`, `orrd`, `pubu`, `pubugn`, `purd`, `purples`, `rdpu`, `reds`,
+`ylgn`, `ylgnbu`, `ylorbr`, `ylorrd` (9 colors) and diverging `brbg`, `piyg`, `prgn`, `puor`,
+`rdbu`, `rdgy`, `rdylbu`, `rdylgn`, `spectral` (11 colors); Crameri's Scientific colour maps
+8 (MIT; Crameri, Shephard and Heron 2020): sequential `batlow`, `batlowk`, `batloww`,
+`devon`, `lajolla`, `bamako`, `davos`, `bilbao`, `nuuk`, `oslo`, `grayc`, `hawaii`, `lapaz`,
+`tokyo`, `buda`, `acton`, `turku`, `imola`, `glasgow`, `lipari`, `navia`, diverging `broc`,
+`cork`, `vik`, `lisbon`, `tofino`, `berlin`, `roma`, `bam`, `vanimo`, `managua`,
+multi-sequential `oleron`, `bukavu`, `fes` and cyclic `romao`, `bamo`, `broco`, `corko`,
+`viko` (256 colors each);
+`ggplot2` is ggplot2's continuous default (`#132B43` → `#56B1F7`). The
+`color_map` setting (alias `cmap`; inherited, default `"rainbow_llhh"`) is the map of heatmaps,
 contours and numbers given as colors. One `ColorMap` object given to several series
 shares its `"auto"` limits.
 
@@ -1577,7 +1810,7 @@ value); `by="diameter"` moves the diameter. `under`/`over` default to the end si
 
 ### Values in color and size
 
-| Given to `color` (also `line_color`, `marker_color`) | Meaning |
+| Given to `color` (also `edge_color`, `marker_color`) | Meaning |
 |---|---|
 | a color string, `CMYK`, `Spot`, or a **tuple** of 3 or 4 numbers | one color |
 | a list of colors | one color per point |
@@ -1590,7 +1823,7 @@ A tuple of numbers is always one color and a list of numbers is always values, s
 `color=[0.2, 0.4, 0.6]` with a point count other than 3 is an error (use a tuple for one
 RGB color). A `ColorMap` goes in `color_map`, not `color`.
 
-`size` takes a diameter (pt), diameters per point, or values per point mapped through
+`size` takes a diameter (a length), diameters per point (px), or values per point mapped through
 `size_map` when it is set; `"density"` uses `size_map` or `SizeMap()`. A `SizeMap` goes in
 `size_map`.
 
@@ -1614,7 +1847,7 @@ on the axis positions (log axes in log space); NaN points get NaN. `normalize`:
 under automatic limits. `method`: `"exact"` (the sum over all points, multithreaded in
 C, equal to scipy's), `"grid"` (binned, blurred and read back, about 1e-4 relative) or
 `"auto"` (exact up to 20,000 points). A `Density` (or `"density"`) is accepted by
-`color`, `line_color`, `size` (through `size_map`, default `SizeMap()`), `alpha` (mapped
+`color`, `edge_color`, `size` (through `size_map`, default `SizeMap()`), `alpha` (mapped
 linearly to `alpha_range`, default (0.2, 1)) and `order`; one object computes each
 series' own density, cached until a setting changes, and exposed as
 `series.stats["density"]`. The colorbar label defaults to `"density"`.
@@ -1678,18 +1911,18 @@ for pdf_io's `draw_markers`; `pl.marker_area(name)` its area.
 ## 8. Output
 
 ```python
-fig.save(path, **options)          # .pdf, .png, .jpg/.jpeg, .jxl
+fig.save(path, **options)          # .pdf, .png, .jpg/.jpeg, .jxl, .avif
 fig.to_bytes(format="pdf", **options)
-fig.draw(canvas, x=0, y=0)         # on any pdf_io canvas; returns (width, height) in pt
-fig.size()                         # (width, height) in pt
+fig.draw(canvas, x=0, y=0)         # on any pdf_io canvas; returns (width, height) in px
+fig.size()                         # (width, height) in px
 p.save(path, …)   p.to_bytes(…)   p.draw(canvas, …)   # one plot alone, at its size in the figure
 ```
 
-Options: `dpi` (images, default 150), `background` (images, default the figure's or
-white), `quality` (the figure's `quality` when not given; JPEG, default 90; JPEG XL,
+Options: `dpi` (images, default 192: two image pixels per px), `background` (default the figure's; unset is
+transparent, white in JPEG), `quality` (the figure's `quality` when not given; JPEG, default 90; JPEG XL and AVIF,
 default lossless; in a PDF, of rasterized content, default lossless), and pdf_io `Document` arguments: `title`, `author`, `compress`, `compression`,
 `system_fonts`, `font_dirs`, `color_mode`, `pdf_a`, … JPEG XL output (`.jxl`) needs
-libjxl. Images inside a PDF (rasterized series, heatmaps) are stored losslessly or as
+libjxl, AVIF output (`.avif`) libavif 1.x. Images inside a PDF (rasterized series, heatmaps) are stored losslessly or as
 JPEG (`quality`), never as JPEG XL, so every PDF reader shows them. `simplify` culls hidden content in PDF output only: PNG, JPEG and
 JPEG XL output draw everything (rasterizing hidden content costs less than culling it,
 and the pixels are the same), and dense lines are still decimated. A plot
@@ -1746,7 +1979,8 @@ pl.style_settings("house")             # the resolved dict (base theme included)
   `"Colorbar.<axis setting>"` (`"Colorbar.tick_direction"`, `"Colorbar.tick_color"`, …)
   applies to colorbar axes only, and `"XAxis.<setting>"`, `"YAxis.<setting>"` to the x or
   y axis of plots only; each wins over `"Axis.<setting>"` there.
-  Values are checked when the style is registered or set.
+  Keys starting with `--` are custom variables (`"--accent": "#c00"`), read by
+  `var(--accent)`. Values are checked when the style is registered or set.
 * **`"base"`.** A style name or a list of names, applied left to right (later ones win);
   the dict's own keys are applied over them. Registered styles use the same form.
 * **Resolution.** A setting is looked up on the object, then as `"Class.name"` in the
@@ -1757,8 +1991,9 @@ pl.style_settings("house")             # the resolved dict (base theme included)
   created (`use_style` innermost, else `set_style`), else `"default"`, which adds nothing
   to `DEFAULTS`.
 * **`scaling`.** A figure setting (default 1, or `"Figure.scaling"` in the style) that
-  multiplies the style's lengths: font sizes, line widths, marker sizes, tick lengths and
-  pads, including the defaults. Values set on objects are not scaled.
+  multiplies every absolute length: font sizes, line widths, marker sizes, tick lengths,
+  pads and gaps, from the defaults, the style or set on objects (not the figure size).
+  Lengths in `em` follow the scaled font size.
 
 Bundled styles (`pl.styles()`), each the defaults of a library expressed in these
 settings (colors, fonts, grid, axis lines, ticks, legend and title placement, palette,
@@ -1806,10 +2041,10 @@ documented default properties. What cannot be expressed: legend titles naming a
 | `slots.py`, `stacking.py`, `labels.py`, `shapes.py` | category slots, stacking, value labels, bulk rectangles and polygons |
 | `stats.py` | bins, densities, contours, LOWESS and swarm layout (pdf_io's C helpers) |
 | `decorations.py` | reference lines, spans, text and annotations |
-| `maps/` | `ColorMap`, `SizeMap`, Oklab, bundled map data |
-| `markers.py`, `style.py`, `text.py` | marker shapes, palette references and dashes, rich one-line text |
-| `palettes.py` | palette registry, bundled palettes, ggplot2's hues (CIE LCh(uv)) |
-| `styles/` | style registry, expansion and scaling; bundled styles |
+| `color/` | colors: `values.py` (the `color` validator, named color scales, palette references, alpha, saturation, luminance), `palettes.py` (palettes: the discrete colors series take in turn; registry, ggplot2's hues), `maps.py` (`ColorMap`: gradients numbers are mapped onto; Oklab from pdf_io), `data.py` (bundled map and palette colors) |
+| `sizemaps.py` | `SizeMap`: values to marker diameters |
+| `markers.py`, `lines.py`, `text.py` | marker shapes, line dash styles, rich one-line text |
+| `styles/` | style registry and expansion; bundled styles (point libraries in `pt`) |
 | `values.py`, `density.py` | values given to `color`/`size` and their rules; `Density` (point density) |
 | `tables.py`, `facets.py` | columns of tables, `group=` splitting (`SeriesGroup`); `facet` |
 | `sharing.py`, `times.py` | shared axes; dates and times on axes |