@eifi1/ui-kit 0.33.0 → 0.34.0

package/src/components/appearance-labels.ts

@@ -1,4 +1,4 @@
-import { useKitLabels } from "../i18n/kit-labels";
+import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
 import type { ContrastMode } from "../theme/contrast";
 import type { TextSize } from "../theme/text-size";
 
@@ -42,6 +42,6 @@ export const DEFAULT_APPEARANCE_LABELS: AppearanceLabels = {
 
 /** The `appearance` namespace, resolved — English, then the provider, then `labels`. For
  *  an app's catalogue entries and quick switches, without restating the defaults. */
-export function useAppearanceLabels(labels?: Partial<AppearanceLabels>): AppearanceLabels {
+export function useAppearanceLabels(labels?: LabelOverride<AppearanceLabels>): AppearanceLabels {
   return useKitLabels("appearance", DEFAULT_APPEARANCE_LABELS, labels);
 }

package/src/components/authed-image-labels.ts

@@ -0,0 +1,11 @@
+// The English words of ./authed-image, 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). ./authed-image re-exports them.
+
+import type { AuthedImageLabels } from "./authed-image";
+
+export const DEFAULT_AUTHED_IMAGE_LABELS: AuthedImageLabels = {
+  loading: "Loading image…",
+  loadError: "Image couldn’t be loaded",
+  failedImage: (alt) => `${alt}: image couldn’t be loaded`,
+};

package/src/components/authed-image.tsx

@@ -3,10 +3,11 @@ import type { ImgHTMLAttributes, ReactNode } from "react";
 import { ImageOff } from "lucide-react";
 
 import { cn } from "../lib/cn";
-import { useKitLabels } from "../i18n/kit-labels";
+import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
 import { SKELETON_CLASS } from "./skeleton";
 import { useAuthedSrc } from "../hooks/use-authed-src";
 import type { AuthedFetcher, UseAuthedSrcResult } from "../hooks/use-authed-src";
+import { DEFAULT_AUTHED_IMAGE_LABELS } from "./authed-image-labels";
 
 /** The two states an image can be in besides "there". */
 export interface AuthedImageLabels {
@@ -18,11 +19,8 @@ export interface AuthedImageLabels {
   failedImage: (alt: string) => string;
 }
 
-export const DEFAULT_AUTHED_IMAGE_LABELS: AuthedImageLabels = {
-  loading: "Loading image…",
-  loadError: "Image couldn’t be loaded",
-  failedImage: (alt) => `${alt}: image couldn’t be loaded`,
-};
+// Defined in ./authed-image-labels, which holds no component code (0.34, KS U8).
+export { DEFAULT_AUTHED_IMAGE_LABELS };
 
 export interface AuthedImageProps
   extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "alt" | "children"> {
@@ -56,7 +54,7 @@ export interface AuthedImageProps
    * of also running the row's action. As TextLink's and IconButton's `stopPropagation`.
    */
   stopPropagation?: boolean;
-  labels?: Partial<AuthedImageLabels>;
+  labels?: LabelOverride<AuthedImageLabels>;
 }
 
 /**
@@ -197,7 +195,7 @@ export function ImageStates({
             // the one fact a reader needs about it.
             role="img"
             aria-label={alt ? labels.failedImage(alt) : labels.loadError}
-            className="flex h-full min-h-16 w-full flex-col items-center justify-center gap-1 bg-[var(--bg-hover)] p-2 text-center text-xs text-[var(--text-muted)]"
+            className="flex h-full min-h-16 w-full flex-col items-center justify-center gap-1 bg-hover p-2 text-center text-xs text-muted"
           >
             <ImageOff aria-hidden className="size-5 shrink-0" />
             <span aria-hidden className="line-clamp-2">{labels.loadError}</span>

package/src/components/autocomplete.tsx

@@ -1,15 +1,12 @@
-import { Fragment, forwardRef, useId, useRef, useState } from "react";
-import type {
-  ComponentPropsWithoutRef,
-  ForwardedRef,
-  ReactElement,
-  ReactNode,
-  RefAttributes,
-} from "react";
+import { Fragment, useId, useRef, useState } from "react";
+import type { ComponentPropsWithoutRef, ReactNode, Ref } from "react";
 import { createPortal } from "react-dom";
 import { cn } from "../lib/cn";
-import { FIELD_BASE, FIELD_FLOATING_PAD, FIELD_INVALID, Spinner } from "./ui";
+import { FIELD_BASE, FIELD_FLOATING_PAD, FIELD_INVALID } from "./field-base";
+import { Spinner } from "./spinner";
 import { useAnchoredPanel } from "../hooks/use-anchored-panel";
+import { takeEscape, useDismissLayer } from "../hooks/use-dismiss";
+import { isImeEnter } from "../lib/ime";
 import { useAnchorDir } from "./use-anchor-dir";
 import {
   ComboboxFieldLabel,
@@ -17,8 +14,9 @@ import {
   endHintRowProps,
   isOptionEnabled,
   stepEnabled,
+  SUGGESTION_LIST_CLASS,
+  suggestionRowClass,
   useActiveOptionScroll,
-  useComboboxFieldError,
   useOptionSource,
   type ComboOption,
 } from "./combobox-core";
@@ -28,11 +26,13 @@ import {
   FieldCaption,
   LABEL_IN_ROW,
   LockedReason,
+  mergeDescribedBy,
   StaticLabelRow,
+  useFieldError,
   useFieldHint,
   useLockReason,
+  type DisabledReasonDisplay,
 } from "./field-parts";
-import { mergeDescribedBy } from "./choice-parts";
 import type { CommitScope } from "./write-lock";
 
 /**
@@ -163,13 +163,48 @@ export interface AutocompleteProps<V extends string | number = string>
    * stays live under the lock. No provider, or an unlocked one: no effect.
    */
   commit?: CommitScope;
+  /** Where the reason shows — {@link Button}'s `disabledReasonDisplay`: a line under the
+   *  field at Large and on a touch screen by default, the tooltip otherwise (DUP-3). */
+  disabledReasonDisplay?: DisabledReasonDisplay;
+  /** The `<input>`. A React 19 ref prop since 0.34 (MOD-4, refactor audit 2026-10): it was
+   *  `forwardRef`, cast back to a generic function, with a `displayName` line beside it. */
+  ref?: Ref<HTMLInputElement>;
 }
 
-function AutocompleteInner<V extends string | number = string>(
-  props: AutocompleteProps<V>,
-  ref: ForwardedRef<HTMLInputElement>,
-) {
+/**
+ * An inline, async-capable text field with a suggestion list under it — the
+ * WAI-ARIA APG "editable combobox with list autocomplete".
+ *
+ * Two jobs, one control:
+ *  - **free text** (kastlan's address field): the text is the value, the list only
+ *    offers completions, and taking one fills the field (`fillOnSelect`, default);
+ *  - **search-then-act** (keksdose's address search): the text is a query, taking a
+ *    row calls `onSelect` and nothing is held (`fillOnSelect={false}`).
+ *
+ * How it differs from its siblings: {@link Combobox} is free text over a STATIC
+ * string pool and opens on focus; {@link EntityCombobox} is a trigger holding an id.
+ * This one keeps no value of its own, never resets the text, asks nothing below
+ * `minChars`, and reports a failed lookup instead of showing stale rows.
+ *
+ * Focus never leaves the `<input>`: `aria-activedescendant` names the highlighted
+ * row, `aria-controls` the list, and a polite live region says what the list now
+ * holds. Keyboard: ↓/↑ move (↓ opens) over every row but a `disabled` one, Enter
+ * takes the highlighted row (with none,
+ * Enter is left to the form), Escape closes, Tab closes and moves on; Home/End stay
+ * with the caret. An Escape that closes an open list is consumed and never reaches the
+ * caller; with the list closed it does. For every other key a caller's `onKeyDown`
+ * runs first and may `preventDefault()` to
+ * keep a key for itself.
+ *
+ * The list is portalled and anchored under the field on every screen size: the
+ * field already carries the keyboard, and `useAnchoredPanel` keeps the list clear
+ * of it on a phone. There is no full-screen sheet as {@link Combobox} has.
+ *
+ * Generic over the option value (`ComboOption<V>`); the ref is the `<input>`'s.
+ */
+export function Autocomplete<V extends string | number = string>(props: AutocompleteProps<V>) {
   const {
+    ref,
     value,
     onChange,
     options,
@@ -196,6 +231,7 @@ function AutocompleteInner<V extends string | number = string>(
     id,
     disabled,
     disabledReason,
+    disabledReasonDisplay,
     commit,
     onKeyDown,
     onFocus,
@@ -217,7 +253,9 @@ function AutocompleteInner<V extends string | number = string>(
     loadError: loadErrorLabel,
   });
   const hintParts = useFieldHint(hint, ariaDescribedBy);
-  const field = useComboboxFieldError(error, invalid, hintParts.describedBy);
+  // A form library's `aria-invalid` paints as well as announces (DUP-8: it only
+  // announced, through the spread below).
+  const field = useFieldError(error, invalid, hintParts.describedBy, rest["aria-invalid"]);
 
   /** The user's intent: the field is focused and the list has not been dismissed.
    *  Whether anything SHOWS is decided below, from what there is to show. */
@@ -266,13 +304,15 @@ function AutocompleteInner<V extends string | number = string>(
   // the highlight put one there.
   const activeId = expanded && isOptionEnabled(results[active]) ? optionId(active) : undefined;
   useActiveOptionScroll(activeId);
-  const { rect, top, maxHeight } = useAnchoredPanel(fieldRef, expanded, { preferredHeight: 256 });
+  const { rect, top, bottom, maxHeight, above } = useAnchoredPanel(fieldRef, expanded, { preferredHeight: 256 });
   const dir = useAnchorDir(fieldRef, expanded);
 
   const close = () => {
     setOpen(false);
     setActive(-1);
   };
+  // The list is a layer on the kit's Escape stack while it shows (Wave 2, DUP-1).
+  useDismissLayer(expanded, close);
   const take = (o: ComboOption<V>) => {
     if (o.disabled || locked) return;
     if (fillOnSelect) onChange(o.label);
@@ -293,7 +333,7 @@ function AutocompleteInner<V extends string | number = string>(
   // copy of the reason, Button's anatomy; `block` so a full-width field stays full width.
   const withLock = (box: ReactNode) =>
     locked ? (
-      <LockedReason lock={lock} className="block">
+      <LockedReason lock={lock} display={disabledReasonDisplay} className="block">
         {box}
       </LockedReason>
     ) : (
@@ -322,7 +362,7 @@ function AutocompleteInner<V extends string | number = string>(
               <span
                 aria-hidden
                 className={cn(
-                  "pointer-events-none absolute flex text-[var(--text-muted)]",
+                  "pointer-events-none absolute flex text-muted",
                   small ? "start-2 [&>svg]:size-3.5" : "start-2.5 [&>svg]:size-4",
                   // Labelled, the icon sits on the VALUE's line — the one line box below
                   // FIELD_FLOATING_PAD's `pt-4` and the 1px border — not on the middle of
@@ -392,12 +432,7 @@ function AutocompleteInner<V extends string | number = string>(
                 // the caller sees it. A caller whose Escape means "close the panel" (keksdose's
                 // address search) otherwise closed the whole panel when the user only meant
                 // to dismiss the suggestions — the opposite of what the docs promised.
-                if (e.key === "Escape" && expanded) {
-                  e.preventDefault();
-                  e.stopPropagation();
-                  close();
-                  return;
-                }
+                if (e.key === "Escape" && expanded && takeEscape(e)) return;
                 onKeyDown?.(e);
                 if (e.defaultPrevented) return;
                 // Disabled rows are passed over; at either end the highlight stays put.
@@ -412,8 +447,9 @@ function AutocompleteInner<V extends string | number = string>(
                   else setActive((i) => stepEnabled(results, i < 0 ? results.length : i, -1));
                 } else if (e.key === "Enter") {
                   // No row highlighted: the text is the answer, and a form's own submit
-                  // is left alone.
-                  if (expanded && activeId) {
+                  // is left alone. Nor is a row taken by the Enter that confirms an IME
+                  // composition, which is the IME's (BUG-9).
+                  if (expanded && activeId && !isImeEnter(e)) {
                     e.preventDefault();
                     take(results[active]);
                   }
@@ -483,8 +519,13 @@ function AutocompleteInner<V extends string | number = string>(
             // exactly the field's width, so `left` places it in either direction.
             dir={dir}
             onMouseDown={(e) => e.preventDefault()}
-            className="fixed z-50 flex flex-col overflow-hidden rounded-md border border-[var(--border)] bg-[var(--bg-surface)] shadow-lg"
-            style={{ top, left: rect.left, width: rect.width, maxHeight }}
+            // The family's suggestion box (DUP-4), as a column: the list scrolls inside
+            // it and the status line stays under the rows.
+            className={cn(SUGGESTION_LIST_CLASS, "fixed z-50 flex flex-col overflow-hidden py-0")}
+            // Flipped above, the list hangs from its bottom edge: three rows under a
+            // 256 px cap, placed by `top`, floated ~176 px above the field (keksdose K1),
+            // and the rows come and go as the user types.
+            style={{ ...(above ? { bottom } : { top }), left: rect.left, width: rect.width, maxHeight }}
           >
             {results.length > 0 && (
               <ul
@@ -503,7 +544,7 @@ function AutocompleteInner<V extends string | number = string>(
                       {startsGroup && (
                         <li
                           role="presentation"
-                          className="px-3 pb-0.5 pt-2 text-caption font-semibold uppercase tracking-wide text-[var(--text-muted)] first:pt-1"
+                          className="px-3 pb-0.5 pt-2 text-caption font-semibold uppercase tracking-wide text-muted first:pt-1"
                         >
                           {o.group}
                         </li>
@@ -526,29 +567,30 @@ function AutocompleteInner<V extends string | number = string>(
                             if (!o.disabled) setActive(i);
                           }}
                           className={cn(
-                            "flex w-full items-center gap-2 px-3 text-start",
-                            small ? "py-1 text-xs" : "py-1.5 text-sm",
-                            o.disabled
-                              ? DISABLED_ROW_CLASS
-                              : i === active
-                                ? "bg-[var(--bg-active)]"
-                                : "hover:bg-[var(--bg-hover)]",
+                            // The family's suggestion row (DUP-4): it hand-rolled its
+                            // own with a plain `truncate`, so a long address was cut at
+                            // Large, where Combobox's rows wrap (text size §10.17, T1).
+                            // A flex row here, for the icon and the two lines.
+                            suggestionRowClass(i === active && !o.disabled),
+                            "flex items-center gap-2",
+                            small && "py-1 text-xs",
+                            o.disabled && DISABLED_ROW_CLASS,
                             o.group != null && "ps-6",
                           )}
                         >
                           {o.icon && (
-                            <span aria-hidden className="shrink-0 text-[var(--text-muted)]">
+                            <span aria-hidden className="shrink-0 text-muted">
                               {o.icon}
                             </span>
                           )}
                           <span className="min-w-0 flex-1">
-                            <span className="block truncate text-[var(--text-primary)]">
+                            <span className="block truncate-until-large text-primary">
                               {o.label}
                             </span>
                             {o.sublabel && (
                               <span
                                 className={cn(
-                                  "block truncate text-[var(--text-placeholder)]",
+                                  "block truncate-until-large text-placeholder",
                                   small ? "text-caption" : "text-xs",
                                 )}
                               >
@@ -569,8 +611,8 @@ function AutocompleteInner<V extends string | number = string>(
                 aria-hidden
                 className={cn(
                   small ? "px-3 py-1.5 text-xs" : "px-3 py-2 text-sm",
-                  failed && !hasStatus ? "text-[var(--danger)]" : "text-[var(--text-muted)]",
-                  results.length > 0 && "border-t border-[var(--border)] text-xs",
+                  failed && !hasStatus ? "text-danger" : "text-muted",
+                  results.length > 0 && "border-t border-subtle text-xs",
                 )}
               >
                 {statusLine}
@@ -582,41 +624,3 @@ function AutocompleteInner<V extends string | number = string>(
     </div>
   );
 }
-
-const AutocompleteBase = forwardRef(AutocompleteInner);
-AutocompleteBase.displayName = "Autocomplete";
-
-/**
- * An inline, async-capable text field with a suggestion list under it — the
- * WAI-ARIA APG "editable combobox with list autocomplete".
- *
- * Two jobs, one control:
- *  - **free text** (kastlan's address field): the text is the value, the list only
- *    offers completions, and taking one fills the field (`fillOnSelect`, default);
- *  - **search-then-act** (keksdose's address search): the text is a query, taking a
- *    row calls `onSelect` and nothing is held (`fillOnSelect={false}`).
- *
- * How it differs from its siblings: {@link Combobox} is free text over a STATIC
- * string pool and opens on focus; {@link EntityCombobox} is a trigger holding an id.
- * This one keeps no value of its own, never resets the text, asks nothing below
- * `minChars`, and reports a failed lookup instead of showing stale rows.
- *
- * Focus never leaves the `<input>`: `aria-activedescendant` names the highlighted
- * row, `aria-controls` the list, and a polite live region says what the list now
- * holds. Keyboard: ↓/↑ move (↓ opens) over every row but a `disabled` one, Enter
- * takes the highlighted row (with none,
- * Enter is left to the form), Escape closes, Tab closes and moves on; Home/End stay
- * with the caret. An Escape that closes an open list is consumed and never reaches the
- * caller; with the list closed it does. For every other key a caller's `onKeyDown`
- * runs first and may `preventDefault()` to
- * keep a key for itself.
- *
- * The list is portalled and anchored under the field on every screen size: the
- * field already carries the keyboard, and `useAnchoredPanel` keeps the list clear
- * of it on a phone. There is no full-screen sheet as {@link Combobox} has.
-
- * Generic over the option value (`ComboOption<V>`); the ref is the `<input>`'s.
- */
-export const Autocomplete = AutocompleteBase as <V extends string | number = string>(
-  props: AutocompleteProps<V> & RefAttributes<HTMLInputElement>,
-) => ReactElement | null;

package/src/components/breadcrumbs-labels.ts

@@ -0,0 +1,10 @@
+// The English words of ./breadcrumbs, 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). ./breadcrumbs re-exports them.
+
+import type { BreadcrumbsLabels } from "./breadcrumbs";
+
+export const DEFAULT_BREADCRUMBS_LABELS: BreadcrumbsLabels = {
+  label: "Breadcrumb",
+  showAll: "Show full path",
+};

package/src/components/breadcrumbs.tsx

@@ -1,10 +1,11 @@
 import { Fragment, useEffect, useRef, useState } from "react";
-import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from "react";
+import type { ComponentPropsWithRef, ReactElement, ReactNode } from "react";
 import { ChevronRight, MoreHorizontal } from "lucide-react";
 import { cn } from "../lib/cn";
 import { FOCUS_RING } from "./focus-ring";
-import { useKitLabels, useKitLink } from "../i18n/kit-labels";
+import { useKitLabels, useKitLink, type LabelOverride } from "../i18n/kit-labels";
 import { pickLinkRenderer, RenderedKitLink } from "./text-link";
+import { DEFAULT_BREADCRUMBS_LABELS } from "./breadcrumbs-labels";
 
 export interface BreadcrumbsLabels {
   /** The `nav` landmark's name — what a screen reader lists it as. */
@@ -13,10 +14,8 @@ export interface BreadcrumbsLabels {
   showAll: string;
 }
 
-export const DEFAULT_BREADCRUMBS_LABELS: BreadcrumbsLabels = {
-  label: "Breadcrumb",
-  showAll: "Show full path",
-};
+// Defined in ./breadcrumbs-labels, which holds no component code (0.34, KS U8).
+export { DEFAULT_BREADCRUMBS_LABELS };
 
 export interface BreadcrumbItem {
   label: ReactNode;
@@ -35,7 +34,7 @@ export interface BreadcrumbLinkProps {
   children: ReactNode;
 }
 
-export interface BreadcrumbsProps extends Omit<ComponentPropsWithoutRef<"nav">, "children"> {
+export interface BreadcrumbsProps extends Omit<ComponentPropsWithRef<"nav">, "children"> {
   items: BreadcrumbItem[];
   /** Your router's link. Default: the `<UiKitProvider linkComponent>` (for an in-app
    *  `href`), then `<a>`. The API `Chip`, `StatTile` and `ListItem` share. */
@@ -57,7 +56,7 @@ export interface BreadcrumbsProps extends Omit<ComponentPropsWithoutRef<"nav">,
    *  parent by default (2), because "up one level" is what a phone user reaches for. */
   keepEnd?: number;
   /** Overrides the {@link UiKitProvider}'s `breadcrumbs` labels. */
-  labels?: Partial<BreadcrumbsLabels>;
+  labels?: LabelOverride<BreadcrumbsLabels>;
 }
 
 /**
@@ -103,22 +102,26 @@ export function Breadcrumbs({
   const isHidden = (i: number) => collapsible && i >= 1 && i < firstKept;
 
   const sep = (
-    <span aria-hidden className="flex shrink-0 items-center text-[var(--text-placeholder)]">
+    <span aria-hidden className="flex shrink-0 items-center text-placeholder">
       {separator ?? <ChevronRight className="size-3.5 rtl:-scale-x-100" />}
     </span>
   );
-  const linkClass = cn("block max-w-[14rem] truncate rounded-sm hover:text-[var(--text-primary)]", FOCUS_RING);
+  // Each crumb is capped (in rem, so the cap grows with the text) and cut with an
+  // ellipsis at Normal; from Large up it wraps inside its cap instead (text size §10.17,
+  // round 0.34 T1): the list already wraps between crumbs, and a crumb cut to "Inv…" at
+  // 150 % names no page.
+  const linkClass = cn("block max-w-[14rem] truncate-until-large rounded-sm hover:text-primary", FOCUS_RING);
 
   return (
     <nav {...rest} aria-label={ariaLabel ?? labels.label} className={cn("min-w-0 text-sm", className)}>
-      <ol className="m-0 flex min-w-0 list-none flex-wrap items-center gap-x-1.5 gap-y-1 p-0 text-[var(--text-muted)]">
+      <ol className="m-0 flex min-w-0 list-none flex-wrap items-center gap-x-1.5 gap-y-1 p-0 text-muted">
         {items.map((item, i) => {
           const last = i === items.length - 1;
           const key = item.key ?? (typeof item.label === "string" ? `${i}-${item.label}` : String(i));
           let content: ReactNode;
           if (last) {
             content = (
-              <span aria-current="page" className="block max-w-[16rem] truncate font-medium text-[var(--text-primary)]">
+              <span aria-current="page" className="block max-w-[16rem] truncate-until-large font-medium text-primary">
                 {item.label}
               </span>
             );
@@ -135,7 +138,7 @@ export function Breadcrumbs({
               </a>
             );
           } else {
-            content = <span className="block max-w-[14rem] truncate">{item.label}</span>;
+            content = <span className="block max-w-[14rem] truncate-until-large">{item.label}</span>;
           }
           return (
             <Fragment key={key}>
@@ -150,7 +153,7 @@ export function Breadcrumbs({
                     }}
                     aria-label={labels.showAll}
                     aria-expanded={false}
-                    className={cn("flex items-center rounded-sm px-0.5 hover:text-[var(--text-primary)]", FOCUS_RING)}
+                    className={cn("flex items-center rounded-sm px-0.5 hover:text-primary", FOCUS_RING)}
                   >
                     <MoreHorizontal className="size-4" aria-hidden />
                   </button>

package/src/components/bulk-action-bar-labels.ts

@@ -0,0 +1,11 @@
+// The English words of ./bulk-action-bar, 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). ./bulk-action-bar re-exports them.
+
+import type { BulkActionBarLabels } from "./bulk-action-bar";
+
+export const DEFAULT_BULK_ACTION_BAR_LABELS: BulkActionBarLabels = {
+  selected: (count) => `${count} selected`,
+  clear: "Clear selection",
+  cleared: "Selection cleared",
+};

package/src/components/bulk-action-bar.tsx

@@ -1,14 +1,16 @@
 import { useEffect, useLayoutEffect, useRef, useState } from "react";
-import type { ComponentPropsWithoutRef, CSSProperties, KeyboardEvent, ReactNode } from "react";
+import type { ComponentPropsWithRef, CSSProperties, KeyboardEvent, ReactNode } from "react";
 import { X } from "lucide-react";
 
 import { cn } from "../lib/cn";
 import { horizontalStep } from "../lib/direction";
-import { useKitLabels } from "../i18n/kit-labels";
+import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
 import { useAnnounce } from "../hooks/use-announce";
 import { useBreakpoint } from "../hooks/use-breakpoint";
-import { OVERLAY_EXIT_MS, prefersReducedMotion } from "../hooks/use-close-transition";
-import { Button, IconButton } from "./ui";
+import { OVERLAY_EXIT_MS, skipsExitAnimation } from "../hooks/use-close-transition";
+import { Button } from "./button";
+import { IconButton } from "./icon-button";
+import { DEFAULT_BULK_ACTION_BAR_LABELS } from "./bulk-action-bar-labels";
 
 export interface BulkActionBarLabels {
   /** The count, shown in the bar, spoken by its live region and used as the toolbar's
@@ -21,11 +23,8 @@ export interface BulkActionBarLabels {
   cleared: string;
 }
 
-export const DEFAULT_BULK_ACTION_BAR_LABELS: BulkActionBarLabels = {
-  selected: (count) => `${count} selected`,
-  clear: "Clear selection",
-  cleared: "Selection cleared",
-};
+// Defined in ./bulk-action-bar-labels, which holds no component code (0.34, KS U8).
+export { DEFAULT_BULK_ACTION_BAR_LABELS };
 
 /**
  * `floating` — the phone's: fixed above `AppShell`'s bottom nav (`--app-nav-h`) and the
@@ -78,7 +77,7 @@ function useResolvedVariant(variant: BulkActionBarVariant | ResponsiveBulkAction
   return variant.base;
 }
 
-export interface BulkActionBarProps extends Omit<ComponentPropsWithoutRef<"div">, "role" | "children"> {
+export interface BulkActionBarProps extends Omit<ComponentPropsWithRef<"div">, "role" | "children"> {
   /** How many items are selected. The bar shows only while this is above zero —
    *  unless {@link open} says otherwise. */
   count: number;
@@ -124,7 +123,7 @@ export interface BulkActionBarProps extends Omit<ComponentPropsWithoutRef<"div">
    */
   panel?: ReactNode;
   /** Default: `bulkActionBar` from the {@link UiKitProvider}, else English. */
-  labels?: Partial<BulkActionBarLabels>;
+  labels?: LabelOverride<BulkActionBarLabels>;
 }
 
 /** Where the floating bar sits: clear of the phone nav and of the home indicator,
@@ -217,7 +216,7 @@ export function BulkActionBar({
       setShownCount(count);
       setLeaving(false);
     } else if (prev.shown) {
-      setLeaving(!prefersReducedMotion());
+      setLeaving(!skipsExitAnimation());
     }
   }
   useEffect(() => {
@@ -286,12 +285,12 @@ export function BulkActionBar({
   // one the surface wraps the row and the panel, so both share its tint and position.
   const surfaceClass = floating
     ? cn(
-        "fixed z-30 rounded-2xl border border-[var(--border)] bg-[var(--bg-surface)] shadow-lg",
+        "fixed z-30 rounded-2xl border border-subtle bg-surface shadow-lg",
         shown ? "animate-sheet" : "animate-sheet-out",
       )
     : cn(
         variant === "sticky" &&
-          "sticky top-0 z-20 border-b border-[var(--border)] bg-[color-mix(in_srgb,var(--brand)_8%,var(--bg-surface))] backdrop-blur",
+          "sticky top-0 z-20 border-b border-subtle bg-[color-mix(in_srgb,var(--brand)_8%,var(--bg-surface))] backdrop-blur",
         shown ? "animate-overlay" : "animate-overlay-out",
       );
   // `flex-wrap`: on a phone the count, three actions and a text "Clear selection" are
@@ -330,7 +329,7 @@ export function BulkActionBar({
           no room, so it was the item squeezed to nothing instead of a line breaking.
           Its own width is its basis now; `truncate` is left for a label too long for a
           line on its own. */}
-      <span className="min-w-0 flex-auto truncate text-sm font-medium text-[var(--text-primary)]">
+      <span className="min-w-0 flex-auto truncate text-sm font-medium text-primary">
         {labels.selected(shownCount)}
       </span>
       {/* `contents`, so the caller's controls are flex items of the bar itself. */}
@@ -354,7 +353,7 @@ export function BulkActionBar({
           <div
             data-bulk-action-bar-panel=""
             className={cn(
-              "border-t border-[var(--border)] px-3 py-3",
+              "border-t border-subtle px-3 py-3",
               floating && "max-h-[60dvh] overflow-y-auto",
             )}
           >

package/src/components/button-group.tsx

@@ -1,6 +1,6 @@
-import type { ComponentPropsWithoutRef, MouseEvent, ReactElement, ReactNode, Ref } from "react";
+import type { ComponentPropsWithoutRef, ComponentPropsWithRef, MouseEvent, ReactElement, ReactNode, Ref } from "react";
 import { cn } from "../lib/cn";
-import { buttonClasses, type ButtonSize, type ButtonVariant } from "./ui";
+import { buttonClasses, type ButtonSize, type ButtonVariant } from "./button-look";
 import { useKitLink } from "../i18n/kit-labels";
 import { pickLinkRenderer } from "./text-link";
 
@@ -15,12 +15,12 @@ import { pickLinkRenderer } from "./text-link";
 // `<a>` one level down: a router link member (see {@link ButtonGroupLink}) under a
 // tooltip. A bare link is a direct child and needs nothing extra.
 const JOINED_COMMON = cn(
-  "inline-flex rounded-md border border-[var(--border)]",
+  "inline-flex rounded-md border border-subtle",
   // The group draws the frame; each member gives up its own border, radius and shadow.
   "[&>*]:rounded-none [&>*]:border-0 [&>*]:shadow-none",
   "[&>*>button]:rounded-none [&>*>button]:border-0 [&>*>button]:shadow-none",
   "[&>*>a]:rounded-none [&>*>a]:border-0 [&>*>a]:shadow-none",
-  "[&>*]:border-[var(--border)]",
+  "[&>*]:border-subtle",
   // A focused member rises above its neighbours so its ring is not painted over by
   // the next one's background.
   "[&>*]:relative [&>*:focus-within]:z-10",
@@ -82,14 +82,14 @@ const GAPPED: Record<"horizontal" | "vertical", string> = {
 // `elevated`, joined: the frame itself floats — a filled surface under the members (a
 // ghost member would otherwise show the content through it) and the shadow of a
 // control lifted over the page.
-const ELEVATED_JOINED = "bg-[var(--bg-surface)] shadow-lg";
+const ELEVATED_JOINED = "bg-surface shadow-lg";
 // `elevated`, gapped: there is no frame, so each disc carries the shadow. Aimed at the
 // control, not the tooltip's square wrapper span, whose shadow would be a box round a
 // round disc.
 const ELEVATED_GAPPED =
   "[&>button]:shadow-md [&>a]:shadow-md [&>*>button]:shadow-md [&>*>a]:shadow-md";
 
-export interface ButtonGroupProps extends Omit<ComponentPropsWithoutRef<"div">, "role"> {
+export interface ButtonGroupProps extends Omit<ComponentPropsWithRef<"div">, "role"> {
   /** `horizontal` (default): side by side, in reading order. `vertical`: stacked —
    *  the map's zoom + over −. */
   orientation?: "horizontal" | "vertical";
@@ -181,7 +181,7 @@ export interface ButtonGroupLinkProps extends Omit<ComponentPropsWithoutRef<"a">
 // The brand AS TEXT is `--brand-muted` (0.33, docs/colour-roles-harmonization.md §5.5):
 // `--brand` itself is solved to 3:1 and read 2.97:1 on its own wash in the derived dark
 // presets; the muted form holds 4.5:1 on it in every preset.
-const LINK_CURRENT = "bg-[var(--brand-bg)] text-brand-muted hover:bg-[var(--brand-bg-hover)]";
+const LINK_CURRENT = "bg-brand-soft text-brand-muted hover:bg-brand-soft-hover";
 
 /**
  * A {@link ButtonGroup} member that navigates: a link drawn as a {@link Button}, so it