@axiapps/axi-design 1.34.0 → 1.36.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;
@@ -388,7 +407,12 @@ button.axi-panel--tile:hover,
   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);
@@ -471,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);
@@ -665,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);
@@ -700,20 +728,64 @@ 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);
   padding: 1px 5px;
 }
 
+/* ---------- link ---------- */
+/* The same trap .axi-code was pulled out of, one component later. `.axi-prose
+   a` was the language's only word for a link, and it is reachable only by
+   adopting a whole typography layer - so a consumer with a "learn more" beside
+   a setting, or a docs URL in a modal footer, writes its own. One real consumer
+   had fifteen of them, hand-spelled, and a third of those were <button>s
+   calling an openExternal bridge rather than anchors at all.
+
+   Both selectors, one rule, for the reason written at .axi-code: a link in
+   rendered markdown and a link in interface copy are the same object, and the
+   last time this language spelled one object twice the two copies drifted.
+   There is a test that they stay one rule.
+
+   The underline is stated rather than inherited. An <a href> draws one by
+   default and a <button> does not, so leaving it to the user agent is exactly
+   how the two spellings would come apart - the declaration is a no-op on the
+   anchor and load-bearing on the button. Same for the background, border and
+   padding resets: they say nothing about an anchor and are the whole reason a
+   button can wear this class.
+
+   `font-family` and `font-size` inherit, but the weight does not: a link is
+   600 wherever it lands, and `font: inherit` would quietly take that away.
+
+   The hover is written `:where(:hover)` so it weighs one class and the ink
+   layer still lands on top - see rule 6's addendum. A link in a caption that
+   says `axi-link axi-ink-dim` must stay dim under the cursor, and the plain
+   `:hover` form is what made the danger button read white under one. */
+.axi-link,
+.axi-prose a {
+  padding: 0;
+  background: none;
+  border: 0;
+  font-family: inherit;
+  font-size: inherit;
+  font-weight: 600;
+  color: var(--axi-accent);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+  cursor: pointer;
+}
+.axi-link:where(:hover),
+.axi-prose a:where(:hover) { color: var(--axi-text); }
+
 /* ---------- keyboard key ---------- */
 /* A key on the keyboard, named in the interface: the Esc that closes a
    palette, the Ctrl K that opens it. Drawn as a small control rather than as a
@@ -747,7 +819,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;
@@ -806,8 +881,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. */
@@ -906,7 +985,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. */
@@ -921,7 +1000,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);
@@ -929,7 +1009,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);
@@ -994,7 +1074,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
@@ -1116,9 +1198,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 {
@@ -1329,6 +1420,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 {
@@ -1494,7 +1620,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 ---------- */
@@ -1608,7 +1735,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);
@@ -1792,7 +1919,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;
@@ -1858,6 +1986,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:
@@ -1880,7 +2015,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; }
@@ -1897,13 +2033,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);
 }
@@ -2170,10 +2317,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);
 }
@@ -2260,7 +2415,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);
 }
@@ -2364,7 +2520,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;
@@ -2480,7 +2637,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),
@@ -2630,10 +2788,9 @@ textarea.axi-input {
 
 .axi-prose p { margin: 0 0 16px; }
 .axi-prose strong { color: var(--axi-text); font-weight: 800; }
-/* Prose is the one place a link should announce itself: a reader scanning an
-   article is looking for them, and inheriting the body ink would hide them. */
-.axi-prose a { color: var(--axi-accent); font-weight: 600; text-underline-offset: 2px; }
-.axi-prose a:hover { color: var(--axi-text); }
+/* A link is drawn beside .axi-code in primitives.css, in one rule with
+   `.axi-link`, because a link in an article and a link in interface copy are
+   the same object. See the comment there. */
 
 .axi-prose ul, .axi-prose ol { margin: 0 0 16px; padding-left: 22px; }
 .axi-prose li { margin: 0 0 7px; }
@@ -2650,9 +2807,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);
@@ -2663,7 +2823,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,48 @@ 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.
+
+This has now happened twice. `.axi-prose a` was the language's only word for a
+link, and the same consumer had fifteen hand-spelled ones — a third of them
+`<button>`s calling a desktop bridge rather than anchors at all, which is what
+made the drift concrete rather than theoretical: an `<a href>` draws its own
+underline and a `<button>` does not, so the two spellings were not merely
+allowed to come apart, they had already come apart. When you lift a
+layer-scoped style out, look for the declarations the layer was getting for
+free from its element. Those are the ones the new spelling silently loses.
+
+Two instances is a pattern, so the check belongs at the top of the list when
+adding anything: grep `src/` for the component's style living behind a layer
+prefix. If it does, it has consumers you cannot see, and they have already
+drawn their own.
+
+### 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.34.0",
+  "version": "1.36.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

