@axiapps/axi-design 1.33.0 → 1.35.0

package/dist/axi.css

@@ -84,7 +84,26 @@
      against a fill lighter than itself. Every outline in this language is
      near-black on the assumption of a ground the lines can be darker than; a
      well IS at ground level, so an ink edge round one is a black line on a
-     black field. Raised takes ink, sunk takes the rule. */
+     black field. Raised takes ink, sunk takes the rule.
+
+     And what the fill names is not the .axi-well class - it is the level. A
+     button at rest, a field, a select, a checkbox, an avatar, a rank, a code
+     span, a hovered row in a popover: not one of them is raised off what holds
+     it, and every one of them was spelled --axi-ground, because on a theme
+     whose surfaces are opaque "flat on its container" and "the page colour"
+     are the same colour. They stop being the same colour the instant a theme
+     makes the container translucent, which is how the whole set went black at
+     once and why this is written here rather than fourteen times downstream.
+     Above this level is --axi-surface (.axi-kbd is the one control in the
+     language that is genuinely raised, and says so). Below it is --axi-ground
+     proper, which now means the page and only the page: body, the sheet, the
+     window, the masthead - the things content scrolls under, which need real
+     opacity and not a subtraction. Everything between the two is this token.
+
+     The LINE does not come along. --axi-well-line is for a well cut into the
+     page, where there is nothing left for ink to be darker than; a control is
+     cut into a SURFACE and its ink edge still has a fill above it to read
+     against. Every component below keeps --axi-ink-line. */
   --axi-well-fill: var(--axi-ground);
   --axi-well-line: var(--axi-rule);
   --axi-text: #f4f6f9;
@@ -371,13 +390,29 @@ button.axi-panel--tile:hover,
   padding: var(--axi-well-pad, 10px);
 }
 
