@apliteni/apliteni-ui 0.23.1 → 0.23.2

package/package.json

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

package/src/components/confirm.js

@@ -3,18 +3,13 @@
 //   container.innerHTML = confirm({ title, body, confirmLabel, cancelLabel });
 //   wireConfirm(container);   // scrim/Esc/answers + focus trap
 //
-// A page trigger opens it by id:  <button data-confirm-open="ID">…</button>
-// (or call openConfirm(rootEl) directly). Pass `open: true` to render it already
-// open, or `specimen: true` for a picture of one on a documentation page.
+// A page trigger opens it by id: <button data-confirm-open="ID">. Answering is
+// the caller's job — a listener on [data-confirm-accept] is where the
+// destructive work goes — and focus opens on the SAFE answer, so a reader who
+// hits Enter out of habit keeps what they have.
 //
-// Answering is the caller's job: both answers close the dialog, and a listener
-// on [data-confirm-accept] is where the destructive work goes. Focus opens on
-// the SAFE answer, never the destructive one, so a reader who hits Enter out of
-// habit keeps what they have.
-//
-// Inertness, Escape and the focus trap come from ./overlay.js — one stack for
-// every overlay on the page, so a confirm over a drawer never has to guess which
-// of the two the keyboard belongs to.
+// Inertness, Escape and the focus trap come from ./overlay.js: one stack for
+// every overlay on the page.
 import { button, esc } from './index.js';
 import { OVERLAY_LAYER, adoptOverlay, focusablesIn, popOverlay, pushOverlay, returnFocus, syncOverlays } from './overlay.js';
 
@@ -24,23 +19,27 @@ const cx = (...a) => a.filter(Boolean).join(' ');
 let _uid = 0;
 const nextId = (p = 'confirm') => `${p}-${++_uid}`;
 
