@jsenv/navi 0.29.417 → 0.29.419

package/docs/css_architecture.md

@@ -1,9 +1,13 @@
 # Navi CSS Architecture
 
-- [Overview](#overview)
+Navi components are styled through CSS custom properties and scoped rules. The
+rules that paint and lay a component out are unlayered, so **navi wins by
+default**; the defaults those rules read sit in `@layer navi`, so **any
+unlayered app rule beats them** without `!important`; and the preferred
+override surface is a **component prop**.
+
 - [Where CSS lives: `import.meta.css`](#where-css-lives-importmetacss)
   - [`${}` blinds the whole stylesheet](#-blinds-the-whole-stylesheet)
-  - [Beware when moving a shared sheet out](#beware-when-moving-a-shared-sheet-out)
   - [Browser support: navi's css and your target](#browser-support-navis-css-and-your-target)
 - [Layer structure](#layer-structure)
   - [Why defaults go inside `@layer navi`](#why-defaults-go-inside-layer-navi)
@@ -17,14 +21,6 @@
   - [Say which children the rule means](#say-which-children-the-rule-means)
 - [Summary](#summary)
 
-## Overview
-
-Navi components are styled through a combination of CSS custom properties (variables) and scoped CSS rules. The architecture is designed so that:
-
-1. **Navi wins by default** — the rules that paint and lay a component out are not placed inside `@layer`, so they beat any layered global style. The exception is deliberate and always says so in a comment: a rule navi is happy to hand back sits in `@layer navi` next to the defaults — see [The exception](#the-exception-a-rule-navi-offers-back).
-2. **Defaults are easy to override** — default values for CSS variables are declared inside `@layer navi`, which any unlayered rule on the same element beats whatever its specificity, making them trivially overridable from outside.
-3. **The preferred override surface is component props** — props translate to inline styles or data attributes, not class names.
-
 ---
 
 ## Where CSS lives: `import.meta.css`
@@ -41,20 +37,23 @@ const css = /* css */ `
 import.meta.css = css;
 ```
 
-The `css` constant may be declared next to the assignment or anywhere in the same
-module — the build follows the name to where it is declared. What it cannot
-follow is a name coming from **another** module: `import.meta.css = importedCss`
-is read only when the constant belongs to the module doing the assignment.
+The build reads the css where it is written: **an inline template, or a
+`const` declared at the top level of the module doing the assignment.** It
+follows nothing else — not a `let`, not a name imported from another module,
+and not a `const` declared inside the component next to an assignment made in
+render: that one ships unparsed, and without a warning.
 
-**Keep the assignment in a render, not at module scope.** A component's
-stylesheet is adopted when the component first renders, so a page that never
-renders it never carries it, and a bundler that sees no caller drops the css
-along with the code. `import.meta.css = css` at the top level of a module makes
-the sheet a module side effect: it lands on every page importing the module, for
-a component that may never appear, and nothing can shake it out.
+**Keep the assignment in a render, not at module scope.** The sheet is adopted
+when the assignment runs: from a render, a page that never renders the
+component never carries it, and a bundler that sees no caller drops the css
+along with the code; at module scope, it lands on every page importing the
+module, and nothing can shake it out. Assign at module scope only for a module
+that is a side effect by design — an app's tokens, say.
 
-That is also how a stylesheet shared between components is written — a module of
-its own, exposing an install function its callers run from their render:
+The setter is keyed by module: **two assignments in one module do not add up**,
+the second replaces the first. A stylesheet shared between components is
+therefore a module of its own, exposing an install function its callers run
+from their render:
 
 ```js
 // input_css.js
@@ -65,8 +64,6 @@ const inputCss = /* css */ `
     }
   }
 `;
-// Keyed on this module, so the controls drawn as a .navi_input box share one
-// stylesheet instead of each carrying a copy.
 export const installInputCss = () => {
   import.meta.css = inputCss;
 };
@@ -83,36 +80,48 @@ export const Textarea = (props) => {
 };
 ```
 
-Note the setter is keyed by module: **two assignments in one module do not add
-up**, the second replaces the first. One `import.meta.css` per module — which is
-why the shared sheet has to live in a module of its own rather than be
-concatenated into the component's.
+Extracting a shared sheet changes **cascade order**: the install call runs
+before the component's own assignment, so the extracted rules come _before_ the
+component's sheet rather than where they were written. That matters only for
+the same selector at the same specificity in the same layer — check for that
+before splitting.
 
-The exception is a module that is a side effect by design — `navi_css_vars.js`
-and the sheets it pulls in are the app's tokens, always needed, and assign at
-module scope on purpose.
+A module reached by `import()` carries its sheet in its chunk, adopted when the
+chunk runs: see
+[dynamic_import.md](./dynamic_import.md#importmetacss-on-the-far-side-of-a-split).
 
 ### `${}` blinds the whole stylesheet
 
 A substitution the build cannot read makes the **entire** template opaque, not
 just its line, and the stylesheet then ships verbatim: comments and whitespace
-included, nothing transpiled for the browsers the app targets (nesting,
-`light-dark()`, `color-mix()` reach them as written), a `url("./icon.svg")`
-neither copied nor hashed and resolved against the document — a silent 404 in
-production — nothing checked, nothing minified. The build warns about it; a css comment
-containing `jsenv-css-opaque` inside the template silences that one template when there
-is no way around it.
+included, nothing lowered for the browsers the app targets, a
+`url("./icon.svg")` neither copied nor hashed and resolved against the
+document — a silent 404 in production — nothing checked, nothing minified.
 
 The one substitution the build reads stands exactly **where a css value
-stands** — inside a rule block, after the `:` of a declaration, not in a string,
-in `url()`, in a selector, a property name or an at-rule prelude. Everything
-else blinds the sheet. So write css without a `${}`: a value the JS knows is a
-custom property the css reads (`width: var(--panel-width, 300px)`, set from JS
-with `element.style.setProperty`); a selector or attribute name held in a JS
-constant is written out literally in the css, the constant staying on the JS
-side; a variant is a data attribute with both branches in the css; a repeated
-block is a selector list; a shared sheet is a module exposing an install
-function, as above.
+stands**: inside a rule block, after the `:` of a declaration — not in a
+string, in `url()`, in an at-rule prelude, in a selector or a property name —
+and it must come out of the build's css transformation exactly once (a
+declaration duplicated under a vendor prefix makes it twice). Anything else
+ships the template as written, and the build warns
+(`import.meta.css shipped as written`, naming the file and the `${}`). When
+there is genuinely no way around it, a css comment containing
+`jsenv-css-opaque` inside the template silences that one template — keep it
+short: an opaque template ships its comments.
+
+So write css without a `${}`:
+
+- a value the JS knows → a custom property the css reads
+  (`width: var(--panel-width, 300px)`), set with `element.style.setProperty`;
+- a class or attribute name held in a JS constant → written out literally in
+  the css, the constant staying on the JS side; a name you did not want to
+  repeat → css nesting (`&[data-loading]`);
+- a variant → a data attribute, both branches written out in the css;
+- an asset → a literal `url()`, which the build follows, copies and versions (a
+  truly dynamic url goes in a custom property);
+- a block of declarations repeated in several rules → a selector list;
+- a sheet shared between modules → a module exposing an install function, as
+  above.
 
 ```js
 const SWIPE_AXES_ATTRIBUTE = "data-swipe";
@@ -129,52 +138,36 @@ import.meta.css = /* css */ `
 element.setAttribute(SWIPE_AXES_ATTRIBUTE, "x");
 ```
 
-### Beware when moving a shared sheet out
-
-Splitting a chunk out of a template changes **cascade order**: in the template
-it sits where it was written, while an extracted sheet is adopted by the install
-call, which runs before the component's own assignment — so its rules come
-_before_ the component's sheet. That matters only when the two carry
-the same selector at the same specificity and in the same layer — check for that
-before splitting. In navi, `popup_css.js` and `surface_text_css.js` overlap
-`.navi_dialog` and `.navi_popover` with dialog's and popover's own css, which is
-why dialog.jsx and popover.jsx interpolate them, and mark those two templates
-`jsenv-css-opaque`.
+### Browser support: navi's css and your target
 
-### A sheet on the far side of a split
+navi's css is written for current browsers — css nesting, `light-dark()`,
+`color-mix()` on `currentColor` — and `dist/` ships it as authored, built for
+Chrome 123.
 
-A module reached by `import()` carries its stylesheet in its chunk, adopted
-when the chunk runs: a fallback rendered before it cannot use its classes, and
-between unlayered sheets the last adopted wins. What follows for code loaded
-on demand is in [dynamic_import.md](./dynamic_import.md).
+An app built with jsenv reads navi's stylesheets like its own and lowers them
+to the target it declares. jsenv's default target is recent and touches
+nothing; an app that must support older browsers says so once, and both its
+dev server and its build follow — the declaration and what each step down
+costs are in
+[jsenv's browser support](https://github.com/jsenv/core/blob/main/docs/users/c_build/c_build.md#21-browser-support).
+Most of navi's css then comes out lowered, not all of it:
 
-### Browser support: navi's css and your target
+- the `color-mix()` formulas built on `currentColor` or a `var()` are kept as
+  written — the color keywords and the hover, read-only and disabled shades
+  are made of them — and a browser without `color-mix()` drops them;
+- a few of navi's stylesheets (`Dialog`'s, `Popover`'s, the callout's) are
+  opaque templates, shipped as written: they need native nesting;
+- a lowered `light-dark()` is a switch keyed on `prefers-color-scheme`: navi's
+  tokens, resolved on `:root`, no longer follow a `color-scheme` set on one
+  element (the dark panel a `Wheel` relies on).
 
-**navi does not require recent browsers.** Its css is written with modern
-features — css nesting, `light-dark()`, `color-mix()` — and it ships that way:
-navi's own build targets a runtime where all of it is native, so what lands in
-`dist/` is what was authored, unrewritten.
-
-The runtime that decides is **yours**. An app's build reads navi's stylesheets
-out of `node_modules` like any other css and lowers them to the target the app
-declares. Targeting Chrome 89, everything above comes out as nesting-free rules
-and a pair of custom properties standing in for `light-dark()`; targeting the
-default, nothing is touched.
-
-Which is the part worth knowing: **jsenv's default target is recent**, and by
-default it assumes the modern form is fine. An app that must support older
-browsers says so, once, and both its dev server and its build follow — the
-declaration and what each step down costs are in
-[jsenv's browser support](https://github.com/jsenv/core/blob/main/docs/users/c_build/c_build.md#21-browser-support).
-Nothing in the app's own css has to change either: it is lowered by the same
-pass.
+Under another bundler nothing is lowered: the css runs as navi's own build
+wrote it.
 
-One thing is NOT lowered, and it is the trap the section above already names: a
-stylesheet the build cannot parse. A `${}` outside a value position makes the
-whole template opaque, and an opaque template is shipped verbatim — nesting
-included, `light-dark()` included, whatever the target. Such a stylesheet
-silently requires the browsers its own css requires, and no declaration can
-lower it. That is the strongest reason not to write one.
+The same holds for the app's own sheets, with one hard stop: **an opaque
+template is never lowered**, whatever the target. It silently requires the
+browsers its own css requires, and no declaration can change that — the
+strongest reason not to write a `${}`.
 
 ---
 
@@ -183,24 +176,24 @@ lower it. That is the strongest reason not to write one.
 ```
 @layer navi {
   /* CSS variable defaults — and, when navi says so, a rule it offers back */
-  .navi_button {
-    --button-font-size: var(--navi-control-font-size);
-    --button-border-radius: var(--navi-control-border-radius);
+  .navi_thing {
+    --thing-border-radius: var(--navi-control-border-radius);
   }
 }
 
 /* The rules that paint and lay out — outside any layer */
-.navi_button {
-  font-size: var(--button-font-size);
-  border-radius: var(--button-border-radius);
+.navi_thing {
+  box-sizing: border-box;
+  border-radius: var(--thing-border-radius);
 }
 ```
 
 ### Why defaults go inside `@layer navi`
 
-CSS cascade layers are ordered below unlayered styles. Anything declared in `@layer navi` is automatically beaten by any unlayered rule from the page or a design system, without needing `!important`.
-
-This means an app can override a Navi default from its own unlayered CSS, without `!important`, as long as its selector targets the same element the default was declared on:
+Cascade layers are ordered below unlayered styles: anything declared in
+`@layer navi` is beaten by any unlayered rule from the page or a design system,
+without `!important`, as long as that rule targets the element the default was
+declared on:
 
 ```css
 /* App CSS — no layer needed, automatically wins over @layer navi */
@@ -209,34 +202,29 @@ This means an app can override a Navi default from its own unlayered CSS, withou
 }
 ```
 
-Targeting the same element is not a detail — see [`--navi-*` vs `--component-*`](#--navi--vs---component--where-the-override-has-to-go) below.
+Targeting the same element is not a detail — see
+[`--navi-*` vs `--component-*`](#--navi--vs---component--where-the-override-has-to-go)
+below.
 
 ### Why actual rules stay outside any layer
 
-Navi components often need to enforce specific values that global resets or utility libraries may clobber — for example `box-sizing: content-box`, `white-space: nowrap`, or `display: inline-flex`. If these rules were inside `@layer navi`, any unlayered global style (e.g. `* { box-sizing: border-box }`) would silently override them, breaking component layout.
-
-By keeping rules outside any layer, Navi wins by default without resorting to `!important`. An app that genuinely needs to change a structural rule should do so through the CSS variable surface, not by overriding the rule directly.
+A component enforces values that global resets and utility libraries clobber —
+`box-sizing: content-box`, `white-space: nowrap`, `display: inline-flex`.
+Inside `@layer navi`, any unlayered global style
+(`* { box-sizing: border-box }`) would silently override them and break the
+layout. Unlayered, navi wins by default without `!important`; an app that needs
+to change a structural rule does it through the CSS variable that feeds it, not
+by overriding the rule.
 
 ### The exception: a rule navi offers back
 
-Some rules are not structure — they are what navi puts there in the absence of
-anything else, and an app (or another navi component) is meant to win over them
-plainly. Those go **inside** `@layer navi`, rules and all, and each one carries a
-comment naming who is supposed to win:
-
-- `[navi-aspect-ratio]`'s `min-width/min-height` and `.navi_icon`'s `display`
-  (`box.jsx`, `text.jsx`), so box.jsx's own unlayered `[navi-box-flow]`
-  attributes can still change the display;
-- the text properties a surface takes back from its opener
-  (`surface_text_css.js`), so an app that wants one of them back says so;
-- the `[data-url-target]` mark, the document's `line-height` and
-  `font-family`, a Field's spacing and a Label's dimmed color — appearance with
-  no structural role;
-- `[data-navi-safe-area]`'s padding (`safe_area.js`), which is a suggestion for
-  an element the **app** owns.
-
-So the layer is readable from the outside as a statement rather than an
-accident:
+Some rules are not structure: they are what navi puts there when nothing else
+says anything, and an app (or another navi component) is meant to win over them
+plainly. Those go **inside** `@layer navi`, rules and all, and each carries a
+comment naming who is supposed to win — `[data-navi-safe-area]`'s padding, a
+suggestion for an element the **app** owns; a button's `display`, font and
+line, so an app's own button typography wins without going through the
+`--button-*` variables.
 
 | In `@layer navi`                                 | Unlayered                        |
 | ------------------------------------------------ | -------------------------------- |
@@ -245,9 +233,8 @@ accident:
 
 Either way an app never has to inflate a selector: a layered rule loses to any
 unlayered rule of the app's, and an unlayered one is reached through the
-variable that feeds it — `--picker-border-radius` for the picker's corners,
-`--navi-control-border-radius` for every control's, both declared in the layer
-and both overridable from a single-class rule.
+variable that feeds it (`--picker-border-radius` for a picker's corners,
+`--navi-control-border-radius` for every control's).
 
 ---
 
@@ -255,7 +242,9 @@ and both overridable from a single-class rule.
 
 ### 1. Component props (preferred)
 
-Props are the primary way to customize appearance. They translate to inline `style` attributes or `data-*` attributes, both of which have higher specificity than class-based rules.
+Props are the primary way to customize appearance. They translate to an inline
+`style`, which outranks any selector, or to a `data-*` attribute navi's own
+rules read (an attribute selector weighs what a class does).
 
 ```jsx
 // Size and color via props
@@ -265,60 +254,14 @@ Props are the primary way to customize appearance. They translate to inline `sty
 <Button style={{ "--button-font-size": "18px" }} />
 ```
 
-#### Variants set defaults, never resolved values
-
-A control resolves each styled property in two steps: the public variable
-holds what was asked for (`--picker-background-color`), and an internal
-`--x-` variable holds what is finally painted, per state:
-
-```css
-.navi_picker {
-  --x-picker-background-color: var(--picker-background-color);
-
-  &[data-hover] {
-    --x-picker-background-color: var(--picker-background-color-hover);
-  }
-}
-```
-
 A variant (`icon`, `discrete`, `bare`, `border`, `headless`…) describes what
-the caller did **not** say, so it writes the public variable — the default —
-and never the `--x-` one:
-
-```css
-&[data-variant="icon"] {
-  /* ✅ a default: a backgroundColor prop, being inline on this same element, wins */
-  --picker-background-color: transparent;
-  /* ❌ a verdict: the prop is read, translated, and then thrown away */
-  --x-picker-background-color: transparent;
-}
-```
-
-Writing `--x-` from a variant is the one failure mode that costs real time to
-diagnose: the prop is accepted, it reaches its variable with the right value,
-and nothing happens. A prop silently without effect is worse than a prop
-refused.
-
-Two things come with moving the default:
-
-- the **per-state** variables are derived from the base one by formula
-  (`hover` = 5% black over the background, `disabled` = 5% grey), so a variant
-  that clears the background must re-point them at the base
-  (`--picker-background-color-hover: var(--picker-background-color)`), or a box
-  reappears on hover under a control that is supposed to have none. When the
-  variant does have a resting movement, express it as a mix **into** the
-  background (`color-mix(in srgb, currentColor 8%, var(--picker-background-color))`)
-  rather than a replacement, so it still composes with a color the caller gave.
-- a variable fed by another prop keeps that chain in its fallback:
-  `--button-background-color: var(--button-background, transparent)` leaves both
-  `background` and `backgroundColor` working.
-
-The same holds for sizing: a variant lowers `--picker-padding-x-default`, not
-`--x-picker-padding-left`.
+the caller did not say: it only moves defaults, so a prop given next to it
+always wins.
 
 ### 2. CSS variables (for global or theme-level changes)
 
-When the same change applies to many components (e.g. a design token update), set the variable at a higher scope:
+When the same change applies to many components (e.g. a design token update),
+set the variable at a higher scope:
 
 ```css
 /* Override Navi's default at the page or theme level */
@@ -327,20 +270,33 @@ When the same change applies to many components (e.g. a design token update), se
 }
 ```
 
-Because Navi's `--navi-*` defaults are themselves declared on `:root` inside `@layer navi`, this unlayered `:root` rule targets the same element and wins automatically.
+Navi's `--navi-*` defaults are themselves declared on `:root` inside
+`@layer navi`, so this unlayered `:root` rule targets the same element and wins
+automatically.
+
+How wide popups may ever get is the app's own screen, stated once on `:root`
+with `--navi-app-max-width` — never `--dialog-max-width`, a `--component-*`
+token every dialog resets on itself: see
+[safe_area.md](./safe_area.md#an-app-that-is-narrower-than-the-window).
 
 #### `--navi-*` vs `--component-*`: where the override has to go
 
-The two families are **not** interchangeable, and layers have nothing to do with it:
+The two families are **not** interchangeable, and layers have nothing to do
+with it:
 
-| Token           | Declared on             | Overridable from `:root`?       |
-| --------------- | ----------------------- | ------------------------------- |
-| `--navi-*`      | `:root` (`@layer navi`) | Yes                             |
-| `--component-*` | `.navi_<component>`     | **No** — must match the element |
+| Token           | Declared on             | Overridable from `:root`?                                                    |
+| --------------- | ----------------------- | ---------------------------------------------------------------------------- |
+| `--navi-*`      | `:root` (`@layer navi`) | Yes — but the five color keywords stop at each popup and callout (see below) |
+| `--component-*` | `.navi_<component>`     | **No** — must match the element                                              |
 
-For a custom property, a declaration made **on the element itself** always beats the same property **inherited** from an ancestor. The cascade (specificity, layers, `!important`) only arbitrates between declarations targeting the same element — it never lets an ancestor win over the element's own declaration.
+For a custom property, a declaration made **on the element itself** always
+beats the same property **inherited** from an ancestor. The cascade
+(specificity, layers, `!important`) only arbitrates between declarations
+targeting the same element — it never lets an ancestor win over the element's
+own declaration.
 
-So this does nothing, because `.navi_link` declares `--link-color-pressed` on itself:
+So this does nothing, because `.navi_link` declares `--link-color-pressed` on
+itself:
 
 ```css
 :root {
@@ -367,54 +323,47 @@ Three ways to actually change it:
 <Link style={{ "--link-color-pressed": "blue" }} />
 ```
 
-Note that scoping to an ancestor is not enough: `.my-sidebar { --link-color-pressed: blue }` fails for the same reason `:root` does. The selector has to reach the link element itself.
+Scoping to an ancestor is not enough: `.my-sidebar { --link-color-pressed: blue }`
+fails for the same reason `:root` does. The selector has to reach the link
+element itself.
 
-When a component default deserves to be themed globally, promote it: declare a `--navi-<component>-<thing>` in [navi_css_vars.js](../src/navi_css_vars.js) and make the component default read `var(--navi-…)`.
+When a component default deserves to be themed globally, promote it: declare a
+`--navi-<component>-<thing>` in [navi_css_vars.js](../src/navi_css_vars.js) and
+make the component default read `var(--navi-…)`.
 
 #### Two planes: the paper and the frame
 
-An app draws on two planes, and navi names both so that nothing has to invent
-the second one:
-
-- **the paper**, `--navi-surface-color`, what content sits on — a control's
-  background, a card, a popup;
-- **the frame**, `--navi-chrome-color`, what surrounds a screen — a top bar, a
-  side menu, a toolbar.
-
-```jsx
-<Box background="chrome" />
-```
-
-The frame is derived from the paper (a step toward the dark on a light page,
-toward the light on a dark one) rather than written as a literal, which is the
-whole point: `#f6f7f9` on a bar is a bar that stops being one in dark mode, and
-a bar painted in the paper's own color on a page of that color is not a bar, it
-is a line. An app that wants another frame sets the one token on `:root`.
+The frame around a screen — a top bar, a side menu, a toolbar:
+`--navi-chrome-color`, `<Box background="chrome" />` — is derived from the
+paper content sits on (`--navi-surface-color`), never written as a literal: a
+literal on a bar stops being a bar in dark mode. An app that wants another
+frame sets the one token on `:root`.
 
 #### A surface is a new paper: what reaches a popup from its opener
 
 A popup (`Dialog`, `Popover`, everything built on them) and a callout are
-painted in the top layer but live in the DOM subtree of what opened them. For
-the cascade they are descendants of that element: every inherited property and
-every custom property declared on an ancestor reaches them, the top layer
-changing nothing about it. A dark card that writes in white, declared on the
-card, is the color a dialog opened from that card starts with.
+painted in the top layer but live in the DOM subtree of what opened them — on
+purpose: they inherit the opener's fonts, colors and custom properties, and
+they leave with the screen that opened them. For the cascade they are
+descendants of that element, the top layer changing nothing about it: a dark
+card that writes in white, declared on the card, is the color a dialog opened
+from that card starts with.
 
 Navi takes back what it knows a surface needs of its own — declared on the
 surface element itself, so it beats whatever an ancestor declared, whatever
-the layer (see the table above):
+the layer:
 
-| taken back                                                                                  | where                                                                                                         |
-| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| the ink (`color`)                                                                           | `--navi-popup-color` on `.navi_popover` / `.navi_dialog`; `revert` (the UA's `CanvasText`) on `.navi_callout` |
-| text properties that belong to the opener (alignment, transform, shadow, spacing, wrapping) | `surface_text_css.js`, which also says what is deliberately kept                                              |
-| the five color keywords `--navi-color-primary/secondary/emphasis/discrete/hint`             | re-declared on each surface in `navi_css_vars.js`                                                             |
+| taken back                                                                                  | how                                                                                  |
+| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| the ink (`color`)                                                                           | `--navi-popup-color` on a popup; the UA's `CanvasText` on a callout                  |
+| text properties that belong to the opener (alignment, transform, shadow, spacing, wrapping) | reset in `@layer navi`, so an app that wants one of them back says so on the surface |
+| the five color keywords `--navi-color-primary/secondary/emphasis/discrete/hint`             | re-declared on each surface, so a `:root` value of one stops there                   |
 
-Everything else declared on a container is inherited by the popup it opens.
-That is the shape of the bug to expect: a token an app pinned on a container
-for that container's paper — a background, a border color, a spacing, one of
-its own `--app-*` — arriving on a popup that has a different paper. When it
-hits, the answers are, in order:
+Everything else declared on a container reaches the popup it opens. That is the
+shape of the bug to expect: a token an app pinned on a container for that
+container's paper — a background, a border color, a spacing, one of its own
+`--app-*` — arriving on a popup that has a different paper. The answers, in
+order:
 
 1. the token is about the paper and navi owns it: re-declare it on the surface,
    next to the color keywords;
@@ -443,14 +392,13 @@ ratio on `:root`, and the page and its popups agree:
 }
 ```
 
-The ratio is a `:root` knob only, and this is the trap to know about. A `var()`
-inside a custom property is substituted where **that** property is declared,
-not where it is read: `--navi-color-secondary` is declared on `:root` (and on
-each surface), so the `80%` is baked in there and a card inherits the
-already-mixed formula. A ratio set on a container changes nothing for the
-container's own text — and it _is_ read by the next surface opened from it,
-which re-declares the formula and resolves the `var()` against the inherited
-ratio:
+The ratio is a `:root` knob only. A `var()` inside a custom property is
+substituted where **that** property is declared, not where it is read:
+`--navi-color-secondary` is declared on `:root` (and on each surface), so the
+`80%` is baked in there and a card inherits the already-mixed formula. A ratio
+set on a container changes nothing for the container's own text — and it _is_
+read by the next surface opened from it, which re-declares the formula and
+resolves the `var()` against the inherited ratio:
 
 ```css
 .card {
@@ -462,35 +410,26 @@ ratio:
 ```
 
 So a theme is a number on `:root`; a paper is a color, pinned on the container,
-and it stops at the surface. What must not be done to make container ratios
-work is declaring the formulas on `*` so they resolve on every element: the
-pinned keyword above would then be overwritten on each of the card's children,
-and a paper could no longer say anything.
-
-#### An app narrower than the screen
-
-A dialog lives in the browser's top layer and is calibrated on the viewport, so
-an app that is a column in a wide window states its own screen once, on `:root`,
-with `--navi-app-max-width` — and never caps popups through
-`--dialog-max-width`, a `--component-*` token every dialog resets on itself and
-a `maxWidth` prop writes inline. The whole of it, placement included, is in
-[safe_area.md](./safe_area.md#an-app-that-is-narrower-than-the-window).
+and it stops at the surface. Declaring the formulas on `*` to make container
+ratios work is the thing not to do: it would overwrite the pinned keyword on
+each of the card's children, and a paper could no longer say anything.
 
 ### 3. Direct rule override (avoid unless necessary)
 
-Overriding the actual CSS rules (not the variables) is intentionally hard — that is by design. If you find yourself needing to do this, it usually means a CSS variable should be exposed for that property. Open an issue or add the variable yourself and contribute it back.
+Overriding the actual CSS rules (not the variables) is intentionally hard. If
+you find yourself needing to, a CSS variable should usually be exposed for that
+property: open an issue, or add the variable and contribute it back.
 
 ---
 
 ## Counting children: what navi puts in your tree
 
-Some of what navi shows is rendered inside the tree you wrote. A popup renders
-in its opener's own subtree, so a `Dialog` or `Popover` written next to the
-button that opens it is a sibling of that button. A callout — the speech bubble
-a control pops to explain itself — is mounted on what it explains, or beside it
-when that element cannot hold it (a `<button>`, an `<input>`, anything inside a
-`<label>`). This is deliberate: they inherit your fonts, your colors, your
-custom properties, and they leave with the screen that opened them.
+Some of what navi shows is rendered inside the tree you wrote (see
+[A surface is a new paper](#a-surface-is-a-new-paper-what-reaches-a-popup-from-its-opener)):
+a `Dialog` or `Popover` written next to the button that opens it is a sibling
+of that button, and a callout — the speech bubble a control pops to explain
+itself — is mounted on what it explains, or beside it when that element cannot
+hold it (a `<button>`, an `<input>`, anything inside a `<label>`).
 
 None of them draws in the flow. They are `position: fixed`/`absolute`, most of
 them in the top layer: no grid track, no flex item, no line box, no gap. They
@@ -512,17 +451,14 @@ open:
 ```
 
 Press the third cell, its callout opens, and the cell is no longer the last
-child: it loses the span and halves. Close the callout and it comes back. The
-grid reserved nothing — the rule simply stopped matching. What makes this one
-nasty is that it is invisible from the app: the CSS is right, the JSX is right,
-and the trap only springs on an interaction, after the layout was reviewed.
+child: it loses the span and halves. Close the callout and it comes back.
 
 ### Say which children the rule means
 
 A counting pseudo-class takes what to count: `:nth-child(An+B of S)` and
 `:nth-last-child(An+B of S)` walk only the children matching `S`, so name your
 own — either by what they are, or by what navi's out-of-flow elements all carry
-(`navi-out-of-flow`, the same marker navi's own `Group` reads):
+(`navi-out-of-flow`, the same marker navi's own [`Group`](./group.md) reads):
 
 ```css
 .grid > .cell:nth-last-child(1 of .cell):nth-child(odd of .cell) {
@@ -553,14 +489,14 @@ elements and the boxes before and after.
 
 ## Summary
 
-| What you want to change                                       | How to do it                                                                                                                   |
-| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| One component instance                                        | Component prop or `style` attribute                                                                                            |
-| All instances of a component                                  | `--component-*` in unlayered app CSS, on a selector matching the component                                                     |
-| A global design token                                         | `--navi-*` on `:root`                                                                                                          |
-| The share of ink in `secondary`/`emphasis`/`discrete`/`hint`  | `--navi-color-*-mix` on `:root` — never on a container                                                                         |
-| A container's own paper (a dark card)                         | `color` on the container, plus a `--navi-color-*` keyword pinned if its formula reads wrong there; both stop at the next popup |
-| How wide popups may ever get                                  | `--navi-app-max-width` on `:root`                                                                                              |
-| A structural layout rule                                      | Expose a new CSS variable (contribute)                                                                                         |
-| A rule counting children of a container holding navi controls | `:nth-child(… of S)`, `:not([navi-out-of-flow])`, or a class — a popup or a callout is a child too                             |
-| What a variant decided                                        | A prop — a variant only ever moves defaults, so props keep winning                                                             |
+| What you want to change                                       | How to do it                                                                                       |
+| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| One component instance                                        | Component prop or `style` attribute                                                                |
+| All instances of a component                                  | `--component-*` in unlayered app CSS, on a selector matching the component                         |
+| A global design token                                         | `--navi-*` on `:root`                                                                              |
+| The share of ink in `secondary`/`emphasis`/`discrete`/`hint`  | `--navi-color-*-mix` on `:root` — never on a container                                             |
+| A container's own paper (a dark card)                         | `color` on it, plus a keyword pinned if its formula reads wrong; both stop at the next popup       |
+| How wide popups may ever get                                  | `--navi-app-max-width` on `:root`                                                                  |
+| A structural layout rule                                      | Expose a new CSS variable (contribute)                                                             |
+| A rule counting children of a container holding navi controls | `:nth-child(… of S)`, `:not([navi-out-of-flow])`, or a class — a popup or a callout is a child too |
+| What a variant decided                                        | A prop — a variant only ever moves defaults, so props keep winning                                 |