@juwel-development/design-system 3.9.1 → 3.11.0

package/src/Layout/Header/Header.tsx

@@ -2,19 +2,15 @@ import type { VariantProps } from 'class-variance-authority';
 import { cva } from 'class-variance-authority';
 import type { FunctionComponent, ReactNode } from 'react';
 
-// The recipe on the <header>. It sets the label type role - the "small grotesk, letter-spaced, muted"
-// the issue described, whose "never grows past 1rem" was a role wearing a number, so no size literal
-// appears here (#14). The shell's air is one value in every direction: --space-region above, below and
-// (on the nav) between, --gutter across, so the bar aligns with every inset Section. The current-page
-// treatment keys on the attribute, not on a component: [&_[aria-current=page]] compiles to specificity
-// 0,2,0 and beats Link's quiet text-muted (0,1,0) with no !important and no import, so the current item
-// sits at foreground - the colour every other item reaches only on hover. `edge` draws the bottom
-// hairline in `rule`, the one weight a page's boundaries share with a Section join, and defaults to
-// `rule` - the conventional header - so a ruleless shell opts out. Colours are semantic tokens re-pointed
-// by `.dark`, so no `dark:` class.
+// The recipe on the <header>. It sets the label type role - whose "never grows past 1rem" was a role
+// wearing a number, so no size literal appears here (#14) - and one air value in every direction:
+// --space-region above and below, --gutter across, so the bar aligns with every inset Section. The
+// current-page treatment keys on the attribute, not on a component: [&_[aria-current=page]] compiles
+// to specificity 0,2,0 and beats Link's quiet text-muted (0,1,0) with no !important and no import.
+// Colours are semantic tokens re-pointed by `.dark`, so no `dark:` class.
 const header = cva(
   [
-    'flex items-baseline justify-between',
+    'flex items-baseline',
     'font-secondary text-label leading-label tracking-label text-muted',
     'py-[var(--space-region)] px-[var(--gutter)]',
     '[&_[aria-current=page]]:text-foreground',
@@ -25,26 +21,48 @@ const header = cva(
         none: '',
         rule: 'border-b border-solid border-rule',
       },
+      // Read off the slots the caller filled, never set by a caller (see IHeaderProps). `navigation` is
+      // the arrangement the bar always had. `statusAction` breaks into lines instead of overflowing:
+      // --space-region along a line, the role the nav gaps its items with, and --space-stack between
+      // lines, Cluster's rule for a wrapped row (docs/adr/0008).
+      mode: {
+        navigation: 'justify-between',
+        statusAction:
+          'flex-wrap gap-x-[var(--space-region)] gap-y-[var(--space-stack)]',
+      },
     },
-    defaultVariants: { edge: 'rule' },
+    defaultVariants: { edge: 'rule', mode: 'navigation' },
   },
 );
 
-// Not a second recipe - the standing slot has nothing to vary, and the standard allows a component
-// one cva() (design-system-components.md §4), which is the bar's own above. A named constant beside
-// the nav's inline class string, so the comment has something to sit on.
-//
-// The height floor is the nav's own line box, written from the two tokens the recipe above sets the
-// header from, so the declared floor and the rendered line cannot drift (#81). `shrink-0` because an
-// explicit min-width replaces a flex item's automatic minimum - without it the bar squeezes the slot
-// below its content and wraps the place name the floor exists to keep on one line.
+// Not a second recipe - no slot has anything to vary, and the standard allows a component one cva()
+// (design-system-components.md §4), which is the bar's own above. The standing floor is the nav's own
+// line box, written from the two tokens the recipe sets the header from, so floor and rendered line
+// cannot drift (#81); `shrink-0` because an explicit min-width replaces a flex item's automatic one.
 const standingSlot = [
   'inline-flex shrink-0 items-center',
   'min-h-[calc(var(--text-label)*var(--leading-label))]',
   'min-w-[var(--standing-min-width)]',
 ].join(' ');
 
