@apliteni/apliteni-ui 0.23.1 → 0.23.3

package/src/components/shell.js

@@ -10,9 +10,8 @@ import { sidebarNav, breadcrumbs } from './nav.js';
 import { prism } from '../assets/brand.js';
 import { ACCOUNT_NAV, toMenuTuple, initials } from './account-nav.js';
 
-// The one account navigation definition lives in account-nav.js, because
-// topbar.js needs it too and this file already imports topbar.js. Re-exported
-// here so the published name docs/library.md documents keeps working.
+// 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.
 export { ACCOUNT_NAV };
 
 const str = (v) => (v == null ? '' : String(v));
@@ -20,32 +19,24 @@ const isRecord = (v) => typeof v === 'object' && v !== null;
 
 // ---- the options bag, settled once --------------------------------------
 //
-// Every option below carries a shape, and a default parameter covers
-// `undefined` and nothing else — so `nav: null` from an /auth/me, a `maxWidth`
-// out of tenant config, a `crumbs` string written by somebody reading the
-// migration note all arrived as they were. A shell that throws mid-render takes
-// the page with it, so each is settled here, before the first sink sees it, and
-// a parameter is protected by being declared rather than by what it crashes
-// into. Adding one to appShell() means adding it to SHAPES or deciding in the
-// open that it needs nothing.
-
-// accountShell() has always taken its nav as [id, icon, label, href?, target?].
-// Accept that shape and nav.js's object shape side by side, so a consumer's
-// existing tuples and the exported ACCOUNT_NAV both work. A nav that is not a
-// list at all falls back to the default; an entry inside one that is neither
-// shape is dropped, because sideItem() reads `.items` off whatever it is given.
-// An empty list is an answer, not a mistake — it stays empty.
+// A default parameter covers `undefined` and nothing else, so `nav: null` from an
+// /auth/me and a `crumbs` string from somebody reading the migration note both arrived
+// as they were. A shell that throws mid-render takes the page with it, so each option is
+// settled here, before the first sink sees it. Adding one to appShell() means adding it
+// to SHAPES or deciding in the open that it needs nothing.
+
+// accountShell()'s tuple nav — [id, icon, label, href?, target?] — and nav.js's object
+// shape are accepted side by side. A nav that is not a list falls back to the default;
+// an entry that is neither shape is dropped. An empty list is an answer and stays.
 const toItems = (nav) => (Array.isArray(nav) ? nav : ACCOUNT_NAV)
   .filter(isRecord)
   .map((n) => (Array.isArray(n)
     ? { id: n[0], icon: n[1], label: n[2], href: n[3], target: n[4] }
     : n));
 
-// The trail is the caller's, and `crumbs` is the one option whose shape changed
-// in this release: the old API was `crumb: 'Payouts'`, a string, and the new one
-// is `crumbs: [{ label }]`. One letter apart. A value that is not a list is not
-// read as a one-crumb trail — that would draw a plausible page and hide the
-// migration mistake — so it is no trail at all, which is the visible answer. A
+// The trail is the caller's, and `crumbs` changed shape this release: `crumb: 'Payouts'`
+// became `crumbs: [{ label }]`, one letter apart. A non-list is NOT read as a one-crumb
+// trail — that hides the migration mistake — so it is no trail at all, which shows. A
 // crumb with no label would draw an empty cell, so it goes too.
 const toCrumbs = (crumbs) => (Array.isArray(crumbs) ? crumbs : [])
   .filter((c) => isRecord(c) && !Array.isArray(c) && str(c.label) !== '');
