@eifi1/ui-kit 0.33.1 → 0.34.0

package/src/components/spinner.tsx

@@ -0,0 +1,81 @@
+import type { ComponentPropsWithRef } from "react";
+import { cn } from "../lib/cn";
+import { DEFAULT_COMMON_LABELS, useKitLabels } from "../i18n/kit-labels";
+
+/** A `<span>`'s props plus the words a reader hears — see {@link CardHeaderProps}.
+ *  The ring is drawn with a border, so there is nothing inside it to put children in. */
+export interface SpinnerProps extends Omit<ComponentPropsWithRef<"span">, "children"> {
+  /**
+   * What the spinner means, for a screen reader. Default: `common.loading` from the
+   * {@link UiKitProvider}, else "Loading…".
+   *
+   * `null` makes it DECORATIVE — no role, no text, hidden from assistive tech. Use it
+   * whenever words are already there: beside visible "Loading…" text (otherwise it is
+   * announced twice), inside a labelled button (otherwise its text joins the button's
+   * name), or inside a live region of the app's own (otherwise that region and this
+   * one both announce).
+   */
+  label?: string | null;
+  /**
+   * Show the label as TEXT beside the ring, not only to a screen reader. kastlan's
+   * LoadingState (feedback/loading-state.tsx:14) builds exactly this by hand — a
+   * `role="status"` wrapper, the spinner at `label={null}`, a `<p>` of text — so it
+   * has to get the three-part aria arrangement right itself. Here the visible text IS
+   * the live region's content (the label stays the accessible name, said once), and
+   * the ring is decorative. `className` still sizes the ring; the other props go on
+   * the wrapper. Ignored with `label={null}`: there are no words to show.
+   */
+  showLabel?: boolean;
+  /** Where the shown label sits: `end` (default) — beside the ring, for a row or a
+   *  button; `below` — under it, centred, for a panel's loading state. */
+  labelPosition?: "end" | "below";
+}
+
+/**
+ * A spinning ring that also SAYS it is loading.
+ *
+ * It used to be a bordered span and nothing else, so a reader met no element at all
+ * where a sighted user saw the page working — or, beside an emptied list, met the
+ * empty list and concluded there was nothing there. `role="status"` makes it a polite
+ * live region, and the text inside is what that region announces. Text rather than
+ * `aria-label`: a live region's announcement is its CONTENT, and several readers
+ * ignore a name on one.
+ *
+ * `relative` so the `sr-only` text has a local containing block (see
+ * sr-only-containment.test). Where the words are already on screen, pass
+ * `label={null}`: announcing is right for a spinner standing alone and wrong for one
+ * beside text, inside a button, or inside the app's own live region.
+ */
+export function Spinner({ className, label, showLabel, labelPosition = "end", ...rest }: SpinnerProps) {
+  const common = useKitLabels("common", DEFAULT_COMMON_LABELS, {
+    loading: label ?? undefined,
+  });
+  const ring = cn(
+    "relative inline-block h-5 w-5 animate-spin rounded-full border-2 border-subtle border-t-[var(--text-primary)]",
+    className,
+  );
+  if (label === null) return <span aria-hidden {...rest} className={ring} />;
+  if (showLabel) {
+    return (
+      <span
+        role="status"
+        {...rest}
+        className={cn(
+          "inline-flex items-center text-sm text-secondary",
+          labelPosition === "below" ? "flex-col gap-2 text-center" : "gap-2",
+        )}
+      >
+        <span aria-hidden className={ring} />
+        <span>{common.loading}</span>
+      </span>
+    );
+  }
+  return (
+    <span role="status" {...rest} className={ring}>
+      {/* The trailing space is a separator for the case the caller forgot `label={null}`
+          inside a button: a name is the concatenation of its text, and without it the
+          spinner's word ran straight into the button's — "Loadingconfirm". */}
+      <span className="sr-only">{common.loading} </span>
+    </span>
+  );
+}