-export interface IHeaderProps extends VariantProps<typeof header> {
+const navSlot = 'flex flex-wrap items-baseline gap-[var(--space-region)]';
+
+// The readout may shrink below its longest word once it has a line of its own, and an unbroken token
+// then breaks inside the slot rather than widening the page. No role, no name, no live region.
+const statusSlot = 'min-w-0 wrap-anywhere';
+
+// One auto margin puts the action on the end edge whatever the line holds - beside the readout, or
+// alone once the bar has broken. It is not `shrink-0`: a Button narrower than its label wraps the
+// label itself (#119), where a bar refusing to shrink it would overflow the page instead.
+const actionSlot = 'ms-auto';
+
+interface IHeaderShellProps extends Omit<VariantProps<typeof header>, 'mode'> {
+  testId?: string;
+}
+
+/** The navigation bar: the mode every existing caller is in, and the default. A standing link and a
+ *  `<nav>`, and never a status or an action slot - the other shape is `IHeaderStatusActionProps`. */
+export interface IHeaderNavigationProps extends IHeaderShellProps {
   /** The standing link: a place name, a mark, or a home link. The consumer supplies the whole anchor -
    *  Header renders no link of its own. A place name uses `<Link treatment="quiet" href="/">…</Link>`; a
    *  mark uses `<Link treatment="graphic" href="/"><Brandmark …/></Link>`, whose `graphic` treatment
@@ -54,16 +72,56 @@ export interface IHeaderProps extends VariantProps<typeof header> {
   navName?: string;
   /** The nav links. */
   children?: ReactNode;
-  testId?: string;
+  status?: never;
+  action?: never;
 }
 
+/** The status/action bar: a bar that reports and acts rather than navigates, for a product whose
+ *  shell carries a readout and a control and no links. It has no standing link and no `<nav>` - a
+ *  button is not navigation - and the two shapes cannot be mixed: the compiler rejects a call that
+ *  hands this bar a standing link, a nav name or nav children. */
+export interface IHeaderStatusActionProps extends IHeaderShellProps {
+  /** The readout - a date, a balance, a short note, or a `Cluster` of them - at the start edge, first
+   *  in reading order. A plain `div` with no role, no name and no live region: what it holds carries its
+   *  own semantics, and whether a change is announced is the consumer's decision, made by wrapping its
+   *  own live region. Long and unbroken wording wraps inside the slot. Omitted, nothing renders. */
+  status?: ReactNode;
+  /** The control - a `Button`, or a `Cluster` of them - at the end edge, last in reading and keyboard
+   *  order, on whichever line it lands when the bar breaks. A plain `div` like `status`. Header never
+   *  decides whether the control is available: pass it disabled, or withhold it (`{ready && <Button/>}`
+   *  renders no box). Omitted, nothing renders. */
+  action?: ReactNode;
+  standing?: never;
+  navName?: never;
+  children?: never;
+}
+
+export type IHeaderProps = IHeaderNavigationProps | IHeaderStatusActionProps;
+
+// What React paints nothing for: `undefined`, `null`, a boolean and the empty string. A withheld slot
+// gets no box, so a status-only or action-only bar carries no empty one.
+const isPainted = (slot: ReactNode): boolean =>
+  slot !== undefined &&
+  slot !== null &&
+  typeof slot !== 'boolean' &&
+  slot !== '';
+
 /**
- * The shell's top edge: a standing link and a nav, at the label type role. It renders the banner
- * landmark and a single `<nav>`, arranging nothing beyond the two slots, so it works with no hydration.
+ * The shell's top edge, at the label type role, in one of two mutually exclusive modes. The
+ * **navigation bar** - the default, and what every existing caller renders - is a standing link and a
+ * single `<nav>`. The **status/action bar** is a readout at the start edge and a control at the end
+ * edge, both plain boxes with no landmark of their own and no `<nav>` anywhere. The props type is a
+ * union of the two shapes, so a call that mixes them does not compile. Either bar arranges nothing
+ * beyond its slots and works with no hydration.
  *
  * @Guarantees — enforced on every render
  * - The header is set at the label role and carries no size of its own: `font-secondary text-label
  *   leading-label tracking-label text-muted`, so it never grows past that role whatever the page font size.
+ * - The shell's air is one value above, below and between: `--space-region` vertically, between the
+ *   nav's items and between the status/action bar's slots along a line, `--gutter` across, so the bar
+ *   aligns with every inset `Section`. It is never sticky and needs no JavaScript.
+ *
+ * The navigation bar, unchanged by #125:
  * - The nav's line box is the library's own rather than the consuming document's: the header leads
  *   itself at the label role, so the height it declares for its slot is the height it renders.
  * - The standing slot is floored, never fixed: its minimum height is that same line box - the label
@@ -73,10 +131,24 @@ export interface IHeaderProps extends VariantProps<typeof header> {
  *   grows the slot, on one line, and is never clamped or wrapped.
  * - A nav item marked `aria-current="page"` renders at `foreground` whatever supplied it - the treatment
  *   keys on the attribute, not on `Link`, so it holds against a bare anchor or any component.
- * - The shell's air is one value above, below and between: `--space-region` vertically and between nav
- *   items, `--gutter` across, so the bar aligns with every inset `Section`.
- * - It is never sticky and needs no JavaScript: there is no `sticky` variant and nothing to hydrate.
- * - Omitting `navName` emits no `aria-label` at all, not an empty one.
+ * - The standing slot and the `<nav>` are the bar's two children whatever the caller passes, the nav
+ *   flush with the end content edge and absorbing narrowing by wrapping its links. Omitting `navName`
+ *   emits no `aria-label` at all, not an empty one.
+ *
+ * The status/action bar:
+ * - It renders no `<nav>`, no standing slot, no role, no name and no live region of its own. Each
+ *   filled slot is one `div` directly inside the banner; an omitted or withheld slot (`false`, `null`)
+ *   renders no box and reserves no space, so a status-only bar starts with its readout and an action-only
+ *   bar is the control alone at the end edge.
+ * - Reading and keyboard order is status, then action, and the DOM order is the same at every width.
+ * - With both fitting, the readout sits at the start content edge and the control at the end content
+ *   edge on one line. When they cannot share a line, the control drops below the readout and stays
+ *   flush with the end edge; a readout then takes the whole line and wraps inside it, unbroken wording
+ *   included, so the bar never widens the page and never clips.
+ * - Breaking is CSS alone: a width change re-flows the same elements, so descendant state and focus
+ *   survive it.
+ * - What the consumer passes keeps its semantics: a heading stays a heading, a live region stays one, a
+ *   disabled control stays disabled. Header adds, removes and announces nothing.
  *
  * @CallerMustEnsure — the component cannot see these and does not check them
  * - A mark that should *fill* the standing slot is given a **definite width** by whoever placed it -
@@ -89,6 +161,10 @@ export interface IHeaderProps extends VariantProps<typeof header> {
  *   width; `flex: 1 1 0; min-width: 0` only collapses the mark when the bar is already out of room, so
  *   it is not the rule to reach for. The library cannot apply either rule for you: the same width on a
  *   place name would clamp the name and wrap it.
+ * - Set the type of what fills a status/action slot: the bar sets the label role, so a bare string in
+ *   `status` reads as a label, while a `P` or a `Note` wears its own role and a `Button` its own.
+ * - Whether a changing readout interrupts is yours to decide: wrap your own live region inside `status`
+ *   where a change must be announced, and leave it out where it must not. Header takes neither side.
  *
  * @UXGuidelines
  * - Name the nav with `navName` once the page has more than one navigation landmark - a footer nav will
@@ -97,21 +173,45 @@ export interface IHeaderProps extends VariantProps<typeof header> {
  *   `aria-current`, so set `current` on the `Link` and style nothing yourself.
  * - The nav does not collapse into a menu: a disclosure needs JavaScript, so on a narrow viewport the
  *   items wrap. A mobile menu is out of scope, not a follow-up.
+ * - A bar that reports and acts is a status/action bar, never a navigation bar with a button among its
+ *   links: a Balance line or a Continue button inside a `<nav>` is announced as navigation. A product
+ *   whose shell needs links as well as a control has two bars, not one.
+ * - Several readouts or several actions go in a `Cluster` inside the slot: `gap="stack"` keeps them one
+ *   group, and the Cluster wraps inside the slot before the bar runs out of room.
  */
 export const Header: FunctionComponent<IHeaderProps> = ({
   edge,
+  testId,
   standing,
   navName,
   children,
-  testId,
-}) => (
-  <header className={header({ edge })} data-testid={testId}>
-    <div className={standingSlot}>{standing}</div>
-    <nav
-      aria-label={navName}
-      className={'flex flex-wrap items-baseline gap-[var(--space-region)]'}
+  status,
+  action,
+}) => {
+  // A slot the caller named decides the mode, even one withheld as `false`: `action={ready && …}` is a
+  // status/action bar with its control withheld, not a navigation bar with an empty nav.
+  const reportsOrActs = status !== undefined || action !== undefined;
+  return (
+    <header
+      className={header({
+        edge,
+        mode: reportsOrActs ? 'statusAction' : 'navigation',
+      })}
+      data-testid={testId}
     >
-      {children}
-    </nav>
-  </header>
-);
+      {reportsOrActs ? (
+        <>
+          {isPainted(status) && <div className={statusSlot}>{status}</div>}
+          {isPainted(action) && <div className={actionSlot}>{action}</div>}
+        </>
+      ) : (
+        <>
+          <div className={standingSlot}>{standing}</div>
+          <nav aria-label={navName} className={navSlot}>
+            {children}
+          </nav>
+        </>
+      )}
+    </header>
+  );
+};