@@ -56,23 +47,16 @@ const toReader = (a) => (isRecord(a) ? { name: str(a.name), email: str(a.email)
 
 // ---- the topbar, which interpolates where the rail escapes ----------------
 //
-// brand() writes `word` straight into its markup and accountMenu() does the
-// same with the reader's name, address and menu entries. So the escaping is
-// here, on the one path into productTopbar(), and not in each caller:
-// accountShell() escaped for itself and the `topbar` option underneath it
-// escaped for nobody. The caller passes text either way.
-
-// The reader the menu draws. Both fields are always written, empty when the
-// caller gave none — accountMenu()'s own defaults are a demo identity, and a
-// key dropped here is a key its default fills in, which is how a consumer's
-// page came to name its own reader in the rail and the kit's fixture beside it.
-//
-// `initials` travels with them because it is derived, and a derived value comes
-// from what the caller passed, not from the entities made of it: `<Ada>` and
-// `&lt;Ada&gt;` do not start with the same character. The entries land in the
-// same sink and toMenuTuple() is what escapes them; it reads item objects, so
-// tuples go through toItems() first. A nav nobody passed stays unpassed, and
-// accountMenu() falls back to its own derived default rather than to nothing.
+// brand() writes `word` straight into its markup and accountMenu() does the same with
+// the reader's name, address and menu entries, so the escaping is here on the one path
+// into productTopbar() rather than in each caller. The caller passes text either way.
+
+// The reader the menu draws. Both fields are always written, empty when the caller gave
+// none: accountMenu()'s defaults are a demo identity, so a key dropped here is a key its
+// fixture fills in. `initials` is derived from what the caller passed rather than from
+// the entities made of it — `<Ada>` and `&lt;Ada&gt;` do not start with the same
+// character. toMenuTuple() escapes the entries and reads item objects, so tuples go
+// through toItems() first; a nav nobody passed stays unpassed.
 const toMenuReader = (a) => {
   const { name, email } = toReader(a);
   const rest = isRecord(a) && !Array.isArray(a) ? a : {};
@@ -89,12 +73,11 @@ const toTopbar = (t) => {
   return out;
 };
 
-// `maxWidth` lands inside a style attribute, so a length is all this accepts —
-// a number and a unit, or `none`. Anything else yields '' and the caller writes
-// no style attribute, letting layout.css fall through to --measure. It must
-// REMOVE the property rather than pass a default or 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.
+// `maxWidth` lands inside a style attribute, so a length is all this accepts — a number
+// and a unit, or `none`. Anything else yields '' and the caller writes no style
+// 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
 const LENGTH = /^(?:\d+|\d*\.\d+)(?:px|rem|em|ch|%|vw)$/;
 const mainMax = (v) => {
@@ -108,11 +91,9 @@ const SHAPES = {
   nav: toItems, crumbs: toCrumbs, account: toReader, maxWidth: mainMax, topbar: toTopbar,
 };
 
-// The text options settle too, by the same argument the rest of them do. A
-// default parameter covers `undefined` and not `null`, so `body: null` from a
-// record with no description drew the word "null" on the page, and `word: null`
-// left the brand link with no accessible name at all. Dropping the key is what
-// lets the declared default apply.
+// The text options settle by the same argument. `body: null` from a record with no
+// description drew the word "null" on the page and `word: null` left the brand link with
+// no accessible name; dropping the key is what lets the declared default apply.
 const TEXT = ['word', 'brandHref', 'navLabel', 'title', 'sub', 'body', 'signOutHref', 'active'];
 
 function settle(options) {
@@ -122,23 +103,18 @@ function settle(options) {
   return out;
 }
 
-// Signing out is a navigation action, so it belongs in the rail nav's footer
-// slot. Opt-in: a shell that renders it unasked puts a dead link on a page with
-// no session behind it.
+// Signing out is a navigation action, so it belongs in the rail nav's footer slot.
+// Opt-in: rendering it unasked puts a dead link on a page with no session behind it.
 const signOut = (href) =>
   `<a class="ui-nav__item is-danger" href="${esc(href)}" aria-label="Sign out">` +
   `<span class="ui-nav__ic">${icon('logout')}</span>` +
   `<span class="ui-nav__label">Sign out</span></a>`;
 
-// Who is signed in. A sibling of the <nav>, not its footer: a reader's name and
-// address are not navigation, and inside the landmark a screen reader announces
-// the address as an entry. Empty when nobody is — a shell must not invent an
-// identity for a reader it does not know.
-//
-// The initials carry the name, and the spelled-out half is aria-hidden. The
-// narrow rail folds `.ui-app__who` out of view, so a name that lived only there
-// left the initials on screen with nothing at all in the accessibility tree.
-// Naming the mark instead makes the two agree at every width, and says it once.
+// Who is signed in. A sibling of the <nav>, not its footer: a name and address are not
+// navigation, and inside the landmark a screen reader announces the address as an entry.
+// Empty when nobody is. The initials carry the name and the spelled-out half is
+// aria-hidden, because the narrow rail folds `.ui-app__who` out of view and a name that
+// lived only there left nothing in the accessibility tree.
 function railUser({ name, email }) {
   if (!name && !email) return '';
   const who = [name, email].filter(Boolean).join(', ');
@@ -179,16 +155,14 @@ export function appShell(options = {}) {
     ariaLabel: navLabel,
     footer: signOutHref ? signOut(signOutHref) : '',
   });
-  // The topbar already says the product word. Two lockups on one screen is one
-  // product word too many, so the rail head steps aside when there is a topbar.
-  // 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 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.
   const brand = topbar ? '' : `<a class="ui-app__brand" href="${esc(brandHref)}" aria-label="${esc(word)}">`
     + `${prism(`appb-${++_shellUid}`, 24)}<span>${esc(word)}</span></a>`;
-  // A <div>, not an <aside>: <aside> is the `complementary` landmark — content
-  // related to the page but separable from it — and this holds the page's
-  // primary navigation and the reader who is signed in. The <nav> inside it is
-  // already the landmark that names the menu.
+  // A <div>, not an <aside>: <aside> is the `complementary` landmark, and this holds the
+  // page's primary navigation and the signed-in reader. The <nav> inside it is already
+  // the landmark that names the menu.
   const grid = `<div class="ui-app">
     <div class="ui-app__rail">
       ${brand}
@@ -225,11 +199,9 @@ export function accountShell({
   // topbar menu are handed one list rather than two readings of `nav`.
   const items = toItems(nav);
   const trail = [{ label: cap }, { label: crumb || title }];
-  // The preset hands the topbar the caller's text, exactly as it hands the rail
-  // the caller's text. toTopbar() is what escapes for the menu's raw sinks, and
-  // it runs once inside appShell() — escaping here as well would reach the menu
-  // as entities, and escaping nowhere is what the public `topbar` option used
-  // to do.
+  // The preset hands the topbar the caller's text, as it does the rail. toTopbar()
+  // escapes for the menu's raw sinks and runs once inside appShell(); escaping here as
+  // well would reach the menu as entities.
   return appShell({
     word,
     nav: items,

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

@@ -34,14 +34,10 @@
 .ui-table tbody tr { transition: background var(--dur-fast) var(--ease); }
 
 /* Row hover: an inset, rounded fill so the highlight never sits flush against a
- * container's border (issue #71 — the full-bleed rectangle collided with a card's
- * left edge). Separate border model with zero spacing keeps the row separators
- * continuous while letting the row ends round; table padding (which only applies
- * in the separate model) insets the rows so the fill clears the container edge.
- * Zebra tables keep the original full-bleed tint (finance ledger), so they're
- * excluded here — their hover rule lives further down.
- * The inset was 6px, which is a tie between --space-1 and --space-2; it rounds
- * up, because what it buys is clearance and clearance rounds away from the edge. */
+ * container's border (#71). The separate border model with zero spacing keeps the row
+ * separators continuous while letting the row ends round, and table padding — which
+ * only applies in that model — insets the rows. Zebra keeps the original full-bleed
+ * tint (finance ledger) and is excluded here; its hover rule is below. */
 .ui-table--hover:not(.ui-table--zebra) {
   border-collapse: separate;
   border-spacing: 0;
@@ -53,18 +49,10 @@
 .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
- *            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).
+/* Data-table modifiers, composable: .ui-table--dense --zebra --hover.
+ *   --dense  --space-3 across, --space-2 down — one step in from the base 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; }
@@ -77,15 +65,11 @@
 .ui-table--zebra th { border-bottom-width: 2px; }
 .ui-table--zebra td { border-bottom: 0; }
 .ui-table--zebra tbody tr:nth-child(even) td { background: var(--surface-2); }
-/* The stripe is full-bleed on purpose — the hover note above inset the hover fill for
- * #71 and deliberately left the ledger stripe alone. But full-bleed only reads right if
- * the end cells are inset from the tint's own edge, and the base rhythm does not inset
- * them: `.ui-table td` sets `padding-left: 0`. Only `--dense` supplied the inset, so a
- * `--zebra` table composed WITHOUT `--dense` put the first cell's content at exactly
- * x=0 of the stripe. `DataTable` is that composition — it writes `ui-table
- * ui-table--hover ui-table--zebra` and no `--dense` — so its select-all and per-row
- * checkboxes sat flush against the tint with a measured 0px gap.
- * Header and body are inset together, or the columns stop lining up. */
+/* The stripe stays full-bleed (the #71 inset above is hover only), but it only reads right
+ * if the end cells are inset from the tint's own edge, and `.ui-table td` sets
+ * `padding-left: 0`. Only `--dense` supplied that inset, so `--zebra` without `--dense` —
+ * `DataTable`'s composition — sat its checkboxes at x=0 of the stripe. Head and body are
+ * inset together, or the columns stop lining up. */
 .ui-table--zebra th:first-child,
 .ui-table--zebra td:first-child { padding-left: var(--space-3); }
 .ui-table--zebra th:last-child,

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"] {
@@ -66,25 +62,15 @@
   --purple: #1156b8;
   --purple-light: #1568d6;
   --purple-mid: #1560c8;
-  /* Deepened for WCAG AA on the raised grey panel and its wash: #1568d6 read
-     4.54:1 on --surface-3 and 3.98:1 on --glow-purple over it; #005bc8 clears
-     both at 5.43:1 and 4.76:1. Both washed figures are at the 0.10 alpha below,
-     which is what this cell ships — an earlier version of this comment quoted
-     them at the 0.05 the wash briefly carried, which flattered both inks.
-     Light Ocean is the one light accent #96 never deepened, because it happened
-     to clear plain white. Same kind of move, smaller: hue and chroma unchanged
-     in OKLCH (H 258, C 0.185) and four points of lightness down, where #96's
-     two took about ten points and gave up 15.9% of the chroma on Phoenix and
-     17.6% on Emerald. See issues #96 and #157. */
+  /* Deepened for WCAG AA on the raised grey panel and its wash — hue and chroma held
+     in OKLCH (H 258, C 0.185), four points of lightness down. The washed figures are
+     read at the 0.10 alpha below, which is what this cell ships. See issues #96, #157. */
   --accent: #005bc8;
   --accent-strong: var(--accent);
   --accent-contrast: #ffffff;
-  /* Back to 0.10, the alpha this cell carried before #157. #157 thinned it to
-     0.05 while --accent was still #1568d6, because no alpha could carry that
-     blue over the grey panel. Deepening the ink is what closed the pair, so the
-     wash does not have to be the thing that gives. The rgb stays --purple-light
-     rather than the accent — in light a glow tints --purple-light, which
-     stories/signal-contrast.test.js holds. See issue #157. */
+  /* Back to the 0.10 this cell carried before #157: deepening the ink closed the pair,
+     so the wash does not have to give. The rgb stays --purple-light rather than the
+     accent — in light a glow tints --purple-light, which signal-contrast.test.js holds. */
   --glow-purple: rgba(21, 104, 214, 0.10);
   --grad-from: #1568d6;
   --grad-to: #17a2c0;