@apliteni/apliteni-ui 0.92.0 → 0.94.0

package/src/styles/file-drop.css

@@ -1,5 +1,5 @@
 /* File drop — .ui-drop. One row at rest; the field-sized box stays with .ui-file.
- * why: docs/specification.md#react-file-drop */
+ * why: docs/components.md#react-file-drop */
 .ui-drop { position: relative; }
 
 /* What the region accepts the file for, above the control. */

package/src/styles/filter-bar.css

@@ -14,13 +14,13 @@
 
 /* Shut, a panel is the trigger's width, never the 240px floor a standalone
    dropdown gets: it is laid out while hidden, so a wider one widened the page
-   (#467). why: docs/specification.md#a-filter-row-holds-its-panels */
+   (#467). why: docs/components.md#a-filter-row-holds-its-panels */
 .ui-filter-bar .ui-dropdown__panel { min-width: 100%; max-width: 100%; overflow-wrap: anywhere; }
 /* The clear action takes the kit's bordered skin minus its fill: words belong on
    the page, not on a grey block, in any state — Artur, round r28. Rest stays at
    (0,1,1) so `.ui-btn:hover`'s accent wash still outranks it; the rules under it
    answer each state that paints a NEUTRAL fill, one step above the kit rule
-   writing it. Held by filter-bar.test.js. why: docs/specification.md#a-filter-row-holds-its-panels */
+   writing it. Held by filter-bar.test.js. why: docs/components.md#a-filter-row-holds-its-panels */
 [data-filter-clear] button { background: transparent; }
 .ui-filter-bar [data-filter-clear] button:disabled,
 .ui-filter-bar [data-filter-clear] button[aria-disabled="true"],
@@ -35,7 +35,7 @@
 
 /* Open, a chip's menu takes the kit's menu floor, measured and slid by
    filterPanelFit(); `is-closing` holds that geometry through the fade. #549
-   why: docs/specification.md#a-filter-row-holds-its-panels */
+   why: docs/components.md#a-filter-row-holds-its-panels */
 .ui-filter-bar__chip .ui-dropdown.open .ui-dropdown__panel,
 .ui-filter-bar__chip .ui-dropdown__panel.is-closing {
   min-width: min(var(--ui-filter-panel-floor, 240px), var(--ui-filter-panel-room, 100%));
@@ -57,7 +57,7 @@
    open menu too and left 9.8px of the check in a 240px menu — a chevron, not a
    tick. Open the menu is at the floor with room for the mark, and `is-closing`
    holds the open geometry through the fade, so it is open for this as well. #550
-   why: docs/specification.md#a-filter-row-holds-its-panels */
+   why: docs/components.md#a-filter-row-holds-its-panels */
 .ui-filter-bar__chip .ui-dropdown:not(.open) .ui-dropdown__panel:not(.is-closing) .ui-dropdown__tick {
   flex-shrink: 1;
   min-width: 0;
@@ -68,7 +68,7 @@
    tab you are on, and keeps the kit's 16px check. The wash is a 1.2:1 tint, so the
    check is what identifies the state under WCAG 1.4.1; Apple, Material, Carbon,
    Primer and Radix all tick a chosen menu row. #549
-   why: docs/specification.md#a-filter-row-holds-its-panels */
+   why: docs/components.md#a-filter-row-holds-its-panels */
 .ui-filter-bar .ui-dropdown__item.is-selected { background: var(--glow-purple); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ }
 /* Kit-wide a chosen label steps down to --text, which left the row in force the
    faintest in the panel. Under the wash it holds --strong. */
@@ -82,5 +82,5 @@
 /* Hover's other paint is a 1px edge, 1.06:1 on the wash, which left the row in force
    the one row a pointer got no answer from. Selection is a background highlight, so
    hover deepens it: 9% more accent, the step .ui-table--zebra gives a hovered row.
-   why: docs/specification.md#a-filter-row-holds-its-panels */
+   why: docs/components.md#a-filter-row-holds-its-panels */
 .ui-filter-bar .ui-dropdown__item.is-selected:hover { background: color-mix(in srgb, var(--glow-purple), var(--accent) 9%); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ }

package/src/styles/footer.css

@@ -121,7 +121,7 @@
 
 /* Responsive — columns collapse to a stacked layout on narrow screens. Two of
    the kit's three steps, and the second one is the phone step rather than a
-   fourth value of the footer's own: docs/specification.md#breakpoints. */
+   fourth value of the footer's own: docs/foundations.md#breakpoints. */
 @media (max-width: 720px) {
   .ui-footer__top { flex-direction: column; gap: 30px; }
   .ui-footer__nav { grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 26px 30px; }

package/src/styles/input.css

@@ -24,7 +24,7 @@
   font-size: var(--text-base);
   color: var(--strong);
   /* Fields use the card surface and an edge in both themes.
-     why: docs/specification.md#elevation */
+     why: docs/foundations.md#elevation */
   background: var(--field-bg); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
   border: 1px solid var(--field-edge);
   border-radius: var(--radius-md);
@@ -57,8 +57,8 @@
    longhands the chevron is drawn with (#511). Held by stories/select-chevron.test.js.
    `opacity` is the other half of that grey-out, and no colour here outranks it, so
    the fade is reset below — it took the edge and the words down together. #564,
-   argued at docs/specification.md#colour-and-contrast.
-   why: docs/specification.md#icons-and-glyphs */
+   argued at docs/foundations.md#colour-and-contrast.
+   why: docs/foundations.md#icons-and-glyphs */
 .ui-input:disabled,
 .ui-select:disabled,
 .ui-textarea:disabled {
@@ -81,7 +81,7 @@
    `search` glyph and no clear button, so a field without one is what the
    design already says. Measured in Chromium; Firefox draws nothing here and
    Edge is untested.
-   why: docs/specification.md#colour-and-contrast */
+   why: docs/foundations.md#colour-and-contrast */
 .ui-input[type="search"]::-webkit-search-cancel-button {
   appearance: none;
   display: none;
@@ -106,7 +106,7 @@
    which is the colour every other quiet glyph on a field takes. It was one frozen
    hex until #295, dark --muted's old value, which the ladder's re-pick left behind
    at 2.49:1 on the light field. Held by stories/colour-tokens.test.js.
-   why: docs/specification.md#colour-and-contrast */
+   why: docs/foundations.md#colour-and-contrast */
 .ui-select {
   appearance: none;
   background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 24 24' fill='none' stroke='%23a29db6' stroke-width='2.4' stroke-linecap='round'%3E%3Cpath d='M6 9l6 6 6-6'/%3E%3C/svg%3E");
@@ -233,7 +233,7 @@
   /* --shadow-sm was the knob's only edge until #295, and a white knob on a light
      off-track has 1.20:1 to spare. --border-strong and not --border, which measures
      1.03:1 against that track and draws nothing — the checkbox above edges itself
-     the same way. why: docs/specification.md#elevation */
+     the same way. why: docs/foundations.md#elevation */
   border: 1px solid var(--border-strong);
   box-sizing: border-box;
   border-radius: 50%;

package/src/styles/layout.css

@@ -18,7 +18,7 @@
   font-family: var(--font-sans);
   /* The rail's width, and the one property the fold moves: the nav's own column
      plus the inset either side plus the rule, so the shell has no geometry of its
-     own to drift from the rows inside it. why: docs/specification.md#the-page-shell */
+     own to drift from the rows inside it. why: docs/components.md#the-page-shell */
   --ui-rail-rule: 1px;
   --ui-rail-w: calc(var(--ui-nav-col) + 2 * var(--space-4) + var(--ui-rail-rule));
 }
@@ -30,7 +30,7 @@
 /* The rail uses the card surface so its labels stay on a reading ground.
    Dark keeps its edge (--rail-edge); light casts --elev-rail, sideways, because the rail
    is flush to a screen edge. Reopens the light half of #454.
-   why: docs/specification.md#elevation
+   why: docs/foundations.md#elevation
    overflow-y, because the box is pinned at the viewport's height for the whole
    scroll of .ui-app — without it a row past that height paints below the fold
    and no amount of document scrolling brings it back. The rail's own padding is
@@ -49,7 +49,7 @@
   width: var(--ui-rail-w);
   /* hidden across, auto down: the fold clips what leaves the screen rather than
      laying it out again. Two longhands, not the shorthand — the gates' CSS engine
-     does not read the pair. why: docs/specification.md#the-page-shell */
+     does not read the pair. why: docs/components.md#the-page-shell */
   overflow-x: hidden;
   overflow-y: auto;
   transition: width var(--dur-med) var(--ease);
@@ -58,15 +58,17 @@
    nav declares its own; these are the three that are not the nav. Scoped to the rail,
    because the topbar layout draws the reader's block in its band instead and a column
    the rail's width is no measurement for a box on a 52px line.
-   why: docs/specification.md#the-page-shell */
+   why: docs/components.md#the-page-shell */
 .ui-app__rail > .ui-app__head,
 .ui-app__rail > .ui-app__user,
 .ui-app__rail > .ui-app__foot { width: var(--ui-nav-col); flex: none; }
-/* Hover keeps the reading surface and uses the edge declared in nav.css.
-   The danger row and the current row are left out by name because this
-   rule outranks the states nav.css writes for them.
-   */
-.ui-app__rail .ui-nav__item:not(.is-danger):not(.is-active):hover { background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
+/* The rail is itself --surface, so nav.css's plate has no step here: 1.000:1, with a
+   hairline as the whole resting mark. Both marks go a rung further — the current row
+   to the --surface-3 the folded rail already paints, a hovered row to half of it, so
+   the pointer stays quieter than the reader's own row in both themes (#475 r34). The
+   danger and current rows are named out: this rule outranks nav.css's states. */
+.ui-app__rail .ui-nav__item:not(.is-danger):not(.is-active):hover { background: color-mix(in srgb, var(--surface-3) 50%, transparent); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ }
+.ui-app__rail .ui-nav__item.is-active { background: var(--surface-3); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
 .ui-app__brand {
   display: flex;
   align-items: center;
@@ -75,7 +77,7 @@
   text-decoration: none;
   /* The lockup leaves on the words' clock, `visibility` with it so the link leaves
      the tab order — `linear`, as every discrete property in the kit is.
-     why: docs/specification.md#the-page-shell */
+     why: docs/components.md#the-page-shell */
   transition: opacity var(--dur-fast) var(--ease), visibility var(--dur-fast) linear;
   /* display: brand — the rail's lockup is the same mark topbar.css sets, and the
      two have to be the same face or the shell reads as two products. */
@@ -91,7 +93,7 @@
 
 /* The head band: the product's mark, and the rail's own control at the far end of
    the same line. `min-width: 0` so a long word shrinks the lockup rather than pushing
-   the control off the band. why: docs/specification.md#the-page-shell */
+   the control off the band. why: docs/components.md#the-page-shell */
 .ui-app__head {
   display: flex;
   align-items: center;
@@ -107,18 +109,18 @@
    anywhere — so the rail's foot is the account block alone. */
 .ui-app__rail .ui-nav--side { flex: 1 1 auto; }
 
-/* Which row is current is structural here, not chromatic: the resting glyphs
-   step down so the current one is the brightest whatever --accent is doing, and
-   the bar beside it carries the hue. A 3x17px bar on a 45x44 tile was the
-   smallest of three weak signals doing the most work, so it grows with the row.
-   The current glyph's own ink is nav.css's rule now, not a copy here: since #429
-   EVERY rail reads it that way, so the rail's copy was the same sentence in a
-   second file. What is left here is the rail's own resting step. */
+/* Which row is current is structural here, not chromatic: the resting glyphs step
+   down so the current one is the brightest whatever --accent is doing, and the
+   plate nav.css draws around it carries no hue at all. #475 took the accent bar
+   that used to stand beside the glyph off every rail, so the line that grew it to
+   the taller tile here went with it. The current glyph's own ink is nav.css's rule
+   too, not a copy here: since #429 EVERY rail reads it that way, so the rail's copy
+   was the same sentence in a second file. What is left here is the rail's own
+   resting step. */
 /* Re-tuned at #295, which took the light rail down a step with the page. Below 720px
    the glyph is the whole row, so it is held at text grade rather than at 1.4.11's bar —
-   stories/apps/shell-states.test.js:1491 `a resting glyph is dimmer but still legible`. */
+   stories/apps/shell-states.test.js:1595 `a resting glyph is dimmer but still legible`. */
 .ui-app__rail .ui-nav__ic svg { opacity: 0.66; }
-.ui-app__rail .ui-nav__item.is-active::before { width: 3px; height: 62%; }
 
 /* A destructive row of the rail is a navigation row and rests like one; the danger
    intent is the step nav.css writes for it. Both of nav.css's danger states are
@@ -139,7 +141,7 @@
 }
 /* The other thing that can close a rail: where the reader's block is in the band,
    the fold's control takes its place under the same rule.
-   why: docs/specification.md#the-page-shell */
+   why: docs/components.md#the-page-shell */
 .ui-app__foot {
   display: flex;
   align-items: center;
@@ -152,7 +154,7 @@
 /* The avatar is the reader block's own glyph, so half the difference between the
    glyph column and itself is the inset that centres it on the line every glyph above
    it stands on. The arithmetic and not the 5.5 it comes to: both numbers are declared
-   elsewhere. why: docs/specification.md#the-page-shell */
+   elsewhere. why: docs/components.md#the-page-shell */
 .ui-app { --ui-app-av: 30px; }
 .ui-app__av {
   width: var(--ui-app-av); height: var(--ui-app-av); flex: none;
@@ -173,7 +175,7 @@
 /* -- the reader's menu ---------------------------------------------------- */
 /* The account block is a dropdown() trigger, so it takes the rail's own row skin
    rather than the dropdown's pill — in place it is the last row of the rail. The
-   dropdown's own ring is left standing. why: docs/specification.md#the-page-shell */
+   dropdown's own ring is left standing. why: docs/components.md#the-page-shell */
 .ui-app__user .ui-dropdown { width: 100%; }
 .ui-app .ui-app__user-trigger {
   width: 100%;
@@ -196,7 +198,7 @@
 .ui-app__user-trigger .ui-app__who { flex: 1 1 auto; text-align: left; }
 /* The panel is portalled onto <body>, so nothing here may hang off .ui-app: by the
    time it is open it is no longer inside the rail that drew it.
-   why: docs/specification.md#the-dropdown-panel */
+   why: docs/components.md#the-dropdown-panel */
 .ui-app__user-panel .ui-dropdown__head { display: flex; flex-direction: column; gap: 2px; }
 .ui-app__user-panel .ui-dropdown__head b { display: block; color: var(--strong); font-size: calc(var(--text-sm) - 0.5px); font-weight: var(--weight-semibold); }
 /* The address wraps rather than truncating: nothing bounds this line, so
@@ -208,7 +210,7 @@
 /* The toggle's cell, at the far end of the brand row: the auto margin puts it there
    with or without a wordmark beside it, and the offset below rides it back onto the
    glyph column as the rail closes. `position: relative` and not a transform, because
-   the chip inside is `position: fixed`. why: docs/specification.md#the-page-shell */
+   the chip inside is `position: fixed`. why: docs/components.md#the-page-shell */
 .ui-app__fold-row {
   flex: none;
   margin-inline-start: auto;
@@ -219,12 +221,12 @@
 /* One box on the glyph column at both widths — --ui-nav-strip, the width nav.css
    derives the closed rail from. `gap: 0` leaves that column the whole of the
    content box, so the label below is squeezed to nothing until the chip rule lifts
-   it out. why: docs/specification.md#the-page-shell */
+   it out. why: docs/components.md#the-page-shell */
 .ui-app__fold { width: var(--ui-nav-strip); gap: 0; }
 /* The chip rule lifts the name out of the flow, and a 17px glyph is shorter than
    the line the name occupied — so the button lost 0.39px on hover and moved every
    row under it. The glyph box carries the line instead, in both states.
-   why: docs/specification.md#the-page-shell */
+   why: docs/components.md#the-page-shell */
 .ui-app__fold .ui-nav__ic { height: 1lh; }
 .ui-app .ui-app__fold { color: var(--text); }
 .ui-app .ui-app__fold:hover,
@@ -243,7 +245,7 @@
 
    The width's own clock, not the words', so the mark and the closing edge arrive
    together; no `!important`, so the reduced-motion net still takes it.
-   why: docs/specification.md#the-page-shell */
+   why: docs/components.md#the-page-shell */
 .ui-app__fold .ui-app__fold-arrow {
   transform-box: view-box;
   transform-origin: 15px 12px;
@@ -253,7 +255,7 @@
 
 /* -- The collapsed rail --------------------------------------------------- */
 /* Each rule here has its twin in the 720px block below; nothing lays a row out
-   again. why: docs/specification.md#the-page-shell */
+   again. why: docs/components.md#the-page-shell */
 .ui-app.is-collapsed { --ui-rail-w: calc(var(--ui-nav-strip) + 2 * var(--space-4) + var(--ui-rail-rule)); }
 :where(.ui-app.is-collapsed) .ui-app__rail .ui-nav__cap,
 :where(.ui-app.is-collapsed) .ui-app__rail .ui-nav__label,
@@ -266,27 +268,23 @@
    lockup goes whole, since that column is where its mark stood. The mark may only go
    where the control arrives: below 720px the toggle is not drawn, so the 720px block
    gives the lockup back rather than leaving an empty band with a hairline under it.
-   why: docs/specification.md#the-page-shell */
+   why: docs/components.md#the-page-shell */
 :where(.ui-app.is-collapsed) .ui-app__head > .ui-app__fold-row { inset-inline-start: calc(var(--ui-nav-strip) - var(--ui-nav-col)); }
 /* …and only in the layout where something arrives on the mark's column. In the
    topbar layout the toggle is at the rail's foot, nothing lands where the mark
    stands, and a lockup faded out there leaves a band with nothing in it and its
    hairline still under it — the defect the 720px block below exists to avoid. So
    that layout keeps the mark and lets the shared rule above fold away its words.
-   why: docs/specification.md#the-page-shell */
+   why: docs/components.md#the-page-shell */
 :where(.ui-app:not(.ui-app--topbar).is-collapsed) .ui-app__brand { opacity: 0; visibility: hidden; pointer-events: none; }
 :where(.ui-app.is-collapsed) .ui-app__rail .ui-nav__sub { margin-inline-start: 0; padding-inline-start: 0; border-inline-start-width: 0; }
 :where(.ui-app.is-collapsed) .ui-app__rail .ui-nav__item:not(:has(.ui-nav__ic))::after { opacity: 0.62; }
-/* The current row is ONE plate on the glyph column. Same rules as nav.css writes
-   for a standalone folded rail, and for the same reasons: the bar stands in the
-   row's own left padding, which on the strip is the rail's edge; the hairline is
-   drawn on a row that keeps the open column, so its right edge is off the strip;
-   and --ui-nav-strip is twice the glyph's centre, so a box that wide at the row's
-   edge is centred on the glyph. why: docs/specification.md#the-page-shell */
+/* The current row's plate on the glyph column, and beside it the one thing a bare rail
+   does not do: an ordinary row drops its wash here, answered by the floating name below.
+   nav.css's folded rules, a rung further. why: docs/components.md#the-page-shell */
 :where(.ui-app.is-collapsed) .ui-app__rail .ui-nav__item.is-active { isolation: isolate; background: none; }
-:where(.ui-app.is-collapsed) .ui-app__rail .ui-nav__item.is-active:not(:focus-visible) { box-shadow: none; }
-:where(.ui-app.is-collapsed) .ui-app__rail .ui-nav__item.is-active::before { left: 0; width: var(--ui-nav-strip); height: 100%; border-radius: 10px; background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ z-index: -1; }
-:where(.ui-app.is-collapsed) .ui-app__rail .ui-nav__item:hover:not(:focus-visible) { outline: none; }
+:where(.ui-app.is-collapsed) .ui-app__rail .ui-nav__item.is-active::before { content: ""; position: absolute; left: 0; top: 50%; width: var(--ui-nav-strip); height: 100%; border-radius: 10px; transform: translateY(-50%); /* motion: still — a mark on the current row, whose own highlight already transitions; this centres it, it does not travel */ background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ z-index: -1; }
+:where(.ui-app.is-collapsed) .ui-app__rail .ui-nav__item:not(.is-danger):not(.is-active):hover { background: none; }
 /* The label IS the chip. `fixed` is the fallback placement, out of the rail's own
    clip; the @supports branch below pins it to the row and is the only one that
    survives a scroll. The toggle's selector is unscoped, because it is wordless at
@@ -295,8 +293,8 @@
    It floats by role — a readout placed over the page for as long as a pointer
    rests on a row — so it takes the floating treatment the hover readout takes,
    which is the same shape on the same step: the two-step edge and the drops.
-   why: docs/specification.md#the-page-shell
-   why: docs/specification.md#elevation */
+   why: docs/components.md#the-page-shell
+   why: docs/foundations.md#elevation */
 :where(.ui-app.is-collapsed) .ui-app__rail .ui-nav__item:is(:hover, :focus-visible) > .ui-nav__label,
 :where(.ui-app.is-collapsed) .ui-app__rail .ui-app__user-trigger:is(:hover, :focus-visible) > .ui-app__who,
 .ui-app__rail .ui-app__fold:is(:hover, :focus-visible) > .ui-nav__label { position: fixed; left: calc(var(--ui-rail-w) + var(--space-2)); z-index: var(--z-dropdown); width: max-content; max-width: 15rem; margin-block: -7px; padding: 6px 10px; border: 1px solid var(--float-edge); box-shadow: inset 0 0 0 1px var(--elev-edge, var(--float-edge-inner)), var(--elev-drop); border-radius: var(--radius-xs); background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ color: var(--strong); opacity: 1; pointer-events: none; }
@@ -330,7 +328,7 @@
   padding: 40px clamp(24px, 4vw, 56px) 72px;
 }
 /* The whole of the difference: `centered` is the rule above and `wide` takes its cap
-   off. `maxWidth` is the number under either name. why: docs/specification.md#widths */
+   off. `maxWidth` is the number under either name. why: docs/foundations.md#widths */
 .ui-app__main--wide { max-width: var(--ui-app-main, none); }
 
 /* -- The topbar layout ----------------------------------------------------- */
@@ -338,7 +336,7 @@
    arrangement where the rail's head band and the band close at the same height — what
    the three heights below are for. Level, not one continuous stroke: the rail insets
    its own rule, and in light that half is 1.009:1 on the rail's ground.
-   why: docs/specification.md#the-second-layout */
+   why: docs/components.md#the-second-layout */
 .ui-app { --ui-app-band: 52px; }
 .ui-app__well { display: flex; flex-direction: column; min-width: 0; }
 .ui-app__bar {
@@ -368,7 +366,7 @@
    like is the point. The STEP is not, and that is the one thing this control does
    differently from every other field in the kit: the reason is on the declaration
    below. It gives way before anything else on the band.
-   why: docs/specification.md#the-page-shell */
+   why: docs/components.md#the-page-shell */
 .ui-app__search {
   display: flex;
   align-items: center;
@@ -383,7 +381,7 @@
   text-align: start;
   color: var(--text);
   /* The band search uses the same reading surface as other text controls.
-     why: docs/specification.md#elevation */
+     why: docs/foundations.md#elevation */
   background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
   border: 1px solid var(--border);
   border-radius: var(--radius-md);
@@ -394,7 +392,7 @@
 /* Every other control on the band takes the kit's ring. This one is a <button>
    without `.ui-btn`, so base.css's shared rule never reached it and focus fell
    through to the browser's own square outline, drawn around a 12px radius.
-   why: docs/specification.md#the-focus-ring */
+   why: docs/foundations.md#the-focus-ring */
 .ui-app__search:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); border-color: var(--accent); }
 /* The same glyph the palette draws in its own search box, at the same box and the
    same stroke: the trigger and the thing it opens are not two search marks.
@@ -409,7 +407,7 @@
 
 /* The mark alone — no room for two lines on a 52px row. No rule over it, since the
    band's hairline is under the whole of it, and no column, since this is not the rail.
-   why: docs/specification.md#the-page-shell */
+   why: docs/components.md#the-page-shell */
 .ui-app__user--bar { flex: none; padding-top: 0; border-top: 0; }
 .ui-app__user--bar .ui-app__av { margin-inline-start: 0; }
 /* Crumb, then the title block. At --space-2 the crumb sat 8px off the h1 and
@@ -447,7 +445,7 @@
 .ui-toolbar > .ui-input-group { flex: 1 1 6rem; min-width: 0; }
 /* At one column the 6rem basis stops being a floor and becomes the field's size:
    a row with two narrow chips beside it keeps all three on the line and cuts the
-   field's own placeholder off. why: docs/specification.md#a-toolbar-at-one-column */
+   field's own placeholder off. why: docs/components.md#a-toolbar-at-one-column */
 @media (max-width: 560px) {
   .ui-toolbar > .ui-input,
   .ui-toolbar > .ui-input-group { flex-basis: 100%; }
@@ -466,19 +464,19 @@
   /* …and the foot goes with it, for the reason the head band does below: in the
      topbar layout that box holds the toggle and nothing else, so at this width it is
      padding and a hairline drawn over nothing. Scoped to the shell's own rail, like
-     every other rule in this block. why: docs/specification.md#the-page-shell */
+     every other rule in this block. why: docs/components.md#the-page-shell */
   .ui-app__rail .ui-app__foot { display: none; }
   /* …and with it the band, when the band has nothing else in it: a head with no
      wordmark is the toggle alone, so at this width it is padding and a hairline
      drawn over nothing. The reader's fold cannot take this rule — there the toggle
-     IS drawn. why: docs/specification.md#the-page-shell */
+     IS drawn. why: docs/components.md#the-page-shell */
   .ui-app__head:not(:has(> .ui-app__brand)) { display: none; }
   /* And where the band does hold the mark, the mark stays — at this width the press
      that folded the rail on a desktop still reads out of the cookie, and the control
      that would undo it is the one above. A head band faded to nothing here is an empty
      41px box over a rule, with no way home. The reader's fold cannot take this rule —
      there the toggle lands on the column the mark gives up.
-     why: docs/specification.md#the-page-shell */
+     why: docs/components.md#the-page-shell */
   .ui-app__brand { opacity: 1; visibility: visible; pointer-events: auto; }
   .ui-app__rail .ui-nav__cap,
   .ui-app__rail .ui-nav__label,
@@ -490,13 +488,12 @@
   .ui-app__rail .ui-nav__sub { margin-inline-start: 0; padding-inline-start: 0; border-inline-start-width: 0; }
   .ui-app__rail .ui-nav__item:not(:has(.ui-nav__ic))::after { opacity: 0.62; }
   .ui-app__rail .ui-nav__item.is-active { isolation: isolate; background: none; }
-  .ui-app__rail .ui-nav__item.is-active:not(:focus-visible) { box-shadow: none; }
-  .ui-app__rail .ui-nav__item.is-active::before { left: 0; width: var(--ui-nav-strip); height: 100%; border-radius: 10px; background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ z-index: -1; }
-  .ui-app__rail .ui-nav__item:hover:not(:focus-visible) { outline: none; }
+  .ui-app__rail .ui-nav__item.is-active::before { content: ""; position: absolute; left: 0; top: 50%; width: var(--ui-nav-strip); height: 100%; border-radius: 10px; transform: translateY(-50%); /* motion: still — a mark on the current row, whose own highlight already transitions; this centres it, it does not travel */ background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ z-index: -1; }
+  .ui-app__rail .ui-nav__item:not(.is-danger):not(.is-active):hover { background: none; }
   /* The one line of this block that is deliberately NOT the reader's fold: a finger
      is the only pointer this width has, so a row and the account block are held to
      44px. Neither floor can spread to the press, where growing the box is the one
-     thing the travel promises nothing does. why: docs/specification.md#the-page-shell */
+     thing the travel promises nothing does. why: docs/components.md#the-page-shell */
   .ui-app__rail .ui-nav__item,
   .ui-app__rail .ui-app__user-trigger { min-height: 44px; }
   .ui-app__rail .ui-nav__item:is(:hover, :focus-visible) > .ui-nav__label,
@@ -534,7 +531,7 @@
   max-width: var(--panel-md);
   /* Floats over a spotlit page, so it takes the floating step and the floating
      treatment: the two-step edge in dark, the drop alone in light.
-     why: docs/specification.md#elevation */
+     why: docs/foundations.md#elevation */
   background: var(--bg-elevated); --ring-gap: var(--bg-elevated);
   border: 1px solid var(--float-edge);
   box-shadow: inset 0 0 0 1px var(--elev-edge, var(--float-edge-inner)), var(--elev-drop);

package/src/styles/loading.css

@@ -9,7 +9,7 @@
  * own red made it read as a fault the reader had committed. The lock says which
  * of the two it is.
  *
- * why: docs/specification.md#pending-and-denied-states */
+ * why: docs/components.md#pending-and-denied-states */
 
 /* Visually hidden, still read aloud. The kit had no such utility, and the live
    region needs one: its message is for assistive tech only — the sighted

package/src/styles/motion.css

@@ -13,7 +13,7 @@
  * @imported from here — the icon gates read each stylesheet on its own and
  * refuse a sheet that pulls in another.
  *
- * why: docs/specification.md#motion */
+ * why: docs/foundations.md#motion */
 
 /* -- Entrances -------------------------------------------------------------
  * `both` fill so the element starts at the "from" frame (hidden) and holds

package/src/styles/nav.css

@@ -43,7 +43,7 @@
 .ui-nav__cap {
   /* rank: label */
   /* Words, never a control, at BOTH widths — as __label, __badge and __caret below.
-     why: docs/specification.md#a-folded-rail-takes-the-pointer-only-where-it-draws */
+     why: docs/components.md#a-folded-rail-takes-the-pointer-only-where-it-draws */
   pointer-events: none;
   font-size: var(--text-sm);
   font-weight: var(--weight-medium);
@@ -74,35 +74,28 @@
   font-family: inherit;
   transition: background var(--dur-fast) var(--ease), color var(--dur-fast) var(--ease);
 }
-.ui-nav .ui-nav__item { color: var(--text); } /* (0,2,0): a host sheet's a:link is (0,1,1) — why: docs/specification.md#the-page-shell */
-.ui-nav__item:hover { outline: 1px solid var(--control-edge); outline-offset: -1px; background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ color: var(--strong); }
+.ui-nav .ui-nav__item { color: var(--text); } /* (0,2,0): a host sheet's a:link is (0,1,1) — why: docs/components.md#the-page-shell */
+.ui-nav__item:hover { background: color-mix(in srgb, var(--surface) 50%, transparent); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ color: var(--strong); }
 .ui-nav__item.is-active {
   background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
   color: var(--strong);
   font-weight: 500;
 }
-.ui-nav--side .ui-nav__item.is-active {
-  box-shadow: inset 0 0 0 1px var(--border);
-}
-/* Accent rail marker on the active item */
-.ui-nav--side .ui-nav__item.is-active::before {
-  content: "";
-  position: absolute;
-  left: 4px; top: 50%;
-  width: 3px; height: 17px;
-  border-radius: 3px;
-  background: var(--accent);
-  transform: translateY(-50%); /* motion: still — a mark on the current row, whose own highlight already transitions; this centres it, it does not travel */
-}
+/* The current row's one mark is a plate, and nothing closes it: on a rail row an
+   outline means focus and only focus. The plate is the quiet fill a rung off the
+   ground the rail stands on, so layout.css takes it the next rung where the rail
+   is itself --surface. #475 r33/r34. why: docs/components.md#the-page-shell */
+
 .ui-nav__item:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); }
 .ui-nav__item.is-active:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); }
 
 .ui-nav__ic { display: inline-flex; flex: none; }
 .ui-nav__ic svg { width: 17px; height: 17px; stroke: currentColor; fill: none; stroke-width: 2.2; opacity: 0.72; }
-/* The glyph brightens with its row and takes the row's ink, not the accent. One
-   accent signal per row: that is the marker above, which is the only thing on a
-   rail that means "here". A glyph in --accent beside it is the same sentence
-   said twice, and beside an accent counter it was said three times. See #429. */
+/* The glyph brightens with its row and takes the row's ink, not the accent. A
+   rail row carries no accent at all since #475: the plate above is what means
+   "here", and the glyph's own step to full ink is the other half of that pair.
+   A glyph in --accent beside it was the same sentence said twice, and beside an
+   accent counter it was said three times. See #429 and #475. */
 .ui-nav__item.is-active .ui-nav__ic svg,
 .ui-nav__item.is-current .ui-nav__ic svg { opacity: 1; stroke: currentColor; } /* motion: still — the glyph brightens with its row, whose own highlight already transitions */
 .ui-nav__label {
@@ -127,12 +120,6 @@
    background and pull its label toward the rail behind it (#220). */
 .ui-nav__item.is-disabled { /* muted-ink: state — unavailable control */ color: var(--disabled-ink); cursor: default; pointer-events: none; }
 
-/* Hover adds an edge without changing the current row's reading surface.
-   The danger row keeps its own state treatment. */
-.ui-nav__item.is-active:not(.is-danger):hover {
-  background: var(--surface); outline: 1px solid var(--control-edge); outline-offset: -1px; /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
-}
-
 /* Per-item badge / counter */
 .ui-nav__badge {
   flex: none;
@@ -160,11 +147,11 @@
 .ui-nav__item.is-active .ui-nav__badge.is-neutral { background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ color: var(--strong); }
 /* Same shape, one row up: on the current row the accent counter drops both the
    wash and the accent and reads as the neutral one beside it. The row already
-   carries the one accent signal it is allowed — the marker — and the count is a
-   number, not a second answer to "where am I". It also retires the pair #157
+   carries the one mark it is allowed — the plate — and the count is a number,
+   not a second answer to "where am I". It also retires the pair #157
    recorded: accent ink on --surface fell under WCAG AA in four of the eight
    theme x accent cells (4.08 in dark Nebula), and no alpha cleared it. Nothing
-   now paints that pair. See #429 and docs/specification.md#colour-and-contrast. */
+   now paints that pair. See #429 and docs/foundations.md#colour-and-contrast. */
 .ui-nav__item.is-active .ui-nav__badge.is-accent { background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ color: var(--strong); }
 
 /* Collapsible group */
@@ -195,12 +182,10 @@
   animation: m-slide-down var(--dur-fast) var(--ease-out) both;
 }
 .ui-nav__item--sub { font-size: calc(var(--text-base) - 0.5px); padding: 7px 12px; }
-/* No hairline on a nested current row — but only at rest. box-shadow carries
-   both the hairline and the focus ring, so a rule about the resting look must
-   say so, or it silently cancels the ring (WCAG 2.4.7). */
-.ui-nav--side .ui-nav__item--sub.is-active:not(:focus-visible) { box-shadow: none; }
-/* Hangs back onto the guide hairline the indent above draws. */
-.ui-nav--side .ui-nav__item--sub.is-active::before { left: calc(-1 * var(--space-3)); height: 15px; }
+/* A nested current row takes the plate whole, like a top-level one. It used to
+   take neither half — the bar hung back onto the guide hairline and the plate's
+   own hairline was switched off so the two would not stack — and a fill with no
+   edge is not a mark the kit accepts. See #475. */
 
 /* Footer slot (divider + trailing links, e.g. sign-out) */
 .ui-nav__foot { margin-top: 12px; padding-top: 10px; border-top: 1px solid var(--border); }
@@ -242,7 +227,7 @@
 /* Every box in the rail closes with it, whether it paints or not. A block that keeps
    the open column paints nothing and still takes the pointer off 175px of the page
    beside a positioned rail (#588); clipping it instead cut the rows' ring (#575).
-   why: docs/specification.md#a-folded-rail-takes-the-pointer-only-where-it-draws */
+   why: docs/components.md#a-folded-rail-takes-the-pointer-only-where-it-draws */
 .ui-nav--side.is-collapsed > * { width: var(--ui-nav-strip); }
 .ui-nav--side.is-collapsed .ui-nav__item { width: var(--ui-nav-strip); }
 /* The heading is the one box that keeps the open column: its line breaks are the rail's
@@ -272,27 +257,31 @@
 /* The current row on a folded rail: one plate on the glyph column, and nothing else.
    The open rail's 3px marker would stand in the rail's edge at this width, and a
    nested row would put it outside the rail; the hairline would be the same mark said
-   twice. The plate is the strip, so it is centred on the glyph, and --surface-3 is the
-   kit's quiet non-text fill — a step off the rail in both themes. The glyph's own step
-   from 0.66 to full ink is the second half of that pair. `isolation` is what puts the
-   plate behind the glyph: a positioned ::before paints over its row's content, and a
-   negative z-index with no stacking context of its own would drop it behind the rail.
-   why: #429 */
+   twice. The plate is the strip, so it is centred on the glyph, and its fill is the
+   rung the open row takes — one off the ground the rail stands on, which layout.css
+   takes one further in the shell — so a rail marks the same row with the same
+   material at both widths. The glyph's own step from 0.66 to full ink is the second
+   half of that pair. `isolation` is what puts the plate behind the glyph: a
+   positioned ::before paints over its row's content, and a negative z-index with no
+   stacking context of its own would drop it behind the rail.
+   why: #429 and #475 */
 .ui-nav--side.is-collapsed .ui-nav__item.is-active { isolation: isolate; background: none; }
-/* At rest only — box-shadow carries the hairline AND the focus ring (WCAG 2.4.7). */
-.ui-nav--side.is-collapsed .ui-nav__item.is-active:not(:focus-visible) { box-shadow: none; }
 .ui-nav--side.is-collapsed .ui-nav__item.is-active::before {
-  left: 0;
+  content: "";
+  position: absolute;
+  left: 0; top: 50%;
   width: var(--ui-nav-strip);
   height: 100%;
   border-radius: 10px;
-  background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
+  transform: translateY(-50%); /* motion: still — a mark on the current row, whose own highlight already transitions; this centres it, it does not travel */
+  background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
   z-index: -1;
 }
-/* A folded rail answers a pointer with the row's own ink and the name beside it,
-   which is the whole readout at this width — the hover wash stands, the edge
-   around it does not. At rest only, so the focus ring is left standing. */
-.ui-nav--side.is-collapsed .ui-nav__item:hover:not(:focus-visible) { outline: none; }
+/* Nothing switches the hover wash off here: since #588 a folded row is only as wide
+   as the rail draws, so the wash is the box the plate paints, a rung quieter. It is
+   the whole answer a pointer gets outside the shell, where the floating name is
+   layout.css's. (The `outline: none` that stood here switched off an edge #475
+   removed.) #475 */
 
 /* -- Horizontal tabs ----------------------------------------------------- */
 .ui-nav--tabs {