package/src/Layout/PageHead/PageHead.tsx

@@ -16,20 +16,21 @@ const pageHead = cva(
   'flex flex-col gap-[var(--space-stack)] py-[var(--space-band)] px-[var(--gutter)]',
 );
 
-// The scale event: the title role, led and tracked as a large heading, foreground. No measure - the
-// head is full-bleed and the consumer keeps titles short.
+// The scale event: the title role, led and tracked as a large heading, foreground, in the heading
+// face every heading reads (#120). No measure - the head is full-bleed and the consumer keeps titles
+// short.
 const pageHeadTitle = cva(
-  'font-primary text-title leading-title tracking-optical text-foreground',
+  'font-heading text-title leading-title tracking-optical text-foreground',
 );
 
 // The standfirst: the lede role, foreground, run one measure wider than the reading column (#18).
 const pageHeadLede = cva(
-  'font-primary text-lede leading-lede text-foreground max-w-[var(--measure-wide)]',
+  'font-body text-lede leading-lede text-foreground max-w-[var(--measure-wide)]',
 );
 
 // The small print: the small role, muted, held to the reading measure like Prose's tail.
 const pageHeadIntro = cva(
-  'font-primary text-small text-muted max-w-[var(--measure)]',
+  'font-body text-small text-muted max-w-[var(--measure)]',
 );
 
 export interface IPageHeadProps {

package/src/Layout/ScrollContainer/ScrollContainer.tsx

@@ -0,0 +1,149 @@
+import type { VariantProps } from 'class-variance-authority';
+import { cva } from 'class-variance-authority';
+import {
+  type FunctionComponent,
+  type ReactNode,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from 'react';
+
+// The container paints nothing: no fill, no border, no size of its own. `max-h-full`/`max-w-full`
+// let a sized parent bound it and resolve to nothing under an unsized one, so no viewport bound is
+// invented. A disabled axis is `hidden`, so overflow there is clipped rather than scrolled. The one
+// focus ring is drawn with outline, colour at rest - docs/adr/0002.
+const scrollContainer = cva(
+  'max-h-full max-w-full min-h-0 min-w-0 outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)]',
+  {
+    variants: {
+      axis: {
+        both: 'overflow-auto',
+        horizontal: 'overflow-x-auto overflow-y-hidden',
+        vertical: 'overflow-y-auto overflow-x-hidden',
+      },
+    },
+    defaultVariants: { axis: 'both' },
+  },
+);
+
+// The content box is `fit-content` floored at the container's width where horizontal scrolling is
+// on, so unwrappable content grows it - which a ResizeObserver can see, since growth inside an
+// overflow box never changes the container's size - and the container's width where only vertical
+// is on, so a Table keeps its own horizontal scroll region. The padding is the focus ring's room.
+const scrollContent = cva(
+  'p-[calc(var(--focus-ring-width)+var(--focus-ring-offset))]',
+  {
+    variants: {
+      axis: {
+        both: 'w-fit min-w-full',
+        horizontal: 'w-fit min-w-full',
+        vertical: 'w-full',
+      },
+    },
+    defaultVariants: { axis: 'both' },
+  },
+);
+
+type Axis = NonNullable<VariantProps<typeof scrollContainer>['axis']>;
+
+const isOverflowing = (element: HTMLElement, axis: Axis): boolean => {
+  const horizontally = element.scrollWidth > element.clientWidth;
+  const vertically = element.scrollHeight > element.clientHeight;
+  return (
+    (axis !== 'vertical' && horizontally) ||
+    (axis !== 'horizontal' && vertically)
+  );
+};
+
+// A tab stop only while an enabled axis overflows (WCAG 2.1.1 wants the scroll container itself
+// focusable when nothing inside is): reachable until measured, so server markup is operable before
+// hydration, and kept reachable while it holds focus itself, since dropping tabindex from the
+// focused element would let the browser relocate focus - the one thing a re-measure must not do.
+const useOverflow = (
+  container: { current: HTMLElement | null },
+  content: { current: HTMLElement | null },
+  axis: Axis,
+): boolean => {
+  const [isScrollable, setIsScrollable] = useState(true);
+  useLayoutEffect(() => {
+    const element = container.current;
+    if (element === null) return;
+    const measure = () =>
+      setIsScrollable(
+        isOverflowing(element, axis) || element === document.activeElement,
+      );
+    measure();
+    const observer =
+      typeof ResizeObserver === 'undefined'
+        ? undefined
+        : new ResizeObserver(measure);
+    observer?.observe(element);
+    if (content.current !== null) observer?.observe(content.current);
+    window.addEventListener('resize', measure);
+    element.addEventListener('blur', measure);
+    return () => {
+      observer?.disconnect();
+      window.removeEventListener('resize', measure);
+      element.removeEventListener('blur', measure);
+    };
+  }, [container, content, axis]);
+  return isScrollable;
+};
+
+export interface IScrollContainerProps
+  extends VariantProps<typeof scrollContainer> {
+  /** The group's accessible name while it can be scrolled. Required: a tab stop with no name is a
+   *  mystery to a screen reader. The consuming app words it, usually after the heading above. */
+  ariaLabel: string;
+  children?: ReactNode;
+  testId?: string;
+}
+
+/**
+ * Makes overflowing content reachable along the chosen axes, within the space its parent allocates.
+ * It owns the scrolling; the consumer owns the content and the allocation of space.
+ *
+ * @Guarantees — enforced on every render
+ * - Scrolls only an enabled axis and only once content overflows it; overflow on a disabled axis is
+ *   clipped. Content wraps as it would anywhere else.
+ * - Keyboard-reachable - a named `group` with a tab stop - exactly while an enabled axis overflows,
+ *   static content included; no stop and no group while everything fits. Scrollability is re-read on
+ *   resize and on content change without moving focus.
+ * - Native scrolling: scrollbars, wheel, touch and the browser's own arrow/page keys on the focused
+ *   container. No key of a control inside it is intercepted and focus is never trapped.
+ * - Invents no bound: no height, width or viewport unit of its own. The only space it adds is the
+ *   focus ring's room around its content, so a focusable child flush with its edge - a Table's
+ *   scroll region, a button - keeps a visible ring instead of having it clipped at the edge.
+ *
+ * @CallerMustEnsure
+ * - The parent allocates finite space on every axis the container should scroll - a sized box, or a
+ *   flex/grid item allowed to shrink (`flex: 1 1 0; min-height: 0` in a column). Under an unbounded
+ *   parent it simply grows with its content, as any block would.
+ * - Content fits a disabled axis. Clipping is not a way to hide essential content or controls.
+ * - `ariaLabel` is wording the viewer would recognise, typically the heading above the content.
+ */
+export const ScrollContainer: FunctionComponent<IScrollContainerProps> = ({
+  axis,
+  ariaLabel,
+  children,
+  testId,
+}) => {
+  const container = useRef<HTMLDivElement>(null);
+  const content = useRef<HTMLDivElement>(null);
+  const isScrollable = useOverflow(container, content, axis ?? 'both');
+  return (
+    // biome-ignore lint/a11y/useAriaPropsSupportedByRole: the name and the `group` role are set together; biome cannot see the pair
+    <div
+      ref={container}
+      className={scrollContainer({ axis })}
+      data-testid={testId}
+      role={isScrollable ? 'group' : undefined}
+      aria-label={isScrollable ? ariaLabel : undefined}
+      tabIndex={isScrollable ? 0 : undefined}
+    >
+      <div ref={content} className={scrollContent({ axis })}>
+        {children}
+      </div>
+    </div>
+  );
+};

package/src/Layout/Sidebar/Sidebar.tsx

@@ -62,12 +62,12 @@ const observeScrollport: RefCallback<HTMLElement> = (navigation) => {
 };
 
 // An entry at the label role, told apart by colour and underline alone - the agreed treatment carries
-// no active-background role. Active keeps a persistent underline at the at-rest thickness; usable
-// raises one on hover, instantly (underlines are off the motion allowlist, docs/adr/0001); inert is
-// muted with no interactive response. The focus ring is the library's one contract (docs/adr/0002).
+// no active-background role. Active keeps a persistent underline; usable raises one on hover, instantly
+// (docs/adr/0001); inert is muted. The focus ring is the one contract (docs/adr/0002). Labels wrap with
+// `overflow-wrap: anywhere`: unlike `break-word` it folds an unbroken word into min-content (#122).
 const sidebarEntry = cva(
   [
-    'w-full text-left font-secondary text-label tracking-label',
+    'w-full text-left font-secondary text-label tracking-label wrap-anywhere',
     'underline-offset-[var(--underline-offset)]',
     'outline-focus-ring outline-offset-[var(--focus-ring-offset)] focus-visible:outline focus-visible:outline-[length:var(--focus-ring-width)]',
   ].join(' '),
@@ -196,6 +196,10 @@ const SidebarRoot: FunctionComponent<ISidebarRootProps> = ({
  * - Activating the active entry or an inert one emits nothing; no render emits anything. Entries are
  *   non-submitting `type="button"` buttons with native Tab/Enter/Space behaviour - no tabs/menu model.
  * - An inert entry stays visible but muted and disabled, so Tab skips it and activation is inert too.
+ * - A label is rendered in full inside its entry, in either arrangement: a phrase wraps at its spaces
+ *   and a word wider than the track breaks within itself. Nothing is truncated, renamed or hidden
+ *   behind a tooltip, no horizontal scrolling is introduced, and a translated label neither widens
+ *   the 12rem track nor displaces the content.
  * - At and above 64rem the nav is a fixed 12rem track, sticky at the top of the scrolling area with no
  *   assumed top-bar offset, capped to the screen/scrolling-area height with independent entry scrolling.
  *   Content sits beside it in `minmax(0,1fr)`, so wide content cannot displace the track.

package/src/Theme/Palette.ts

@@ -9,7 +9,8 @@
  *
  * Light and dark are two complete sets of the same roles rather than a set of `dark:` overrides
  * scattered through the components. A component therefore carries no dark-mode classes at all:
- * swapping the `.dark` class re-points the variables underneath it.
+ * swapping the `.dark` class re-points the variables underneath it. Complete means `Required`: the
+ * two roles the type marks optional are optional for a consumer's palette object, never here.
  *
  * The values below are still depot-tracker's brand (primary is its violet). They are carried over
  * so nothing changed visually during the extraction - a starting point to replace, not a decision.
@@ -121,8 +122,28 @@ export type PaletteTokens = {
    *  constraint stated on `success`. */
   warning: string;
   /** The error status tone. Carries the general status-tone contract and 4.5:1-against-`surface`
-   *  constraint stated on `success`, plus the depletion-path constraint stated on `meterFill`. */
+   *  constraint stated on `success`, plus the depletion-path constraint stated on `meterFill`. It is
+   *  also Button's destructive fill (#119), identified like `primary` by the fill alone: at least 3:1
+   *  against `surface` in the same theme, `errorHover` included - which the 4.5:1 text floor already
+   *  clears - and constrained from the other side by the ink it carries, stated on `errorForeground`.
+   *  See docs/adr/0011-status-tones-are-general-roles.md, Amendments. */
   error: string;
+  /** The destructive fill's hover step. Constraint (WCAG 2.2 SC 1.4.11): at least 3:1 against
+   *  `surface` in the same theme, and at least 4.5:1 against `errorForeground`, since a hovered
+   *  control has to stay identifiable and readable too. Not a status tone: it carries no text of its
+   *  own and the status-tone text floor does not apply to it. Optional in the type so a palette
+   *  object written before #119 keeps compiling: the shipped stylesheet declares `--color-error-hover`,
+   *  and a theme that omits the role inherits that default - which pairs with the shipped `error`,
+   *  so a theme that re-points `error` re-points this too. */
+  errorHover?: string;
+  /** Text and icons drawn on top of `error` and `errorHover`. Constraint (WCAG 2.2 SC 1.4.3): at
+   *  least 4.5:1 against both in the same theme, hover included. Optional in the type for the same
+   *  reason as `errorHover`, with the same obligation: the shipped default is the ink for the
+   *  shipped `error`. The ink inverts with the theme as `primaryForeground` does, and in light it is
+   *  pure white rather than slate-50 because the shipped `error` sits exactly on the 4.5:1 floor
+   *  against white (4.501:1) and slate-50 measures 4.30:1 - under it. Not required against
+   *  `disabled`, which SC 1.4.3 exempts. */
+  errorForeground?: string;
   /** The informational status tone. Carries the general status-tone contract and
    *  4.5:1-against-`surface` constraint stated on `success`. */
   info: string;
@@ -147,7 +168,7 @@ export type PaletteTokens = {
  *   against `#0f172a`, the dark set's own `surface`, sky-600 lands at 4.36 and fails. It also buys
  *   a light theme with white text on one button and black on the one beside it.
  */
-export const light: PaletteTokens = {
+export const light: Required<PaletteTokens> = {
   surface: '#ffffff',
   foreground: '#0f172a',
   muted: '#64748b',
@@ -179,6 +200,8 @@ export const light: PaletteTokens = {
   success: '#047857',
   warning: '#b45309',
   error: '#d63384',
+  errorHover: '#be185d',
+  errorForeground: '#ffffff',
   info: '#0e7490',
 };
 
@@ -193,11 +216,14 @@ export const light: PaletteTokens = {
  * under its darker ones. The pair is the two ends of the one neutral ramp the rest of the palette is
  * already built from - `#f8fafc` is slate-50, `surface` slate-900, `muted` slate-500 - rather than a
  * new colour arriving for a single job. `#020617` is also the lightest slate step that still admits
- * violet-500 and sky-600, which is what leaves this set's `secondary` pair unmoved: slate-900 draws
- * 4.22 and 4.36 against them and fails. Why the ink follows the theme at all, and the two routes
- * rejected in getting here: see the light set.
+ * violet-500: slate-900 draws 4.22 against it and fails. The `secondary` pair sits one ramp step
+ * above where it first shipped - sky-500 at rest, sky-400 on hover, where it was sky-600 and sky-500 -
+ * because #119 made `secondary` an ink as well as a fill: the outlined Button draws its text and edge
+ * in it, and sky-600 measures 4.36:1 against this surface, under the 4.5:1 text floor (now 6.44:1
+ * and 8.33:1, both still clearing `secondaryForeground` at 7.28:1 and 9.42:1). Why the ink follows
+ * the theme at all, and the two routes rejected in getting here: see the light set.
  */
-export const dark: PaletteTokens = {
+export const dark: Required<PaletteTokens> = {
   surface: '#0f172a',
   foreground: '#f8fafc',
   muted: '#94a3b8',
@@ -215,8 +241,8 @@ export const dark: PaletteTokens = {
   primaryHover: '#a78bfa',
   primaryForeground: '#020617',
 
-  secondary: '#0284c7',
-  secondaryHover: '#0ea5e9',
+  secondary: '#0ea5e9',
+  secondaryHover: '#38bdf8',
   secondaryForeground: '#020617',
 
   disabled: '#475569',
@@ -229,5 +255,7 @@ export const dark: PaletteTokens = {
   success: '#34d399',
   warning: '#fbbf24',
   error: '#f48fb1',
+  errorHover: '#f8bbd0',
+  errorForeground: '#020617',
   info: '#22d3ee',
 };