@apliteni/apliteni-ui 0.92.0 → 0.94.0

package/README.md

@@ -61,7 +61,7 @@ import { DataTable, Modal } from '@apliteni/apliteni-ui/react';
 
 The `appShell()` factory provides the complete product layout: the sticky rail, the page body
 and a topbar over it when you ask for one, so no product rebuilds it. The
-[component catalog](docs/library.md#component-catalog) lists this factory and every other one.
+[component catalog](docs/components.md#component-catalog) lists this factory and every other one.
 Account and personal settings belong in a modal over the product rather than on a page of
 their own — see [Guidelines / Account and settings](guidelines/account-and-settings.md).
 
@@ -100,7 +100,7 @@ only `data-accent` is present, the kit uses that accent with the dark theme. An
 `data-theme` does *not* mean “follow the system”: the kit has no `prefers-color-scheme`
 rule. If the host wants to follow the operating system preference, its JavaScript must
 choose the theme and add the attribute. See
-[an absent attribute means dark](docs/library.md#an-absent-attribute-means-dark).
+[an absent attribute means dark](docs/components.md#an-absent-attribute-means-dark).
 
 You can change the settings at runtime with `applyTheme('light')` and
 `applyAccent('phoenix')`. These functions save the choices to `localStorage`. You can also
@@ -121,12 +121,10 @@ section.
 
 | Page | What it answers |
 | --- | --- |
-| [specification.md](docs/specification.md) | What the kit guarantees and what it refuses to do. A gate on `npm test` holds every statement. |
-| [library.md](docs/library.md) | Architecture, the `src/` layout, tokens and theming, the component catalog. |
+| [foundations.md](docs/foundations.md) | The tokens and the floors: widths, breakpoints, spacing, type, colour, elevation, the focus ring, the tap floor. |
+| [components.md](docs/components.md) | The package: what to import, theming, the component catalog, and what each component guarantees. |
 | [react/README.md](react/README.md) | The React components, their props, and the Storybook on port 6007. |
-| [storybook.md](docs/storybook.md) | The workbench: config, theming toolbar, story conventions. |
-| [landing-page.md](docs/landing-page.md) | ui.apli.tech: the chrome, the static build, the hosting. |
-| [changelog.md](docs/changelog.md) | The changelog's data model and its Storybook deeplinks. |
+| [contributing.md](docs/contributing.md) | Working on the kit: the repository's layout, Storybook, the guidelines collection, the site, the changelog and releases. |
 
 ## Contribute
 

package/guidelines/colour-and-theming.md

@@ -66,3 +66,5 @@
 **Do:** Draw inputs with an edge. Keep grey fills for non-text states, such as disabled tracks and dividers.
 
 **Don't:** Put text on grey fields, chips, headers or footers.
+
+**Except:** The sidebar rail's current row. Its mark may be neither an accent nor an edge — an outline there means focus — and in the page shell the rail is the card surface already. It takes the quiet fill a rung off its rail, label and all. Artur, r34 of [#475](https://github.com/apliteni/apliteni-ui/issues/475).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.92.0",
+  "version": "0.94.0",
   "workspaces": [
     "react"
   ],

package/react/README.md

@@ -246,7 +246,7 @@ this component and compares what is left.
 Two things the factory has that this does not, both deliberate. It emits no `data-dropdown`
 on the container, so a page that calls `wireDropdown(document)` cannot adopt a dropdown React
 owns — the same decision `Drawer` makes about `data-drawer`; the row and panel hooks stay,
-because they are the row contract `docs/library.md` publishes. And it has no `portal: true`: the
+because they are the row contract `docs/components.md` publishes. And it has no `portal: true`: the
 panel is a child of the trigger's container, so a dropdown inside `.ui-app__rail`
 (`position: sticky` with `overflow-y: auto`) still wants the vanilla factory.
 
@@ -541,7 +541,7 @@ An optional `id` lets the caller choose the control ID; it must be unique.
 `type="search"` input, and no visible label, so the row keeps the height of the
 unlabelled controls beside it. `ariaLabel` is required and is the control's only
 name. It forwards its ref and the native input props, and `className` joins
-`.ui-input`. There is no clear button — see the specification for why.
+`.ui-input`. There is no clear button — see docs/components.md#react-search-field for why.
 
 ```tsx
 <div className="ui-toolbar">

package/react/dist/index.d.ts

@@ -730,7 +730,7 @@ type SearchFieldProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'ar
  * No clear button. The browser paints its own near-black on the light field and
  * white on the dark one, beside the kit's `--muted` magnifier — two glyphs, and
  * only one answers to a token — so `input.css` suppresses it.
- * why: docs/specification.md#react-search-field
+ * why: docs/components.md#react-search-field
  */
 declare const SearchField: react.ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "aria-label"> & {
     /** The control's name. A toolbar search box shows no label, so this is the
@@ -850,7 +850,7 @@ type SuccessProps = Omit<HTMLAttributes<HTMLDivElement>, 'title' | 'children'> &
     check?: SuccessMark;
     title?: string;
     /** One short line under the title, or nothing. There is no eyebrow tier.
-     *  why: docs/specification.md#success-confirmations */
+     *  why: docs/components.md#success-confirmations */
     body?: string;
     /** Removed: a confirmation carries one title and at most one line. Typed as
      *  `never` so a caller still passing it is told where it went rather than
@@ -869,7 +869,7 @@ declare const Success: react.ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLD
     check?: SuccessMark;
     title?: string;
     /** One short line under the title, or nothing. There is no eyebrow tier.
-     *  why: docs/specification.md#success-confirmations */
+     *  why: docs/components.md#success-confirmations */
     body?: string;
     /** Removed: a confirmation carries one title and at most one line. Typed as
      *  `never` so a caller still passing it is told where it went rather than

package/src/assets/icons.js

@@ -166,7 +166,7 @@ export const iconNames = Object.keys(ICONS);
 // `filter` — Lucide's funnel — fails the first test. Depicting a thing is not the
 // fault; `copy` is on this list and depicts one too. The kit reads the funnel alone
 // as not saying whether the control filters, sorts or exports — its own inference
-// from the sources in docs/specification.md, not a measured recognition finding.
+// from the sources in docs/foundations.md, not a measured recognition finding.
 // See #565.
 export const iconOnlyAllowed = {
   x: 'close or dismiss',

package/src/components/account-nav.js

@@ -2,8 +2,8 @@
 // that interpolates raw. It lives here rather than in shell.js because both
 // shell.js and topbar.js need it and shell.js already imports topbar.js — the
 // other direction would be a cycle. shell.js re-exports ACCOUNT_NAV, which is
-// the published name docs/library.md documents.
-// why: docs/specification.md#the-page-shell
+// the published name docs/components.md documents.
+// why: docs/components.md#the-page-shell
 import { esc } from './index.js';
 
 // nav.js item objects. Labels are raw text — every nav primitive escapes, so a

package/src/components/back.js

@@ -11,7 +11,7 @@
 // docs/reviews/270-back-control.html and the owner chose this one, so the other
 // three — a bordered button above the title, an icon-only arrow beside it, and
 // the breadcrumb trail alone — are not built here.
-// why: docs/specification.md#the-back-link
+// why: docs/components.md#the-back-link
 import { esc, icon } from './index.js';
 
 // "Back" names a direction rather than a place. It is what a caller who names no
@@ -29,7 +29,7 @@ const TAB_OR_NEWLINE = /[\t\n\r]/g;
 
 // A label that already says "Back to Invoices" names the place after those words, or the
 // link would be read as "Back to Back to Invoices". The whole phrase, since "Backups" and
-// "Back office" are places too. why: docs/specification.md#the-back-link
+// "Back office" are places too. why: docs/components.md#the-back-link
 const SAID = /^back\s+to(?:\s+|$)/i;
 
 const text = (v) => (typeof v === 'string' || typeof v === 'number' ? String(v).trim() : '');

package/src/components/command-palette.js

@@ -9,7 +9,7 @@ export { SCORE, scoreCommand, rankCommands, rankGroups, paletteHotkey } from '..
 // The kit ships the shell and the ranking and names no result kinds; a row goes
 // somewhere, runs something, or asks a confirm first. Inertness, Escape and the
 // focus trap come from ./overlay.js, the stack the drawer and the confirm share.
-// why: docs/specification.md#the-command-palette
+// why: docs/components.md#the-command-palette
 import { esc, icon } from './index.js';
 import { OVERLAY_LAYER, adoptOverlay, popOverlay, pushOverlay, returnFocus, syncOverlays } from './overlay.js';
 import { safeUrl } from '../html.js';
@@ -61,7 +61,7 @@ function keysFor(shortcut) {
  * the wiring, which is also what makes Cmd+Enter open it in a tab.
  *
  * A destructive item that names no confirm is rendered DISABLED. The kit's rule
- * is that a delete asks first (docs/specification.md#the-command-palette), and a
+ * is that a delete asks first (docs/components.md#the-command-palette), and a
  * palette is the one surface where a reader is typing fast and choosing from a
  * list that reorders under them.
  */

package/src/components/drawer.js

@@ -75,7 +75,7 @@ export function drawer({
  *
  *   drawer({ title, body: drawerSection({ title: 'Source', rows: [['Statement', '#4102']] }) })
  *
- * why: docs/specification.md#the-drawer
+ * why: docs/components.md#the-drawer
  *
  * @param {object} [o]
  * @param {string} [o.title]  group heading (escaped)

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