@apliteni/apliteni-ui 0.91.0 → 0.93.0

package/src/components/dropdown.js

@@ -80,7 +80,7 @@ function ddBody({ items, sections }, listbox, sx) {
 // The match is a substring of the label, anywhere in it, ignoring case and
 // accents; rows keep their order. The factory and the wiring both ask
 // dropdownMatch(), so a preset query and a typed one hide the same rows.
-// why: docs/specification.md#a-dropdown-with-a-search-field
+// why: docs/components.md#a-dropdown-with-a-search-field
 // NFD takes the mark off é or ö; ł, ø, đ and the rest are letters of their own
 // with nothing to take off, so they are mapped by hand.
 const ddIsRow = (it) => it && it !== '---' && !it.separator;
@@ -207,7 +207,7 @@ export function dropdown({
 
   // The block the sheet bleeds to the panel's bottom edge. It sits OUTSIDE the
   // unwrapped `footer`, because the block that bleeds is the one that has to
-  // touch the edge. why: docs/specification.md#the-dropdown-panel
+  // touch the edge. why: docs/components.md#the-dropdown-panel
   const footBlock = foot ? `<div class="ui-dropdown__foot">${foot}</div>` : '';
 
   const ddAttrs = 'data-dropdown'
@@ -236,7 +236,7 @@ export function dropdown({
 // Every wired container, so the close handlers can reach a dropdown wherever it
 // was drawn: `document.querySelectorAll` enters no shadow root and sees no other
 // document. A Set and not a WeakSet, because this has to be walked.
-// why: docs/specification.md#the-dropdown-panel
+// why: docs/components.md#the-dropdown-panel
 const _ddAll = new Set();
 // One pair of close handlers per document that holds a dropdown, the same way
 // wireShell() listens once per document it is handed.
@@ -276,7 +276,7 @@ function ddItemsOf(dd) {
 }
 
 // ---- Search wiring ---------------------------------------------------------
-// why: docs/specification.md#a-dropdown-with-a-search-field
+// why: docs/components.md#a-dropdown-with-a-search-field
 const ddSearchOf = (dd) => ddPanelOf(dd)?.querySelector('[data-dd-search]') || null;
 const ddActiveOf = (dd) => ddPanelOf(dd)?.querySelector('[data-dd-item].is-active') || null;
 const ddComposing = (e) => e.isComposing || e.keyCode === 229;
@@ -342,7 +342,7 @@ export const DD_MENU_FLOOR = 240;
  * A panel is anchored at one edge of its dropdown — its inline end when it
  * carries `is-end` — so room is measured from that edge and the slide goes the
  * other way. Measuring an end-anchored panel forwards put one off the page.
- * why: docs/specification.md#a-filter-row-holds-its-panels
+ * why: docs/components.md#a-filter-row-holds-its-panels
  *
  * @param {Element} dd a `.ui-dropdown` that may be inside a filter row
  * @param {number} [floor] the width to reach for
@@ -405,7 +405,7 @@ function ddFitFilterPanel(dd, panel) {
  *  the old width too, and inline beats the sheet, so it is read again off the
  *  newly bounded box; only when the fit moved, because re-reading it is itself a
  *  write.
- *  why: docs/specification.md#a-filter-row-holds-its-panels */
+ *  why: docs/components.md#a-filter-row-holds-its-panels */
 function ddRefitFilterPanel(dd, panel) {
   const fit = panel?.style ? filterPanelFit(dd) : null;
   if (!fit || !ddWriteFit(panel, fit)) return;
@@ -424,7 +424,7 @@ function ddRowOf(dd) {
  *  `position: absolute`, so nothing in it can move a chip along its row. Any
  *  panel, not only the one being fitted: two open menus in one row would
  *  otherwise answer each other a mutation at a time.
- *  why: docs/specification.md#a-filter-row-holds-its-panels */
+ *  why: docs/components.md#a-filter-row-holds-its-panels */
 function ddOurs(node) {
   const el = node?.nodeType === 1 ? node : node?.parentElement;
   return !!el?.closest?.('[data-dropdown-panel]');
@@ -443,7 +443,7 @@ function ddOurs(node) {
  * is laid out.
  *
  * Why those two cover the arithmetic, and the one case they do not:
- * why: docs/specification.md#a-filter-row-holds-its-panels
+ * why: docs/components.md#a-filter-row-holds-its-panels
  */
 function ddWatchRow(dd, panel) {
   ddUnwatchRow(dd);
@@ -664,7 +664,7 @@ function selectOption(dd, item) {
 // Click-outside, Escape and the repositioning sweep, registered once per document
 // that holds a dropdown — the same shape wireShell()'s listen() has, and for the
 // same reason: a frame is its own document and a listener on the page's never
-// fires there. why: docs/specification.md#the-dropdown-panel
+// fires there. why: docs/components.md#the-dropdown-panel
 function ddListen(doc) {
   if (!doc || _ddWiredDocs.has(doc)) return;
   _ddWiredDocs.add(doc);
@@ -683,7 +683,7 @@ function ddListen(doc) {
   };
   /* The fallback re-fit, for a view with no ResizeObserver. Not taken as well where
    * ddWatchRow() is watching: a `resize` event is the worse measurement of the two.
-   * why: docs/specification.md#a-filter-row-holds-its-panels */
+   * why: docs/components.md#a-filter-row-holds-its-panels */
   const refit = () => {
     for (const dd of ddLive()) {
       if (dd.classList.contains('open') && !dd.__ddPanel && !dd.__ddRowFit) {
@@ -712,11 +712,11 @@ export function wireDropdown(root = document) {
     // Portal: lift the panel onto <body>. An ancestor whose overflow is not
     // `visible` clips it on both axes, and one that is `position: sticky` opens
     // a stacking context whatever z-index the panel carries — the app rail is
-    // both at once. why: docs/specification.md#the-dropdown-panel
+    // both at once. why: docs/components.md#the-dropdown-panel
     if (panel && dd.hasAttribute('data-dropdown-portal')) {
       // The tree the trigger is in, not the page's: a panel lifted out of a
       // frame or a shadow root into the top document leaves its stylesheet and
-      // its close handler behind. why: docs/specification.md#the-dropdown-panel
+      // its close handler behind. why: docs/components.md#the-dropdown-panel
       const host = ddHostOf(dd);
       sweepOrphanPanels(host);
       panel.setAttribute('data-dropdown-portal', '');

package/src/components/filter-bar.js

@@ -9,7 +9,7 @@ export function filterBar({ filters = [], label = 'Filters', clearLabel = 'Clear
       + `<legend class="ui-filter-bar__legend">${esc(filter.label)}</legend>`
       + dropdown({ items: filterChipItems(filter), variant: 'select',
         // The chip prints one line; the field's name reaches a reader through the
-        // trigger's name and the chip's own legend. why: docs/specification.md#dense-financial-tables
+        // trigger's name and the chip's own legend. why: docs/components.md#dense-financial-tables
         triggerContent: `<span class="${filterChipUnset(filter) ? 'ui-dropdown__value is-placeholder' : 'ui-dropdown__value'}">${esc(filterChipText(filter))}</span>`,
         ariaLabel: filterChipName(filter), open: !!filter.open && !disabled && !busy && !filter.disabled })
       + `<button type="button" class="ui-filter-bar__remove" data-filter-remove aria-label="${esc(`Remove ${filter.label} filter`)}">×</button></fieldset>`).join('')
@@ -19,7 +19,7 @@ export function filterBar({ filters = [], label = 'Filters', clearLabel = 'Clear
     // rule — a control with no action to offer is not shown. It returns with
     // the first chip, in the bordered skin rather than the ghost one, because a
     // live action beside two chips has to read as live.
-    // why: docs/specification.md#a-filter-row-holds-its-panels
+    // why: docs/components.md#a-filter-row-holds-its-panels
     + (filters.length
       ? `<span data-filter-clear>${button({ label: clearLabel, size: 'sm' })}</span>`
       : '')

package/src/components/footer.js

@@ -36,7 +36,7 @@ function linkList(links = []) {
 // matter, and h2 is the one rank that cannot skip whatever heading came before
 // it. It was an h4 — the only h4 the kit drew — which read h2 → h4 on the
 // landing page and left a rank a reader hears missing. The look is the class's,
-// not the tag's. why: docs/specification.md#the-page
+// not the tag's. why: guidelines/the-page.md#the-page
 function column({ title, links = [] } = {}) {
   return `<div class="ui-footer__col">` +
     (title ? `<h2 class="ui-footer__col-title">${esc(title)}</h2>` : '') +

package/src/components/index.js

@@ -61,7 +61,7 @@ export function statusDot(live = false) {
 
 // ---- Card ----------------------------------------------------------------
 // The title is a heading one level under the page's h1 unless `level` says
-// otherwise. why: docs/specification.md#labels-and-titles
+// otherwise. why: docs/foundations.md#labels-and-titles
 export function card({ title, sub, body = '', variant, pad, icon: ic, level = 2 } = {}) {
   const cls = cx('ui-card', variant && `ui-card--${variant}`, pad && `ui-card--pad-${pad}`);
   const h = [2, 3, 4, 5, 6].includes(Number(level)) ? `h${Number(level)}` : 'h2';

package/src/components/loading.js

@@ -5,7 +5,7 @@
 // Three things land in that body: skeleton() while it fetches, your markup once
 // the rows arrive, deniedState() when the answer came back 403.
 //
-// why: docs/specification.md#pending-and-denied-states
+// why: docs/components.md#pending-and-denied-states
 import { icon } from '../assets/icons.js';
 import { button, esc } from './index.js';
 import { playEntrance } from '../motion.js';

package/src/components/shell.js

@@ -1,7 +1,7 @@
 // The kit's one page shell: a full-height rail beside one <main>, in two layouts.
 // `topbar` switches the product band on; it is off unless the caller hands one over.
 // wireShell() once after mounting wires the fold, the nav's groups and the reader's menu.
-// why: docs/specification.md#the-page-shell
+// why: docs/components.md#the-page-shell
 import { topbar as productTopbar } from './topbar.js';
 import { esc, icon } from './index.js';
 import { sidebarNav, breadcrumbs, wireNav } from './nav.js';
@@ -12,7 +12,7 @@ import { ACCOUNT_NAV, toMenuTuple, initials } from './account-nav.js';
 import { paletteHotkey } from './command-palette.js';
 import { safeUrl } from '../html.js';
 // The one account navigation definition lives in account-nav.js because topbar.js needs
-// it too; re-exported here so the name docs/library.md publishes keeps working.
+// it too; re-exported here so the name docs/components.md publishes keeps working.
 export { ACCOUNT_NAV };
 
 const str = (v) => (v == null ? '' : String(v));
@@ -44,7 +44,7 @@ const toCrumbs = (crumbs) => (Array.isArray(crumbs) ? crumbs : [])
 
 // A back link replaces the trail rather than joining it: the two would name the same parent
 // twice. Anything but a record is no back link; its fields go through as given, so a back
-// backLink() refuses leaves the trail standing. why: docs/specification.md#the-back-link
+// backLink() refuses leaves the trail standing. why: docs/components.md#the-back-link
 const toBack = (b) => (isRecord(b) && !Array.isArray(b) ? { href: b.href, label: b.label } : null);
 
 // The reader, as two strings. railUser() and initials() both read them, and an
@@ -83,15 +83,15 @@ const toTopbar = (t) => {
 //
 // Each is a name the kit knows or the default — read strictly, and not through
 // String(), which turned `['topbar']` into a layout and drew half a page.
-// why: docs/specification.md#the-page-shell
+// why: docs/components.md#the-page-shell
 const toLayout = (v) => (v === 'topbar' ? 'topbar' : 'rail');
 
-// why: docs/specification.md#widths
+// why: docs/foundations.md#widths
 const toWidth = (v) => (v === 'wide' ? 'wide' : 'centered');
 
 // `search: 'palette-id'`, or the same id in `{ palette }` with a placeholder beside
 // it. No palette to open, no field — the argument `signOutHref` takes.
-// why: docs/specification.md#the-page-shell
+// why: docs/components.md#the-page-shell
 const toSearch = (v) => {
   const given = typeof v === 'string' ? { palette: v } : (isRecord(v) && !Array.isArray(v) ? v : null);
   const palette = given && typeof given.palette === 'string' ? given.palette.trim() : '';
@@ -104,7 +104,7 @@ const toSearch = (v) => {
 // attribute, falling through to --measure. It must REMOVE the property rather than pass
 // a bad value on: a custom property accepts any token stream, so garbage is a valid
 // declaration that drops the column to `none`, the full track.
-// why: docs/specification.md#widths
+// why: docs/foundations.md#widths
 const LENGTH = /^(?:\d+|\d*\.\d+)(?:px|rem|em|ch|%|vw)$/;
 const mainMax = (v) => {
   const s = str(v).trim();
@@ -114,7 +114,7 @@ const mainMax = (v) => {
 // ---- the fold, and where the reader's choice is kept ---------------------
 //
 // A cookie rather than localStorage, because a server can read one and paint the
-// rail at the width the reader left it. why: docs/specification.md#the-page-shell
+// rail at the width the reader left it. why: docs/components.md#the-page-shell
 export const RAIL_COOKIE = 'apliteni-ui-rail';
 const RAIL_MAX_AGE = 60 * 60 * 24 * 365;
 const RAIL_VALUE = new RegExp(`(?:^|;\\s*)${RAIL_COOKIE}=(collapsed|expanded)(?:;|$)`);
@@ -142,7 +142,7 @@ const railName = (collapsed) => (collapsed ? 'Expand sidebar' : 'Collapse sideba
 // hand. The seam does not move: it IS the rail, and the compartment it cuts off
 // stays on the side the rail is on. Only the nodes are written here — a child a
 // stylesheet can reach — and they are spliced into icon()'s own wrapper rather
-// than a copy of it. why: docs/specification.md#the-page-shell
+// than a copy of it. why: docs/components.md#the-page-shell
 const MARK = '<rect x="3" y="3" width="18" height="18" rx="2"/>'
   + '<path class="ui-app__fold-seam" d="M9 3v18"/>'
   + '<path class="ui-app__fold-arrow" d="m16 15-3-3 3-3"/>';
@@ -151,7 +151,7 @@ const railMark = () => icon('').replace('></svg>', `>${MARK}</svg>`);
 // The rail's own skin, outside the <nav>: folding the rail is not a place to go.
 // It stands at the far end of the head band's brand row, and its name is written
 // out rather than put in a tooltip, because the name IS the chip layout.css lands
-// beside the glyph — at both widths. why: docs/specification.md#the-page-shell
+// beside the glyph — at both widths. why: docs/components.md#the-page-shell
 const railToggle = (collapsed) =>
   `<div class="ui-app__fold-row">`
   + `<button type="button" class="ui-nav__item ui-app__fold" data-rail-toggle`
@@ -165,7 +165,7 @@ const SHAPES = {
   nav: toItems, crumbs: toCrumbs, back: toBack, account: toReader, maxWidth: mainMax, topbar: toTopbar,
   layout: toLayout, width: toWidth, search: toSearch,
   // Drawn by default; `collapsible: false` is the way out, for a page that will
-  // never call wireShell(). why: docs/specification.md#the-page-shell
+  // never call wireShell(). why: docs/components.md#the-page-shell
   collapsible: (v) => v !== false,
   // A boolean is the caller's answer. Anything else leaves it to the reader.
   collapsed: (v) => (typeof v === 'boolean' ? v : null),
@@ -186,7 +186,7 @@ function settle(options) {
 // The face of the reader block: the initials, and the two lines beside them that
 // the fold takes away. `named` is the accessible name when nothing else carries
 // one; under the menu trigger it is null, because the button is named by the words
-// inside it. why: docs/specification.md#the-page-shell
+// inside it. why: docs/components.md#the-page-shell
 const readerFace = (name, email, named, markOnly = false) =>
   `<span class="ui-app__av"${named ? ` role="img" aria-label="Signed in as ${esc(named)}"` : ' aria-hidden="true"'}>`
   + `${esc(initials(name, email))}</span>`
@@ -235,7 +235,7 @@ function readerBlock({ name, email }, signOutHref, { band = false } = {}) {
 
 // A field to look at, a button to press. `data-cmdk-open` and the cap's class are the
 // palette's own, and the cap is NOT aria-hidden: it is half the button's name.
-// why: docs/specification.md#the-page-shell
+// why: docs/components.md#the-page-shell
 const searchField = ({ palette, placeholder }) =>
   `<button type="button" class="ui-app__search" data-cmdk-open="${esc(palette)}" aria-haspopup="dialog">`
   + `<span class="ui-app__search-ic" aria-hidden="true">${icon('search')}</span>`
@@ -244,7 +244,7 @@ const searchField = ({ palette, placeholder }) =>
   + `</button>`;
 
 // The band: search at its start, the reader at its end, beside the rail rather than
-// across the top of both. why: docs/specification.md#the-page-shell
+// across the top of both. why: docs/components.md#the-page-shell
 const shellBar = (search, account, signOutHref) =>
   `<header class="ui-app__bar">`
   + (search ? searchField(search) : '')
@@ -292,13 +292,13 @@ export function appShell(options = {}) {
     ariaLabel: navLabel,
   });
   // One band over a page, never two: the banded layout draws its own, so the
-  // compatibility bag is not drawn beside it. why: docs/specification.md#the-page-shell
+  // compatibility bag is not drawn beside it. why: docs/components.md#the-page-shell
   const compat = banded ? null : topbar;
   // The topbar already says the product word, so the rail head steps aside when there is
   // one. The word is the link's only text and the narrow rail folds it out of view, so
   // the name is written out — the mark itself is aria-hidden. The banded layout's own
   // bar says no word, so there the rail keeps the lockup: that layout's head band IS
-  // the product's mark. why: docs/specification.md#the-page-shell
+  // the product's mark. why: docs/components.md#the-page-shell
   const brand = compat ? '' : `<a class="ui-app__brand" href="${esc(safeUrl(brandHref))}" aria-label="${esc(word)}">`
     + `${prism(`appb-${++_shellUid}`, 24)}<span>${esc(word)}</span></a>`;
   // A <div>, not an <aside>: <aside> is the `complementary` landmark, and this holds the
@@ -319,7 +319,7 @@ export function appShell(options = {}) {
     ? `<div class="ui-app__head">${brand}${inHead}</div>`
     : '';
   // The rail's foot: the reader, or the control that took their place. One block
-  // either way. why: docs/specification.md#the-page-shell
+  // either way. why: docs/components.md#the-page-shell
   const foot = banded
     ? (fold ? `<div class="ui-app__foot">${fold}</div>` : '')
     : readerBlock(account, signOutHref);
@@ -357,7 +357,7 @@ const _unpersisted = new WeakSet();
 // path is written once — the listener, the reflector and wireShell() all have to mean
 // the same control. A descendant and not a child, because the two layouts stand the
 // row in two places: the head band, or the rail's foot.
-// why: docs/specification.md#the-page-shell
+// why: docs/components.md#the-page-shell
 const FOLD_PATH = '.ui-app__fold-row > [data-rail-toggle]';
 const RAIL_FOLD = `.ui-app__rail ${FOLD_PATH}`;
 
@@ -413,7 +413,7 @@ export function wireShell(root = document, { persist } = {}) {
   // other. Idempotent, and a shell with no account draws none to find.
   wireDropdown(root);
   // A server cannot know which key the reader holds, so the browser corrects it here —
-  // off the ROOT's window, not the global one. why: docs/specification.md#the-page-shell
+  // off the ROOT's window, not the global one. why: docs/components.md#the-page-shell
   const here = root.nodeType === 9 ? root : root.ownerDocument;
   const view = here && here.defaultView;
   const key = paletteHotkey(view && view.navigator ? view.navigator.platform : '');

package/src/components/stat.js

@@ -1,5 +1,5 @@
 // Stat band — a row of key figures, as an HTML string.
-// why: docs/specification.md#stat-bands
+// why: docs/components.md#stat-bands
 //
 // A band is a <dl>: each figure is a <div> holding its label as a <dt> and its
 // value, change and trend as <dd>s, which is the grouping HTML allows inside a
@@ -24,7 +24,7 @@ const GLYPH = { up: 'arrowUp', down: 'arrowDown', flat: 'minus' };
 const hasChange = (delta) => delta && delta.value != null && delta.value !== '';
 
 // One row and one line: the caption, the change, then what it is measured
-// against. Nothing to compare draws no row. why: docs/specification.md#stat-bands
+// against. Nothing to compare draws no row. why: docs/components.md#stat-bands
 const contextRow = (caption, delta, basisId) => {
   if (!hasChange(delta)) return caption ? `<dd class="ui-stat__caption">${esc(caption)}</dd>` : '';
   // The space is read where the CSS gap is only drawn: "of income+1.2 pts" else.
@@ -58,7 +58,7 @@ const figure = ({ label = '', value = '', caption = '', delta, trend = '' }, til
 // `basis` is the band's caption: what every change is measured against, said
 // once before the list the way a table's <caption> is, in every layout — under
 // a row of tiles it would read as a note on the last card.
-// why: docs/specification.md#stat-bands
+// why: docs/components.md#stat-bands
 export function statBand({ stats = [], variant = 'tiles', basis = '', label, id } = {}) {
   const v = STAT_VARIANTS.includes(variant) ? variant : 'tiles';
   const base = id ? esc(id) : `ui-stats-${++seq}`;

package/src/components/success.js

@@ -10,7 +10,7 @@ import { esc, button } from './index.js';
 
 // 'line' is the bare Lucide `check`, 'circled' is Lucide circle-check-big. Which
 // is the default, and why that departs from Guidelines / Iconography:
-// why: docs/specification.md#success-confirmations
+// why: docs/components.md#success-confirmations
 // Each is written whole because the icon-sizing and glyph-stroke gates find their
 // subjects by scanning source for a class on an `<svg …>`: a tag split across
 // string pieces leaves both silent rather than failing.
@@ -66,7 +66,7 @@ function countdownEl({ seconds = 5, label = 'Redirecting' } = {}) {
 // Both carry one title and at most one short line under it. There is no eyebrow
 // tier: a confirmation stacking a label, a headline and a paragraph reads as
 // three competing voices for one outcome.
-// why: docs/specification.md#success-confirmations
+// why: docs/components.md#success-confirmations
 export function success({
   layout = 'hero',          // 'hero' | 'split' | 'compact'
   level,                    // heading level of the title; see the note below
@@ -88,7 +88,7 @@ export function success({
   // takes h2. It was an h3 either way, which left a page whose whole content is
   // a success() with no h1 at all — the fault Guidelines / The page names.
   // A caller who knows better passes `level`. The look is the class's.
-  // why: docs/specification.md#the-page
+  // why: guidelines/the-page.md#the-page
   const rank = [1, 2, 3, 4, 5, 6].includes(Number(level)) ? Number(level) : (layout === 'compact' ? 2 : 1);
   const h = `h${rank}`;
 

package/src/components/tooltip.js

@@ -11,7 +11,7 @@
 // A mark carries `data-tip-value`, with `data-tip-label` and `data-tip-detail`;
 // a `[data-tip-anchor]` inside it is where the readout opens. Under a finger
 // there is no hover, so a tap is the switch: see Pointer kinds below.
-// why: docs/specification.md#the-hover-readout
+// why: docs/components.md#the-hover-readout
 import { esc } from './index.js';
 
 const cx = (...a) => a.filter(Boolean).join(' ');

package/src/components/topbar.js

@@ -30,7 +30,7 @@ export function deckTextSwitch(active = 'deck') {
 // bespoke .vsw/.vopt classes for a pixel-identical look, but emits the generic
 // [data-dropdown] hooks so there's ONE open/close/keyboard implementation.
 // `badge` is a tone key and the kit writes the word for it; the stylesheet used
-// to uppercase the key itself. why: docs/specification.md#labels-and-titles
+// to uppercase the key itself. why: docs/foundations.md#labels-and-titles
 const VBADGE = { live: 'Live', archive: 'Archive' };
 export function versionSwitcher(versions = [], activeIdx = 0) {
   const cur = versions[activeIdx]?.label || '';

package/src/html.js

@@ -5,7 +5,7 @@ export const esc = value => String(value == null ? '' : value).replace(/[&<>"]/g
 // Legacy topbar/brand slots accept already escaped HTML. Preserve their entities.
 export const trustedAttr = value => String(value ?? '').replace(/[<>"]/g, c => ENTITIES[c]);
 
-// why: docs/specification.md#vanilla-html-boundaries
+// why: docs/components.md#escaping-and-url-slots
 export function safeUrl(value, fallback = '#') {
   const raw = String(value ?? '');
   const scheme = raw.replace(/[\t\n\r]/g, '').replace(/^[\u0000-\u0020]+/, '');

package/src/index.css

@@ -9,7 +9,7 @@
  * (--font-sans, everything else). Weights 300-700 in both. Neither is
  * bundled; a family that never loads falls back to the system stack behind
  * it, in silence.
- * why: docs/specification.md#typefaces
+ * why: docs/foundations.md#typefaces
  * ========================================================================== */
 @import "./tokens/brand.generated.css";
 @import "./tokens/tokens.css";

package/src/index.d.ts

@@ -41,7 +41,7 @@ export declare const DD_MENU_FLOOR: number;
  *  the width it reached for, and whether it is anchored at its inline end.
  *  `null` unless the dropdown is inside a `.ui-filter-bar__chip`: the slide is a
  *  chip's offset along its row, so a panel anchored to the row itself is not this
- *  function's subject and sizes itself. why: docs/library.md */
+ *  function's subject and sizes itself. why: docs/components.md */
 export declare function filterPanelFit(
   dd: Element | null | undefined,
   floor?: number,

package/src/logic/accents.js

@@ -5,7 +5,7 @@
 // react/src/AccentPicker.tsx call accentSwatchStyle(); site/chrome.mjs and
 // site/index.html still hand-keep the same four gradients. Held by
 // stories/accent-swatch.test.js, which derives both sides out of src/tokens/.
-// why: docs/specification.md#react-accent-picker. See issues #190 and #429.
+// why: docs/components.md#page-furniture. See issues #190 and #429.
 export const ACCENTS = ['default', 'phoenix', 'ocean', 'emerald'];
 
 // Per accent, the gradient's two stops — each the value src/tokens/ declares for

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 {