@apliteni/apliteni-ui 0.92.0 → 0.93.0

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,7 +58,7 @@
    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; }
@@ -75,7 +75,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 +91,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;
@@ -139,7 +139,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 +152,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 +173,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 +196,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 +208,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 +219,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 +243,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 +253,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,14 +266,14 @@
    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; }
@@ -282,7 +282,7 @@
    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 */
+   edge is centred on the glyph. 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; }
@@ -295,8 +295,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 +330,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 +338,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 +368,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 +383,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 +394,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 +409,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 +447,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 +466,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,
@@ -496,7 +496,7 @@
   /* 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 +534,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,7 +74,7 @@
   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 .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 { 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__item.is-active {
   background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
@@ -164,7 +164,7 @@
    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 */
@@ -242,7 +242,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

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. */