@@ -114,7 +114,12 @@ button.axi-panel--tile:hover,
   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);
@@ -197,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);
@@ -391,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);
@@ -426,20 +435,64 @@ 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);
   padding: 1px 5px;
 }
 
+/* ---------- link ---------- */
+/* The same trap .axi-code was pulled out of, one component later. `.axi-prose
+   a` was the language's only word for a link, and it is reachable only by
+   adopting a whole typography layer - so a consumer with a "learn more" beside
+   a setting, or a docs URL in a modal footer, writes its own. One real consumer
+   had fifteen of them, hand-spelled, and a third of those were <button>s
+   calling an openExternal bridge rather than anchors at all.
+
+   Both selectors, one rule, for the reason written at .axi-code: a link in
+   rendered markdown and a link in interface copy are the same object, and the
+   last time this language spelled one object twice the two copies drifted.
+   There is a test that they stay one rule.
+
+   The underline is stated rather than inherited. An <a href> draws one by
+   default and a <button> does not, so leaving it to the user agent is exactly
+   how the two spellings would come apart - the declaration is a no-op on the
+   anchor and load-bearing on the button. Same for the background, border and
+   padding resets: they say nothing about an anchor and are the whole reason a
+   button can wear this class.
+
+   `font-family` and `font-size` inherit, but the weight does not: a link is
+   600 wherever it lands, and `font: inherit` would quietly take that away.
+
+   The hover is written `:where(:hover)` so it weighs one class and the ink
+   layer still lands on top - see rule 6's addendum. A link in a caption that
+   says `axi-link axi-ink-dim` must stay dim under the cursor, and the plain
+   `:hover` form is what made the danger button read white under one. */
+.axi-link,
+.axi-prose a {
+  padding: 0;
+  background: none;
+  border: 0;
+  font-family: inherit;
+  font-size: inherit;
+  font-weight: 600;
+  color: var(--axi-accent);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+  cursor: pointer;
+}
+.axi-link:where(:hover),
+.axi-prose a:where(:hover) { color: var(--axi-text); }
+
 /* ---------- keyboard key ---------- */
 /* A key on the keyboard, named in the interface: the Esc that closes a
    palette, the Ctrl K that opens it. Drawn as a small control rather than as a
@@ -473,7 +526,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;
@@ -532,8 +588,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. */
@@ -632,7 +692,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. */
@@ -647,7 +707,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);
@@ -655,7 +716,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

@@ -28,10 +28,9 @@
 
 .axi-prose p { margin: 0 0 16px; }
 .axi-prose strong { color: var(--axi-text); font-weight: 800; }
-/* Prose is the one place a link should announce itself: a reader scanning an
-   article is looking for them, and inheriting the body ink would hide them. */
-.axi-prose a { color: var(--axi-accent); font-weight: 600; text-underline-offset: 2px; }
-.axi-prose a:hover { color: var(--axi-text); }
+/* A link is drawn beside .axi-code in primitives.css, in one rule with
+   `.axi-link`, because a link in an article and a link in interface copy are
+   the same object. See the comment there. */
 
 .axi-prose ul, .axi-prose ol { margin: 0 0 16px; padding-left: 22px; }
 .axi-prose li { margin: 0 0 7px; }
@@ -48,9 +47,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 +63,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;