package/src/components/stat-tile-labels.ts

@@ -0,0 +1,15 @@
+// The English words of ./stat-tile, in a module with no component code: the English
+// catalogue (src/i18n/defaults.ts) imports them without the component, so `en` loads as one
+// chunk like the other languages (0.34, KS U8). ./stat-tile re-exports them.
+
+import type { StatTileLabels } from "./stat-tile";
+
+export const DEFAULT_STAT_TILE_LABELS: StatTileLabels = {
+  increase: (amount) => `Up ${amount}`,
+  decrease: (amount) => `Down ${amount}`,
+  unchanged: "No change",
+  better: (change) => `${change} (better)`,
+  worse: (change) => `${change} (worse)`,
+  noValue: "No data",
+  loading: "Loading…",
+};

package/src/components/stat-tile.tsx

@@ -1,10 +1,11 @@
 import { createContext, isValidElement, useContext, useId, useLayoutEffect, useState } from "react";
-import type { ComponentPropsWithoutRef, CSSProperties, ReactElement, ReactNode } from "react";
+import type { ComponentPropsWithoutRef, ComponentPropsWithRef, CSSProperties, ReactElement, ReactNode } from "react";
 import { ArrowDown, ArrowUp, Minus } from "lucide-react";
 import { cn } from "../lib/cn";
-import { useKitLabels, useKitLink, useKitLocale } from "../i18n/kit-labels";
+import { useKitLabels, useKitLink, useKitLocale, type LabelOverride } from "../i18n/kit-labels";
 import { pickLinkRenderer, RenderedKitLink } from "./text-link";
-import { Card, FieldHint } from "./ui";
+import { Card } from "./card";
+import { FieldHint } from "./field-parts";
 import { useInlineFacts, useLargeText } from "../hooks/use-large-text";
 import { Sparkline } from "./sparkline";
 import { Tooltip } from "./tooltip";
@@ -12,6 +13,7 @@ import { Tooltip } from "./tooltip";
 // shimmer as one surface — and both stop under `prefers-reduced-motion`, which this
 // tile's private copy of the string did not.
 import { SKELETON_CLASS } from "./skeleton";
+import { DEFAULT_STAT_TILE_LABELS } from "./stat-tile-labels";
 
 /**
  * The words a stat tile speaks. The delta's arrow is an icon, and an icon is not a
@@ -33,15 +35,8 @@ export interface StatTileLabels {
   loading: string;
 }
 
-export const DEFAULT_STAT_TILE_LABELS: StatTileLabels = {
-  increase: (amount) => `Up ${amount}`,
-  decrease: (amount) => `Down ${amount}`,
-  unchanged: "No change",
-  better: (change) => `${change} (better)`,
-  worse: (change) => `${change} (worse)`,
-  noValue: "No data",
-  loading: "Loading…",
-};
+// Defined in ./stat-tile-labels, which holds no component code (0.34, KS U8).
+export { DEFAULT_STAT_TILE_LABELS };
 
 /**
  * What colours a figure. Token-backed like everything else in the kit.
@@ -66,15 +61,15 @@ export type StatTileTone =
   | "info";
 
 const TONE_CLASS: Record<Exclude<StatTileTone, "signed">, string> = {
-  neutral: "text-[var(--text-primary)]",
-  brand: "text-[var(--brand)]",
-  income: "text-[var(--money-income)]",
-  expense: "text-[var(--money-expense)]",
-  net: "text-[var(--money-net)]",
-  success: "text-[var(--success)]",
-  warning: "text-[var(--warning)]",
-  danger: "text-[var(--danger)]",
-  info: "text-[var(--info)]",
+  neutral: "text-primary",
+  brand: "text-brand",
+  income: "text-money-income",
+  expense: "text-money-expense",
+  net: "text-money-net",
+  success: "text-success",
+  warning: "text-warning",
+  danger: "text-danger",
+  info: "text-info",
 };
 
 function toneClass(tone: StatTileTone, value: unknown): string {
@@ -252,7 +247,7 @@ export interface StatTileProps
   renderLink?: (props: StatTileLinkProps) => ReactElement;
   /** Makes the tile a button (ignored when `href` is given). */
   onClick?: () => void;
