From f35ad93e8777501f197e7424cfd935e24f90f514 Mon Sep 17 00:00:00 2001
From: Mike Bostock <mbostock@gmail.com>
Date: Mon, 25 Nov 2024 11:36:58 -0800
Subject: [PATCH] document ordinal aspectRatio

---
 docs/features/plots.md  | 2 +-
 docs/features/scales.md | 2 +-
 src/plot.d.ts           | 6 ++++--
 3 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/docs/features/plots.md b/docs/features/plots.md
index ce1e3e89ed..362178cdf5 100644
--- a/docs/features/plots.md
+++ b/docs/features/plots.md
@@ -224,7 +224,7 @@ The default **width** is 640. On Observable, the width can be set to the [standa
 Plot does not adjust margins automatically to make room for long tick labels. If your *y* axis labels are too long, you can increase the **marginLeft** to make more room. Also consider using a different **tickFormat** for short labels (*e.g.*, `s` for SI prefix notation), or a scale **transform** (say to convert units to millions or billions).
 :::
 
-The **aspectRatio** option<a id="aspectRatio" href="#aspectRatio" aria-label="Permalink to &quot;aspectRatio&quot;"></a> <VersionBadge version="0.6.4" />, if not null, computes a default **height** such that a variation of one unit in the *x* dimension is represented by the corresponding number of pixels as a variation in the *y* dimension of one unit.
+The **aspectRatio** option<a id="aspectRatio" href="#aspectRatio" aria-label="Permalink to &quot;aspectRatio&quot;"></a> <VersionBadge version="0.6.4" />, if not null, computes a default **height** such that a variation of one unit in the *x* dimension is represented by the corresponding number of pixels as a variation in the *y* dimension of one unit. The **aspectRatio** option is recommended only when *x* and *y* domains share the same units, such as millimeters. When a position scale is [ordinal](./scales#discrete-scales) (*point* or *band*), consecutive domain values are treated as one unit length apart; for example, if both *x* and *y* are ordinal, then an aspect ratio of one produces a square grid.
 
 <p>
   <label class="label-input">
diff --git a/docs/features/scales.md b/docs/features/scales.md
index 49fed33ea0..f40894570c 100644
--- a/docs/features/scales.md
+++ b/docs/features/scales.md
@@ -292,7 +292,7 @@ Plot.plot({
 ```
 :::
 
-Positions scales also have a **round** option which forces the scale to snap to integer pixels. This defaults to true for point and band scales, and false for quantitative scales. Use caution with high-cardinality ordinal domains (*i.e.*, a point or band scale used to encode many different values), as rounding can lead to “wasted” space or even zero-width bands.
+Position scales also have a **round** option which forces the scale to snap to integer pixels. This defaults to true for point and band scales, and false for quantitative scales. Use caution with high-cardinality ordinal domains (*i.e.*, a point or band scale used to encode many different values), as rounding can lead to “wasted” space or even zero-width bands.
 
 ## Color scales
 
diff --git a/src/plot.d.ts b/src/plot.d.ts
index 05fc238dc5..5024d49694 100644
--- a/src/plot.d.ts
+++ b/src/plot.d.ts
@@ -30,8 +30,10 @@ export interface PlotOptions extends ScaleDefaults {
    * height. Given an aspect ratio of *dx* / *dy*, and assuming that the *x* and
    * *y* scales represent equivalent units (say, degrees Celsius or meters),
    * computes a default height such that *dx* pixels along *x* represents the
-   * same variation as *dy* pixels along *y*. Note: when faceting, set the *fx*
-   * and *fy* scales’ **round** option to false for an exact aspect ratio.
+   * same variation as *dy* pixels along *y*. When *x* or *y* is ordinal,
+   * consecutive domain values are treated as one unit length apart. Note: when
+   * faceting, set the *fx* and *fy* scales’ **round** option to false for an
+   * exact aspect ratio.
    */
   aspectRatio?: number | boolean | null;