@apliteni/apliteni-ui 0.92.0 → 0.94.0

package/src/styles/pagination.css

@@ -107,7 +107,7 @@
    declared on the one adjacency the kit can see. `.rx-pager` carried a bare
    `margin-top: 16px` for this, which is --space-4; the number moves to the scale
    with it rather than travelling as a literal.
-   why: docs/specification.md#spacing-and-rhythm */
+   why: docs/foundations.md#spacing-and-rhythm */
 .ui-table + .ui-pager { margin-top: var(--space-4); }
 
 /* A step given an `href` is an anchor, and a host stylesheet's `a:link` is
@@ -118,7 +118,7 @@
    `.ui-nav .ui-nav__item` in nav.css. Storybook ships no `a:link`, so the "Pages
    as links" story cannot show it — which is why the rule is stated rather than
    discovered.
-   why: docs/specification.md#pagination */
+   why: docs/components.md#pagination */
 a.ui-pager__step,
 a.ui-pager__page { color: var(--text); }
 a.ui-pager__step:hover,

package/src/styles/reduced-motion.css

@@ -6,8 +6,8 @@
  * `iteration-count: 1` lets one-shot animations settle on their final frame — a
  * checkmark stays drawn — instead of snapping back to the start.
  *
- * why: docs/specification.md#reduced-motion-travels-with-the-stylesheet
- * why: docs/specification.md#motion */
+ * why: docs/foundations.md#reduced-motion-travels-with-the-stylesheet
+ * why: docs/foundations.md#motion */
 
 @media (prefers-reduced-motion: reduce) {
   html { scroll-behavior: auto !important; }

package/src/styles/segmented.css

@@ -75,7 +75,7 @@
  * 2px stroke, in --signal-contrast — the circle wears the accent's dark ramp in
  * both themes, so its ink is the one for a fill, not the --accent-contrast that
  * pairs with --accent-strong. Held by stories/accent-mark.test.js.
- * why: docs/specification.md#react-accent-picker */
+ * why: docs/components.md#page-furniture, and #472 for the ring that was rejected. */
 .ui-accent-picker button.is-active::after {
   content: "";
   position: absolute;
@@ -92,7 +92,7 @@
 
 /* Underline tabs wrap for the reason the pills above do — #435 — and draw no
    rule of their own: the chosen tab carries the selection. #527, #545
-   why: docs/specification.md#the-chosen-tab-in-an-underline-strip */
+   why: docs/components.md#the-chosen-tab-in-an-underline-strip */
 .ui-seg--underline { flex-wrap: wrap; overflow: visible; row-gap: var(--space-1); align-self: stretch; justify-self: stretch; background: transparent; --ring-gap: inherit; border-radius: 0; padding: var(--space-1); max-width: 100%; }
 /* `anywhere` is the half `break-word` cannot do: it lowers the tab's min-content
    width, so one unbreakable word narrows rather than widening the page. The
@@ -106,7 +106,7 @@
 /* The chosen tab is its label and one bar under it: no plate, no hairline, no
    upright rail — those read as a list-row grip. `outline: 0` cancels the accent
    outline the pill rule gives every chosen button, which is #544's second mark.
-   #527 r31. why: docs/specification.md#the-chosen-tab-in-an-underline-strip */
+   #527 r31. why: docs/components.md#the-chosen-tab-in-an-underline-strip */
 .ui-seg--underline button.is-active,
 .ui-seg--underline button[aria-pressed="true"] {
   background: none;

package/src/styles/stat.css

@@ -3,7 +3,7 @@
  *   .ui-stats--tiles  one card per figure — the default
  *   .ui-stats--band   one card, figures divided by space
  *   .ui-stats--open   no surface; a rule over each figure
- * why: docs/specification.md#stat-bands
+ * why: docs/components.md#stat-bands
  * ========================================================================== */
 
 /* The band lays out from the width of its own box, not the window's: a band in
@@ -76,7 +76,7 @@ dd.ui-stat__caption { margin-top: var(--space-2); }
   font-weight: var(--weight-medium);
   line-height: var(--leading-snug);
 }
-.ui-stat__delta svg { width: 14px; height: 14px; flex: none; stroke-width: 2.7; } /* 2.7 of a 24 box drawn at 14px = 1.58 CSS px. docs/specification.md#icons-and-glyphs */
+.ui-stat__delta svg { width: 14px; height: 14px; flex: none; stroke-width: 2.7; } /* 2.7 of a 24 box drawn at 14px = 1.58 CSS px. docs/foundations.md#icons-and-glyphs */
 .ui-stat__change { font-variant-numeric: tabular-nums; white-space: nowrap; flex: none; }
 .ui-stat__basis { color: var(--text); font-weight: var(--weight-normal); }
 
@@ -129,7 +129,7 @@ dd.ui-stat__caption { contain: inline-size; }
    count stacks. The widths are where four and three tiles of `€ 6,459,401`
    stop fitting, and the open band's larger value moves them out; a longer
    figure still wraps rather than overlaps.
-   why: docs/specification.md#stat-bands */
+   why: docs/components.md#stat-bands */
 @container (28rem < width <= 56rem) {
   .ui-stats:not(.ui-stats--open) .ui-stats__list:has(> .ui-stat:nth-child(4):last-child) > .ui-stat { flex-basis: 34%; }
 }

package/src/styles/success.css

@@ -18,7 +18,7 @@
   border-radius: 20px;
   background: var(--bg-elevated); --ring-gap: var(--bg-elevated);   /* Elevated surface for the confirmation and its actions. */
   /* The floating treatment, like every other surface on that step.
-     why: docs/specification.md#elevation */
+     why: docs/foundations.md#elevation */
   border: 1px solid var(--float-edge);
   box-shadow: inset 0 0 0 1px var(--elev-edge, var(--float-edge-inner)), var(--elev-drop);
   isolation: isolate;

package/src/styles/table.css

@@ -33,7 +33,7 @@
 /* The last row of the last section, so a final body row keeps its separator when a
  * footer follows it. `tr:last-child td` closed the wrong edge: it stripped the border
  * from the last row of every section, leaving items and totals with nothing between
- * them. why: docs/specification.md#spacing-and-rhythm */
+ * them. why: docs/foundations.md#spacing-and-rhythm */
 .ui-table > :last-child > tr:last-child > :is(th, td) { border-bottom: 0; }
 /* Totals open with the 2px rule the zebra header already uses, so a reader can see
  * where items end and totals begin; five identical hairlines told them nothing.
@@ -77,7 +77,7 @@
  *   --dense  --space-3 across, --space-2 down — one step in from the base table
  *   --zebra  legacy spacing and 2px header rule; the base-surface rule below removes stripes
  * Cell helpers: .ui-table__num (right, tabular), .ui-table__code.
- * why: docs/specification.md#spacing-and-rhythm
+ * why: docs/foundations.md#spacing-and-rhythm
  * held by: stories/table-rhythm.test.js */
 .ui-table--dense th { padding: 0 var(--space-3) var(--space-2); }
 .ui-table--dense td,
@@ -187,7 +187,7 @@
 /* The end-cell inset above gives a row's highlight room; the bleed is what stops the grid
    paying for it. The table hangs out by the same --space-3, into the card's 20-24px
    padding and never past it, so the columns start on the card's own text edge and the
-   scroll region stays empty at rest. why: docs/specification.md#spacing-and-rhythm */
+   scroll region stays empty at rest. why: docs/foundations.md#spacing-and-rhythm */
 .ui-card > :where(.ui-table--dense, .ui-table--zebra) {
   width: calc(100% + 2 * var(--space-3));
   margin-inline: calc(-1 * var(--space-3));
@@ -212,7 +212,7 @@
    It had no room of its own to draw in — the padding above is horizontal — which is the
    second reason the band is an outline: it is painted over the rows, in the cell padding
    of the first and last, rather than under them. #531
-   why: docs/specification.md#the-focus-ring */
+   why: docs/foundations.md#the-focus-ring */
 .ui-table-scroll:focus-visible { outline: var(--ring-scroll); outline-offset: var(--ring-scroll-offset); }
 .ui-table--sticky { border-collapse: separate; border-spacing: 0; }
 .ui-table--sticky thead th { position: sticky; top: 0; z-index: var(--z-sticky); background: var(--table-bg); --ring-gap: var(--table-bg); padding-top: var(--space-2); }
@@ -249,8 +249,8 @@ a.ui-identity:hover { text-decoration: underline; }
  * __title reach a cell with two classes, and one class would lose to them and leave
  * `nowrap` on a paragraph.
  *
- * The consumer's half — the roles a changed `display` drops — is in the specification.
- * why: docs/specification.md#dense-financial-tables
+ * The consumer's half — the roles a changed `display` drops — is in docs/components.md.
+ * why: docs/components.md#dense-financial-tables
  * held by: src/styles/table-stack.test.js (layout), stories/table-stack.test.js (roles)
  * ========================================================================== */
 

package/src/styles/tap-zone.css

@@ -8,7 +8,7 @@
  * Read LAST, after every component sheet — see src/index.css — because each
  * opening overrides a gap one of them already set.
  *
- * why: docs/specification.md#a-tap-reaches-the-floor-below-the-phone-step
+ * why: docs/foundations.md#a-tap-reaches-the-floor-below-the-phone-step
  * Held by stories/tap-zone.test.js, measured in a browser at 390.
  */
 

package/src/styles/tooltip.css

@@ -5,7 +5,7 @@
  *   .ui-tip        the readout — __label, __value, __detail
  * The readout is an overlay in every state. It is absolutely placed inside its
  * host, so showing it, filling it and moving it change the size of nothing.
- * why: docs/specification.md#the-hover-readout
+ * why: docs/components.md#the-hover-readout
  * ========================================================================== */
 
 .ui-tip-host { position: relative; }
@@ -29,7 +29,7 @@
   /* The two-step edge and the drop, through the level's own names: in DARK that is
      --border-strong outside and --border one pixel inside it, then the drop; in LIGHT
      both lines are transparent and the drop carries the whole separation.
-     why: docs/specification.md#elevation */
+     why: docs/foundations.md#elevation */
   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-sm);
@@ -51,7 +51,7 @@
 
 /* The readout uses the floating panel surface in both themes. Its edge
    and shadow separate it from the card underneath.
-   why: docs/specification.md#elevation */
+   why: docs/foundations.md#elevation */
 
 /* Below the mark: the wiring's flip when above would be clipped, or the
    author's own choice. */

package/src/styles/topbar.css

@@ -132,7 +132,7 @@
   /* The two-step edge and the drop, through the level's own names: in DARK that is
      --border-strong outside and --border one pixel inside it, then the drop; in LIGHT
      both lines are transparent and the drop carries the whole separation.
-     why: docs/specification.md#elevation */
+     why: docs/foundations.md#elevation */
   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: 16px;
@@ -141,7 +141,7 @@
   visibility: hidden;
   /* Drawn for the whole of the fade out, so the rows do not vanish mid-fade — and a box
      that is drawn is a box that is hit. The open rule takes this back.
-     why: docs/specification.md#the-dropdown-panel */
+     why: docs/components.md#the-dropdown-panel */
   pointer-events: none;
   transform: translateY(-6px);
   /* Named properties, not the bare shorthand: `transition: 0.18s` is `all`, and `all`
@@ -159,7 +159,7 @@
    open transition, because the frame the open class lands is the frame the wiring moves
    focus onto a row in and a browser will not focus inside a hidden box; and
    `pointer-events` back on, because the closed rule turned it off.
-   why: docs/specification.md#the-dropdown-panel */
+   why: docs/components.md#the-dropdown-panel */
 .vsw.open .vsw__menu {
   opacity: 1;
   visibility: visible;
@@ -189,7 +189,7 @@
 }
 /* Menu rows use the reading surface and an edge on hover — see
    src/styles/dropdown.css:176 `.ui-dropdown__item:hover`.
-   why: docs/specification.md#elevation */
+   why: docs/foundations.md#elevation */
 .vopt: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. */ }
 /* The row is a keyboard stop: src/components/dropdown.js:804
    `items[next < 0 ? 0 : next]?.focus()` moves focus onto a `[data-dd-item]` with
@@ -210,7 +210,7 @@
 }
 .vbadge.live { color: var(--chip-success-ink); background: var(--chip-success-fill); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
 .vbadge.arch { /* muted-ink: state — archived version */ color: var(--muted); background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
-/* The phone step — the same one the rail folds at: docs/specification.md#breakpoints.
+/* The phone step — the same one the rail folds at: docs/foundations.md#breakpoints.
    The switcher keeps its glyph and drops its label.
    The menu hangs the other way here. Anchored by its left edge it opened
    rightwards off a band that is as wide as the page, and a CLOSED menu is still
@@ -231,7 +231,7 @@
    area. Packed to --space-2 the band needs 352 of the 362 it has there, so the
    avatar is whole with the band's own gutter beside it. 320 is still short of the
    room these controls want, which stays #558.
-   why: docs/specification.md#breakpoints */
+   why: docs/foundations.md#breakpoints */
 @media (max-width: 560px) {
   .topbar__in { gap: var(--space-2); }
 }
@@ -265,14 +265,14 @@
   /* The two-step edge and the drop, through the level's own names: in DARK that is
      --border-strong outside and --border one pixel inside it, then the drop; in LIGHT
      both lines are transparent and the drop carries the whole separation.
-     why: docs/specification.md#elevation */
+     why: docs/foundations.md#elevation */
   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: 14px;
   /* No clip. The rows reach this panel's edges, and the ring a focused row draws reaches
      3px past itself; `overflow: hidden` here cut that down to the one pixel of border it
      had, and the reader met two accent bars instead of a ring. The ring crosses the edge
-     now. #519 why: docs/specification.md#a-menu-panel-does-not-cut-off-its-rows-ring */
+     now. #519 why: docs/components.md#a-menu-panel-does-not-cut-off-its-rows-ring */
   opacity: 0;
   visibility: hidden;
   pointer-events: none; /* see .vsw__menu above */

package/src/tokens/accents.css

@@ -25,7 +25,7 @@
  * property to one half of a pair and not the other is what breaks that, and
  * stories/accent-without-theme.test.js is the gate that says so.
  *
- * why: docs/specification.md#the-focus-ring */
+ * why: docs/foundations.md#the-focus-ring */
 
 /* ---- Phoenix — ember / rising fire (the strategy's namesake) ------------- */
 :root[data-accent="phoenix"],

package/src/tokens/tokens.css

@@ -38,7 +38,7 @@
   /* -- Measure ------------------------------------------------------------
    * --container is the page, gutter to gutter; --measure is the reading column
    * INSIDE a track, beside a sidebar. Different axes, never interchangeable.
-   * why: docs/specification.md#widths */
+   * why: docs/foundations.md#widths */
   --container: 1120px;
   --measure: 860px;
 
@@ -50,7 +50,7 @@
    * smears, worst of all in Cyrillic, which is where the kit spends most of its
    * pixels. IBM Plex Sans is humanist and narrower, and its Cyrillic was drawn
    * by the same team as its Latin.
-   * why: docs/specification.md#typefaces */
+   * why: docs/foundations.md#typefaces */
   --font-display: 'Poppins', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
   --font-sans: 'IBM Plex Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
   --font-mono: ui-monospace, 'SF Mono', Menlo, Consolas, monospace;
@@ -136,7 +136,7 @@
   /* The elevation ladder, bottom to top. A surface says how high it is with its step
      and, IN DARK, with the hairline around it; --muted caps how far the ladder can go.
      Nothing casts in dark below the floating step, and the floating step adds
-     --elev-drop under its inner line. why: docs/specification.md#elevation */
+     --elev-drop under its inner line. why: docs/foundations.md#elevation */
   --bg: #0e0d14;
   --table-bg: var(--bg);
   /* A dark table is flush with the page, so the reading surface an inline code chip has
@@ -163,20 +163,20 @@
   /* WHICH EDGE EACH LEVEL DRAWS. One name per level, so a sheet never has to ask
      which theme it is in. Dark answers all four with the hairline, because a drop
      on a near-black page reaches 1.20 at its core and has nowhere else to go —
-     light answers them with the drop instead. why: docs/specification.md#elevation */
+     light answers them with the drop instead. why: docs/foundations.md#elevation */
   --card-edge: var(--border);          /* a card */
   --rail-edge: var(--border);          /* the shell's rail */
   --float-edge: var(--border-strong);  /* a floating surface, outer line */
   --float-edge-inner: var(--border);   /* a floating surface, inner line */
 
-  /* Fields use the card surface and an edge in both themes. why: docs/specification.md#elevation */
+  /* Fields use the card surface and an edge in both themes. why: docs/foundations.md#elevation */
   --field-bg: var(--surface);
   --field-edge: var(--border);
   --field-edge-hover: var(--border-strong);
   --control-edge: var(--border);
 
   /* How much of its own colour a tinted card mixes in. Dark mixes upward off a mid-grey
-     card, so it can afford this much. why: docs/specification.md#elevation */
+     card, so it can afford this much. why: docs/foundations.md#elevation */
   --card-tint: 9%;
 
   --text: #e9e7f0;
@@ -184,31 +184,31 @@
   --dim: #c6c2d6;
   /* Picked against the TOP of the ladder above, not against the page: #948fa8 cleared the
      two floating steps by hundredths. Same violet-grey, fourteen steps up every channel.
-     why: docs/specification.md#elevation */
+     why: docs/foundations.md#elevation */
   --muted: #a29db6;
 
   /* The paint of a control that is off. NOT an opacity: `opacity` is a group property,
      so it fades label and box toward the ground TOGETHER — a disabled primary button
      measured 1.48:1 that way. These three are aliases that composite predictably, the
      ink read on the surface beside it. Held by guidelines/accessibility-floor.test.js.
-     why: docs/specification.md#colour-and-contrast */
+     why: docs/foundations.md#colour-and-contrast */
   --disabled-ink: var(--muted);
   --disabled-surface: var(--surface);
   /* One rung below the hairline, so an off box is not the live box with quieter words
      in it: dark answered both with --border. 1.16:1 on the card against the live
      1.27:1, and as far down as the headroom goes. #564
-     why: docs/specification.md#colour-and-contrast */
+     why: docs/foundations.md#colour-and-contrast */
   --disabled-border: var(--surface-3);
   /* The ink of a disabled control that paints no box of its own — a ghost button. With
      no surface beside it, it is read on whatever is behind it, so it is set to clear the
      floor on the dullest ground there is (--surface-3). #273
-     why: docs/specification.md#colour-and-contrast */
+     why: docs/foundations.md#colour-and-contrast */
   --disabled-ink-bare: #a39eb7;
 
   /* Lifted from #9b5dff, which cleared the flat surfaces and failed on its own wash over
      a card; the value was already in the ramp. --ring-color is var(--accent) and follows by
      reference. Held by stories/accent-contrast.test.js. #157.
-     why: docs/specification.md#colour-and-contrast */
+     why: docs/foundations.md#colour-and-contrast */
   --accent: #b479ff;
   --accent-strong: #7c3aed; /* button bg — white text clears WCAG AA at 5.70:1 */
   --accent-contrast: #ffffff;
@@ -216,7 +216,7 @@
   /* Ink that reads on a SIGNAL colour once that colour becomes a fill — the glyph in a
      success circle, or on a toast's status circle. One near-black ink clears all five in
      dark; danger keeps its own token because LIGHT still needs one.
-     why: docs/specification.md#colour-and-contrast */
+     why: docs/foundations.md#colour-and-contrast */
   --signal-contrast: #0c0c0c;
   --danger-contrast: var(--signal-contrast);
 
@@ -257,13 +257,13 @@
      A transparent shadow, not `none`, because these are read in a LIST. The kit's own
      pre-0.32 pattern was `box-shadow: var(--shadow-lg), var(--ring)`, and `none` is only
      valid alone — it makes the whole declaration invalid, which silently takes the focus
-     ring with it. `0 0 #0000` composes. why: docs/specification.md#elevation */
+     ring with it. `0 0 #0000` composes. why: docs/foundations.md#elevation */
   --shadow-sm: 0 0 #0000;
   --shadow-md: 0 0 #0000;
   --shadow-lg: 0 0 #0000;
   --shadow-seg: 0 0 #0000;
   --shadow-card: 0 0 #0000;
-  /* G2: the band carries contrast; the halo decorates it. why: docs/specification.md#the-focus-ring */
+  /* G2: the band carries contrast; the halo decorates it. why: docs/foundations.md#the-focus-ring */
   --ring-width: 2px;
   --ring-color: var(--accent);
   --ring-gap-width: 1px;
@@ -273,7 +273,7 @@
      no halo. An OUTLINE, because an inset shadow is painted under the box's own
      children and a table scrolled under one erases it. The gap is left unpainted, so
      neither half reads --ring-gap and neither is recomposed per surface. Chosen by
-     Artur on #531 round r30. why: docs/specification.md#the-focus-ring */
+     Artur on #531 round r30. why: docs/foundations.md#the-focus-ring */
   --ring-scroll: var(--ring-width) solid var(--ring-color);
   --ring-scroll-offset: calc(-1 * (var(--ring-gap-width) + var(--ring-width)));
 
@@ -289,7 +289,7 @@
      nothing below could re-point it. A floating surface writes the pair itself:
        box-shadow: inset 0 0 0 1px var(--elev-edge, var(--float-edge-inner)), var(--elev-drop);
      Dark spends 62% / 50% of the ink and reaches 1.20 at the drop's core, having
-     nowhere to go on a near-black page. why: docs/specification.md#elevation */
+     nowhere to go on a near-black page. why: docs/foundations.md#elevation */
   --elev-drop:
     0 14px 30px -12px color-mix(in srgb, var(--shadow-ink) 62%, transparent),
     0 3px 9px -4px color-mix(in srgb, var(--shadow-ink) 50%, transparent);
@@ -297,7 +297,7 @@
   /* The ladder's two resting rungs, which only light climbs. Transparent here and
      not `none`, for the reason the deprecated --shadow-* tokens are: these are read
      in a layer list, and `none` is valid only alone — it would invalidate the whole
-     declaration and take the focus ring with it. why: docs/specification.md#elevation */
+     declaration and take the focus ring with it. why: docs/foundations.md#elevation */
   --elev-rest: 0 0 #0000;   /* a card */
   --elev-rail: 0 0 #0000;   /* the shell's rail, cast sideways */
 
@@ -337,7 +337,7 @@
      blue than the one it replaces. Light spends its white on the surface you read
      ON, and separates the panel that floats over it by role — its two-step edge and
      its drop — rather than by a rung it has nothing left to pay for. See issue #448.
-     why: docs/specification.md#elevation */
+     why: docs/foundations.md#elevation */
   --bg: #f2f3f6;
   --table-bg: #ffffff;
   --table-code-bg: var(--bg);
@@ -356,7 +356,7 @@
      the reference he supplied. A line divides two regions of ONE surface (a card's
      rows, a table's rules, the rail's head band, the topbar); a drop says a surface
      is HIGHER, and only a higher surface may cast one.
-     why: docs/specification.md#elevation */
+     why: docs/foundations.md#elevation */
   --card-edge: transparent;
   --rail-edge: transparent;
   --float-edge: transparent;
@@ -364,14 +364,14 @@
 
   /* Light draws a field with its EDGE, because since #448 it has no well left to draw it
      with: a card and a panel are both white, the sunken step falls two rungs under either,
-     and --border on it measures 1.047:1. why: docs/specification.md#elevation */
+     and --border on it measures 1.047:1. why: docs/foundations.md#elevation */
   --field-bg: var(--surface);
   --field-edge: var(--border-strong);
   --field-edge-hover: var(--muted);
   --control-edge: var(--border-strong);
 
   /* Light mixes DOWN from white, so tint costs lightness: 5% is the most a card can spend
-     and stay above the page. why: docs/specification.md#elevation */
+     and stay above the page. why: docs/foundations.md#elevation */
   --card-tint: 5%;
 
   --text: #1a1e27;
@@ -446,7 +446,7 @@
      and held in by a negative spread. None is a glow — a glow is a zero-offset layer of
      the signal's own colour. A level with no line casts a rung that reaches on every
      side it exposes, which is why the wide layer's offset stays under half its blur.
-     why: docs/specification.md#elevation */
+     why: docs/foundations.md#elevation */
   --elev-rest:
     0 2px 26px -3px color-mix(in srgb, var(--shadow-ink) 9%, transparent),
     0 1px 3px -1px color-mix(in srgb, var(--shadow-ink) 7%, transparent);
@@ -471,7 +471,7 @@
  *   a box that holds a LINE        ->  --prose-*   (ch)
  *
  * Both are theme-invariant, so they sit outside the palette blocks.
- * why: docs/specification.md#boxes-below-the-page
+ * why: docs/foundations.md#boxes-below-the-page
  * ========================================================================== */
 :root {
   /* -- Panel widths -------------------------------------------------------
@@ -502,14 +502,14 @@
  * substituted on the element that DECLARES it — so the painted container hands it the one
  * it is not using itself, and the chip keeps a step wherever it is written. The page hands
  * over the card below; every painted container hands over the page, in the recipe under it.
- * Held by stories/code-chip.test.js. why: docs/specification.md#elevation */
+ * Held by stories/code-chip.test.js. why: docs/foundations.md#elevation */
 :root { --code-bg: var(--surface); }
 
 /* Recompose only at painted containers; controls inherit the outside gap, and each hands an
  * inline code chip the page. One recipe keeps surface propagation cheap and consistent.
  * .ui-code composes its own ring in src/styles/code.css instead of joining this list: a
  * chip cannot both paint --code-bg and re-point it, and its gap has to be the surface it
- * actually paints. why: docs/specification.md#the-focus-ring */
+ * actually paints. why: docs/foundations.md#the-focus-ring */
 .amenu,
 .dtsw,
 .rx-modal,