Update README

Author: mbostock

README.md

@@ -93,9 +93,7 @@ These options determine the overall layout of the plot; all are specified as num
 * **width** - the outer width of the plot (including margins)
 * **height** - the outer height of the plot (including margins)
 
-The default **width** is 640. On Observable, the width can be set to the [standard width](https://github.com/observablehq/stdlib/blob/main/README.md#width) to make responsive plots. The default **height** is chosen automatically based on the plot’s associated scales; for example, if *y* is linear and there is no *fy* scale, it might be 396.
-
-The default margins depend on the maximum margins of the plot’s constituent [marks](#mark-options). While most marks default to zero margins (because they are drawn inside the chart area), Plot’s [axis](#axis) mark has non-zero default margins. For example, **marginTop** and **marginBottom** are at least 30 if there is a corresponding top or bottom *x* axis, and **marginLeft** and **marginRight** are at least 40 if there is a corresponding left or right *y* axis. For simplicity’s sake and for consistent layout across plots, axis margins are not automatically sized to make room for tick labels; instead, shorten your tick labels or increase the margins as needed.
+The default **width** is 640. On Observable, the width can be set to the [standard width](https://github.com/observablehq/stdlib/blob/main/README.md#width) to make responsive plots. The default **height** is chosen automatically based on the plot’s associated scales; for example, if *y* is linear and there is no *fy* scale, it might be 396. The default margins depend on the maximum margins of the plot’s constituent [marks](#mark-options). While most marks default to zero margins (because they are drawn inside the chart area), Plot’s [axis mark](#axis) has non-zero default margins.
 
 The **style** option allows custom styles to override Plot’s defaults. It may be specified either as a string of inline styles (*e.g.*, `"color: red;"`, in the same fashion as assigning [*element*.style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style)) or an object of properties (*e.g.*, `{color: "red"}`, in the same fashion as assigning [*element*.style properties](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleDeclaration)). Note that unitless numbers ([quirky lengths](https://www.w3.org/TR/css-values-4/#deprecated-quirky-length)) such as `{padding: 20}` may not supported by some browsers; you should instead specify a string with units such as `{padding: "20px"}`. By default, the returned plot has a white background, a max-width of 100%, and the system-ui font. Plot’s marks and axes default to [currentColor](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#currentcolor_keyword), meaning that they will inherit the surrounding content’s color. For example, a dark theme:
 
@@ -968,50 +966,51 @@ Returns a new arrow with the given *data* and *options*.
 
 ### Axis
 
-[Source](./src/marks/axis.js) · [Examples](https://observablehq.com/@observablehq/plot-axis) · Draws an axis to document the visual encoding of the corresponding position scale: *x* and *y*, and *fx* and *fy* if faceting. The axis mark is a [composite mark](#marks) comprised of (up to) three marks: a [vector](#vector) for ticks, a [text](#text) for tick labels, and another [text](#text) for an axis label.
+[Source](./src/marks/axis.js) · [Examples](https://observablehq.com/@observablehq/plot-axis) · Draws an axis to document the visual encoding of the corresponding position scale: *x* or *y*, and *fx* or *fy* if faceting. The axis mark is a [composite mark](#marks) comprised of (up to) three marks: a [vector](#vector) for ticks, a [text](#text) for tick labels, and another [text](#text) for an axis label.
 
-By default, the data for an axis mark are its tick values sampled from the associated position scale’s domain. For control over tick values, you can specify the axis mark’s data explicitly, or use one of the following options:
+By default, the data for an axis mark are its tick values sampled from the associated scale’s domain. For control over tick values, you can specify the axis mark’s data explicitly (_e.g._ as an array of numbers), or use one of the following options:
 
 * **ticks** - the approximate number of ticks to generate, or interval, or array of values
 * **tickSpacing** - the approximate number of pixels between ticks (if **ticks** is not specified)
 * **interval** - an interval or time interval
 
-Note that when an axis mark is declared explicitly (as opposed to an implicit axis), the corresponding scale’s *scale*.ticks and *scale*.tickSpacing options are *not* automatically inherited by the axis mark; however, the *scale*.interval option *is* inherited (because it typically affects the behavior of the position encoding), as is the *scale*.label option. You can declare multiple axis marks for the same position scale with different ticks, and different styles, as desired.
+Note that when an axis mark is declared explicitly using the [**marks** option](#mark-options) (as opposed to an implicit axis), the corresponding scale’s *scale*.ticks and *scale*.tickSpacing options are not automatically inherited by the axis mark; however, the *scale*.interval option *is* inherited, as is the *scale*.label option. You can declare multiple axis marks for the same scale with different ticks, and styles, as desired.
 
-The axis mark supports the following additional options:
+In addition to the [standard mark options](#marks), the axis mark supports the following additional options:
 
-* **anchor** - the orientation: *top*, *bottom* (*x* and *fx*); *left*, *right* (*y* and *fy*); *both*; null to suppress
-* **tickSize** - the length of the tick vector (in pixels; default 6 for *x* and *y*, or 0 for *fx* and *fy*)
+* **anchor** - the orientation: *top*, *bottom* (*x* or *fx*); *left*, *right* (*y* or *fy*); *both*; null to suppress
+* **tickSize** - the length of the tick vector (in pixels; default 6 for *x* or *y*, or 0 for *fx* or *fy*)
 * **tickPadding** - the separation between the tick vector and its label (in pixels; default 3)
 * **tickFormat** - either a function or specifier string to format tick values; see [Formats](#formats)
 * **tickRotate** - whether to rotate tick labels (an angle in degrees clockwise; default 0)
 * **fontVariant** - the font-variant attribute for ticks; defaults to tabular-nums for quantitative axes
 * **label** - a string to label the axis; defaults to the scale’s label, perhaps with an arrow
 * **labelAnchor** - the label anchor: *top*, *right*, *bottom*, *left*, or *center*
 * **labelOffset** - the label position offset (in pixels; default depends on margins and orientation)
-* **ariaLabel** - a short label representing the axis in the accessibility tree
-* **ariaDescription** - a longer textual description for the axis
 * **color** - the color of the ticks and labels (defaults to *currentColor*)
-* **stroke** - the color of the tick vector (defaults to **color**)
-* **fill** - the color of the text labels (defaults to **color**)
 * **textStroke** - the color of the stroke around tick labels (defaults to *none*)
 * **textStrokeOpacity** - the opacity of the stroke around tick labels
 * **textStrokeWidth** - the thickness of the stroke around tick labels (in pixels)
 
-The **x** and **y** channels, if specified, describes the position of the tick and defaults to the axis anchor.
+As a composite mark, the **stroke** option affects the color of the tick vector, while the **fill** option affects the color the text labels; both default to the **color** option, which defaults to *currentColor*. The **x** and **y** channels, if specified, position the ticks; if not specified, the tick positions depend on the axis **anchor**. The orientation of the tick labels likewise depends on the **anchor**. See the [text mark](#text) for details on available options for the tick and axis labels.
+
+The axis mark’s [**facetAnchor**](#facetanchor) option defaults to *top-empty* if anchor is *top*, *right-empty* if anchor is *right*, *bottom-empty* if anchor is *bottom*, and *left-empty* if anchor is *left*. This ensures the proper positioning of the axes with respect to empty facets.
 
-The **axis** option, in this context, is called **anchor** and is one of *top* or *bottom*.
+The axis mark’s default margins depend on its orientation (**anchor**) as follows, in order of **marginTop**, **marginRight**, **marginBottom**, and **marginLeft**, in pixels:
 
-The [**facetAnchor**](#facetanchor) mark option defaults to *bottom-empty* if anchor is bottom, and *top-empty* if anchor is top. This ensures the proper positioning of the axes with respect to empty facets.
+* *top* - 30, 20, 0, 20
+* *right* - 20, 40, 20, 0
+* *bottom* - 0, 20, 30, 20
+* *left* - 20, 0, 20, 40
 
-Plot automatically generates axes for position scales, and draws them below the other marks. When you need more control, you can add axis and grid marks explicitly in the marks options. Note that Plot’s automatic axis for *x* is disabled when a mark’s aria-label property begins by `x-axis `—and likewise for *y*, *fx*, and *fy*.
+For simplicity’s sake and for consistent layout across plots, axis margins are not automatically sized to make room for tick labels; instead, shorten your tick labels (for example using the *k* SI-prefix tick format, or setting a *scale*.transform to show thousands or millions, or setting the **lineWidth** option to wrap long labels) or increase the margins as needed.
 
 #### Plot.axisX(*data*, *options*)
 
 <!-- jsdoc axisX -->
 
 ```js
-Plot.axisX({anchor: "bottom"})
+Plot.axisX({anchor: "bottom", tickSpacing: 80})
 ```
 
 Returns a new *x* axis with the given *options*.
@@ -1020,15 +1019,39 @@ Returns a new *x* axis with the given *options*.
 
 #### Plot.axisY(*data*, *options*)
 
-…same…
+<!-- jsdoc axisY -->
+
+```js
+Plot.axisY({anchor: "left", tickSpacing: 35})
+```
+
+Returns a new *y* axis with the given *options*.
+
+<!-- jsdocEnd axisY -->
 
 #### Plot.axisFx(*data*, *options*)
 
-…same…
+<!-- jsdoc axisFx -->
+
+```js
+Plot.axisFx({anchor: "top", label: null})
+```
+
+Returns a new *fx* axis with the given *options*.
+
+<!-- jsdocEnd axisFx -->
 
 #### Plot.axisFy(*data*, *options*)
 
-…same…
+<!-- jsdoc axisFy -->
+
+```js
+Plot.axisFy({anchor: "right", label: null})
+```
+
+Returns a new *fy* axis with the given *options*.
+
+<!-- jsdocEnd axisFy -->
 
 ### Bar
 
@@ -1475,7 +1498,6 @@ Returns a new *x* grid with the given *options*.
 
 …same…
 
-
 ### Hexgrid
 
 The hexgrid mark can be used to support marks using the [hexbin](#hexbin) layout.