@apliteni/apliteni-ui 0.92.0 → 0.94.0

package/src/logic/filter-bar.js

@@ -6,7 +6,7 @@
  *
  * `value` is display text: it is the chip's only visible line, so a consumer
  * answers a change with text a reader can read, not a raw code.
- * why: docs/specification.md#dense-financial-tables
+ * why: docs/components.md#dense-financial-tables
  */
 
 const text = (v) => (v == null ? '' : String(v));
@@ -71,7 +71,7 @@ function stopsAround(host) {
  *  order, else the nearest one behind it. A filter bar that has just dropped its
  *  last control keeps no box the focus ring can sit on, so the focus has to
  *  leave the bar rather than land on a line with no height.
- *  why: docs/specification.md#a-filter-row-holds-its-panels */
+ *  why: docs/components.md#a-filter-row-holds-its-panels */
 export function nextFocusStop(host) {
   return stopsAround(host)[0] || null;
 }
@@ -88,7 +88,7 @@ export function nextFocusStop(host) {
  *  Being reachable is not the same as taking the focus: a control can be visible
  *  and enabled and still refuse, so each candidate is asked and then checked, and
  *  the next one tried.
- *  why: docs/specification.md#a-filter-row-holds-its-panels */
+ *  why: docs/components.md#a-filter-row-holds-its-panels */
 export function focusNextStop(host) {
   const doc = host && host.ownerDocument;
   if (!doc) return null;
@@ -114,7 +114,7 @@ export function focusNextStop(host) {
  *  consumer wrote them left whatever they had marked standing — a menu checking
  *  `All`, `aria-selected="true"` on it, under a chip printing `Asia`. The
  *  consumer's own array and objects are not written to. #550
- *  why: docs/specification.md#a-filter-row-holds-its-panels */
+ *  why: docs/components.md#a-filter-row-holds-its-panels */
 export function filterChipItems(filter = {}) {
   const items = filter.items || [];
   const chosen = text(filter.value);

package/src/styles/back.css

@@ -3,7 +3,7 @@
  * The way up from a page to the page it sits under. It stands above the page
  * title, in the slot a breadcrumb trail would take, and it is quiet at rest: it
  * is on every page below a list, and it is never what the page is for.
- * why: docs/specification.md#the-back-link
+ * why: docs/components.md#the-back-link
  * ========================================================================== */
 
 /* Its own line, and only as wide as its words, so the hover ground does not run
@@ -36,7 +36,7 @@
 
 /* 16px, with the stroke raised to match: the glyph set draws at 1.7 on a 24-unit
    box, which is 1.13 CSS px at this size and under the kit's 1.5 for a stroked
-   mark. 2.4 paints 1.6. why: docs/specification.md#icons-and-glyphs */
+   mark. 2.4 paints 1.6. why: docs/foundations.md#icons-and-glyphs */
 .ui-back svg { width: 16px; height: 16px; flex: none; stroke-width: 2.4; }
 
 /* In the page shell it takes the trail's place, and the trail's distance from
@@ -44,7 +44,7 @@
 .ui-app__main > .ui-back { margin-bottom: var(--space-5); }
 
 /* The one part that can run long. It clips rather than wrapping, as .ui-nav__label
-   does. why: docs/specification.md#the-back-link */
+   does. why: docs/components.md#the-back-link */
 .ui-back__label {
   min-width: 0;
   overflow: hidden;

package/src/styles/base.css

@@ -43,7 +43,7 @@ a {
  * reader notices. A component that wants a heading tag set in the text face
  * says so on its own rule, which outranks this one at (0,1,0); .ui-card__title,
  * .ui-drawer__title and .ui-confirm__title are the three that do.
- * why: docs/specification.md#typefaces */
+ * why: docs/foundations.md#typefaces */
 h1, h2, h3, h4, h5, h6 {
   font-family: var(--font-display);
 }
@@ -52,7 +52,7 @@ h1, h2, h3, h4, h5, h6 {
  * chat feeds run at, 700 stops reading as emphasis and starts reading as a
  * filled-in shape. The semibold step is the emphasis; the bold step stays
  * available to anything that asks for it by name.
- * why: docs/specification.md#typefaces */
+ * why: docs/foundations.md#typefaces */
 b,
 strong {
   font-weight: var(--weight-semibold);
@@ -115,7 +115,7 @@ strong {
 .ui-stack > * + * { margin-top: var(--space-4); }
 
 /* Eyebrow — the label above a title or a figure, in sentence case like every
-   label in the kit. why: docs/specification.md#labels-and-titles */
+   label in the kit. why: docs/foundations.md#labels-and-titles */
 .ui-eyebrow {
   /* rank: label */
   font-size: var(--text-sm);

package/src/styles/button.css

@@ -20,7 +20,7 @@
   padding: var(--btn-pad-y) var(--btn-pad-x);
   cursor: pointer;
   /* Light needs a stronger line here: --border on this fill measures 1.047:1.
-     why: docs/specification.md#elevation */
+     why: docs/foundations.md#elevation */
   border: 1px solid var(--control-edge);
   background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
   color: var(--text);
@@ -74,7 +74,7 @@
 }
 
 /* -- Sizes -------------------------------------------------------------- */
-/* why: docs/specification.md#extra-small-buttons */
+/* why: docs/components.md#extra-small-buttons */
 .ui-btn--xs { --btn-pad-y: 4.5px; --btn-pad-x: 8px; --btn-font: var(--text-xs); min-width: 24px; min-height: 24px; }
 .ui-btn--xs svg { width: 13px; height: 13px; stroke-width: 2.8; }
 .ui-btn--sm { --btn-pad-y: 6px; --btn-pad-x: 12px; --btn-font: calc(var(--text-sm) - 0.5px); }
@@ -123,7 +123,7 @@
    contrast table shows that. The box was reverted and this ink shipped.
    Held by src/styles/button-disabled.test.js. */
 
-/* why: docs/specification.md#busy-button-labels */
+/* why: docs/components.md#busy-button-labels */
 .ui-btn { position: relative; }
 .ui-btn[aria-busy="true"] { pointer-events: none; }
 .ui-btn[aria-busy="true"][data-btn-wired] {

package/src/styles/callout.css

@@ -15,7 +15,7 @@
 .ui-callout__body { min-width: 0; overflow-wrap: break-word; }
 .ui-callout__actions { margin-top: 15px; }
 .ui-callout__icon { width: 18px; height: 18px; flex: none; margin-top: 1px; /* muted-ink: glyph — nonverbal callout icon */ color: var(--muted); }
-.ui-callout__icon svg { width: 100%; height: 100%; stroke: currentColor; fill: none; stroke-width: 2.1; } /* 2.1 of a 24 box drawn at 18px = 1.58 CSS px, which is what buys the 3:1 graphic bar rather than the 4.5:1 text one. docs/specification.md#icons-and-glyphs */
+.ui-callout__icon svg { width: 100%; height: 100%; stroke: currentColor; fill: none; stroke-width: 2.1; } /* 2.1 of a 24 box drawn at 18px = 1.58 CSS px, which is what buys the 3:1 graphic bar rather than the 4.5:1 text one. docs/foundations.md#icons-and-glyphs */
 .ui-callout b { color: var(--text); font-weight: var(--weight-semibold); }
 .ui-callout code { font-family: var(--font-mono); font-size: 0.92em; color: var(--text); }
 
@@ -133,7 +133,7 @@
    the 20px success() draws it at, rather than stretching a status mark to fill the
    line mark's box. The mark fills the box, so the box is what decides. The modifier
    is written by successPanel(), as success() writes ui-sx--check-circled on its root.
-   why: docs/specification.md#success-confirmations */
+   why: docs/components.md#success-confirmations */
 .ui-success__check--circled { width: 20px; height: 20px; }
 .ui-success__title { color: var(--strong); font-size: var(--text-lg); font-weight: var(--weight-semibold); margin-bottom: 5px; }
 .ui-success__sub { color: var(--text); font-size: var(--text-base); }

package/src/styles/card.css

@@ -6,14 +6,14 @@
 /* The surface is the step; what makes it legible depends on the theme. Dark edges the
    card with the hairline (--card-edge). Light draws no line at all and casts --elev-rest
    instead — a 22px penumbra off a 10px offset, the width Artur's reference uses on a
-   card. Chosen by him on #490 round t3. why: docs/specification.md#elevation */
+   card. Chosen by him on #490 round t3. why: docs/foundations.md#elevation */
 .ui-card {
   background: var(--surface); --ring-gap: var(--surface);
   border: 1px solid var(--card-edge);
   box-shadow: var(--elev-rest);
   border-radius: var(--radius-xl);
   /* Was `var(--space-6) 26px`; 26 is off the scale and broke the column's text edge.
-     why: docs/specification.md#spacing-and-rhythm */
+     why: docs/foundations.md#spacing-and-rhythm */
   padding: var(--space-6);
   position: relative;
 }
@@ -26,7 +26,7 @@
    answered with the native outline. It is a scroll region, so it takes --ring-scroll:
    the band drawn inward, inside the card's 24px padding and clear of the table.
    --elev-rest is left alone: the band is an outline, not a layer of the shadow list.
-   why: docs/specification.md#the-focus-ring */
+   why: docs/foundations.md#the-focus-ring */
 .ui-card:has(> .ui-table):focus-visible { outline: var(--ring-scroll); outline-offset: var(--ring-scroll-offset); }
 
 /* Vertical stacks space cards with the container's gap — see .ui-card-stack.
@@ -36,7 +36,7 @@
 /* A padding modifier moves the vertical rhythm and keeps the text edge, so cards of
    different padding line up in one column. --pad-lg is the centred landing card, never
    stacked with plain ones, and keeps its own inset.
-   why: docs/specification.md#spacing-and-rhythm */
+   why: docs/foundations.md#spacing-and-rhythm */
 .ui-card--pad-sm { padding: var(--space-5) var(--space-6); }
 .ui-card--pad-lg { padding: var(--space-8) var(--space-10); }
 
@@ -44,7 +44,7 @@
    the card's own hairline re-coloured: an inset ring over it would draw two. #295
    The strength is --card-tint, per theme: light mixes down from white, so a tint that
    works in dark sinks a light card below the page. Each variant edges itself in its own
-   colour. why: docs/specification.md#elevation */
+   colour. why: docs/foundations.md#elevation */
 .ui-card--accent {
   background: color-mix(in srgb, var(--accent) var(--card-tint), var(--surface)); --ring-gap: color-mix(in srgb, var(--accent) var(--card-tint), var(--surface));
   border-color: color-mix(in srgb, var(--accent) 22%, transparent);
@@ -66,12 +66,12 @@
   transition: transform var(--dur-fast) var(--ease);
 }
 /* The lift alone: the card's own rung is what says it is raised, and hover is not a
-   change of level. why: docs/specification.md#elevation */
+   change of level. why: docs/foundations.md#elevation */
 .ui-card--interactive:hover { transform: translateY(-2px); }
 .ui-card--interactive:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); }
 
 /* card() emits the title as an h2, so the text face is named here rather than
-   left to the element. why: docs/specification.md#labels-and-titles */
+   left to the element. why: docs/foundations.md#labels-and-titles */
 .ui-card__title {
   color: var(--strong);
   font-family: var(--font-sans);
@@ -82,7 +82,7 @@
   display: flex;
   align-items: center;
   gap: 10px;
-  /* Title to description: the step, not the 5px it was. why: docs/specification.md#spacing-and-rhythm */
+  /* Title to description: the step, not the 5px it was. why: docs/foundations.md#spacing-and-rhythm */
   margin: 0 0 var(--space-2);
 }
 .ui-card__sub {

package/src/styles/command-palette.css

@@ -12,10 +12,10 @@
  * Two densities, one markup: the default packs a row onto one line, and
  * `.ui-cmdk--roomy` gives the description a line of its own.
  *
- * why: docs/specification.md#the-command-palette */
+ * why: docs/components.md#the-command-palette */
 
 .ui-cmdk {
-  /* The floating step; nothing casts. why: docs/specification.md#elevation */
+  /* The floating step; nothing casts. why: docs/foundations.md#elevation */
   --cmdk-surface: var(--bg-elevated);
   --cmdk-scrim: var(--scrim);
   --cmdk-w: 560px;
@@ -72,7 +72,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-lg);
@@ -87,7 +87,7 @@
 /* The ring is COMPOSED with the floating treatment, not written over it: a
    box-shadow list replaces the whole list, so `box-shadow: var(--ring)` alone
    took the panel's edge and its drop off for as long as it held focus.
-   why: docs/specification.md#elevation */
+   why: docs/foundations.md#elevation */
 .ui-cmdk__panel:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring), inset 0 0 0 1px var(--elev-edge, var(--float-edge-inner)), var(--elev-drop); }
 
 /* -- The text box --------------------------------------------------------- */
@@ -105,7 +105,7 @@
   flex: none;
 }
 /* 2.2 of a 24 box drawn at 17px = 1.56 CSS px, which is what keeps the mark a
-   graphic rather than a smudge. why: docs/specification.md#icons-and-glyphs */
+   graphic rather than a smudge. why: docs/foundations.md#icons-and-glyphs */
 .ui-cmdk__search-ic svg { width: 17px; height: 17px; stroke: currentColor; fill: none; stroke-width: 2.2; }
 
 /* Not .ui-input: this one has no box of its own — the panel is the box — and a
@@ -149,7 +149,7 @@
    arrive at the native outline. The band is drawn INWARD, on the list: the panel clips
    with `overflow: hidden`, so an outset one is cut off, and the panel is not the box
    that scrolls. The list's own 8px of padding is where it lands.
-   why: docs/specification.md#the-focus-ring */
+   why: docs/foundations.md#the-focus-ring */
 .ui-cmdk__list:focus-visible { outline: var(--ring-scroll); outline-offset: var(--ring-scroll-offset); }
 .ui-cmdk__group + .ui-cmdk__group { margin-top: var(--space-2); }
 
@@ -169,7 +169,7 @@
    13.3333px Arial`, centred text and a shrink-to-fit width, and a consumer who
    needs the row operable from the keyboard should get the row this sheet
    describes rather than that. `font: inherit` comes before the line-height it
-   keeps. why: docs/specification.md#a-dropdown-row-is-a-div-a-link-or-a-button */
+   keeps. why: docs/components.md#a-dropdown-row-is-a-div-a-link-or-a-button */
 .ui-cmdk__item {
   display: flex;
   border: 0;
@@ -197,7 +197,7 @@
   flex: none;
 }
 /* 2.3 of a 24 box drawn at 16px = 1.53 CSS px. Same arithmetic as the dropdown's
-   row icon next door. why: docs/specification.md#icons-and-glyphs */
+   row icon next door. why: docs/foundations.md#icons-and-glyphs */
 .ui-cmdk__ic svg { width: 16px; height: 16px; stroke: currentColor; fill: none; stroke-width: 2.3; }
 .ui-cmdk__item.is-active .ui-cmdk__ic { color: var(--accent); }
 
@@ -220,7 +220,7 @@
   font-size: var(--text-sm);
   /* Body ink: a row's note is how two rows called INV-4812 and
      INV-4809 are told apart, which is not something a reader may skip.
-     why: docs/specification.md#text-ink */
+     why: docs/foundations.md#text-ink */
   color: var(--text);
   white-space: nowrap;
   overflow: hidden;
@@ -242,7 +242,7 @@
    writes with :hover. A palette row is reached with an arrow key far more often
    than with a pointer, so `.is-active` carries the signal beside :hover: it is
    the same moment, and it is the row Enter would run.
-   why: docs/specification.md#text-ink */
+   why: docs/foundations.md#text-ink */
 .ui-cmdk__item.is-danger .ui-cmdk__label { color: var(--text); }
 .ui-cmdk__item.is-danger:hover .ui-cmdk__label,
 .ui-cmdk__item.is-danger.is-active .ui-cmdk__label { color: var(--pink); }
@@ -252,7 +252,7 @@
    for a control with no box of its own. Disabled rows keep the panel's
    surface and their labels remain readable on that ground without
    adding a grey box behind the text.
-   why: docs/specification.md#text-ink */
+   why: docs/foundations.md#text-ink */
 .ui-cmdk__item.is-disabled { cursor: default; /* muted-ink: state — unavailable control */ color: var(--disabled-ink-bare); }
 .ui-cmdk__item.is-disabled .ui-cmdk__label,
 .ui-cmdk__item.is-disabled .ui-cmdk__desc,
@@ -267,7 +267,7 @@
   border: 1px solid var(--border);
   border-radius: var(--radius-xs);
   /* Key caps use an edge on the card surface, keeping the shortcut readable.
-     why: docs/specification.md#elevation */
+     why: docs/foundations.md#elevation */
   background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
   font-family: var(--font-sans);
   font-size: var(--text-xs);
@@ -319,7 +319,7 @@
 /* -- Narrow --------------------------------------------------------------- */
 /* At the kit's narrowest step the palette is the page: full width, off the top
    edge, and the key legend goes — there is no keyboard to legend.
-   why: docs/specification.md#breakpoints */
+   why: docs/foundations.md#breakpoints */
 @media (max-width: 560px) {
   .ui-cmdk { --cmdk-top: var(--space-4); --cmdk-list-h: 60vh; }
   .ui-cmdk__panel { width: calc(100vw - var(--space-4)); }
@@ -333,7 +333,7 @@
    carries no transition inside it at all — for as long as it is open, not only
    in the frame it opens — which is what reduced motion asked for anyway: under
    the net nothing inside had longer than 0.01ms to run.
-   why: docs/specification.md#reduced-motion-travels-with-the-stylesheet */
+   why: docs/foundations.md#reduced-motion-travels-with-the-stylesheet */
 @media (prefers-reduced-motion: reduce) {
   .ui-cmdk.is-open * { transition: none !important; }
 }

package/src/styles/confirm.css

@@ -1,10 +1,10 @@
 /* Confirm — the kit's confirmation dialog: a centred panel over a scrim, for the
  * question a destructive action has to ask. Shares its scrim and focus trap with
  * the drawer (see overlay.js). Local tokens: --confirm-surface, --confirm-scrim.
- * why: docs/specification.md#motion */
+ * why: docs/foundations.md#motion */
 
 .ui-confirm {
-  /* The floating step; nothing casts. why: docs/specification.md#elevation */
+  /* The floating step; nothing casts. why: docs/foundations.md#elevation */
   --confirm-surface: var(--bg-elevated);
   --confirm-scrim: var(--scrim);
   --confirm-w: var(--panel-md);
@@ -65,7 +65,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-lg);
@@ -79,7 +79,7 @@
 /* The ring is COMPOSED with the floating treatment, not written over it: a
    box-shadow list replaces the whole list, so `box-shadow: var(--ring)` alone
    took the panel's edge and its drop off for as long as it held focus.
-   why: docs/specification.md#elevation */
+   why: docs/foundations.md#elevation */
 .ui-confirm__panel:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring), inset 0 0 0 1px var(--elev-edge, var(--float-edge-inner)), var(--elev-drop); }
 
 /* -- Slots ----------------------------------------------------------------- */
@@ -88,7 +88,7 @@
    footer makes. The title is an h2 and opts out of the display face base.css
    gives a heading, for the same reason .ui-drawer__title does: at --text-md it
    is the question on a dialog, set at the size the answer beneath it is set at.
-   why: docs/specification.md#typefaces */
+   why: docs/foundations.md#typefaces */
 .ui-confirm__title {
   margin: 0;
   flex: none;
@@ -118,7 +118,7 @@
    follow it; the markup the kit publishes as a string, rendered open without the
    wiring, has no trap and makes it the first stop. The band is drawn INWARD, inside
    the --space-1 above, which is what keeps it off the glyphs.
-   why: docs/specification.md#the-focus-ring */
+   why: docs/foundations.md#the-focus-ring */
 .ui-confirm__body:focus-visible { outline: var(--ring-scroll); outline-offset: var(--ring-scroll-offset); }
 .ui-confirm__acts {
   display: flex;
@@ -135,7 +135,7 @@
    root, so the answer openConfirm() focuses is still hidden and focus falls to
    <body>. So an open confirm carries no transition inside it at all — for as
    long as it is open, not only in the frame it opens.
-   why: docs/specification.md#reduced-motion-travels-with-the-stylesheet */
+   why: docs/foundations.md#reduced-motion-travels-with-the-stylesheet */
 @media (prefers-reduced-motion: reduce) {
   .ui-confirm.is-open * { transition: none !important; }
 }

package/src/styles/drawer.css

@@ -12,7 +12,7 @@
 
 .ui-drawer {
   /* The floating step; the edge is the hairline each --drawer--<edge> rule below draws.
-     why: docs/specification.md#elevation */
+     why: docs/foundations.md#elevation */
   --drawer-surface: var(--bg-elevated);
   --drawer-scrim: var(--scrim);
   --drawer-w: var(--panel-md);   /* left|right panels: width  */
@@ -66,7 +66,7 @@
      line with the drops instead. The line is a variable so the focus rule can
      compose all three layers without knowing which edge it is on; its default is a
      no-op layer rather than `none`, which is valid only alone and would invalidate
-     the list. why: docs/specification.md#elevation */
+     the list. why: docs/foundations.md#elevation */
   --drawer-line: 0 0 0 0 transparent;
   box-shadow: var(--drawer-line), var(--elev-drop);
   transition: transform var(--dur-med) var(--ease);
@@ -114,7 +114,7 @@
 /* The ring is COMPOSED with the floating treatment rather than written over it — a
    box-shadow list replaces the whole list, so a bare `box-shadow: var(--ring)` would
    take the drawer's edge and its drop off for as long as it held focus.
-   why: docs/specification.md#elevation */
+   why: docs/foundations.md#elevation */
 .ui-drawer__panel:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring), var(--drawer-line), var(--elev-drop); }
 
 /* -- Sizes ----------------------------------------------------------------- */
@@ -140,7 +140,7 @@
 /* An h2, and base.css would give it the display face. It opts out: at 15px in a
    panel header it is a label on a piece of UI rather than a heading anybody
    reads, and the display face at that size is exactly what #253 was about.
-   why: docs/specification.md#typefaces */
+   why: docs/foundations.md#typefaces */
 .ui-drawer__title {
   margin: 0;
   font-family: var(--font-sans);
@@ -184,7 +184,7 @@
    with the native outline. The band is drawn INWARD, inside the 20px padding: the body
    is flush with a panel that is itself flush with a screen edge, so an outset ring — on
    either box — is painted off-screen. Measured at 390, where an outset one left no
-   indicator at all. why: docs/specification.md#the-focus-ring */
+   indicator at all. why: docs/foundations.md#the-focus-ring */
 .ui-drawer__body:focus-visible { outline: var(--ring-scroll); outline-offset: var(--ring-scroll-offset); }
 
 .ui-drawer__footer {
@@ -202,14 +202,14 @@
    panel, and rows are held apart by space alone. Group from group is the one
    division inside the body worth a line; the body's padding insets it, so it
    parts the groups without cutting the panel in two.
-   why: docs/specification.md#the-drawer */
+   why: docs/components.md#the-drawer */
 .ui-drawer__section + .ui-drawer__section {
   margin-top: var(--space-6);
   padding-top: var(--space-6);
   border-top: 1px solid var(--border);
 }
 /* An h3, and it opts out of the display face for the reason .ui-drawer__title does.
-   why: docs/specification.md#typefaces */
+   why: docs/foundations.md#typefaces */
 .ui-drawer__section-title {
   margin: 0 0 var(--space-2);
   font-family: var(--font-sans);
@@ -244,7 +244,7 @@
    open drawer carries no transition inside it at all — for as long as it is
    open, not only in the frame it opens — which is what reduced motion asked
    for anyway: under the net nothing inside had longer than 0.01ms to run.
-   why: docs/specification.md#reduced-motion-travels-with-the-stylesheet */
+   why: docs/foundations.md#reduced-motion-travels-with-the-stylesheet */
 @media (prefers-reduced-motion: reduce) {
   .ui-drawer.is-open * { transition: none !important; }
 }

package/src/styles/dropdown.css

@@ -31,7 +31,7 @@
 /* Chevron — border caret that flips when the container is .open. Its ink is an L
    on a rotated square, so centring the BOX leaves the mark off centre; --caret-off
    is that gap, derived rather than typed.
-   why: docs/specification.md#the-dropdown-panel */
+   why: docs/components.md#the-dropdown-panel */
 .ui-dropdown__chevron {
   --caret: 8px;
   --caret-ink: 1.6px;
@@ -50,11 +50,11 @@
 .ui-dropdown__panel {
   /* One number for the trigger-to-panel offset, read by both edges here and by
      the portal's JS, so an upward panel cannot drift from a downward one.
-     why: docs/specification.md#the-dropdown-panel */
+     why: docs/components.md#the-dropdown-panel */
   --ui-dropdown-gap: 9px;
   /* Named for the same reason the offset is: a block pinned to an edge has to
      bleed back through it, and #306 is a page copying the number by hand.
-     why: docs/specification.md#the-dropdown-panel */
+     why: docs/components.md#the-dropdown-panel */
   --ui-dropdown-pad: 6px;
   /* The panel states its own role rather than inheriting one, because `portal:
      true` moves it onto <body> and an inherited face is then decided by where
@@ -62,19 +62,19 @@
      inside a display-face subtree resolved to var(--font-display) in place and
      var(--font-sans) once portalled — a positioning flag changing the typeface.
      A list of item rows is text, so it is the text face in both placements.
-     why: docs/specification.md#typefaces */
+     why: docs/foundations.md#typefaces */
   font-family: var(--font-sans);
   position: absolute;
   top: calc(100% + var(--ui-dropdown-gap));
   left: 0;
   min-width: 240px;
   /* The floating step, not the sunken one — a panel held open over a card cannot be
-     painted the colour of an inset. why: docs/specification.md#elevation */
+     painted the colour of an inset. why: docs/foundations.md#elevation */
   background: var(--bg-elevated); --ring-gap: var(--bg-elevated);
   /* 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-lg);
@@ -83,7 +83,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 rules take this back.
-     why: docs/specification.md#the-dropdown-panel */
+     why: docs/components.md#the-dropdown-panel */
   pointer-events: none;
   transform: translateY(-6px);
   transition:
@@ -103,7 +103,7 @@
    rather than the scrolling one, as the palette and the drawer write it, because
    a panel that takes focus any other way has the same claim on the ring. The
    ring is COMPOSED with the floating treatment rather than over it: a box-shadow
-   list replaces the whole list. why: docs/specification.md#elevation */
+   list replaces the whole list. why: docs/foundations.md#elevation */
 .ui-dropdown__panel:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring), inset 0 0 0 1px var(--elev-edge, var(--float-edge-inner)), var(--elev-drop); }
 
 /* Opening upward. The kit releases its own `top` here so that nothing outside
@@ -111,7 +111,7 @@
    them, and a consumer who set `bottom` and left our `top` standing got a
    fourteen-pixel panel. The entry travel is mirrored too, so the panel arrives
    from the trigger whichever way it opens.
-   why: docs/specification.md#the-dropdown-panel */
+   why: docs/components.md#the-dropdown-panel */
 .ui-dropdown__panel.is-up {
   top: auto;
   bottom: calc(100% + var(--ui-dropdown-gap));
@@ -122,7 +122,7 @@
 /* Open, the panel is visible AT ONCE: `visibility` is off the list, so it is not
    held at `hidden` for the frame a key opens the panel in — the frame the focus
    call happens in. Closing still fades on every property it always did.
-   why: docs/specification.md#the-dropdown-panel */
+   why: docs/components.md#the-dropdown-panel */
 .ui-dropdown.open .ui-dropdown__panel,
 .ui-dropdown__panel--portal.is-open { transition-property: opacity, transform; }
 
@@ -130,7 +130,7 @@
    property of its own still transitions the inherited `visibility`, so it is hidden in
    the frame openDropdown() focuses into it — #519. Keyed on the data hook, because the
    topbar's two menus open on the same wiring and keep their own CSS.
-   why: docs/specification.md#the-dropdown-panel */
+   why: docs/components.md#the-dropdown-panel */
 @media (prefers-reduced-motion: reduce) {
   .open > [data-dropdown-panel] *,
   [data-dropdown-panel].is-open * { transition: none !important; }
@@ -141,7 +141,7 @@
    selector above stops matching the moment it leaves the trigger's subtree, so
    its open state is a class of its own; the wiring writes the viewport
    coordinates inline, and these `auto`s are what it writes over.
-   why: docs/specification.md#the-dropdown-panel */
+   why: docs/components.md#the-dropdown-panel */
 .ui-dropdown__panel--portal {
   position: fixed;
   top: auto; right: auto; bottom: auto; left: auto;
@@ -152,7 +152,7 @@
    <a href> or a <button>: `is-selected` and __tick below mean a row gets
    chosen, and choosing is a button's job. So the tag's own styling is reset
    here, the way .ui-nav__item resets it, and the three render identically.
-   why: docs/specification.md#a-dropdown-row-is-a-div-a-link-or-a-button */
+   why: docs/components.md#a-dropdown-row-is-a-div-a-link-or-a-button */
 .ui-dropdown__item {
   display: flex;
   gap: 11px;
@@ -172,7 +172,7 @@
   color: var(--text);
   transition: background var(--dur-fast) var(--ease);
 }
-/* Rows keep a reading surface; hover adds an edge. why: docs/specification.md#elevation */
+/* Rows keep a reading surface; hover adds an edge. why: docs/foundations.md#elevation */
 .ui-dropdown__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. */ }
 .ui-dropdown__item:focus-visible { outline: 2px solid transparent; background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ box-shadow: var(--ring); }
 .ui-dropdown__main { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
@@ -213,7 +213,7 @@
 .ui-dropdown__item.is-disabled .ui-dropdown__desc { color: inherit; }
 /* Body ink at rest, --pink on the way to being pressed. Both states, not hover alone:
    the ring says where the reader is, not that this row ends something.
-   why: docs/specification.md#a-dropdown-row-is-a-div-a-link-or-a-button */
+   why: docs/components.md#a-dropdown-row-is-a-div-a-link-or-a-button */
 .ui-dropdown__item.is-danger .ui-dropdown__label { color: var(--text); }
 .ui-dropdown__item.is-danger:hover .ui-dropdown__label,
 .ui-dropdown__item.is-danger:focus-visible .ui-dropdown__label { color: var(--pink); }
@@ -234,7 +234,7 @@
 
 /* Optional pinned head/foot blocks — symmetrical: one inner padding, and each
    bleeding to the edge it sits on, lining the edge it faces.
-   why: docs/specification.md#the-dropdown-panel */
+   why: docs/components.md#the-dropdown-panel */
 .ui-dropdown__panel > .ui-dropdown__head,
 .ui-dropdown__panel > .ui-dropdown__foot {
   padding: 11px 13px;
@@ -254,7 +254,7 @@
    reader types. The rows move into a list of their own, so the field stays put
    while the list scrolls. Every rule below keys on a class only the search
    variant emits, so the plain dropdown renders as it did.
-   why: docs/specification.md#a-dropdown-with-a-search-field */
+   why: docs/components.md#a-dropdown-with-a-search-field */
 .ui-dropdown__panel--search { min-width: 280px; }
 
 .ui-dropdown__search { position: relative; display: flex; align-items: center; margin-bottom: 6px; }
@@ -269,13 +269,13 @@
 .ui-dropdown__search-ic svg { width: 16px; height: 16px; stroke: currentColor; fill: none; stroke-width: 2.4; }
 /* 12.5px with a mouse only. On a touch screen the touch-zoom net in
    src/styles/field-zoom.css takes this field, and every other field the kit
-   ships, to 16px. why: docs/specification.md#a-field-is-16px-on-a-touch-screen */
+   ships, to 16px. why: docs/foundations.md#a-field-is-16px-on-a-touch-screen */
 .ui-dropdown__search-input {
   width: 100%;
   font: inherit;
   font-size: calc(var(--text-sm) - 0.5px);
   color: var(--strong);
-  /* The ground and line .ui-input takes. why: docs/specification.md#elevation */
+  /* The ground and line .ui-input takes. 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-sm);
@@ -287,7 +287,7 @@
 }
 /* The light-only `background: var(--bg)` override this field used to carry is gone:
    --field-bg says the same thing for every field. Gated by
-   stories/dropdown-field-ground.test.js. why: docs/specification.md#elevation */
+   stories/dropdown-field-ground.test.js. why: docs/foundations.md#elevation */
 
 .ui-dropdown__search-input::placeholder { /* muted-ink: placeholder — empty search field */ color: var(--muted); }
 .ui-dropdown__search-input:hover { border-color: var(--field-edge-hover); }
@@ -298,7 +298,7 @@
    answered with the native outline. The band is drawn INWARD, on the list: an outset
    one 6px inside a --radius-lg corner leaves the panel, and the panel is not the box
    that scrolls. It lands in the rows' own 9px of padding, never on a label.
-   why: docs/specification.md#the-focus-ring */
+   why: docs/foundations.md#the-focus-ring */
 .ui-dropdown__list:focus-visible { outline: var(--ring-scroll); outline-offset: var(--ring-scroll-offset); }
 /* A row is `display: flex`, which outranks the UA's [hidden], so a row the
    query hides is put away here. */

package/src/styles/feedback.css

@@ -38,7 +38,7 @@
      fill strength on the page, found the way the solid toast is found. What is left is an
      inset sheen — gloss on the surface, not a shadow under it — so the hover is the travel
      alone and the box-shadow it transitioned went with it.
-     why: docs/specification.md#elevation */
+     why: docs/foundations.md#elevation */
   box-shadow: inset 0 1px 0 color-mix(in srgb, var(--sheen) 28%, transparent);
   transition:
     transform var(--dur-fast) var(--ease-spring),
@@ -69,7 +69,7 @@
   width: min(520px, calc(100vw - 32px)); background: var(--bg-elevated); --ring-gap: var(--bg-elevated); border-radius: 18px;
   /* The shadow was its only edge until #295, which replaced it with the hairline; since
      #490 light is back on the drop and dark keeps the line.
-     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);
   opacity: 0; pointer-events: none;

package/src/styles/field-zoom.css

@@ -8,7 +8,7 @@
  * transform still zooms, and this is a flat size rather than a floor, so a host
  * field designed ABOVE 16px is shrunk here. The override recipe is there too.
  *
- * why: docs/specification.md#a-field-is-16px-on-a-touch-screen */
+ * why: docs/foundations.md#a-field-is-16px-on-a-touch-screen */
 
 @media (pointer: coarse) {
   input:not(:where(