-  labels?: Partial<StatTileLabels>;
+  labels?: LabelOverride<StatTileLabels>;
 }
 
 // One formatter per option set: a metrics wall is twenty of these.
@@ -366,7 +361,7 @@ export function StatTile({
     "after:absolute after:inset-0 after:rounded-lg after:content-['']",
     // The kit's focus frame (0.32, §5), on the overlay — `FOCUS_RING`'s classes cannot
     // carry the `after:`, so its width is spelt out.
-    "focus-visible:outline-none focus-visible:after:ring-[length:var(--focus-ring-width)] focus-visible:after:ring-inset focus-visible:after:ring-[var(--brand)]",
+    "focus-visible:outline-none focus-visible:after:ring-focus focus-visible:after:ring-inset focus-visible:after:ring-brand",
   );
   const describedBy = d ? `${valueId} ${deltaId}` : valueId;
   let labelNode: ReactNode = label;
@@ -407,11 +402,11 @@ export function StatTile({
     const dir = d.value > 0 ? "up" : d.value < 0 ? "down" : "flat";
     const Icon = dir === "up" ? ArrowUp : dir === "down" ? ArrowDown : Minus;
     let spoken = dir === "up" ? text.increase(amount) : dir === "down" ? text.decrease(amount) : text.unchanged;
-    let deltaTone = "text-[var(--text-muted)]";
+    let deltaTone = "text-muted";
     if (goodDirection && dir !== "flat") {
       const good = dir === goodDirection;
       spoken = good ? text.better(spoken) : text.worse(spoken);
-      deltaTone = good ? "text-[var(--success)]" : "text-[var(--danger)]";
+      deltaTone = good ? "text-success" : "text-danger";
     }
     deltaNode = (
       // `relative`: the containing block for the sr-only sentence (see the
@@ -424,7 +419,7 @@ export function StatTile({
           <span aria-hidden>{amount}</span>
           <span className="sr-only">{spoken}</span>
         </span>
-        {d.label != null && <span className="text-[var(--text-muted)]">{d.label}</span>}
+        {d.label != null && <span className="text-muted">{d.label}</span>}
       </div>
     );
   }
@@ -444,11 +439,11 @@ export function StatTile({
     <span id={valueId} data-private={priv} className={cn(valueClass, valueLabel != null && !large && "ms-auto")}>
       {show(value)}
       {unit != null && (
-        <span className="ms-1 text-[0.7em] font-medium text-[var(--text-muted)]">{unit}</span>
+        <span className="ms-1 text-[0.7em] font-medium text-muted">{unit}</span>
       )}
     </span>
   ) : (
-    <span id={valueId} className={cn("relative", valueClass, "text-[var(--text-muted)]")}>
+    <span id={valueId} className={cn("relative", valueClass, "text-muted")}>
       <span aria-hidden>—</span>
       <span className="sr-only">{text.noValue}</span>
     </span>
@@ -484,12 +479,12 @@ export function StatTile({
         // align with the content edge of the card they sit in. (Not `p-0` over the
         // padding: the padding's `sm:p-4` would still win from `sm` up.)
         variant === "plain" ? "rounded-none bg-transparent p-0" : PADDING[size],
-        interactive && "transition-colors hover:border-[var(--border-strong)] hover:bg-[var(--bg-hover)]",
+        interactive && "transition-colors hover:border-strong hover:bg-hover",
         className,
       )}
     >
       <div className="flex items-start gap-2">
-        <div className="flex min-w-0 flex-1 items-center gap-1 break-words text-xs uppercase tracking-wide text-[var(--text-muted)]">
+        <div className="flex min-w-0 flex-1 items-center gap-1 break-words text-xs uppercase tracking-wide text-muted">
           {truncateLabel && labelCut ? (
             // Portalled: the tile is `overflow-hidden`, and a bubble inside it would be
             // clipped by the very box whose edge cut the label.
@@ -507,7 +502,7 @@ export function StatTile({
           {hint && !inlineHint && <FieldHint label={hint} side="top" className="relative z-10 shrink-0" />}
         </div>
         {icon != null && (
-          <span aria-hidden className="shrink-0 text-[var(--text-muted)] [&_svg]:size-4">
+          <span aria-hidden className="shrink-0 text-muted [&_svg]:size-4">
             {icon}
           </span>
         )}
@@ -516,7 +511,7 @@ export function StatTile({
       {inlineHint && (
         // §4: the hint as words under the label — the same muted type as `description`,
         // in the reading case of a sentence rather than the label's capitals.
-        <p data-slot="stat-tile-hint" className="mt-0.5 text-xs text-[var(--text-muted)]">
+        <p data-slot="stat-tile-hint" className="mt-0.5 text-xs text-muted">
           {hint}
         </p>
       )}
@@ -526,7 +521,7 @@ export function StatTile({
         // too-long amount drop to its own end-aligned line instead of overflowing. At
         // Large the period goes over the figure, which then has the tile's width.
         <div className={cn("mt-1 flex items-baseline gap-x-1.5", large ? "flex-col items-start" : "flex-wrap")}>
-          <span className="shrink-0 text-xs uppercase tracking-wide text-[var(--text-muted)]">{valueLabel}</span>
+          <span className="shrink-0 text-xs uppercase tracking-wide text-muted">{valueLabel}</span>
           {headline}
         </div>
       ) : (
@@ -542,7 +537,7 @@ export function StatTile({
       )}
 
       {deltaNode}
-      {description != null && <div className="mt-1 text-xs text-[var(--text-muted)]">{description}</div>}
+      {description != null && <div className="mt-1 text-xs text-muted">{description}</div>}
       {!large && graphic && <div className="mt-2">{graphic}</div>}
 
       {!loading && ((large && projection) || (subValues && subValues.length > 0)) && (
@@ -592,7 +587,7 @@ function FigureRow({
   return (
     <div
       className={cn(
-        "flex text-xs tabular-nums text-[var(--text-muted)]",
+        "flex text-xs tabular-nums text-muted",
         stacked ? "flex-col items-start" : "items-baseline gap-x-2",
       )}
     >
@@ -650,7 +645,7 @@ function useIsTruncated(el: HTMLElement | null): boolean {
   return cut;
 }
 
-export interface StatTileGridProps extends ComponentPropsWithoutRef<"div"> {
+export interface StatTileGridProps extends ComponentPropsWithRef<"div"> {
   /** The narrowest a tile may get before the grid drops a column. The default fits
    *  two tiles on a 320px phone. */
   minTileWidth?: string;
@@ -672,7 +667,7 @@ export interface StatTileGridProps extends ComponentPropsWithoutRef<"div"> {
    */
   loading?: boolean;
   /** The grid's one sentence — `loading` from {@link StatTileLabels}. */
-  labels?: Partial<Pick<StatTileLabels, "loading">>;
+  labels?: LabelOverride<Pick<StatTileLabels, "loading">>;
 }
 
 /** Set by a loading {@link StatTileGrid}; read by each tile in it. */

package/src/components/status-dot.tsx

@@ -1,4 +1,4 @@
-import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import type { ComponentPropsWithRef, ReactNode } from "react";
 import { cn } from "../lib/cn";
 import type { ProgressBarTone } from "./progress-bar";
 import type { ChipHue } from "./chip";
@@ -18,19 +18,19 @@ export type StatusDotTone = ProgressBarTone | ChipHue;
 export type StatusDotSize = "sm" | "md" | "lg";
 
 const FILL: Record<StatusDotTone, string> = {
-  brand: "bg-[var(--brand)]",
+  brand: "bg-brand",
   neutral: "bg-[var(--text-muted)]",
-  success: "bg-[var(--success)]",
-  warning: "bg-[var(--warning)]",
-  danger: "bg-[var(--danger)]",
-  info: "bg-[var(--info)]",
-  income: "bg-[var(--money-income)]",
-  expense: "bg-[var(--money-expense)]",
-  blue: "bg-[var(--hue-blue)]",
-  indigo: "bg-[var(--hue-indigo)]",
-  purple: "bg-[var(--hue-purple)]",
-  teal: "bg-[var(--hue-teal)]",
-  orange: "bg-[var(--hue-orange)]",
+  success: "bg-success",
+  warning: "bg-warning",
+  danger: "bg-danger",
+  info: "bg-info",
+  income: "bg-money-income",
+  expense: "bg-money-expense",
+  blue: "bg-hue-blue",
+  indigo: "bg-hue-indigo",
+  purple: "bg-hue-purple",
+  teal: "bg-hue-teal",
+  orange: "bg-hue-orange",
 };
 
 /**
@@ -88,7 +88,7 @@ const DOT_ON_FIRST_LINE: Record<StatusDotSize, string> = {
   lg: "large:mt-[calc((1lh_-_0.75rem)/2)]",
 };
 
-export interface StatusDotProps extends Omit<ComponentPropsWithoutRef<"span">, "children"> {
+export interface StatusDotProps extends Omit<ComponentPropsWithRef<"span">, "children"> {
   tone?: StatusDotTone;
   size?: StatusDotSize;
   /**
@@ -133,6 +133,9 @@ export function StatusDot({
 }: StatusDotProps) {
   const dot = (
     <span
+      // The tone as data (0.34, refactor audit 2026-10, TST-9): a stable hook for a test or
+      // a caller's selector, where the fill class is the kit's to change.
+      data-tone={tone}
       className={cn(
         "inline-block shrink-0 rounded-full",
         SIZE[size],

package/src/components/swatch-picker-labels.ts

@@ -0,0 +1,10 @@
+// The English words of ./swatch-picker, in a module with no component code: the English
+// catalogue (src/i18n/defaults.ts) imports them without the component, so `en` loads as one
+// chunk like the other languages (0.34, KS U8). ./swatch-picker re-exports them.
+
+import type { SwatchPickerLabels } from "./swatch-picker";
+
+export const DEFAULT_SWATCH_PICKER_LABELS: SwatchPickerLabels = {
+  none: "No colour",
+  mixed: "Mixed: the selected items have different colours",
+};

package/src/components/swatch-picker.tsx

@@ -1,12 +1,14 @@
 import { useId, useMemo } from "react";
-import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import type { ComponentPropsWithRef, ReactNode } from "react";
 import { cn } from "../lib/cn";
-import { useKitLabels } from "../i18n/kit-labels";
+import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
 import { TILE_SIZE, TileRadioGroup } from "./tile-radio";
 import type { TileItem, TileSize } from "./tile-radio";
 import { Tooltip } from "./tooltip";
 import { useCommitReason, type CommitScope } from "./write-lock";
-import { hasContent, LabelStrip } from "./field-parts";
+import { hasContent } from "../lib/presence";
+import { LabelStrip, mergeDescribedBy, useFieldMessages } from "./field-parts";
+import { DEFAULT_SWATCH_PICKER_LABELS } from "./swatch-picker-labels";
 
 export interface SwatchPickerLabels {
   /** The "no colour" tile's name, when `allowNone` is set. */
@@ -15,10 +17,8 @@ export interface SwatchPickerLabels {
   mixed: string;
 }
 
-export const DEFAULT_SWATCH_PICKER_LABELS: SwatchPickerLabels = {
-  none: "No colour",
-  mixed: "Mixed: the selected items have different colours",
-};
+// Defined in ./swatch-picker-labels, which holds no component code (0.34, KS U8).
+export { DEFAULT_SWATCH_PICKER_LABELS };
 
 export interface SwatchOption<T extends string> {
   value: T;
@@ -62,7 +62,7 @@ export interface SwatchOption<T extends string> {
  * is omitted rather than shadowed, as on {@link ToggleGroup}.
  */
 export interface SwatchPickerProps<T extends string>
-  extends Omit<ComponentPropsWithoutRef<"div">, "onChange" | "children" | "defaultValue"> {
+  extends Omit<ComponentPropsWithRef<"div">, "onChange" | "children" | "defaultValue"> {
   options: SwatchOption<T>[];
   /** The chosen colour, or `null` for none. */
   value: T | null;
@@ -90,7 +90,7 @@ export interface SwatchPickerProps<T extends string>
    */
   tileClassName?: string;
   disabled?: boolean;
-  labels?: Partial<SwatchPickerLabels>;
+  labels?: LabelOverride<SwatchPickerLabels>;
   /**
    * An 11px static label in a strip over the swatches, named by it (keksdose K2): the
    * transaction row's flag picker stands between labelled fields and hand-builds this
@@ -101,7 +101,9 @@ export interface SwatchPickerProps<T extends string>
    * explicit `aria-label` / `aria-labelledby` still names the group instead.
    */
   label?: ReactNode;
-  /** A {@link FieldHint} beside the label. Only with `label`. */
+  /** A {@link FieldHint} beside the label. Only with `label`. {@link Select}'s rule since
+   *  0.34 (DUP-2, refactor audit 2026-10): plain TEXT, and a FieldHint at Large and on a
+   *  touch screen (§4), is a caption under the swatches, describing the group. */
   hint?: ReactNode;
   /**
    * Why the colour cannot be changed right now — {@link Button}'s `disabledReason`, for
@@ -155,6 +157,13 @@ export function SwatchPicker<T extends string>({
   const disabledReason = useCommitReason(commit, ownDisabledReason);
   const locked = hasContent(disabledReason);
   const labelled = hasContent(label);
+  // The label line's "?", or the caption under the swatches (DUP-2). Only with a label.
+  // The caller's ids, the caption, then the group's state: mixed, locked.
+  const messages = useFieldMessages({
+    hint: labelled ? hint : undefined,
+    describedBy: rest["aria-describedby"],
+    reasonId: mergeDescribedBy(mixed && mixedId, locked && reasonId),
+  });
   const byValue = useMemo(() => new Map(options.map((o) => [o.value, o])), [options]);
   const items: TileItem<T>[] = [
     ...(allowNone ? [{ key: null, label: text.none }] : []),
@@ -189,7 +198,7 @@ export function SwatchPicker<T extends string>({
                 // not-allowed cursor, and no hover offer on a tile that cannot be
                 // chosen. Not on the selected tile, whose frame IS its state.
                 locked && "cursor-not-allowed opacity-50",
-                locked && !selected && "hover:border-[var(--border)] hover:bg-[var(--bg-surface)]",
+                locked && !selected && "hover:border-subtle hover:bg-surface",
                 tileClassName,
               )
           : undefined
@@ -222,10 +231,7 @@ export function SwatchPicker<T extends string>({
           : rest["aria-labelledby"]
       }
       aria-disabled={disabled || locked || undefined}
-      aria-describedby={
-        [rest["aria-describedby"], mixed && mixedId, locked && reasonId].filter(Boolean).join(" ") ||
-        undefined
-      }
+      aria-describedby={messages.describedBy}
       className={cn("flex flex-wrap items-center gap-1.5", !labelled && className)}
     >
       {locked ? (
@@ -259,8 +265,9 @@ export function SwatchPicker<T extends string>({
   );
   if (!labelled) return group;
   return (
-    <LabelStrip labelId={labelId} label={label} hint={hint} disabled={disabled || locked} pad="clear" className={className}>
+    <LabelStrip labelId={labelId} label={label} hint={messages.labelHint} disabled={disabled || locked} className={className}>
       {group}
+      {messages.below}
     </LabelStrip>
   );
 }

package/src/components/swipeable-row.tsx

@@ -75,12 +75,12 @@ export type SwipeAction = SwipeActionBase &
     | {
         tone?: never;
         paint?: never;
-        /** @deprecated 0.33 — pass `tone`, or `paint` for an exception. Background
-         *  utility class while the action is previewed but not yet armed; the panel is
-         *  dimmed then, and its text is white unless this sets a text colour. */
+        /** @deprecated 0.33 — pass `tone`, or `paint` for an exception; removed in 0.35.
+         *  Background utility class while the action is previewed but not yet armed; the
+         *  panel is dimmed then, and its text is white unless this sets a text colour. */
         className: string;
-        /** @deprecated 0.33 — pass `tone`, or `paint`. Background utility class once
-         *  the drag has passed this action's threshold. */
+        /** @deprecated 0.33 — pass `tone`, or `paint`; removed in 0.35. Background
+         *  utility class once the drag has passed this action's threshold. */
         armedClassName: string;
       }
   );
@@ -337,7 +337,7 @@ export function SwipeableRow({
           e.stopPropagation();
         }}
         className={cn(
-          "relative bg-[var(--bg-surface)]",
+          "relative bg-surface",
           // A mouse drag is a supported way to swipe (use-row-swipe gates only on
           // the button, not the pointer type), and a horizontal mouse drag over
           // text also SELECTS that text — so committing an action left the row
@@ -380,7 +380,7 @@ export function SwipeableRow({
               type="button"
               onClick={action.onCommit}
               className={cn(
-                "sr-only whitespace-nowrap rounded-md border-[var(--border)] bg-[var(--bg-surface)] text-xs font-medium text-[var(--text-primary)] shadow-sm",
+                "sr-only whitespace-nowrap rounded-md border-subtle bg-surface text-xs font-medium text-primary shadow-sm",
                 "focus:not-sr-only focus:pointer-events-auto focus:inline-flex focus:items-center focus:gap-1.5",
                 // The box's padding and border only once it shows (0.32.1, keksdose's
                 // 0.32 report). Unconditional, `px-2` and `border` beat `sr-only`'s

package/src/components/switch.tsx

@@ -1,10 +1,11 @@
-import { forwardRef, useId } from "react";
-import type { ChangeEvent, InputHTMLAttributes, ReactNode } from "react";
+import { useId } from "react";
+import type { ChangeEvent, InputHTMLAttributes, ReactNode, Ref } from "react";
 import { cn } from "../lib/cn";
-import { hasMessage, mergeDescribedBy } from "./choice-parts";
+import { hasContent } from "../lib/presence";
 import {
   DISABLED_REASON_LINE_CLASS,
   LockedReason,
+  mergeDescribedBy,
   useDisabledReasonLine,
   useLockReason,
   type DisabledReasonDisplay,
@@ -49,9 +50,9 @@ export type SwitchSize = keyof typeof SIZES;
 // difference in SHAPE, so the state never rests on colour alone.
 const TRACK =
   "peer block shrink-0 cursor-pointer appearance-none rounded-full bg-[var(--border-strong)] transition-colors " +
-  "checked:bg-[var(--brand)] " +
+  "checked:bg-brand " +
   // The kit's focus frame (§5), stood off the track so it never merges with the fill.
-  `focus:outline-none ${FOCUS_RING} focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-surface)] ` +
+  `focus:outline-none ${FOCUS_RING} focus-visible:ring-offset-2 focus-visible:ring-offset-surface ` +
   "disabled:cursor-not-allowed";
 
 // The thumb, laid over the input and ignoring the pointer so every click still reaches
@@ -59,7 +60,7 @@ const TRACK =
 // match the fill in some presets, and the contrast token is the one guaranteed to read
 // against --brand.
 const THUMB =
-  "pointer-events-none absolute start-0.5 top-1/2 -translate-y-1/2 rounded-full bg-[var(--bg-surface)] shadow-sm " +
+  "pointer-events-none absolute start-0.5 top-1/2 -translate-y-1/2 rounded-full bg-surface shadow-sm " +
   "transition-[inset-inline-start,background-color] motion-reduce:transition-none " +
   "peer-checked:bg-[var(--brand-contrast)]";
 
@@ -119,6 +120,9 @@ export interface SwitchProps extends Omit<InputHTMLAttributes<HTMLInputElement>,
    * own). No provider, or an unlocked one: no effect. Button's `commit`, for K3.
    */
   commit?: CommitScope;
+  /** The `<input type="checkbox" role="switch">`. A React 19 ref prop since 0.34 (MOD-4,
+   *  refactor audit 2026-10); it was `forwardRef`. */
+  ref?: Ref<HTMLInputElement>;
 }
 
 /**
@@ -128,27 +132,25 @@ export interface SwitchProps extends Omit<InputHTMLAttributes<HTMLInputElement>,
  * `onChange`/`onCheckedChange`), uncontrolled (`defaultChecked`) and in a plain
  * `<form>` (`name`, `value`).
  */
-export const Switch = forwardRef<HTMLInputElement, SwitchProps>(function Switch(
-  {
-    size = "md",
-    label,
-    description,
-    switchPosition = "end",
-    onCheckedChange,
-    onChange,
-    className,
-    inputClassName,
-    id,
-    disabled,
-    required,
-    disabledReason,
-    disabledReasonDisplay,
-    commit,
-    onClick,
-    ...rest
-  },
+export function Switch({
   ref,
-) {
+  size = "md",
+  label,
+  description,
+  switchPosition = "end",
+  onCheckedChange,
+  onChange,
+  className,
+  inputClassName,
+  id,
+  disabled,
+  required,
+  disabledReason,
+  disabledReasonDisplay,
+  commit,
+  onClick,
+  ...rest
+}: SwitchProps) {
   const generated = useId();
   const inputId = id ?? generated;
   const lock = useLockReason(commit, disabledReason);
@@ -158,7 +160,7 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(function Switch(
   // click, as for `disabled`.
   const looksDisabled = Boolean(disabled) || locked;
   const descriptionId = `${inputId}-description`;
-  const showDescription = hasMessage(description);
+  const showDescription = hasContent(description);
   const bare = label === undefined && !showDescription;
   const geometry = SIZES[size];
 
@@ -227,21 +229,21 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(function Switch(
         <label
           htmlFor={inputId}
           className={cn(
-            "block text-sm leading-5 text-[var(--text-primary)]",
+            "block text-sm leading-5 text-primary",
             looksDisabled ? "cursor-not-allowed" : "cursor-pointer select-none",
             dimParts && "opacity-60",
           )}
         >
           {label}
           {required && (
-            <span aria-hidden className="ms-0.5 text-[var(--danger)]">
+            <span aria-hidden className="ms-0.5 text-danger">
               *
             </span>
           )}
         </label>
       )}
       {showDescription && (
-        <span id={descriptionId} className={cn("mt-0.5 block text-xs text-[var(--text-muted)]", dimParts && "opacity-60")}>
+        <span id={descriptionId} className={cn("mt-0.5 block text-xs text-muted", dimParts && "opacity-60")}>
           {description}
         </span>
       )}
@@ -268,5 +270,4 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(function Switch(
       )}
     </div>
   );
-});
-Switch.displayName = "Switch";
+}