+/* The reading-scale well, which the comment above describes and this language
+   then made every consumer spell out by hand. Saying `--axi-radius-sm` inline
+   is fine for the handful of instances that comment imagined; the first real
+   consumer to be counted had fifty, and fifty inline style attributes is the
+   thing a class exists to prevent. The same argument produced .axi-btn--sm.
+
+   Only the radius, because that is the only thing that changes: a recess the
+   size of a single reading still holds objects that carry their own padding, so
+   the pad knob is still the right way to say anything else. */
+.axi-well--sm { --axi-well-radius: var(--axi-radius-sm); }
+
 /* ---------- button ---------- */
 .axi-btn {
   display: inline-flex; align-items: center; gap: 8px;
   padding: var(--axi-btn-pad, 12px 20px);
   border: var(--axi-border-control) solid var(--axi-ink-line);
   border-radius: var(--axi-radius-sm);
-  background: var(--axi-ground);
+  /* Flat on its container, which is --axi-well-fill and not the page colour -
+     the argument is in src/tokens.css at that token. A button at rest carries
+     no block: it is level with the panel holding it and lifts on hover, so the
+     resting fill is the level's, and --axi-btn--primary below is the one that
+     rests raised and fills with the accent instead. */
+  background: var(--axi-well-fill);
   color: var(--axi-text-dim);
   font: var(--axi-t-label);
   letter-spacing: var(--axi-ls-label);
@@ -460,7 +495,8 @@ button.axi-panel--tile:hover,
   padding: var(--axi-pill-pad, 12px 20px);
   border: var(--axi-border-control) solid var(--axi-ink-line);
   border-radius: var(--axi-radius-sm);
-  background: var(--axi-ground);
+  /* The button's fill for the button's reason - see .axi-btn above. */
+  background: var(--axi-well-fill);
   color: var(--axi-text-dim);
   font: var(--axi-t-label);
   letter-spacing: var(--axi-ls-label);
@@ -654,7 +690,10 @@ button.axi-panel--tile:hover,
 .axi-input {
   width: 100%;
   padding: var(--axi-input-pad, 11px 12px);
-  background: var(--axi-ground);
+  /* A field is the recessed thing in any bar it sits in - .axi-kbd's comment
+     below leans on exactly that - so it takes the level's fill. See
+     --axi-well-fill in src/tokens.css. */
+  background: var(--axi-well-fill);
   border: var(--axi-border-control) solid var(--axi-ink-line);
   border-radius: var(--axi-radius-sm);
   color: var(--axi-text);
@@ -689,14 +728,15 @@ button.axi-panel--tile:hover,
    `em`, not `px`: this lands in body copy and in 10px captions alike, and a
    literal that does not track the text around it reads as a different voice.
 
-   It sits on --axi-ground where .axi-kbd sits on --axi-surface, and the
+   It sits on --axi-well-fill where .axi-kbd sits on --axi-surface, and the
    reason is already written down one rule below: a key is raised off what it
-   is printed on, and a quoted literal is sunk into it. */
+   is printed on, and a quoted literal is sunk into it. It said --axi-ground
+   for as long as sunk and the page were the same colour; see that token. */
 .axi-code,
 .axi-prose code {
   font-family: var(--axi-mono);
   font-size: .88em;
-  background: var(--axi-ground);
+  background: var(--axi-well-fill);
   color: var(--axi-text);
   border: var(--axi-border-hairline) solid var(--axi-ink-line);
   border-radius: var(--axi-radius-sm);
@@ -736,7 +776,10 @@ button.axi-panel--tile:hover,
   padding: 10px 30px 10px 9px;
   border: var(--axi-border-control) solid var(--axi-ink-line);
   border-radius: var(--axi-radius-sm);
-  background-color: var(--axi-ground);
+  /* The field's fill, because a closed select is a field - see .axi-input. The
+     longhand stays: a caret rides in background-image and the shorthand would
+     reset it. */
+  background-color: var(--axi-well-fill);
   color: var(--axi-text-dim);
   font: var(--axi-t-label);
   font-size: 12.5px;
@@ -795,8 +838,12 @@ button.axi-panel--tile:hover,
     letter-spacing: var(--axi-ls-label);
     text-transform: uppercase;
   }
+  /* A row under the cursor sinks rather than lighting up, so the hover is the
+     level's fill - and this popover is filled with --axi-surface-raised, which
+     a theme may take translucent, so an opaque row here is the black patch
+     --axi-well-fill exists to prevent. Same for the picker's rows below. */
   .axi-select option:hover, .axi-select option:focus {
-    background: var(--axi-ground); color: var(--axi-text);
+    background: var(--axi-well-fill); color: var(--axi-text);
   }
   /* The page-wide focus ring sits 2px outside its element; inside a picker
      that is 2px into the neighbouring row, so pull it back in. */
@@ -895,7 +942,7 @@ button.axi-panel--tile:hover,
   font-weight: 900;
 }
 .axi-picker__opt:hover, .axi-picker__opt:focus {
-  background: var(--axi-ground); color: var(--axi-text);
+  background: var(--axi-well-fill); color: var(--axi-text);
 }
 /* The page-wide focus ring sits 2px outside its element; inside a popover
    this tight that is 2px into the neighbouring row, so pull it back in. */
@@ -910,7 +957,8 @@ button.axi-panel--tile:hover,
    who wants round avatars sets --axi-radius-sm and gets rounded controls
    everywhere - which is the honest version of the request.
    Flat: outlined, no block. An avatar is content inside a panel, the same as
-   .axi-stat and .axi-table__rank, not a thing raised off it. */
+   .axi-stat and .axi-table__rank, not a thing raised off it - which is what
+   --axi-well-fill below is saying, and all three now say it the same way. */
 .axi-avatar {
   width: var(--axi-avatar-size, 40px);
   height: var(--axi-avatar-size, 40px);
@@ -918,7 +966,7 @@ button.axi-panel--tile:hover,
   display: grid;
   place-items: center;
   overflow: hidden;
-  background: var(--axi-ground);
+  background: var(--axi-well-fill);
   color: var(--axi-text-dim);
   border: var(--axi-border-control) solid var(--axi-ink-line);
   border-radius: var(--axi-radius-sm);
@@ -983,7 +1031,9 @@ button.axi-panel--tile:hover,
   height: var(--axi-check-size, 22px);
   display: inline-grid;
   place-items: center;
-  background: var(--axi-ground);
+  /* An empty box is a hole you put a mark in, so the level's fill - see
+     --axi-well-fill in src/tokens.css. :checked below replaces it outright. */
+  background: var(--axi-well-fill);
   border: var(--axi-border-control) solid var(--axi-ink-line);
   /* The text-sized step, not the control-sized one - see --axi-radius-xs in
      src/tokens.css for why a 22px box cannot take a corner scaled for a 36px
@@ -1105,9 +1155,18 @@ textarea.axi-input {
 }
 
 /* ---------- masthead ---------- */
+/* Opaque, because content scrolls under it. Which is also why it paints the
+   page's light as well as the page's colour: an opaque strip across the top of
+   a lit page is a dark band over that light, and the band is there on every
+   page of a site the whole time it is open. Attachment fixed, the same as
+   `body`, so the strip's share of the light is the share the page would have
+   shown there - a wash positioned to this element's own box instead would
+   line up with nothing. */
 .axi-mast {
   position: sticky; top: 0; z-index: 40;
-  background: var(--axi-ground);
+  background-color: var(--axi-ground);
+  background-image: var(--axi-ground-image);
+  background-attachment: fixed;
   border-bottom: var(--axi-border-panel) solid var(--axi-ink-line);
 }
 .axi-mast__in {
@@ -1318,6 +1377,41 @@ textarea.axi-input {
    the faint tone, and inside a filled item it follows the item's ink. */
 .axi-rail__item .axi-icon { color: var(--axi-text-faint); }
 .axi-rail__item[aria-current] .axi-icon { color: var(--axi-accent-ink); }
+/* A rail nested inside a panel whose content already spends the accent: a
+   metric picker beside the table it drives, a filter list beside its results.
+   The language already refuses two fills at two levels inside one rail - that
+   is why .axi-rail__subitem has no fill - and a rail that is itself the inner
+   level is the same refusal one container further out. Two filled rails on
+   one screen name two places, and only one of them is where you are.
+
+   What it cannot do is borrow the subitem's answer. A subitem is one of a
+   handful of leaves under an open category; a picker like this is twenty rows
+   and the primary control of its own panel, so brightened text alone loses
+   the selection in the list. This is the third weight between the two: the
+   row rises off the rail as any hovered row does, and the accent arrives on
+   its leading edge. The accent still says which row without the row claiming
+   to be the place.
+
+   The edge is the item's own border, which .axi-rail__item already reserves
+   at the control weight and draws transparent - so the bar costs no shadow,
+   no extra box and no reflow when it lights up. Logical, not left: this is
+   the leading edge, the same correction .axi-rail--flush took.
+
+   The modifier goes on the list, not on .axi-rail, because a nested picker
+   usually has no rail box around it - it sits directly in the panel or well
+   that holds it, and inheriting a 208px width and a panel shadow is the
+   opposite of what it wants. */
+.axi-rail__nav--quiet .axi-rail__item[aria-current],
+.axi-rail__nav--quiet .axi-rail__item[aria-current]:hover {
+  background: var(--axi-surface-raised);
+  color: var(--axi-text);
+  border-color: transparent;
+  border-inline-start-color: var(--axi-accent);
+}
+/* No accent fill here, so the icon has no accent ink to follow - it follows
+   the row's own text, the way it does in an unselected item. */
+.axi-rail__nav--quiet .axi-rail__item[aria-current] .axi-icon { color: var(--axi-text); }
+
 /* The second level, indented under the item it belongs to. */
 .axi-rail__sub { display: flex; flex-direction: column; margin: 3px 0 5px 10px; }
 .axi-rail__subitem {
@@ -1483,7 +1577,8 @@ textarea.axi-input {
   padding: 7px 8px; border-radius: var(--axi-radius-sm);
   font-size: 13px; font-weight: 600; color: var(--axi-text-dim); cursor: pointer;
 }
-.axi-menu__pop label:hover { background: var(--axi-ground); color: var(--axi-text); }
+/* A hovered row sinks - the same fill the select's and the picker's rows use. */
+.axi-menu__pop label:hover { background: var(--axi-well-fill); color: var(--axi-text); }
 .axi-menu__pop input { margin: 3px 0 0; }
 
 /* ---------- command palette ---------- */
@@ -1597,7 +1692,7 @@ textarea.axi-input {
 .axi-palette__trigger {
   display: flex; align-items: center; width: 100%; overflow: hidden;
   padding: 0 10px 0 0;
-  background: var(--axi-ground);
+  background: var(--axi-well-fill);
   border: var(--axi-border-control) solid var(--axi-ink-line);
   border-radius: var(--axi-radius-sm);
   color: var(--axi-text-dim);
@@ -1781,7 +1876,8 @@ textarea.axi-input {
   width: 32px; height: 32px;
   display: grid; place-items: center;
   border-radius: var(--axi-radius-sm);
-  background: var(--axi-ground);
+  /* A control flat on the drawer's head - see --axi-well-fill in tokens. */
+  background: var(--axi-well-fill);
   border: var(--axi-border-control) solid var(--axi-ink-line);
   color: var(--axi-text-dim);
   font-size: 15px; font-weight: 900; cursor: pointer;
@@ -1847,6 +1943,13 @@ textarea.axi-input {
   overflow-y: auto;
   background-color: var(--axi-ground);
   background-image: var(--axi-ground-image);
+  /* Fixed for both of the reasons `body` is: the light stays put while the
+     sheet's own content scrolls, and it is positioned to the viewport rather
+     than to this box - which matters here because --axi-sheet-top pushes that
+     box down under an app's titlebar, and a wash measured from its top edge
+     would sit lower than the one on the page it covers. Opening a sheet would
+     nudge the light sideways. */
+  background-attachment: fixed;
   padding: var(--axi-sheet-pad, 12px 16px);
 }
 /* The heading the sheet opened with, divided from the body by a rule. Rule 8:
@@ -1869,7 +1972,8 @@ textarea.axi-input {
   margin: 0;
   padding: 11px 13px;
   border-left: var(--axi-border-panel) solid var(--axi-accent);
-  background: var(--axi-ground);
+  /* Sunk into the prose around it, so the well's fill - see .axi-stat. */
+  background: var(--axi-well-fill);
   border-radius: 0 var(--axi-radius-sm) var(--axi-radius-sm) 0;
 }
 .axi-quote :where(p) { margin: 0; font-size: 13px; font-style: italic; color: var(--axi-text-dim); line-height: 1.5; }
@@ -1886,13 +1990,24 @@ textarea.axi-input {
    takes the panel outline. It carries no block, because a block is an
    element's shadow on the surface behind it and there is nothing behind a
    window that this language is entitled to draw on.
+
+   It is the page. Not a page inside one - the only one, for as long as the app
+   is running, which is why it paints the ground's IMAGE as well as the
+   ground's colour. `body` is behind it and lights nothing, because a window
+   covers the viewport and is opaque by the same requirement that makes it
+   opaque over its own content. A window that skipped the image would render a
+   theme whose character is the light - glass - as flat near-black: every panel
+   inside it correctly translucent, over nothing. Longhands for the reason
+   .axi-sheet gives at length below; no attachment, because this element's box
+   IS the viewport and never scrolls, so fixed and scroll paint the same pixels.
    The titlebar is filled with the ink line rather than a surface: it is the
    outline widened into a strip, which is why the app's content reads as
    sitting inside the outline instead of under a second toolbar. */
 .axi-window {
   height: 100vh;
   display: flex; flex-direction: column; overflow: hidden;
-  background: var(--axi-ground);
+  background-color: var(--axi-ground);
+  background-image: var(--axi-ground-image);
   border: var(--axi-border-panel) solid var(--axi-ink-line);
   border-radius: var(--axi-radius);
 }
@@ -2159,10 +2274,18 @@ textarea.axi-input {
    an outline and no block - it is content, not something raised off the
    surface it sits on. The number stays in --axi-text unless it has a real
    state: rule 5 applies to a figure exactly as it applies to a chip, and a
-   tile coloured for emphasis is decoration impersonating status. */
+   tile coloured for emphasis is decoration impersonating status.
+
+   Flat on the ground is the WELL's fill and not the page's. A tile is a recess
+   cut into the panel holding it, which is the same shape .axi-well names, and
+   spelled --axi-ground it stops being a recess the moment a theme makes that
+   panel translucent: an opaque page colour inside a pane of glass is a black
+   patch. The outline stays the ink line rather than following the well's,
+   because a tile is cut into a SURFACE and an ink edge still has something to
+   be darker than there. Same split in .axi-meter and .axi-plot below. */
 .axi-stat {
   padding: 12px 14px;
-  background: var(--axi-ground);
+  background: var(--axi-well-fill);
   border: var(--axi-border-control) solid var(--axi-ink-line);
   border-radius: var(--axi-radius-sm);
 }
@@ -2249,7 +2372,8 @@ textarea.axi-input {
   display: grid; place-items: center;
   border: var(--axi-border-control) solid var(--axi-ink-line);
   border-radius: var(--axi-radius-sm);
-  background: var(--axi-ground);
+  /* Flat in the row, like the tile above and the avatar it stands beside. */
+  background: var(--axi-well-fill);
   font: var(--axi-t-micro);
   color: var(--axi-text-faint);
 }
@@ -2353,7 +2477,8 @@ textarea.axi-input {
 .axi-meter {
   display: flex;
   height: var(--axi-meter-h, 12px);
-  background: var(--axi-ground);
+  /* The trough is a recess, so it takes the well's fill - see .axi-stat. */
+  background: var(--axi-well-fill);
   border: var(--axi-border-control) solid var(--axi-ink-line);
   border-radius: var(--axi-radius-sm);
   overflow: hidden;
@@ -2469,7 +2594,8 @@ textarea.axi-input {
 .axi-plot {
   position: relative;
   height: var(--axi-plot-h, 180px);
-  background-color: var(--axi-ground);
+  /* A frame cut into the panel, not laid on the page - see .axi-stat. */
+  background-color: var(--axi-well-fill);
   background-image: repeating-linear-gradient(
     to top,
     var(--axi-rule) 0 var(--axi-border-hairline),
@@ -2639,9 +2765,12 @@ textarea.axi-input {
 
 /* .axi-prose code is declared beside .axi-code in primitives.css: one rule,
    both selectors, because they are one object. */
+/* A code block and a quote are both fields sunk into the prose around them,
+   so both take --axi-well-fill rather than the page colour - the reason is
+   written out at .axi-stat in src/data.css. */
 .axi-prose pre {
   margin: 0 0 18px; padding: 14px 16px; overflow-x: auto;
-  background: var(--axi-ground);
+  background: var(--axi-well-fill);
   border: var(--axi-border-control) solid var(--axi-ink-line);
   border-radius: var(--axi-radius-sm);
   box-shadow: var(--axi-shadow-control);
@@ -2652,7 +2781,7 @@ textarea.axi-input {
   margin: 0 0 18px;
   padding: 11px 13px;
   border-left: var(--axi-border-panel) solid var(--axi-accent);
-  background: var(--axi-ground);
+  background: var(--axi-well-fill);
   border-radius: 0 var(--axi-radius-sm) var(--axi-radius-sm) 0;
 }
 .axi-prose blockquote p { margin: 0; font-style: italic; }

package/docs/RULES.md

@@ -702,3 +702,34 @@ whole section exists to prevent.
 
 The test to write is not "does `.axi-code` exist". It is "are both spellings in
 the same rule", because only the second one fails when someone splits them.
+
+### A refusal holds at every level, not just the one it was written for
+
+The rail refuses two accent fills inside itself. That is why
+`.axi-rail__subitem` is brightened text and not a second filled row: with two
+fills the reader has to decide which of them answers "where am I", and the
+answer to one question cannot be two things.
+
+Written that way, the refusal sounds like it is about indentation. It is not.
+It is about how many times one screen may claim to be a place, and nesting a
+whole rail inside a panel is the same arithmetic as nesting a row inside a
+rail. A stats page with a category rail down the side and a twenty-row metric
+picker inside each section has two rails, both correct on their own, and both
+filled — so the screen makes the claim twice and neither wins. The app that
+hit this had already reasoned its way to the same conclusion and written the
+quiet treatment by hand, in its own stylesheet, with a comment giving exactly
+this reason. Two parties deriving the same rule independently is the signal
+that the rule belongs in the language, not in either party's override file.
+
+So when adding a component, take every refusal the neighbouring components
+state and ask what it is really counting. If the answer is "per screen" rather
+than "per box", the component needs a way to stand down — and the modifier is
+cheaper than the override every consumer writes instead. `.axi-rail__nav--quiet`
+is that: the fill goes, the accent stays as the leading edge, and nothing else
+moves.
+
+What the modifier must not do is reach for the weaker treatment that already
+exists. A subitem drops the fill *and* the weight, which is right for a few
+leaves under an open category and wrong for a picker that is the primary
+control of its own panel — there, brightened text loses the selection in the
+list. Standing down is one step, not two.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiapps/axi-design",
-  "version": "1.33.0",
+  "version": "1.35.0",
   "description": "The design language for the axi suite — flat and outlined, dark, drawn in saturated ink.",
   "type": "module",
   "license": "MIT",

package/src/data.css

@@ -15,10 +15,18 @@
    an outline and no block - it is content, not something raised off the
    surface it sits on. The number stays in --axi-text unless it has a real
    state: rule 5 applies to a figure exactly as it applies to a chip, and a
-   tile coloured for emphasis is decoration impersonating status. */
+   tile coloured for emphasis is decoration impersonating status.
+
+   Flat on the ground is the WELL's fill and not the page's. A tile is a recess
+   cut into the panel holding it, which is the same shape .axi-well names, and
+   spelled --axi-ground it stops being a recess the moment a theme makes that
+   panel translucent: an opaque page colour inside a pane of glass is a black
+   patch. The outline stays the ink line rather than following the well's,
+   because a tile is cut into a SURFACE and an ink edge still has something to
+   be darker than there. Same split in .axi-meter and .axi-plot below. */
 .axi-stat {
   padding: 12px 14px;
-  background: var(--axi-ground);
+  background: var(--axi-well-fill);
   border: var(--axi-border-control) solid var(--axi-ink-line);
   border-radius: var(--axi-radius-sm);
 }
@@ -105,7 +113,8 @@
   display: grid; place-items: center;
   border: var(--axi-border-control) solid var(--axi-ink-line);
   border-radius: var(--axi-radius-sm);
-  background: var(--axi-ground);
+  /* Flat in the row, like the tile above and the avatar it stands beside. */
+  background: var(--axi-well-fill);
   font: var(--axi-t-micro);
   color: var(--axi-text-faint);
 }
@@ -209,7 +218,8 @@
 .axi-meter {
   display: flex;
   height: var(--axi-meter-h, 12px);
-  background: var(--axi-ground);
+  /* The trough is a recess, so it takes the well's fill - see .axi-stat. */
+  background: var(--axi-well-fill);
   border: var(--axi-border-control) solid var(--axi-ink-line);
   border-radius: var(--axi-radius-sm);
   overflow: hidden;
@@ -325,7 +335,8 @@
 .axi-plot {
   position: relative;
   height: var(--axi-plot-h, 180px);
-  background-color: var(--axi-ground);
+  /* A frame cut into the panel, not laid on the page - see .axi-stat. */
+  background-color: var(--axi-well-fill);
   background-image: repeating-linear-gradient(
     to top,
     var(--axi-rule) 0 var(--axi-border-hairline),

package/src/forms.css

@@ -34,7 +34,9 @@
   height: var(--axi-check-size, 22px);
   display: inline-grid;
   place-items: center;
-  background: var(--axi-ground);
+  /* An empty box is a hole you put a mark in, so the level's fill - see
+     --axi-well-fill in src/tokens.css. :checked below replaces it outright. */
+  background: var(--axi-well-fill);
   border: var(--axi-border-control) solid var(--axi-ink-line);
   /* The text-sized step, not the control-sized one - see --axi-radius-xs in
      src/tokens.css for why a 22px box cannot take a corner scaled for a 36px

package/src/primitives.css

@@ -97,13 +97,29 @@ button.axi-panel--tile:hover,
   padding: var(--axi-well-pad, 10px);
 }
 
+/* The reading-scale well, which the comment above describes and this language
+   then made every consumer spell out by hand. Saying `--axi-radius-sm` inline
+   is fine for the handful of instances that comment imagined; the first real
+   consumer to be counted had fifty, and fifty inline style attributes is the
+   thing a class exists to prevent. The same argument produced .axi-btn--sm.
+
+   Only the radius, because that is the only thing that changes: a recess the
+   size of a single reading still holds objects that carry their own padding, so
+   the pad knob is still the right way to say anything else. */
+.axi-well--sm { --axi-well-radius: var(--axi-radius-sm); }
+
 /* ---------- button ---------- */
 .axi-btn {
   display: inline-flex; align-items: center; gap: 8px;
   padding: var(--axi-btn-pad, 12px 20px);
   border: var(--axi-border-control) solid var(--axi-ink-line);
   border-radius: var(--axi-radius-sm);
-  background: var(--axi-ground);
+  /* Flat on its container, which is --axi-well-fill and not the page colour -
+     the argument is in src/tokens.css at that token. A button at rest carries
+     no block: it is level with the panel holding it and lifts on hover, so the
+     resting fill is the level's, and --axi-btn--primary below is the one that
+     rests raised and fills with the accent instead. */
+  background: var(--axi-well-fill);
   color: var(--axi-text-dim);
   font: var(--axi-t-label);
   letter-spacing: var(--axi-ls-label);
@@ -186,7 +202,8 @@ button.axi-panel--tile:hover,
   padding: var(--axi-pill-pad, 12px 20px);
   border: var(--axi-border-control) solid var(--axi-ink-line);
   border-radius: var(--axi-radius-sm);
-  background: var(--axi-ground);
+  /* The button's fill for the button's reason - see .axi-btn above. */
+  background: var(--axi-well-fill);
   color: var(--axi-text-dim);
   font: var(--axi-t-label);
   letter-spacing: var(--axi-ls-label);
@@ -380,7 +397,10 @@ button.axi-panel--tile:hover,
 .axi-input {
   width: 100%;
   padding: var(--axi-input-pad, 11px 12px);
-  background: var(--axi-ground);
+  /* A field is the recessed thing in any bar it sits in - .axi-kbd's comment
+     below leans on exactly that - so it takes the level's fill. See
+     --axi-well-fill in src/tokens.css. */
+  background: var(--axi-well-fill);
   border: var(--axi-border-control) solid var(--axi-ink-line);
   border-radius: var(--axi-radius-sm);
   color: var(--axi-text);
@@ -415,14 +435,15 @@ button.axi-panel--tile:hover,
    `em`, not `px`: this lands in body copy and in 10px captions alike, and a
    literal that does not track the text around it reads as a different voice.
 
-   It sits on --axi-ground where .axi-kbd sits on --axi-surface, and the
+   It sits on --axi-well-fill where .axi-kbd sits on --axi-surface, and the
    reason is already written down one rule below: a key is raised off what it
-   is printed on, and a quoted literal is sunk into it. */
+   is printed on, and a quoted literal is sunk into it. It said --axi-ground
+   for as long as sunk and the page were the same colour; see that token. */
 .axi-code,
 .axi-prose code {
   font-family: var(--axi-mono);
   font-size: .88em;
-  background: var(--axi-ground);
+  background: var(--axi-well-fill);
   color: var(--axi-text);
   border: var(--axi-border-hairline) solid var(--axi-ink-line);
   border-radius: var(--axi-radius-sm);
@@ -462,7 +483,10 @@ button.axi-panel--tile:hover,
   padding: 10px 30px 10px 9px;
   border: var(--axi-border-control) solid var(--axi-ink-line);
   border-radius: var(--axi-radius-sm);
-  background-color: var(--axi-ground);
+  /* The field's fill, because a closed select is a field - see .axi-input. The
+     longhand stays: a caret rides in background-image and the shorthand would
+     reset it. */
+  background-color: var(--axi-well-fill);
   color: var(--axi-text-dim);
   font: var(--axi-t-label);
   font-size: 12.5px;
@@ -521,8 +545,12 @@ button.axi-panel--tile:hover,
     letter-spacing: var(--axi-ls-label);
     text-transform: uppercase;
   }
+  /* A row under the cursor sinks rather than lighting up, so the hover is the
+     level's fill - and this popover is filled with --axi-surface-raised, which
+     a theme may take translucent, so an opaque row here is the black patch
+     --axi-well-fill exists to prevent. Same for the picker's rows below. */
   .axi-select option:hover, .axi-select option:focus {
-    background: var(--axi-ground); color: var(--axi-text);
+    background: var(--axi-well-fill); color: var(--axi-text);
   }
   /* The page-wide focus ring sits 2px outside its element; inside a picker
      that is 2px into the neighbouring row, so pull it back in. */
@@ -621,7 +649,7 @@ button.axi-panel--tile:hover,
   font-weight: 900;
 }
 .axi-picker__opt:hover, .axi-picker__opt:focus {
-  background: var(--axi-ground); color: var(--axi-text);
+  background: var(--axi-well-fill); color: var(--axi-text);
 }
 /* The page-wide focus ring sits 2px outside its element; inside a popover
    this tight that is 2px into the neighbouring row, so pull it back in. */
@@ -636,7 +664,8 @@ button.axi-panel--tile:hover,
    who wants round avatars sets --axi-radius-sm and gets rounded controls
    everywhere - which is the honest version of the request.
    Flat: outlined, no block. An avatar is content inside a panel, the same as
-   .axi-stat and .axi-table__rank, not a thing raised off it. */
+   .axi-stat and .axi-table__rank, not a thing raised off it - which is what
+   --axi-well-fill below is saying, and all three now say it the same way. */
 .axi-avatar {
   width: var(--axi-avatar-size, 40px);
   height: var(--axi-avatar-size, 40px);
@@ -644,7 +673,7 @@ button.axi-panel--tile:hover,
   display: grid;
   place-items: center;
   overflow: hidden;
-  background: var(--axi-ground);
+  background: var(--axi-well-fill);
   color: var(--axi-text-dim);
   border: var(--axi-border-control) solid var(--axi-ink-line);
   border-radius: var(--axi-radius-sm);

package/src/prose.css

@@ -48,9 +48,12 @@
 
 /* .axi-prose code is declared beside .axi-code in primitives.css: one rule,
    both selectors, because they are one object. */
+/* A code block and a quote are both fields sunk into the prose around them,
+   so both take --axi-well-fill rather than the page colour - the reason is
+   written out at .axi-stat in src/data.css. */
 .axi-prose pre {
   margin: 0 0 18px; padding: 14px 16px; overflow-x: auto;
-  background: var(--axi-ground);
+  background: var(--axi-well-fill);
   border: var(--axi-border-control) solid var(--axi-ink-line);
   border-radius: var(--axi-radius-sm);
   box-shadow: var(--axi-shadow-control);
@@ -61,7 +64,7 @@
   margin: 0 0 18px;
   padding: 11px 13px;
   border-left: var(--axi-border-panel) solid var(--axi-accent);
-  background: var(--axi-ground);
+  background: var(--axi-well-fill);
   border-radius: 0 var(--axi-radius-sm) var(--axi-radius-sm) 0;
 }
 .axi-prose blockquote p { margin: 0; font-style: italic; }

package/src/shells.css

@@ -13,9 +13,18 @@
 }
 
 /* ---------- masthead ---------- */
+/* Opaque, because content scrolls under it. Which is also why it paints the
+   page's light as well as the page's colour: an opaque strip across the top of
+   a lit page is a dark band over that light, and the band is there on every
+   page of a site the whole time it is open. Attachment fixed, the same as
+   `body`, so the strip's share of the light is the share the page would have
+   shown there - a wash positioned to this element's own box instead would
+   line up with nothing. */
 .axi-mast {
   position: sticky; top: 0; z-index: 40;
-  background: var(--axi-ground);
+  background-color: var(--axi-ground);
+  background-image: var(--axi-ground-image);
+  background-attachment: fixed;
   border-bottom: var(--axi-border-panel) solid var(--axi-ink-line);
 }
 .axi-mast__in {
@@ -226,6 +235,41 @@
    the faint tone, and inside a filled item it follows the item's ink. */
 .axi-rail__item .axi-icon { color: var(--axi-text-faint); }
 .axi-rail__item[aria-current] .axi-icon { color: var(--axi-accent-ink); }
+/* A rail nested inside a panel whose content already spends the accent: a
+   metric picker beside the table it drives, a filter list beside its results.
+   The language already refuses two fills at two levels inside one rail - that
+   is why .axi-rail__subitem has no fill - and a rail that is itself the inner
+   level is the same refusal one container further out. Two filled rails on
+   one screen name two places, and only one of them is where you are.
+
+   What it cannot do is borrow the subitem's answer. A subitem is one of a
+   handful of leaves under an open category; a picker like this is twenty rows
+   and the primary control of its own panel, so brightened text alone loses
+   the selection in the list. This is the third weight between the two: the
+   row rises off the rail as any hovered row does, and the accent arrives on
+   its leading edge. The accent still says which row without the row claiming
+   to be the place.
+
+   The edge is the item's own border, which .axi-rail__item already reserves
+   at the control weight and draws transparent - so the bar costs no shadow,
+   no extra box and no reflow when it lights up. Logical, not left: this is
+   the leading edge, the same correction .axi-rail--flush took.
+
+   The modifier goes on the list, not on .axi-rail, because a nested picker
+   usually has no rail box around it - it sits directly in the panel or well
+   that holds it, and inheriting a 208px width and a panel shadow is the
+   opposite of what it wants. */
+.axi-rail__nav--quiet .axi-rail__item[aria-current],
+.axi-rail__nav--quiet .axi-rail__item[aria-current]:hover {
+  background: var(--axi-surface-raised);
+  color: var(--axi-text);
+  border-color: transparent;
+  border-inline-start-color: var(--axi-accent);
+}
+/* No accent fill here, so the icon has no accent ink to follow - it follows
+   the row's own text, the way it does in an unselected item. */
+.axi-rail__nav--quiet .axi-rail__item[aria-current] .axi-icon { color: var(--axi-text); }
+
 /* The second level, indented under the item it belongs to. */
 .axi-rail__sub { display: flex; flex-direction: column; margin: 3px 0 5px 10px; }
 .axi-rail__subitem {
@@ -391,7 +435,8 @@
   padding: 7px 8px; border-radius: var(--axi-radius-sm);
   font-size: 13px; font-weight: 600; color: var(--axi-text-dim); cursor: pointer;
 }
-.axi-menu__pop label:hover { background: var(--axi-ground); color: var(--axi-text); }
+/* A hovered row sinks - the same fill the select's and the picker's rows use. */
+.axi-menu__pop label:hover { background: var(--axi-well-fill); color: var(--axi-text); }
 .axi-menu__pop input { margin: 3px 0 0; }
 
 /* ---------- command palette ---------- */
@@ -505,7 +550,7 @@
 .axi-palette__trigger {
   display: flex; align-items: center; width: 100%; overflow: hidden;
   padding: 0 10px 0 0;
-  background: var(--axi-ground);
+  background: var(--axi-well-fill);
   border: var(--axi-border-control) solid var(--axi-ink-line);
   border-radius: var(--axi-radius-sm);
   color: var(--axi-text-dim);
@@ -689,7 +734,8 @@
   width: 32px; height: 32px;
   display: grid; place-items: center;
   border-radius: var(--axi-radius-sm);
-  background: var(--axi-ground);
+  /* A control flat on the drawer's head - see --axi-well-fill in tokens. */
+  background: var(--axi-well-fill);
   border: var(--axi-border-control) solid var(--axi-ink-line);
   color: var(--axi-text-dim);
   font-size: 15px; font-weight: 900; cursor: pointer;
@@ -755,6 +801,13 @@
   overflow-y: auto;
   background-color: var(--axi-ground);
   background-image: var(--axi-ground-image);
+  /* Fixed for both of the reasons `body` is: the light stays put while the
+     sheet's own content scrolls, and it is positioned to the viewport rather
+     than to this box - which matters here because --axi-sheet-top pushes that
+     box down under an app's titlebar, and a wash measured from its top edge
+     would sit lower than the one on the page it covers. Opening a sheet would
+     nudge the light sideways. */
+  background-attachment: fixed;
   padding: var(--axi-sheet-pad, 12px 16px);
 }
 /* The heading the sheet opened with, divided from the body by a rule. Rule 8:
@@ -777,7 +830,8 @@
   margin: 0;
   padding: 11px 13px;
   border-left: var(--axi-border-panel) solid var(--axi-accent);
-  background: var(--axi-ground);
+  /* Sunk into the prose around it, so the well's fill - see .axi-stat. */
+  background: var(--axi-well-fill);
   border-radius: 0 var(--axi-radius-sm) var(--axi-radius-sm) 0;
 }
 .axi-quote :where(p) { margin: 0; font-size: 13px; font-style: italic; color: var(--axi-text-dim); line-height: 1.5; }
@@ -794,13 +848,24 @@
    takes the panel outline. It carries no block, because a block is an
    element's shadow on the surface behind it and there is nothing behind a
    window that this language is entitled to draw on.
+
+   It is the page. Not a page inside one - the only one, for as long as the app
+   is running, which is why it paints the ground's IMAGE as well as the
+   ground's colour. `body` is behind it and lights nothing, because a window
+   covers the viewport and is opaque by the same requirement that makes it
+   opaque over its own content. A window that skipped the image would render a
+   theme whose character is the light - glass - as flat near-black: every panel
+   inside it correctly translucent, over nothing. Longhands for the reason
+   .axi-sheet gives at length below; no attachment, because this element's box
+   IS the viewport and never scrolls, so fixed and scroll paint the same pixels.
    The titlebar is filled with the ink line rather than a surface: it is the
    outline widened into a strip, which is why the app's content reads as
    sitting inside the outline instead of under a second toolbar. */
 .axi-window {
   height: 100vh;
   display: flex; flex-direction: column; overflow: hidden;
-  background: var(--axi-ground);
+  background-color: var(--axi-ground);
+  background-image: var(--axi-ground-image);
   border: var(--axi-border-panel) solid var(--axi-ink-line);
   border-radius: var(--axi-radius);
 }

package/src/tokens.css

@@ -80,7 +80,26 @@
      against a fill lighter than itself. Every outline in this language is
      near-black on the assumption of a ground the lines can be darker than; a
      well IS at ground level, so an ink edge round one is a black line on a
-     black field. Raised takes ink, sunk takes the rule. */
+     black field. Raised takes ink, sunk takes the rule.
+
+     And what the fill names is not the .axi-well class - it is the level. A
+     button at rest, a field, a select, a checkbox, an avatar, a rank, a code
+     span, a hovered row in a popover: not one of them is raised off what holds
+     it, and every one of them was spelled --axi-ground, because on a theme
+     whose surfaces are opaque "flat on its container" and "the page colour"
+     are the same colour. They stop being the same colour the instant a theme
+     makes the container translucent, which is how the whole set went black at
+     once and why this is written here rather than fourteen times downstream.
+     Above this level is --axi-surface (.axi-kbd is the one control in the
+     language that is genuinely raised, and says so). Below it is --axi-ground
+     proper, which now means the page and only the page: body, the sheet, the
+     window, the masthead - the things content scrolls under, which need real
+     opacity and not a subtraction. Everything between the two is this token.
+
+     The LINE does not come along. --axi-well-line is for a well cut into the
+     page, where there is nothing left for ink to be darker than; a control is
+     cut into a SURFACE and its ink edge still has a fill above it to read
+     against. Every component below keeps --axi-ink-line. */
   --axi-well-fill: var(--axi-ground);
   --axi-well-line: var(--axi-rule);
   --axi-text: #f4f6f9;