@eifi1/ui-kit 0.31.1 → 0.32.1

package/src/components/switch.tsx

@@ -2,7 +2,14 @@ import { forwardRef, useId } from "react";
 import type { ChangeEvent, InputHTMLAttributes, ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { hasMessage, mergeDescribedBy } from "./choice-parts";
-import { LockedReason, useLockReason } from "./field-parts";
+import {
+  DISABLED_REASON_LINE_CLASS,
+  LockedReason,
+  useDisabledReasonLine,
+  useLockReason,
+  type DisabledReasonDisplay,
+} from "./field-parts";
+import { FOCUS_RING } from "./focus-ring";
 
 /**
  * An on/off switch that is still `<input type="checkbox">`, with `role="switch"`.
@@ -14,16 +21,20 @@ import { LockedReason, useLockReason } from "./field-parts";
  * the moment it is flipped; a choice that waits for a Save button is a checkbox.
  */
 
-/** Geometry per size. The thumb sits `2px` in from each end of the track, so its
- *  checked offset is `track width − thumb − 2px`. `start-*`, never `left-*` or a
- *  `translate-x`: an inline-start offset follows the writing direction, so in a
- *  right-to-left form the thumb travels right-to-left with no `rtl:` override to
- *  keep in step. */
+/** Geometry per size. The thumb sits `start-0.5` (0.125rem, 2 px at Normal) in from
+ *  each end of the track, so its checked offset is `track width − thumb − 0.125rem`.
+ *  All of it in rem since 0.32 (docs/text-size-harmonization.md §3.2, §4): the track
+ *  and thumb already grew with the text, and a checked offset left in px (14 / 18) put
+ *  the thumb short of the end at 125 % and in the middle at 150 %. `start-*`, never
+ *  `left-*` or a `translate-x`: an inline-start offset follows the writing direction,
+ *  so in a right-to-left form the thumb travels right-to-left with no `rtl:` override
+ *  to keep in step. */
 const SIZES = {
-  // 28×16 track, 12px thumb: the dense setting rows in Kastlan's tables.
-  sm: { track: "h-4 w-7", thumb: "size-3 peer-checked:start-[14px]" },
-  // 36×20 track, 16px thumb.
-  md: { track: "h-5 w-9", thumb: "size-4 peer-checked:start-[18px]" },
+  // 1.75 × 1rem track, 0.75rem thumb (28×16 / 12 at Normal): the dense setting rows in
+  // Kastlan's tables. Checked: 1.75 − 0.75 − 0.125 = 0.875rem.
+  sm: { track: "h-4 w-7", thumb: "size-3 peer-checked:start-3.5" },
+  // 2.25 × 1.25rem track, 1rem thumb (36×20 / 16). Checked: 2.25 − 1 − 0.125 = 1.125rem.
+  md: { track: "h-5 w-9", thumb: "size-4 peer-checked:start-4.5" },
 } as const;
 
 export type SwitchSize = keyof typeof SIZES;
@@ -38,7 +49,8 @@ export type SwitchSize = keyof typeof SIZES;
 const TRACK =
   "peer block shrink-0 cursor-pointer appearance-none rounded-full bg-[var(--border-strong)] transition-colors " +
   "checked:bg-[var(--brand)] " +
-  "focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-surface)] " +
+  // 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)] ` +
   "disabled:cursor-not-allowed";
 
 // The thumb, laid over the input and ignoring the pointer so every click still reaches
@@ -93,6 +105,13 @@ export interface SwitchProps extends Omit<InputHTMLAttributes<HTMLInputElement>,
    * switch anew (it moves in or out of the Tooltip), as a locked Button is.
    */
   disabledReason?: ReactNode;
+  /**
+   * Where `disabledReason` shows (0.32, §4 "No fact only in a tooltip"): by default, at
+   * Large and on a touch screen, as a line in the words column under the description (a
+   * bare switch: under the track), and in the tooltip otherwise. See
+   * {@link DisabledReasonDisplay}.
+   */
+  disabledReasonDisplay?: DisabledReasonDisplay;
   /**
    * This switch COMMITS — flipping it saves. Under a locked {@link WriteLockProvider} it
    * is locked the `disabledReason` way with the lock's reason (which wins over its
@@ -122,6 +141,7 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(function Switch(
     disabled,
     required,
     disabledReason,
+    disabledReasonDisplay,
     commit,
     onClick,
     ...rest
@@ -132,6 +152,7 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(function Switch(
   const inputId = id ?? generated;
   const lock = useLockReason(commit, disabledReason);
   const locked = lock.locked;
+  const reasonLine = useDisabledReasonLine(disabledReasonDisplay);
   // Locked is disabled the focusable way — the row fades and the words stop inviting a
   // click, as for `disabled`.
   const looksDisabled = Boolean(disabled) || locked;
@@ -177,21 +198,28 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(function Switch(
     </span>
   );
   // The Tooltip goes round the track, not the row — the row is the caller's layout. A
-  // bare switch hands its `className` to the wrapper, then the outermost element.
-  const control = locked ? (
-    <LockedReason lock={lock} className={cn("shrink-0", bare && className)}>
-      {track}
-    </LockedReason>
-  ) : (
-    track
-  );
+  // bare switch hands its `className` to the wrapper, then the outermost element. With
+  // words beside it, the reason LINE goes under them instead (below), so the track
+  // stays where the row puts it.
+  const lineInWords = locked && reasonLine && !bare;
+  const control =
+    locked && !lineInWords ? (
+      <LockedReason lock={lock} line={reasonLine} className={cn("shrink-0", bare && className)}>
+        {track}
+      </LockedReason>
+    ) : (
+      track
+    );
 
   if (bare) return control;
 
-  // The switch's cell is one label line tall (text-sm, 20px) so it centres on the
+  // The switch's cell is one label line tall (text-sm, 1.25rem) so it centres on the
   // FIRST line of a label that wraps, and a description underneath does not drag it
   // down to the middle of the paragraph.
-  const cell = <span className="flex h-5 shrink-0 items-center">{control}</span>;
+  // With the reason line in the words, the row's fade moves onto its parts: the line is
+  // the one thing on the row still to be read, and at 60 % it would not be.
+  const dimParts = lineInWords;
+  const cell = <span className={cn("flex h-5 shrink-0 items-center", dimParts && "opacity-60")}>{control}</span>;
   const words = (
     <span className="min-w-0 flex-1">
       {label !== undefined && (
@@ -200,6 +228,7 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(function Switch(
           className={cn(
             "block text-sm leading-5 text-[var(--text-primary)]",
             looksDisabled ? "cursor-not-allowed" : "cursor-pointer select-none",
+            dimParts && "opacity-60",
           )}
         >
           {label}
@@ -211,15 +240,20 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(function Switch(
         </label>
       )}
       {showDescription && (
-        <span id={descriptionId} className="mt-0.5 block text-xs text-[var(--text-muted)]">
+        <span id={descriptionId} className={cn("mt-0.5 block text-xs text-[var(--text-muted)]", dimParts && "opacity-60")}>
           {description}
         </span>
       )}
+      {lineInWords && (
+        <span id={lock.reasonId} className={DISABLED_REASON_LINE_CLASS}>
+          {lock.reason}
+        </span>
+      )}
     </span>
   );
 
   return (
-    <div className={cn("flex items-start gap-3", looksDisabled && "opacity-60", className)}>
+    <div className={cn("flex items-start gap-3", looksDisabled && !dimParts && "opacity-60", className)}>
       {switchPosition === "end" ? (
         <>
           {words}

package/src/components/table.tsx

@@ -242,7 +242,7 @@ const STACK_PHONE_CLASSES = cn(
   "max-sm:[&_tbody_td]:block max-sm:[&_tbody_td]:px-0 max-sm:[&_tbody_td]:py-0.5 max-sm:[&_tbody_td]:text-start",
   "max-sm:[&_tfoot_td]:block max-sm:[&_tfoot_td]:px-0 max-sm:[&_tfoot_td]:py-0.5",
   "max-sm:[&_tbody_td:first-child]:font-medium",
-  "max-sm:[&_td[data-label]]:before:block max-sm:[&_td[data-label]]:before:text-[11px] max-sm:[&_td[data-label]]:before:font-medium max-sm:[&_td[data-label]]:before:text-[var(--text-muted)] max-sm:[&_td[data-label]]:before:content-[attr(data-label)]",
+  "max-sm:[&_td[data-label]]:before:block max-sm:[&_td[data-label]]:before:text-caption max-sm:[&_td[data-label]]:before:font-medium max-sm:[&_td[data-label]]:before:text-[var(--text-muted)] max-sm:[&_td[data-label]]:before:content-[attr(data-label)]",
 );
 
 /**
@@ -353,7 +353,7 @@ export function Table({
           // rounded corners.
           framed && "rounded-md border border-[var(--border)]",
           THIN_SCROLLBAR_CLASS,
-          "focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-[var(--brand)]",
+          "focus-visible:outline-[length:var(--focus-ring-width)] focus-visible:-outline-offset-2 focus-visible:outline-[var(--brand)]",
           wrapperClassName,
         )}
       >

package/src/components/text-link.tsx

@@ -288,7 +288,7 @@ export function TextLink({
 
   const look = cn(
     "rounded-sm underline-offset-2 transition-colors",
-    "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--brand)]",
+    "focus-visible:outline-[length:var(--focus-ring-width)] focus-visible:outline-offset-2 focus-visible:outline-[var(--brand)]",
     TONE[tone],
     UNDERLINE[underline],
     ariaCurrent && "font-semibold",

package/src/components/text.tsx

@@ -35,10 +35,14 @@ export type SectionLabelSize = "xs" | "md" | "sm";
  * reached as a string than wrapped in a component that only takes a `className`. The
  * uppercase is CSS, so a screen reader reads the text as written: write it in normal
  * case.
+ *
+ * The sizes are the kit's named rem steps since 0.32 (`text-micro` 0.625rem,
+ * `text-caption` 0.6875rem — 10 and 11 px at Normal), so a label grows with the text
+ * size like everything around it (docs/text-size-harmonization.md §3.2).
  */
 export const SECTION_LABEL_CLASS: Record<SectionLabelSize, string> = {
-  xs: "text-[10px] font-semibold uppercase tracking-wide text-[var(--text-muted)]",
-  md: "text-[11px] font-semibold uppercase tracking-wide text-[var(--text-muted)]",
+  xs: "text-micro font-semibold uppercase tracking-wide text-[var(--text-muted)]",
+  md: "text-caption font-semibold uppercase tracking-wide text-[var(--text-muted)]",
   sm: "text-xs font-semibold uppercase tracking-wide text-[var(--text-muted)]",
 };
 
@@ -61,8 +65,8 @@ export type SectionLabelVariant = "plain" | "band";
  *  a font-size arbitrary `text-` value from a colour one. (Not spelt out as class
  *  names here: Tailwind scans comments, and a literal one broke the showcase CSS.) */
 const SECTION_LABEL_BAND_CLASS: Record<SectionLabelSize, string> = {
-  xs: "text-[10px]",
-  md: "text-[11px]",
+  xs: "text-micro",
+  md: "text-caption",
   sm: "text-xs",
 };
 const BAND =
@@ -112,14 +116,15 @@ export function SectionLabel({
 /* ── Caption ──────────────────────────────────────────────────────────────── */
 
 /**
- * The caption type as a class string: 11px, snug, muted. lenkbank's `CAPTION`
+ * The caption type as a class string: `text-caption` (0.6875rem, 11 px at Normal, §3.2),
+ * snug, muted. lenkbank's `CAPTION`
  * (shared/ui/caption.ts:23) — written out 31 times before it was a constant — as a
  * token colour rather than `slate-500 dark:slate-400`, so it follows the palette.
  * Exported for the same reason lenkbank's is a string: every caller positions it
  * differently (`mt-1`, `self-end pb-2`, `border-t`), and what must be one thing is the
  * type, not the box.
  */
-export const CAPTION_CLASS = "text-[11px] leading-snug text-[var(--text-muted)]";
+export const CAPTION_CLASS = "text-caption leading-snug text-[var(--text-muted)]";
 
 export interface CaptionProps extends ComponentPropsWithoutRef<"p"> {
   /** Default `p`; `span` for a caption inside a line of other content. */

package/src/components/tile-radio.tsx

@@ -2,6 +2,7 @@ import { useId, useRef } from "react";
 import type { KeyboardEvent, ReactNode } from "react";
 import { Ban, Check } from "lucide-react";
 import { cn } from "../lib/cn";
+import { FOCUS_RING } from "./focus-ring";
 import { horizontalStep } from "../lib/direction";
 import { Tooltip } from "./tooltip";
 
@@ -133,7 +134,9 @@ export interface TileRadioGroupProps<T extends string> {
  */
 const TILE_BASE =
   "relative inline-flex shrink-0 items-center justify-center rounded-md border transition-colors " +
-  "focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)] 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-[var(--bg-surface)] " +
   "disabled:cursor-not-allowed disabled:opacity-50";
 const TILE_IDLE =
   "border-[var(--border)] bg-[var(--bg-surface)] hover:border-[var(--border-strong)] hover:bg-[var(--bg-hover)]";

package/src/components/toast.tsx

@@ -1,8 +1,7 @@
 import { useEffect, useState, useSyncExternalStore } from "react";
 import type { CSSProperties, MouseEvent, ReactElement, ReactNode } from "react";
 import { useKitLabels } from "../i18n/kit-labels";
-import { useMediaQuery } from "../hooks/use-media-query";
-import { PHONE_QUERY } from "./ui";
+import { usePhoneLayout } from "../hooks/use-breakpoint";
 
 /**
  * The kit's toast layer: a `toast` API and a `<Toaster>`, over sonner.
@@ -298,7 +297,9 @@ export type ToastPosition =
 
 export type ToastSwipeDirection = "top" | "right" | "bottom" | "left";
 
-/** sonner's offset: one value for every edge, or per edge. Numbers are px. */
+/** sonner's offset: one value for every edge, or per edge. Numbers are px, which do not
+ *  follow the text size — prefer a CSS length (rem, or a `calc()` on
+ *  {@link TOASTER_OFFSET_TOP} / {@link TOASTER_OFFSET_BOTTOM}). */
 export type ToasterOffset =
   | string
   | number
@@ -397,6 +398,22 @@ function subscribeDocumentTheme(onChange: () => void): () => void {
 
 const px = (v: string | number) => (typeof v === "number" ? `${v}px` : v);
 
+/**
+ * The Toaster's default distance from the top edge (desktop), as a CSS length (0.32,
+ * docs/text-size-harmonization.md §10.11): below a 3rem top bar with 1rem to spare, and
+ * the safe area. In rem, so it moves with the text size along with the top bar — an
+ * app's `offset={{ top: 64 }}` (keksdose) did not. Pass it, or a `calc()` built on it,
+ * instead of a px number.
+ */
+export const TOASTER_OFFSET_TOP = "calc(env(safe-area-inset-top, 0px) + 4rem)";
+
+/**
+ * The Toaster's default distance from the bottom edge (phone), as a CSS length: above
+ * AppShell's measured bottom nav (`--app-nav-h`) or the home indicator, whichever is
+ * taller, with 0.75rem to spare.
+ */
+export const TOASTER_OFFSET_BOTTOM = "calc(max(var(--app-nav-h, 0px), env(safe-area-inset-bottom, 0px)) + 0.75rem)";
+
 /**
  * Where the toasts appear, with the kit's defaults — mount ONE, near the root and
  * inside `<UiKitProvider>` (it reads the `toast` labels) and inside the router if a
@@ -480,14 +497,17 @@ export function Toaster({
   }, [dismissOnMiddleClick, mod]);
 
   const documentTheme = useSyncExternalStore(subscribeDocumentTheme, readDocumentTheme, () => "light" as const);
-  const phone = useMediaQuery(PHONE_QUERY, false);
+  const phone = usePhoneLayout();
   const resolved: ToastPosition = position ?? (phone ? "bottom-center" : "top-center");
 
   // Above the bottom nav and the home indicator: whichever is taller, since the nav
   // already pads itself by the safe area (the same sum BulkActionBar floats on).
-  const bottom = `calc(max(${navOffset === undefined ? "var(--app-nav-h, 0px)" : px(navOffset)}, env(safe-area-inset-bottom, 0px)) + 0.75rem)`;
-  // Below a 48px TopBar with the same 1rem clearance.
-  const top = "calc(env(safe-area-inset-top, 0px) + 4rem)";
+  const bottom =
+    navOffset === undefined
+      ? TOASTER_OFFSET_BOTTOM
+      : `calc(max(${px(navOffset)}, env(safe-area-inset-bottom, 0px)) + 0.75rem)`;
+  // Below a 3rem TopBar with the same 1rem clearance.
+  const top = TOASTER_OFFSET_TOP;
   const computed = resolved.startsWith("bottom") ? { bottom } : { top };
 
   if (!mod) return null;

package/src/components/toggle-group.tsx

@@ -5,7 +5,17 @@ import { horizontalStep } from "../lib/direction";
 import { FIELD_INVALID, FloatingField, Label } from "./ui";
 import { Tooltip } from "./tooltip";
 import { useCommitReason } from "./write-lock";
-import { hasContent, LabelStrip } from "./field-parts";
+import {
+  DISABLED_REASON_LINE_CLASS,
+  FIELD_CAPTION_CLASS,
+  hasContent,
+  isTextHint,
+  LabelStrip,
+  useDisabledReasonLine,
+  useInlineHint,
+  type DisabledReasonDisplay,
+} from "./field-parts";
+import { FOCUS_RING_WIDTH } from "./focus-ring";
 
 export interface ToggleOption<T extends string> {
   value: T;
@@ -36,6 +46,11 @@ export interface ToggleGroupBaseProps<T extends string>
    * whole ("Bewegung", not "Beweg…"), at the price of a taller group on a narrow
    * screen (lenkbank L4: five signal types on a 390px control page). From the width
    * where they fit, both look the same.
+   *
+   * Since 0.32 a group in the field chrome (`label`, the default placement) with four or
+   * more options wraps at Large and Extra large under `"truncate"` too, inside its frame:
+   * the type is bigger there and the field would otherwise run past a phone's edge
+   * (docs/text-size-harmonization.md §4). The keyboard is the same either way.
    */
   overflow?: "truncate" | "wrap";
   /**
@@ -116,8 +131,15 @@ export interface ToggleGroupBaseProps<T extends string>
    * two stack and both keep their corners.
    */
   chromeClassName?: string;
-  /** A {@link FieldHint} on the label line, as on a labelled {@link Select}. Only with
-   *  `label`. */
+  /**
+   * As on a labelled {@link Select}: a {@link FieldHint} "?" on the label line, and plain
+   * text (a string) as a caption under the group. Only with `label`.
+   *
+   * 0.32.1 (keksdose's 0.32 report): text went on the label line in every placement, so
+   * `TextSizeSetting`'s hint with `labelPlacement="above"` sat beside the label in body
+   * type, and at Extra large became a column one word wide — on the setting a reader who
+   * needs large text opens first. The label line holds the "?" only (`isTextHint`).
+   */
   hint?: ReactNode;
   /** The message under the field when it is wrong: paints the field's border with
    *  `--danger`, marks the group `aria-invalid` and describes it with the message, as
@@ -136,6 +158,12 @@ export interface ToggleGroupBaseProps<T extends string>
    * Wins over `disabled`, as on Button: passing both keeps the group reachable.
    */
   disabledReason?: ReactNode;
+  /**
+   * Where `disabledReason` shows (0.32, §4 "No fact only in a tooltip"): by default, at
+   * Large and on a touch screen, as a line under the group (where its caption goes), and
+   * in the tooltip over the segments otherwise. See {@link DisabledReasonDisplay}.
+   */
+  disabledReasonDisplay?: DisabledReasonDisplay;
   /**
    * This group COMMITS — choosing an option saves it. Under a locked
    * {@link WriteLockProvider} it takes the `disabledReason` path with the lock's
@@ -151,6 +179,11 @@ export interface ToggleGroupBaseProps<T extends string>
  * The field chrome's vertical geometry — keksdose K1, the kit reintroducing feedback
  * #117 that keksdose's hand-built chrome had fixed.
  *
+ * In px at Normal, as measured; since 0.32 every term but the two borders is rem
+ * (§3.2), so the sum stays a labelled Select's at 125 and 150 % too — the Select's own
+ * `pt-4 pb-1` and 1.25rem line grow by the same factor (52 px at Large, 62 at Extra
+ * large). The md line was `leading-[18px]` and is `leading-[1.125rem]`.
+ *
  * The label is the field's static label: `top-1` and 11px in a `leading-tight` line, so
  * its line box runs from 4px to 17.75px. Until 0.22 the chrome was `pt-4` over a 20px
  * (`leading-5`) segment, so the ACTIVE segment's fill — painted from the top of the
@@ -168,7 +201,35 @@ export interface ToggleGroupBaseProps<T extends string>
  *     md: 1 + 20 + 18 + 2 + 1 = 42        sm: 1 + 20 + 16 + 4 + 1 = 42
  */
 const CHROME_PAD: Record<"sm" | "md", string> = { md: "pt-5 pb-0.5", sm: "pt-5 pb-1" };
-const CHROME_SEGMENT: Record<"sm" | "md", string> = { md: "py-0 leading-[18px]", sm: "py-0 leading-4" };
+const CHROME_SEGMENT: Record<"sm" | "md", string> = { md: "py-0 leading-[1.125rem]", sm: "py-0 leading-4" };
+
+/**
+ * A group at Large and Extra large (0.32,
+ * docs/text-size-harmonization.md §4 "nothing truncates", §3.3): the segments flow onto a
+ * second row inside the group's frame instead of overflowing it. At 125 % a 390 px phone
+ * is 312 px of Normal type, and "Month / Quarter / Half-year / Year" in one row of the
+ * field ran 7 px past it: a one-row flex group is as wide as all its labels end to end
+ * when a grid or a stretched column asks how small it can get, however its segments
+ * truncate. Wrapped, it is as wide as its longest label.
+ *
+ * Wrap, not a stacked select-like list: a wrapped radio group is the same radio group —
+ * one Tab stop, and the arrow keys walk the options in reading order whichever row
+ * they are on (←/↑ back, →/↓ on, Home/End) — so nothing about the keyboard changes with
+ * the text size. A list in its place would be a second widget with its own keys.
+ *
+ * Only where it has to: `flex-wrap` breaks a row only when the segments do not fit, so
+ * a wide field at Large stays one row, and a segment shares out what its row leaves
+ * (`flex-1`); a label wider than the whole row still truncates as the last resort.
+ * A `large:` class, so it costs no render and is right on the first paint.
+ * `overflow="wrap"` wraps at every size already.
+ *
+ * 0.32.1 (Kurvenschmiede's 0.32 report): every count and every placement but the
+ * strip, not only a field of four or more. Since a row breaks only where its labels do
+ * not fit, a wrap only ever replaces a truncation — and three options in a card at
+ * Extra large on a 360 px phone read "Syst… Li… D…". The strip keeps one row: its
+ * 26 px group is what lines it up with the 42 px fields beside it (`STRIP_SEGMENT`).
+ */
+const WRAP_AT_LARGE = "large:flex-wrap";
 
 /**
  * The strip placement's segments: a 26px group (1 + 2 + 20 + 2 + 1) under the 16px
@@ -185,7 +246,7 @@ const STRIP_SEGMENT: Record<"sm" | "md", string> = { md: "py-0", sm: "py-0.5" };
  * region, because a description is read when the group is entered and not again when
  * an arrow key changes the choice underneath it.
  *
- * In muted 11px text under the field (or the bare group), above an `error`.
+ * In muted caption-size text under the field (or the bare group), above an `error`.
  */
 type ToggleGroupCaption<V> = ReactNode | ((value: V) => ReactNode);
 
@@ -272,6 +333,7 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
     hint,
     error,
     disabledReason: ownDisabledReason,
+    disabledReasonDisplay,
     commit,
     "aria-label": ariaLabelAttr,
     ...restWithMode
@@ -279,9 +341,17 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
   const labelId = useId();
   const errorId = useId();
   const reasonId = useId();
+  const hintCaptionId = useId();
   // The lock's reason under a locked provider (with `commit`), else the group's own.
   const disabledReason = useCommitReason(commit, ownDisabledReason);
   const locked = hasContent(disabledReason);
+  // §4: at Large and on touch the reason is a line under the group, not a bubble.
+  const reasonLine = useDisabledReasonLine(disabledReasonDisplay) && locked;
+  // §4: likewise a FieldHint "?" on the label line becomes a caption under the group at
+  // Large and on touch; text is a caption at every size, as Select's (see `hint`).
+  const inlineHint = useInlineHint(hint);
+  const hintAsCaption = isTextHint(hint) ? hint : inlineHint !== hint ? inlineHint : undefined;
+  const labelHint = hintAsCaption === undefined ? hint : undefined;
   // Locked looks disabled — the dimmed group, the not-allowed cursor, no hover offer —
   // but stays focusable; `disabled` alone also takes the segments out of the tab order.
   const dimmed = disabled || locked;
@@ -291,6 +361,9 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
   const field = labelled && labelPlacement === "field";
   const above = labelled && labelPlacement === "above";
   const strip = labelled && labelPlacement === "strip";
+  // At Large and Extra large a truncating group wraps instead, the strip excepted (see
+  // WRAP_AT_LARGE).
+  const wrapAtLarge = overflow === "truncate" && !strip;
   const hasError = labelled && hasContent(error);
   // Taken off the rest so neither reaches the DOM; `props` keeps them paired, which is
   // what lets the `onChange` below be called with `null` only in the mode that allows it.
@@ -377,8 +450,11 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
           // overlaying the selected segment's boundary. Inset keeps the ring
           // inside the segment it belongs to; focus-visible keeps it for the
           // keyboard, which is the only input that needs it.
+          //
+          // The ring is the kit's focus frame (0.32, §5): `--focus-ring-width` wide.
           overflow === "wrap" ? "whitespace-nowrap" : "min-w-0 truncate",
-          "flex-1 basis-auto rounded px-3 py-1.5 text-sm font-medium transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-[var(--border-strong)]",
+          "flex-1 basis-auto rounded px-3 py-1.5 text-sm font-medium transition-colors focus:outline-none focus-visible:ring-inset focus-visible:ring-[var(--border-strong)]",
+          FOCUS_RING_WIDTH,
           size === "sm" && "px-2 py-1 text-xs",
           // In the field chrome: no vertical padding, and the line that makes the
           // field 42px under a strip that clears the label — see CHROME_PAD. `sm`
@@ -423,7 +499,9 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
       aria-labelledby={labelled && ariaLabelAttr === undefined && ariaLabel === undefined ? labelId : rest["aria-labelledby"]}
       aria-invalid={hasError || rest["aria-invalid"] || undefined}
       aria-describedby={
-        [rest["aria-describedby"], hasCaption && captionId, hasError && errorId].filter(Boolean).join(" ") || undefined
+        [rest["aria-describedby"], hintAsCaption !== undefined && hintCaptionId, hasCaption && captionId, hasError && errorId]
+          .filter(Boolean)
+          .join(" ") || undefined
       }
       // `aria-disabled` on the group as well as on (or `disabled` on) each button: a
       // radio group is what the user is being refused, and a screen reader announcing
@@ -444,6 +522,7 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
         // phone does see is the focus ring — see the segment's own note below.)
         "inline-flex w-full gap-0.5 rounded-md border border-[var(--border-strong)] bg-[var(--bg-surface)] p-0.5 shadow-sm",
         overflow === "wrap" && "flex-wrap",
+        wrapAtLarge && WRAP_AT_LARGE,
         // The whole group fades, the way every other disabled control in this
         // package does; `cursor-not-allowed` is on the buttons, which is what a
         // pointer is actually over.
@@ -456,7 +535,7 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
         !labelled && className,
       )}
     >
-      {locked ? (
+      {locked && !reasonLine ? (
         // The reason's bubble wraps the SEGMENTS, inside the group, not the group: a
         // wrapper outside it would become the flex or grid item in the caller's row in
         // the group's place, and a `w-full` / `md:w-auto` on the group would size the
@@ -487,16 +566,34 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
       <p
         id={captionId}
         aria-live={captionIsLive ? "polite" : undefined}
-        className={cn("text-[11px] leading-snug text-[var(--text-muted)]", hasCaption && "mt-1")}
+        className={cn("text-caption leading-snug text-[var(--text-muted)]", hasCaption && "mt-1")}
       >
         {hasCaption ? captionNode : null}
       </p>
     ) : null;
   const errorEl = hasError ? (
-    <p id={errorId} className="mt-1 text-[11px] leading-tight text-[var(--danger)]">
+    <p id={errorId} className="mt-1 text-caption leading-tight text-[var(--danger)]">
       {error}
     </p>
   ) : null;
+  // §4: the FieldHint's words and the lock's reason, under the group, before the caption
+  // (standing advice first) and the error (the news). The reason line IS what each
+  // segment's `aria-describedby` names.
+  const belowEl =
+    hintAsCaption !== undefined || reasonLine ? (
+      <>
+        {hintAsCaption !== undefined && (
+          <p id={hintCaptionId} className={FIELD_CAPTION_CLASS}>
+            {hintAsCaption}
+          </p>
+        )}
+        {reasonLine && (
+          <p id={reasonId} className={DISABLED_REASON_LINE_CLASS}>
+            {disabledReason}
+          </p>
+        )}
+      </>
+    ) : null;
   if (above) {
     // `relative` so a caller's `sr-only` label cannot escape (sr-only-containment).
     return (
@@ -512,10 +609,11 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
           >
             {label}
           </Label>
-          {hint}
+          {labelHint}
         </div>
         <div className="min-w-0">
           {group}
+          {belowEl}
           {captionEl}
           {errorEl}
         </div>
@@ -524,19 +622,21 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
   }
   if (strip) {
     return (
-      <LabelStrip labelId={labelId} label={label} hint={hint} disabled={dimmed} pad="field" className={className}>
+      <LabelStrip labelId={labelId} label={label} hint={labelHint} disabled={dimmed} pad="field" className={className}>
         {group}
+        {belowEl}
         {captionEl}
         {errorEl}
       </LabelStrip>
     );
   }
   if (!field) {
-    if (!captionEl) return group;
+    if (!captionEl && !belowEl) return group;
     // The group keeps its `className`, as without a caption; the wrapper only stacks.
     return (
       <div className="min-w-0">
         {group}
+        {belowEl}
         {captionEl}
       </div>
     );
@@ -549,7 +649,7 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
         className="flex flex-1 flex-col"
         label={<span id={labelId}>{label}</span>}
         staticLabel
-        hint={hint}
+        hint={labelHint}
       >
         <div
           className={cn(
@@ -563,6 +663,7 @@ export function ToggleGroup<T extends string>(props: ToggleGroupProps<T>): React
           {group}
         </div>
       </FloatingField>
+      {belowEl}
       {captionEl}
       {errorEl}
     </div>