-// The public factory. Returns an HTML string; wire it with wireConfirm().
-//   title         the question — also the dialog's accessible name
-//   body          the consequence — the dialog's accessible description
-//   confirmLabel  the destructive answer (default 'Confirm')
-//   cancelLabel   the safe answer (default 'Cancel')
-//   variant       'danger' (default) | 'primary' — which button the answer is
-//   open          render already-open, as a real dialog: wireConfirm() adopts it
-//                 onto the overlay stack, so the page behind it goes inert, Tab
-//                 is trapped in the panel and Escape closes it
-//   specimen      render open as a *picture* of the dialog: same markup, minus
-//                 the data-confirm hook and aria-modal, so no wiring and no key
-//                 handler can reach it. A documentation page shows several at
-//                 once and none of them owns the page or answers Escape — an
-//                 answered specimen would erase itself with nothing to bring it
-//                 back, and three modal dialogs on one page trap the reader in
-//                 the first. `open` is the one to use when the dialog is real.
-//   id            root id — a [data-confirm-open="id"] trigger targets it
+/**
+ * The public factory. Returns an HTML string; wire it with wireConfirm().
+ *
+ * `specimen` renders open as a *picture* of the dialog — same markup, minus the
+ * data-confirm hook and aria-modal, so no wiring and no key handler can reach
+ * it. A documentation page shows several at once and none of them may own the
+ * page or answer Escape: an answered specimen would erase itself with nothing to
+ * bring it back, and three modal dialogs on one page trap the reader in the
+ * first. Use `open` when the dialog is real.
+ *
+ * @param {object} [o]
+ * @param {string} [o.title]         the question — also the accessible name
+ * @param {string} [o.body]          the consequence — the accessible description
+ * @param {string} [o.confirmLabel]  the destructive answer (default 'Confirm')
+ * @param {string} [o.cancelLabel]   the safe answer (default 'Cancel')
+ * @param {string} [o.variant]       'danger' (default) | 'primary'
+ * @param {boolean} [o.open]         render already-open, as a real dialog
+ * @param {boolean} [o.specimen]     render open as a picture of the dialog
+ * @param {string} [o.id]            root id a [data-confirm-open] trigger targets
+ * @returns {string} html
+ */
 export function confirm({
   title = 'Are you sure?', body = '', confirmLabel = 'Confirm', cancelLabel = 'Cancel',
   variant = 'danger', id, open = false, specimen = false,

package/src/components/drawer.js

@@ -1,19 +1,15 @@
-// Drawer — the kit's edge-anchored overlay panel (a.k.a. Sheet / Slide-over): a
-// panel that slides in from any screen edge over a scrim. Header (title + close)
-// / scrollable body / footer actions. Sizes sm|md|lg — full-height for
-// left|right, full-width for top|bottom.
+// Drawer — the kit's edge-anchored overlay panel: a panel that slides in from
+// any screen edge over a scrim. Header / scrollable body / footer actions, sizes
+// sm|md|lg along the slide axis.
 //
 //   container.innerHTML = drawer({ side: 'right', title: 'Filters', body });
 //   wireDrawer(container);   // scrim/Esc/close-button + focus trap
 //
-// A page trigger opens it by id:  <button data-drawer-open="ID">…</button>
-// (or call openDrawer(rootEl) directly). Pass `open: true` to render it already
-// open, or `specimen: true` for a picture of one on a documentation page.
-//
-// Inertness, Escape and the focus trap are shared with confirm(): both are
+// A page trigger opens it by id: <button data-drawer-open="ID">. Inertness,
+// Escape and the focus trap are shared with confirm(): both are
 // "content over a scrim, focus-trapped, Esc-dismissable", and they push onto one
-// stack in ./overlay.js so the two can never disagree about which of them the
-// keyboard currently belongs to.
+// stack in ./overlay.js, so the two can never disagree about which of them the
+// keyboard belongs to.
 import { esc, icon } from './index.js';
 import { OVERLAY_LAYER, adoptOverlay, focusablesIn, popOverlay, pushOverlay, returnFocus, syncOverlays } from './overlay.js';
 
@@ -23,23 +19,26 @@ const cx = (...a) => a.filter(Boolean).join(' ');
 let _uid = 0;
 const nextId = (p = 'drawer') => `${p}-${++_uid}`;
 
-// The public factory. Returns an HTML string; wire it with wireDrawer().
-//   side        'right' (default) | 'left' | 'top' | 'bottom' — the edge it hugs
-//   size        'sm' | 'md' (default) | 'lg' — panel extent along the slide axis
-//   title       header heading (also the dialog's accessible name)
-//   body        scrollable body HTML (trusted markup)
-//   footer      pinned footer actions HTML (trusted markup)
-//   open        render already-open, as a real panel: wireDrawer() adopts it onto
-//               the overlay stack, so the page behind it goes inert, Tab is
-//               trapped in the panel and Escape closes it
-//   specimen    render open as a *picture* of the panel: same markup, minus the
-//               data-drawer hook and aria-modal, so no wiring and no key handler
-//               can reach it. See confirm() for why a documentation page wants
-//               that; `open` is the one to use when the drawer is real.
-//   id          root id — a [data-drawer-open="id"] trigger targets it
-//   ariaLabel   accessible name when there's no visible title
-//   dismissible show the close button + allow scrim/Esc dismiss (default true)
-//   closeLabel  accessible name for the close button (default 'Close')
+/**
+ * The public factory. Returns an HTML string; wire it with wireDrawer().
+ *
+ * `specimen` renders open as a *picture* of the panel — see confirm() for why a
+ * documentation page wants that. Use `open` when the drawer is real.
+ *
+ * @param {object} [o]
+ * @param {string} [o.side]        'right' (default) | 'left' | 'top' | 'bottom'
+ * @param {string} [o.size]        'sm' | 'md' (default) | 'lg', along the slide axis
+ * @param {string} [o.title]       header heading, also the accessible name
+ * @param {string} [o.body]        scrollable body HTML (trusted markup)
+ * @param {string} [o.footer]      pinned footer actions HTML (trusted markup)
+ * @param {boolean} [o.open]       render already-open, as a real panel
+ * @param {boolean} [o.specimen]   render open as a picture of the panel
+ * @param {string} [o.id]          root id a [data-drawer-open] trigger targets
+ * @param {string} [o.ariaLabel]   accessible name when there is no visible title
+ * @param {boolean} [o.dismissible] close button + scrim/Esc dismiss (default true)
+ * @param {string} [o.closeLabel]  accessible name for the close button
+ * @returns {string} html
+ */
 export function drawer({
   side = 'right', size = 'md', title, body = '', footer = '',
   open = false, specimen = false, id, ariaLabel, dismissible = true, closeLabel = 'Close',

package/src/components/dropdown.js

@@ -1,20 +1,17 @@
-// Dropdown — the kit's one popover-list primitive. A trigger (label + optional
-// value + rotating chevron) opens a panel of item rows (label, optional
-// description, optional leading icon, optional trailing badge, selected +
-// disabled state). Two flavours share the same panel + the same open/close JS:
+// Dropdown — the kit's one popover-list primitive. A trigger opens a panel of
+// item rows; two flavours share the same panel and the same open/close JS:
 //
 //   variant: 'select'  → role="listbox" / role="option", value shown in trigger
 //   variant: 'menu'    → role="menu"    / role="menuitem", action list
 //
-// "dropdown" (not "menu" or "select") is deliberate: `menu` implies actions
-// only and `select` implies a form control bound to a value — this factory is
-// the umbrella both of those are specialisations of, and it's the word the
-// issue and the topbar already use. The topbar's version switcher and account
-// menu are thin consumers of the SAME wiring (wireDropdown) so there is exactly
-// one open/close/click-outside/Esc/keyboard implementation in the kit.
+// The name is deliberate: `menu` implies actions only and `select` implies a
+// form control bound to a value, and this factory is the umbrella both are
+// specialisations of. The topbar's version switcher and account menu are thin
+// consumers of the SAME wiring, so there is one open/close/Esc/keyboard
+// implementation in the kit.
 //
 //   container.innerHTML = dropdown({ label: 'version:', value: '…', items });
-//   wireDropdown(container);   // or let wireTopbar() do it (it calls this)
+//   wireDropdown(container);   // or let wireTopbar() do it
 import { esc, icon } from './index.js';
 
 const cx = (...a) => a.filter(Boolean).join(' ');
@@ -66,18 +63,24 @@ function ddBody({ items, sections }, listbox) {
   return (items || []).map((it) => ddItem(it, listbox)).join('');
 }
 
-// The public factory. Returns an HTML string; wire it with wireDropdown().
-//   label       muted prefix in the trigger (e.g. "version:")
-//   value       current value shown in the trigger (single-select)
-//   placeholder shown when there's no value
-//   variant     'select' (listbox) | 'menu' (default inferred from items)
-//   items       [{ label, value?, description?, icon?, badge?, selected?, disabled?, href?, danger? }]
-//   sections    [{ label, items }] — grouped alternative to items
-//   header/footer  raw HTML blocks pinned top/bottom of the panel
-//   align       'start' (default) | 'end'  — which edge the panel hugs
-//   scroll      true | maxHeight px — cap panel height and scroll
-//   open        render already-open (handy for screenshots)
-//   ariaLabel   accessible name for the panel (and trigger, if no visible text)
+/**
+ * The public factory. Returns an HTML string; wire it with wireDropdown().
+ *
+ * @param {object} [o]
+ * @param {string} [o.label]       muted prefix in the trigger (e.g. "version:")
+ * @param {string} [o.value]       current value shown in the trigger
+ * @param {string} [o.placeholder] shown when there is no value
+ * @param {string} [o.variant]     'select' (listbox) | 'menu' (inferred from items)
+ * @param {Array}  [o.items]       [{ label, value?, description?, icon?, badge?, selected?, disabled?, href?, danger? }]
+ * @param {Array}  [o.sections]    [{ label, items }] — grouped alternative to items
+ * @param {string} [o.header]      raw HTML pinned to the top of the panel
+ * @param {string} [o.footer]      raw HTML pinned to the bottom of the panel
+ * @param {string} [o.align]       'start' (default) | 'end' — the edge the panel hugs
+ * @param {boolean|number} [o.scroll] true, or a maxHeight in px, to cap and scroll
+ * @param {boolean} [o.open]       render already-open (handy for screenshots)
+ * @param {string} [o.ariaLabel]   accessible name for the panel and trigger
+ * @returns {string} html
+ */
 export function dropdown({
   label, value, placeholder = 'Select…', variant, items, sections,
   header = '', footer = '', triggerContent, triggerClass = '', chevron = true,

package/src/components/index.js

@@ -66,21 +66,17 @@ export function card({ title, sub, body = '', variant, pad, icon: ic } = {}) {
 }
 
 // ---- Segmented control ---------------------------------------------------
-// A strip of mutually exclusive toggle buttons — a filter, a unit switch, a
-// language picker. It is NOT a tablist: it controls no panel, so it must not
-// announce one. `role="toolbar"` with a roving tabindex is the honest shape —
-// one Tab stop for the whole strip, ArrowLeft/ArrowRight to move between the
-// options, Home/End to jump to the ends, and `aria-pressed` to say which is on.
-// wireTopbar() ships that keyboard behaviour (see topbar.js); the markup here
-// carries the state it reads.
+// A strip of mutually exclusive toggle buttons.
+// It is NOT a tablist: it controls no panel, so it must not announce one.
+// `role="toolbar"` with a roving tabindex is the honest shape, and wireTopbar()
+// ships the keyboard behaviour.
 //
-// When the pill drives a real change of view with content behind it, reach for
-// tabs() instead — that one owns panels and earns the tab announcement.
+// When the pill drives a real change of view, reach for tabs() instead —
+// that one owns panels and earns the tab announcement.
 //
-// `ariaLabel` names the strip. `name` seeds data-seg (a hook for callers) and
-// is deliberately not an accessible name — it is an identifier, not prose.
-// Defaults to "Options" so a strip is never left unlabelled, the same way
-// switchToggle() defaults its label.
+// `ariaLabel` names the strip. `name` seeds data-seg and is deliberately
+// not an accessible name — it is an identifier, not prose, defaulting to
+// "Options" so a strip is never left unlabelled.
 export function segmented({ options = [], active = 0, size, block, name = 'seg', ariaLabel = 'Options' } = {}) {
   const cls = cx('ui-seg', size && `ui-seg--${size}`, block && 'ui-seg--block');
   // Exactly one option holds the Tab stop. If `active` points nowhere (nothing

package/src/components/nav.js

@@ -1,24 +1,11 @@
-// Navigation — the kit's primary wayfinding primitives. One umbrella factory,
-// `nav({ variant })`, dispatches to three shapes that share tokens + classes but
-// almost no markup, so each is also exported directly for ergonomic use:
+// Navigation — the kit's primary wayfinding primitives. `nav({ variant })`
+// dispatches to sidebarNav(), navTabs() and breadcrumbs(), each also exported
+// directly: the three share tokens and classes but almost no markup, so a single
+// options bag would mean wildly different fields per variant.
 //
-//   variant: 'sidebar'      → sidebarNav()   vertical rail: sections, icon+label
-//                             items, active state, collapsible groups, an
-//                             icon-only collapsed mode, optional per-item badge.
-//   variant: 'tabs'         → navTabs()      horizontal page tabs with an active
-//                             underline (default) or pill.
-//   variant: 'breadcrumbs'  → breadcrumbs()  the `Finance / Payouts` trail.
-//
-// Why an umbrella AND named exports (unlike dropdown, which is one factory): the
-// three variants don't share a body the way select/menu share a panel, so a
-// single options bag would mean wildly different fields per variant. The named
-// exports keep each call site honest; `nav()` stays the discoverable entry the
-// issue asks for and the one thing to import when the variant is data-driven.
-//
-// These are NAVIGATION controls (links between locations), not tab panels — so
-// tabs render as <nav> + <a aria-current="page">, not role="tablist" (that's
-// what segmented() is for). Only the collapsible sidebar groups need JS; wire
-// them once after mount with wireNav() (preview.js does this for Storybook).
+// These are NAVIGATION controls, not tab panels — so tabs render as
+// <nav> + <a aria-current="page">, not role="tablist" (that is what segmented()
+// is for). Only the collapsible sidebar groups need JS; wire with wireNav().
 import { esc, icon } from './index.js';
 
 const cx = (...a) => a.filter(Boolean).join(' ');

package/src/components/overlay.js

@@ -154,23 +154,14 @@ export function pushOverlay(root, panel, dismiss, layer) {
 /**
  * Take on a root that arrived already open — markup rendered with `open: true`,
  * which nobody called open…() for. Without this its aria-modal is a claim the
- * page contradicts: nothing is inert, Tab walks out, Escape has no owner.
+ * page contradicts.
  *
- * It goes in by paint order, because wiring has no history to order by and the
- * overlay the reader is looking at is the one drawn over the rest: a confirm sits
- * a layer above a drawer whichever component's wiring ran first, and whichever
- * root the markup happens to put first. Document position only separates two
- * overlays on the same layer, and there it is the right answer rather than a
- * fallback — at equal stack levels the later root paints on top (CSS 2.2 Appendix
- * E, steps 8 and 9). That comparison earns its keep whenever adoption order and
- * document order disagree: a root inserted above one already on the stack and
- * wired after it, and — in a browser only — a consumer stylesheet that lifts the
- * drawer onto the confirm's layer, where wiring runs drawer-first however the
- * markup is ordered. A browser refines the layer from the live z-index; JSDOM has
- * none to give, so the tests hold OVERLAY_LAYER to the sheets instead. A root that
- * renders closed is left alone: wiring is not an opening, and it waits for the one
- * that is. A specimen never reaches here at all — it carries no hook for the
- * wiring to find.
+ * It goes in by PAINT ORDER, because wiring has no history to order by. Document
+ * position only separates two overlays on the same layer, and there it is the
+ * right answer rather than a fallback: at equal stack levels the later root
+ * paints on top (CSS 2.2 Appendix E, steps 8 and 9).
+ *
+ * A root that renders closed is left alone — wiring is not an opening.
  */
 export function adoptOverlay(root, panel, dismiss, layer) {
   if (!root.classList.contains('is-open')) return;

package/src/components/success.js

@@ -1,22 +1,13 @@
-// Success / confirmation surface — the emotional high point of a flow, done
-// with craft. One factory, three layouts and three backdrops, an SVG check
-// that draws itself in, optional confetti and an optional auto-redirect
-// countdown. Every motion path is reduced-motion safe (static check, no burst,
-// no confetti, no sweep). Accent-aware via the kit tokens; the success mark
-// stays on the --green family. Styles ship in styles/success.css.
+// Success / confirmation surface. One factory, three layouts and three
+// backdrops, an SVG check that draws itself in, optional confetti and an
+// optional auto-redirect countdown. Every motion path is reduced-motion safe.
+// Accent-aware, but the success mark stays on the --green family.
 //
-//   container.innerHTML = success({
-//     title: 'Feedback sent',
-//     body: 'It goes straight to the strategy owner.',
-//     actions: [
-//       { label: 'Back to strategy', variant: 'primary', icon: 'compass' },
-//       { label: 'Send another', variant: 'ghost' },
-//     ],
-//   });
+//   container.innerHTML = success({ title, body, actions: [{ label, variant }] });
 //
-// The check animation is pure CSS, so string-rendered markup animates on its
-// own once mounted. A live countdown (ticking numbers + redirect) is opt-in via
-// wireSuccess(); the markup alone shows the ring sweep + a static number.
+// The check animation is pure CSS, so string-rendered markup animates on its own
+// once mounted. A live countdown is opt-in via wireSuccess(); the markup alone
+// shows the ring sweep and a static number.
 import { esc, button } from './index.js';
 
 // Self-drawing check: a faint track disc, a filled accent disc that springs in,

package/src/components/topbar.js

@@ -52,19 +52,15 @@ export function versionSwitcher(versions = [], activeIdx = 0) {
     `<div class="vsw__menu" data-dropdown-panel role="listbox" aria-label="Version">${opts}</div></div>`;
 }
 
-// `nav` ([id, icon, label, href?, target?][]) mirrors the account sidebar so the
-// dropdown and the sidebar stay in sync. The fallback is derived from the one
-// ACCOUNT_NAV definition rather than restated here: a second literal agreed
-// with it by hand about the icon and disagreed about the encoding, which is the
-// drift #127 was filed about. Every field below is interpolated raw, so what
-// arrives has to arrive escaped — accountMenuNav() is what does that.
+// `nav` mirrors the account sidebar, DERIVED from the one ACCOUNT_NAV definition
+// rather than restated: a second literal agreed with it by hand about the icon
+// and disagreed about the encoding, which is the drift #127 was filed about.
+// Every field below is interpolated raw, so what arrives has to arrive escaped.
 //
-// `initials` is the avatar, for a caller that escapes on the way in. A mark is
-// derived from the reader's name, and a derived value has to be derived before
-// the escaping: `<Ada>` and `&lt;Ada&gt;` do not begin with the same character,
-// so shell.js — which escapes both fields for this sink — computes the mark
-// from the caller's own strings and passes it down beside them. Left out, it is
-// computed here from `name` and `email`, exactly where it always came from.
+// `initials` is the avatar. A derived value has to be derived BEFORE the
+// escaping — `<Ada>` and `&lt;Ada&gt;` do not begin with the same character — so
+// shell.js computes the mark from the caller's own strings and passes it down
+// beside them. Left out, it is computed here from `name` and `email`.
 export function accountMenu({
   name = 'Ada Lovelace', email = 'ada@apliteni.com', active = 'prefs', nav, initials: mark,
 } = {}) {

package/src/styles/base.css

@@ -102,23 +102,10 @@ a {
 
 /* Sensible default size for inline icons that a parent rule doesn't size.
    A floor, not a ceiling: :where() holds the whole filter at zero specificity,
-   so this weighs (0,0,1) — one element, nothing more — and any component rule
-   that sizes an icon outranks it. Written bare, :not([width]):not([height])
-   would count both attribute selectors and weigh (0,2,1), which beats every
-   `.ui-btn svg`-shaped rule in the kit no matter what order the files load in.
-   It did, for every one of them bar three, and for `.ui-fbck` besides — that
-   one is a class on the svg itself, so it is easy to miss when you go looking.
-   The count is deliberately not written here: it moved once already. Two gates
-   keep the rules that compete with this one honest, each over the ground it
-   actually sweeps: src/styles/icon-size.test.js reads the stylesheets
-   src/index.css imports, and scripts/icon-size-surfaces.test.js reads the
-   surfaces the kit renders — the landing site's pages and the Storybook stories.
-   Neither claims more, and the second one's header lists what it declines to
-   claim; read it before trusting a green run. Two gaps are worth knowing here: a
-   reset scoped to an ancestor that a subject's own selector does not name is out
-   of reach of both, and .storybook/preview.js imports src/index.css into every
-   story iframe, which makes .storybook/ a third rendering surface neither gate
-   sweeps. Nothing in there sizes an icon today. */
+   so this weighs (0,0,1) and any component rule that sizes an icon outranks it.
+   The count of those rules is deliberately not written here — it moved once
+   already, and two gates hold it over the ground each actually sweeps.
+   why: CONTRIBUTING.md#the-reset-is-a-floor-and-its-specificity-is-the-whole-of-that */
 svg:where(:not([width]):not([height])) {
   width: 1.1em;
   height: 1.1em;

package/src/styles/callout.css

@@ -49,18 +49,10 @@
 
 /* status → the paint tokens every style below consumes.
    --toast-accent is the status as a line or a small mark, --toast-glow its wash,
-   --toast-on the glyph ink on the accent circle. --toast-solid is separate on
-   purpose: a full fill is a different job from a 22px circle, and it is chosen
-   as a PAIR with --signal-solid-ink rather than against a global. See #149.
-
-   --toast-action-ink is separate from --toast-accent for the same reason the
-   fill is: the accent is a graphic colour, sized for a 3px rule and a 22px
-   circle, and in the light theme it is not a colour text can be set in. The
-   trailing action is the one part of a toast that is BOTH the status colour and
-   a piece of text, so it takes the chip inks — the text-grade version of the
-   same five statuses, and the same value as the accent in dark by construction.
-   neutral's --toast-on is --signal-solid-ink because the neutral circle IS
-   --signal-solid-neutral: one fill, so one ink, chosen once. #206 */
+   --toast-on the glyph ink on the accent circle. --toast-solid and
+   --toast-action-ink are separate from the accent on purpose: a fill and a piece
+   of text are different jobs from a 22px circle.
+   why: docs/specification.md#colour-and-contrast */
 .ui-toast--success { --toast-accent: var(--green); --toast-action-ink: var(--chip-success-ink); --toast-glow: var(--glow-green); --toast-on: var(--signal-contrast); --toast-solid: var(--signal-solid-success); }
 .ui-toast--danger  { --toast-accent: var(--pink);  --toast-action-ink: var(--chip-danger-ink);  --toast-glow: var(--glow-pink);  --toast-on: var(--danger-contrast); --toast-solid: var(--signal-solid-danger); }
 .ui-toast--warn    { --toast-accent: var(--amber); --toast-action-ink: var(--chip-warn-ink);    --toast-glow: color-mix(in srgb, var(--amber) 14%, transparent); --toast-on: var(--signal-contrast); --toast-solid: var(--signal-solid-warn); }

package/src/styles/confirm.css

@@ -1,19 +1,16 @@
-/* ============================================================================
- * Confirm — the kit's confirmation dialog: a centred panel over a scrim, for
- * the question a destructive action has to ask. Fully token-driven so it
- * re-themes across accents + light/dark. Shares its scrim + focus-trap
- * behaviour with the drawer (see overlay.js).
+/* Confirm — the kit's confirmation dialog: a centred panel over a scrim, for the
+ * question a destructive action has to ask. Fully token-driven, and it shares
+ * its scrim and focus-trap behaviour with the drawer (see overlay.js).
  *
- * Motion is the drawer's, deliberately: --dur-med/--ease, and `visibility`
- * switched rather than transitioned. A transitioned visibility is still
+ * `visibility` is SWITCHED rather than transitioned: transitioned, it is still
  * `hidden` in the frame the class lands, so openConfirm()'s focus() would have
- * nothing to focus and the reader would be left on <body>. The root owns the
- * switch; the panel and scrim inherit it.
+ * nothing to focus. The root owns the switch; panel and scrim inherit it.
  *
- * Local tokens (surface/shadow/scrim) so the panel + scrim re-theme cleanly:
+ * Local tokens so the panel and scrim re-theme cleanly:
  *   --confirm-surface  panel background     --confirm-shadow  panel elevation
- *   --confirm-scrim    backdrop colour (--scrim already re-themes per theme)
- * ========================================================================== */
+ *   --confirm-scrim    backdrop colour
+ *
+ * why: docs/specification.md#motion */
 
 .ui-confirm {
   --confirm-surface: var(--surface-2);

package/src/styles/loading.css

@@ -1,30 +1,15 @@
-/* ============================================================================
- * Loading and permission-denied — the screen-scale states.
+/* Loading and permission-denied — the screen-scale states. Markup comes from
+ * components/loading.js; this file owns layout and nothing else.
  *
- * Markup comes from components/loading.js:
+ * The shimmer is .m-skeleton from styles/motion.css, so reduced motion is
+ * already handled by the global net and there is one shimmer in the kit.
  *
- *   <div class="ui-busy" role="status" aria-live="polite" aria-busy="true">
- *     <span class="ui-sr">Loading your report…</span>
- *     <div class="ui-busy__body">
- *       <div class="ui-skel" aria-hidden="true">
- *         <span class="ui-skel__bar m-skeleton"></span>…
+ * .ui-denied deliberately borrows every colour .ui-empty uses: to a reader the
+ * two are the same event — what you came for is not here — and giving denial its
+ * own red made it read as a fault the reader had committed. The lock says which
+ * of the two it is.
  *
- *   <div class="ui-denied">
- *     <div class="ui-denied__seal">…lock…</div>
- *     <div class="ui-denied__title">You don’t have access</div>
- *     <div class="ui-denied__sub">…</div>
- *     <div class="ui-denied__need">Needs <code class="ui-code">reports.read</code></div>
- *     <div class="ui-denied__actions">…</div>
- *
- * The shimmer is .m-skeleton from styles/motion.css — this file owns layout and
- * nothing else about the animation, so reduced motion is already handled by the
- * global block at the end of that file and there is one shimmer in the kit.
- *
- * .ui-denied deliberately borrows every colour .ui-empty uses. To a reader the
- * two are the same event — what you came for is not here — and giving denial
- * its own red made it read as a fault the reader had committed. The lock says
- * which of the two it is.
- * ========================================================================== */
+ * why: docs/specification.md#pending-and-denied-states */
 
 /* Visually hidden, still read aloud. The kit had no such utility, and the live
    region needs one: its message is for assistive tech only — the sighted

package/src/styles/motion.css

@@ -1,27 +1,19 @@
-/* ============================================================================
- * apliteni-ui — MOTION LIBRARY
- *
- * A small, token-driven, framework-agnostic motion system: reusable entrance,
- * micro-interaction, attention, and scroll-reveal effects as plain classes.
- * Every timing reads the brand motion vocabulary (--duration-* / --easing-*,
- * synced from design-system) so motion re-themes and stays consistent.
+/* apliteni-ui — motion library. Reusable entrance, micro-interaction, attention
+ * and scroll-reveal effects as plain classes, every timing reading the brand
+ * motion vocabulary.
  *
  * Per-effect overrides via custom properties on the element:
- *   --m-dur    duration        (default: per effect)
- *   --m-ease   timing function (default: per effect)
- *   --m-delay  start delay      (default: 0s)
- *   --m-dist   travel distance for slides (default: 16px)
+ *   --m-dur  duration   --m-ease  timing function
+ *   --m-delay  start delay   --m-dist  slide travel (default 16px)
+ *
+ * Scroll reveals need `initReveal()` from apliteni-ui/motion. Without JS,
+ * [data-reveal] content stays fully visible.
  *
- * Scroll reveals need one line of JS — the optional `initReveal()` hook from
- * apliteni-ui/motion. Without JS, [data-reveal] content stays fully visible
- * (progressive enhancement, never hidden behind a script that didn't run).
+ * The global prefers-reduced-motion net lives in reduced-motion.css and is NOT
+ * @imported from here — the icon gates read each stylesheet on its own and
+ * refuse a sheet that pulls in another.
  *
- * The global prefers-reduced-motion net that neutralises ALL of the above — plus
- * any component animation in the kit — lives in reduced-motion.css, because the
- * React bundle needs the same net and two copies would drift. index.css imports
- * it beside this file; it is NOT @imported from here, because the icon gates read
- * each stylesheet on its own and refuse a sheet that pulls in another.
- * ========================================================================== */
+ * why: docs/specification.md#motion */
 
 /* -- Entrances -------------------------------------------------------------
  * `both` fill so the element starts at the "from" frame (hidden) and holds

package/src/styles/reduced-motion.css

@@ -1,24 +1,13 @@
-/* ============================================================================
- * apliteni-ui — REDUCED-MOTION NET
+/* apliteni-ui — reduced-motion net. One file, because it has to reach every
+ * bundle the kit publishes and a second copy would drift; a consumer who imports
+ * both bundles gets it twice, which costs nothing, since every rule here is
+ * idempotent and `!important`.
  *
- * One file, because it has to reach every bundle the kit publishes and a second
- * copy of it would drift. `src/styles/motion.css` imports it, so `apliteni-ui/css`
- * carries it; `react/src/index.ts` imports it, so `apliteni-ui/react/css` carries
- * it too. A consumer who imports both gets it twice, which costs nothing: every
- * rule here is idempotent and `!important`.
+ * `iteration-count: 1` lets one-shot animations settle on their final frame — a
+ * checkmark stays drawn — instead of snapping back to the start.
  *
- * It neutralises every animation and transition in whatever bundle it lands in —
- * the motion library's effects, component motion (button loader, badge pulse,
- * feedback check), and smooth scroll. `iteration-count: 1` lets one-shot
- * animations settle on their final frame (a checkmark stays drawn) instead of
- * snapping back to the start.
- *
- * `0.01ms` is the kill-switch idiom, not a duration: it is short enough that
- * nothing is perceptible and non-zero so `transitionend`/`animationend` still
- * fire, which is what scripts that wait for a close animation depend on. It is
- * the one time literal in the kit that is not a timing — see
- * docs/specification.md#motion.
- * ========================================================================== */
+ * why: docs/specification.md#reduced-motion-travels-with-the-stylesheet
+ * why: docs/specification.md#motion */
 
 @media (prefers-reduced-motion: reduce) {
   html { scroll-behavior: auto !important; }

package/src/styles/table.css

@@ -53,18 +53,12 @@
 .ui-table--hover:not(.ui-table--zebra) tbody tr:hover td:last-child {
   border-top-right-radius: var(--radius-sm); border-bottom-right-radius: var(--radius-sm); }
 
-/* ── Data-table modifiers (composable) ──────────────────────────────────────
- * Compose for a dense financial ledger: .ui-table--dense --zebra --hover.
- *   --dense  compact row rhythm for many-row / many-column data: --space-3
- *            across and --space-2 down, one step in from the base table's
- *            --space-4 across and --space-4 down. Both of its old numbers sat
- *            exactly between two steps — 14px between 12 and 16, 10px between 8
- *            and 12 — and both round DOWN, because the modifier exists to fit
+/* Data-table modifiers, composable: .ui-table--dense --zebra --hover.
+ *   --dense  --space-3 across, --space-2 down — one step in from the base
+ *            table, and both round DOWN, because the modifier exists to fit
  *            more rows and rounding up spends the distinction it is for.
- *   --zebra  row striping instead of per-row rules; 2px header rule; the
- *            (accent) hover tint out-ranks the stripe (defined after it)
- * Cell helpers: .ui-table__num (right, tabular), .ui-table__code (plain
- * monospace id — never a boxed code chip inside a table).
+ *   --zebra  row striping; 2px header rule; the hover tint out-ranks the stripe
+ * Cell helpers: .ui-table__num (right, tabular), .ui-table__code.
  * why: docs/specification.md#spacing-and-rhythm
  * held by: stories/table-rhythm.test.js */
 .ui-table--dense th { padding: 0 var(--space-3) var(--space-2) 0; }

package/src/tokens/accents.css

@@ -1,23 +1,19 @@
-/* ============================================================================
- * Accent sub-themes — an orthogonal `data-accent` dimension on top of
- * `data-theme` (dark/light). Set both on <html>:
+/* Accent sub-themes — an orthogonal `data-accent` dimension on top of
+ * `data-theme`. Set both on <html>:
  *
  *     <html data-theme="dark" data-accent="phoenix">
  *
- * Each sub-theme only re-points the accent family (--accent, --purple*,
- * --glow-purple, --grad-*). Surfaces, text and signal colours (green =
- * live, pink = danger) stay put, so every accent works in light AND dark and
- * every component follows with zero component-level changes.
+ * Each sub-theme only re-points the accent family. Surfaces, text and signal
+ * colours (green = live, pink = danger) stay put, so every accent works in
+ * light AND dark and every component follows with no component-level change.
  *
- * --ring is NOT here. It is declared once, in tokens.css, as var(--accent), so
- * re-pointing --accent above re-points the focus ring too. Six hand-written
- * rgba() rings used to sit in this file and every one of them missed the 3:1
- * of WCAG 1.4.11 — 1.35:1 at worst. See #218 and
- * docs/specification.md#the-focus-ring.
+ * --ring is NOT here: it is declared once in tokens.css as var(--accent), so
+ * re-pointing --accent re-points the focus ring too.
  *
  * Selectors carry two attributes + :root, so they always out-specify the
  * single-attribute theme blocks in tokens.css regardless of import order.
- * ========================================================================== */
+ *
+ * why: docs/specification.md#the-focus-ring */
 
 /* ---- Phoenix — ember / rising fire (the strategy's namesake) ------------- */
 :root[data-theme="dark"][data-accent="phoenix"] {

package/src/tokens/tokens.css

@@ -184,18 +184,10 @@
   --ink: #e9e7f0;
 
   /* Ink that reads on a SIGNAL colour once that colour becomes a fill — the
-     glyph in a success circle, the glyph on a toast's status circle.
-     In dark every signal is a bright hue, so one near-black ink clears all
-     five: 15.87 on --green, 7.35 on --pink, 13.40 on --amber, 11.75 on --cyan
-     and 6.29 on --muted. Danger keeps a token of its own only because LIGHT
-     still needs it: there the signals are deepened to read as ink on white,
-     which parks them mid-luminance, and --pink is the one that comes out ahead
-     against white (5.78) rather than against near-black (3.39).
-     Dark danger was white until now, which was correct while --pink was
-     #e35b8f. Issue #131 lightened it to #e97ca5 to clear AA as INK on its own
-     glow, and that carried the fill up past the point where white could read on
-     it — 2.66 on the toast's status circle, under the 3:1 of WCAG 1.4.11. The
-     ten status x theme icon pairs are gated in stories/signal-contrast.test.js. */
+     glyph in a success circle, the glyph on a toast's status circle. One
+     near-black ink clears all five in dark; danger keeps a token of its own
+     because LIGHT still needs one.
+     why: docs/specification.md#colour-and-contrast */
   --signal-contrast: #0c0c0c;
   --danger-contrast: var(--signal-contrast);