@kinetixui/ui 0.23.2 → 0.24.0

package/src/components/multi-select.tsx

@@ -75,20 +75,29 @@ const MultiSelect = React.forwardRef<HTMLDivElement, MultiSelectProps>(
             tabIndex={0}
             onClick={() => setOpen(true)}
             onKeyDown={(e) => {
-              if (e.key === "Enter" || e.key === " ") {
+              // Enter and Space open it, and so do the vertical arrows: WAI-ARIA's combobox pattern lists
+              // Down Arrow as a way to open the popup, and a keyboard user who has just tabbed onto a
+              // collapsed combobox reaches for it first. Without it the arrows did nothing at all here —
+              // the only way in was Enter or Space.
+              if (e.key === "Enter" || e.key === " " || e.key === "ArrowDown" || e.key === "ArrowUp") {
                 e.preventDefault();
                 setOpen(true);
               }
             }}
             className={cn(
-              "flex min-h-11 w-full flex-wrap items-center gap-1.5 border border-input bg-background px-3 py-2 font-sans",
-              "outline-none focus-visible:border-action focus-visible:shadow-focus",
+              // The text-entry state contract (TOKENS.md, "Composite fields"): one field, whose chips sit inside
+              // its edge. `rounded-sm` is the field radius Input and Select already use; this was square.
+              "flex min-h-11 w-full flex-wrap items-center gap-1.5 rounded-sm border border-muted-foreground/80 bg-background px-3 py-2 font-sans",
+              "outline-none transition-[border-color,box-shadow] duration-instant ease-standard",
+              "[@media(hover:hover)]:hover:[&:not(:focus):not([aria-expanded=true]):not([aria-invalid=true])]:border-muted-foreground",
+              "focus-visible:border-action focus-visible:shadow-focus",
               "aria-expanded:border-action aria-expanded:shadow-focus",
+              "aria-[invalid=true]:border-destructive aria-[invalid=true]:focus-visible:shadow-focus-destructive aria-[invalid=true]:aria-expanded:shadow-focus-destructive",
               className,
             )}
             {...props}
           >
-            {current.length === 0 && <span className="text-body-sm text-muted-foreground">{placeholder}</span>}
+            {current.length === 0 && <span className="text-body-md text-muted-foreground">{placeholder}</span>}
             {current.map((v) => (
               <Tag key={v} variant="secondary" onRemove={() => remove(v)} onClick={(e) => e.stopPropagation()}>
                 {labelFor(v)}
@@ -125,7 +134,7 @@ const MultiSelect = React.forwardRef<HTMLDivElement, MultiSelectProps>(
                 {canCreate ? (
                   <button
                     type="button"
-                    className="flex w-full items-center px-2 py-1.5 text-left text-body-sm text-foreground hover:bg-accent"
+                    className="flex w-full items-center px-2 py-1.5 text-start text-body-sm text-foreground hover:bg-accent"
                     onClick={() => {
                       toggle(trimmed);
                       setQuery("");

package/src/components/native-select.tsx

@@ -12,12 +12,20 @@ import { cn } from "../lib/utils";
  * Matches Input's `inputVariants` styling 1:1 so the two are drop-in
  * interchangeable in a Field. Gap-fill addition (not in the original
  * Figma source) — matches the shadcn/ui Native Select API shape.
+ *
+ * Same text-entry state contract as Input (TOKENS.md, "Text entry and navigation") — rest edge, hover,
+ * focus, invalid, disabled — minus read-only, which `<select>` does not have. Its placeholder is the
+ * empty-valued option: while it is the selection the field's text is `--muted-foreground`, so an unanswered
+ * select reads as unanswered next to a filled one (it used to render in the value's colour). The options in
+ * the open picker keep `--foreground`.
  */
 const nativeSelectVariants = cva(
   [
-    "flex w-full appearance-none border border-input bg-background px-3 py-3 pe-9",
+    "flex w-full appearance-none border border-muted-foreground/80 bg-background px-3 py-3 pe-9",
     "font-sans text-body-md text-foreground",
-    "outline-none transition-colors",
+    "[&:has(option[value='']:checked)]:text-muted-foreground [&_option]:text-foreground",
+    "outline-none transition-[border-color,box-shadow,background-color] duration-instant ease-standard",
+    "[@media(hover:hover)]:enabled:hover:[&:not(:focus):not([aria-invalid=true]):not([readonly]):not([data-state=focus])]:border-muted-foreground",
     "focus-visible:border-action focus-visible:shadow-focus",
     "disabled:cursor-not-allowed disabled:opacity-disabled",
     "aria-[invalid=true]:border-destructive aria-[invalid=true]:focus-visible:border-destructive aria-[invalid=true]:focus-visible:shadow-focus-destructive",

package/src/components/navigation-bar.tsx

@@ -32,7 +32,7 @@ const NavigationBar = React.forwardRef<HTMLElement, NavigationBarProps>(
               aria-label="Back"
               className="flex size-9 items-center justify-center rounded-full text-foreground outline-none transition-colors hover:bg-accent hover:ring-1 hover:ring-inset hover:ring-ring focus-visible:bg-accent focus-visible:ring-1 focus-visible:ring-inset focus-visible:ring-ring"
             >
-              <ChevronLeft className="size-5" />
+              <ChevronLeft className="size-5 rtl:-scale-x-100" />
             </button>
           ))}
       </div>

package/src/components/navigation-menu.tsx

@@ -36,7 +36,7 @@ NavigationMenuList.displayName = NavigationMenuPrimitive.List.displayName;
 const NavigationMenuItem = NavigationMenuPrimitive.Item;
 
 const navigationMenuTriggerStyle = cva(
-  "group inline-flex h-9 w-max items-center justify-center rounded-md bg-background px-4 py-2 text-sm font-medium transition-colors hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground focus:outline-none disabled:pointer-events-none disabled:opacity-disabled data-[state=open]:bg-accent/50",
+  "group inline-flex h-9 w-max items-center justify-center rounded-md bg-background px-4 py-2 text-sm font-medium transition-colors hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground focus:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-disabled data-[state=open]:bg-accent/50",
 );
 
 const NavigationMenuTrigger = React.forwardRef<
@@ -46,7 +46,7 @@ const NavigationMenuTrigger = React.forwardRef<
   <NavigationMenuPrimitive.Trigger ref={ref} className={cn(navigationMenuTriggerStyle(), "group", className)} {...props}>
     {children}
     <ChevronDown
-      className="relative top-px ml-1 size-3 transition-transform duration-fast group-data-[state=open]:rotate-180"
+      className="relative top-px ms-1 size-3 transition-transform duration-fast group-data-[state=open]:rotate-180"
       aria-hidden
     />
   </NavigationMenuPrimitive.Trigger>
@@ -60,7 +60,7 @@ const NavigationMenuContent = React.forwardRef<
   <NavigationMenuPrimitive.Content
     ref={ref}
     className={cn(
-      "left-0 top-0 w-full data-[motion^=from-]:animate-in data-[motion^=to-]:animate-out data-[motion^=from-]:fade-in data-[motion^=to-]:fade-out md:absolute md:w-auto",
+      "start-0 top-0 w-full data-[motion^=from-]:animate-in data-[motion^=to-]:animate-out data-[motion^=from-]:fade-in data-[motion^=to-]:fade-out data-[motion^=from-]:duration-fast data-[motion^=from-]:ease-enter data-[motion^=to-]:duration-instant data-[motion^=to-]:ease-exit md:absolute md:w-auto",
       className,
     )}
     {...props}
@@ -74,11 +74,11 @@ const NavigationMenuViewport = React.forwardRef<
   React.ElementRef<typeof NavigationMenuPrimitive.Viewport>,
   React.ComponentPropsWithoutRef<typeof NavigationMenuPrimitive.Viewport>
 >(({ className, ...props }, ref) => (
-  <div className="absolute left-0 top-full flex justify-center">
+  <div className="absolute start-0 top-full flex justify-center">
     <NavigationMenuPrimitive.Viewport
       ref={ref}
       className={cn(
-        "origin-top-center relative mt-1.5 h-[var(--radix-navigation-menu-viewport-height)] w-full overflow-hidden rounded-md border bg-popover text-popover-foreground shadow data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-90 md:w-[var(--radix-navigation-menu-viewport-width)]",
+        "origin-top-center relative mt-1.5 h-[var(--radix-navigation-menu-viewport-height)] w-full overflow-hidden rounded-md border bg-popover text-popover-foreground shadow data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-90 data-[state=open]:duration-fast data-[state=open]:ease-enter data-[state=closed]:duration-instant data-[state=closed]:ease-exit md:w-[var(--radix-navigation-menu-viewport-width)]",
         className,
       )}
       {...props}
@@ -94,7 +94,7 @@ const NavigationMenuIndicator = React.forwardRef<
   <NavigationMenuPrimitive.Indicator
     ref={ref}
     className={cn(
-      "top-full z-raised flex h-1.5 items-end justify-center overflow-hidden data-[state=visible]:animate-in data-[state=hidden]:animate-out data-[state=hidden]:fade-out data-[state=visible]:fade-in",
+      "top-full z-raised flex h-1.5 items-end justify-center overflow-hidden data-[state=visible]:animate-in data-[state=hidden]:animate-out data-[state=hidden]:fade-out data-[state=visible]:fade-in data-[state=visible]:duration-fast data-[state=visible]:ease-enter data-[state=hidden]:duration-instant data-[state=hidden]:ease-exit",
       className,
     )}
     {...props}

package/src/components/number-input.tsx

@@ -6,9 +6,19 @@ import { cn } from "../lib/utils";
 
 /**
  * NumberInput — a numeric field with increment / decrement controls.
- * The wrapper shows `--shadow-focus` on `focus-within`; each stepper also
- * draws its own `--ring` inset outline on `:focus-visible` so keyboard users
- * can tell which control is focused.
+ *
+ * The wrapper is ONE field and follows the text-entry state contract (TOKENS.md, "Composite fields"); the
+ * steppers sit inside its edge, separated by quiet internal dividers rather than borders of their own.
+ *
+ *   rest       edge `--muted-foreground` at 80% (3:1 on a card; `--input` was 2.2:1)
+ *   hover      the edge steps to full `--muted-foreground` — never over focus, invalid, read-only or disabled
+ *   focus      the INPUT focused → `--action` edge + `--shadow-focus` on the wrapper. A stepper focused → its
+ *              own inset `--ring`, and the wrapper stays at rest, so the ring says which part has focus
+ *   invalid    `aria-invalid="true"` (passed through to the input) → `--destructive` edge, kept under the
+ *              pointer and focus
+ *   read-only  `readOnly` → the inset `--muted` fill, and the steppers are disabled: a read-only value is
+ *              not one a button may change either
+ *   disabled   `--opacity-disabled`, inert
  */
 export interface NumberInputProps
   extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" | "value" | "defaultValue" | "onChange"> {
@@ -21,7 +31,7 @@ export interface NumberInputProps
 }
 
 const NumberInput = React.forwardRef<HTMLInputElement, NumberInputProps>(
-  ({ className, value, defaultValue = 0, min, max, step = 1, onChange, disabled, ...props }, ref) => {
+  ({ className, value, defaultValue = 0, min, max, step = 1, onChange, disabled, readOnly, ...props }, ref) => {
     const [internal, setInternal] = React.useState(defaultValue);
     const current = value ?? internal;
 
@@ -41,7 +51,14 @@ const NumberInput = React.forwardRef<HTMLInputElement, NumberInputProps>(
     return (
       <div
         className={cn(
-          "flex h-10 items-stretch overflow-hidden rounded-md border border-input font-sans focus-within:shadow-focus",
+          // no fixed height: the input's own padding sets it, so it matches Input and InputGroup in the same row
+          // (it was a fixed 40px beside their 46px) and still grows with the text
+          "flex items-stretch overflow-hidden rounded-md border border-muted-foreground/80 bg-background font-sans",
+          "transition-[border-color,box-shadow,background-color] duration-instant ease-standard",
+          !disabled && "[@media(hover:hover)]:hover:[&:not(:has(input:is(:focus,[readonly],[aria-invalid=true])))]:border-muted-foreground",
+          "has-[input[readonly]]:bg-muted",
+          "has-[input:focus:not([aria-invalid=true])]:border-action has-[input:focus]:shadow-focus",
+          "has-[input[aria-invalid=true]]:border-destructive has-[input[aria-invalid=true]:focus]:shadow-focus-destructive",
           disabled && "pointer-events-none opacity-disabled",
           className,
         )}
@@ -49,9 +66,9 @@ const NumberInput = React.forwardRef<HTMLInputElement, NumberInputProps>(
         <button
           type="button"
           aria-label="Decrease"
-          disabled={disabled || (min != null && current <= min)}
+          disabled={disabled || readOnly || (min != null && current <= min)}
           onClick={() => set(current - step)}
-          className="flex w-9 shrink-0 items-center justify-center text-muted-foreground outline-none transition-colors hover:bg-accent hover:text-foreground focus-visible:bg-accent focus-visible:text-foreground focus-visible:ring-1 focus-visible:ring-inset focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-disabled"
+          className="flex w-9 shrink-0 items-center justify-center text-muted-foreground outline-none transition-colors hover:bg-accent hover:text-foreground focus-visible:bg-accent focus-visible:text-foreground focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-disabled"
         >
           <Minus className="size-4" />
         </button>
@@ -64,19 +81,20 @@ const NumberInput = React.forwardRef<HTMLInputElement, NumberInputProps>(
           max={max}
           step={step}
           disabled={disabled}
+          readOnly={readOnly}
           onChange={(e) => {
             const n = e.target.valueAsNumber;
             if (!Number.isNaN(n)) set(n);
           }}
-          className="w-full min-w-0 flex-1 border-x border-input bg-transparent px-2 text-center text-body-md text-foreground outline-none [appearance:textfield] [&::-webkit-inner-spin-button]:appearance-none [&::-webkit-outer-spin-button]:appearance-none"
+          className="w-full min-w-0 flex-1 border-x border-input bg-transparent px-2 py-3 text-center text-body-md text-foreground outline-none [appearance:textfield] [&::-webkit-inner-spin-button]:appearance-none [&::-webkit-outer-spin-button]:appearance-none"
           {...props}
         />
         <button
           type="button"
           aria-label="Increase"
-          disabled={disabled || (max != null && current >= max)}
+          disabled={disabled || readOnly || (max != null && current >= max)}
           onClick={() => set(current + step)}
-          className="flex w-9 shrink-0 items-center justify-center text-muted-foreground outline-none transition-colors hover:bg-accent hover:text-foreground focus-visible:bg-accent focus-visible:text-foreground focus-visible:ring-1 focus-visible:ring-inset focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-disabled"
+          className="flex w-9 shrink-0 items-center justify-center text-muted-foreground outline-none transition-colors hover:bg-accent hover:text-foreground focus-visible:bg-accent focus-visible:text-foreground focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-disabled"
         >
           <Plus className="size-4" />
         </button>

package/src/components/pagination.tsx

@@ -44,7 +44,7 @@ PaginationLink.displayName = "PaginationLink";
 
 const PaginationPrevious = ({ className, ...props }: React.ComponentProps<typeof PaginationLink>) => (
   <PaginationLink aria-label="Go to previous page" className={cn("w-auto gap-1 px-2.5", className)} {...props}>
-    <ChevronLeft className="size-4" />
+    <ChevronLeft className="size-4 rtl:-scale-x-100" />
     <span>Previous</span>
   </PaginationLink>
 );
@@ -53,7 +53,7 @@ PaginationPrevious.displayName = "PaginationPrevious";
 const PaginationNext = ({ className, ...props }: React.ComponentProps<typeof PaginationLink>) => (
   <PaginationLink aria-label="Go to next page" className={cn("w-auto gap-1 px-2.5", className)} {...props}>
     <span>Next</span>
-    <ChevronRight className="size-4" />
+    <ChevronRight className="size-4 rtl:-scale-x-100" />
   </PaginationLink>
 );
 PaginationNext.displayName = "PaginationNext";

package/src/components/popover.tsx

@@ -3,7 +3,9 @@
 import * as React from "react";
 import * as PopoverPrimitive from "@radix-ui/react-popover";
 import { cn } from "../lib/utils";
+import { withDirectionalPortal } from "./direction-provider";
 
+const PopoverPortal = withDirectionalPortal(PopoverPrimitive.Portal);
 const Popover = PopoverPrimitive.Root;
 const PopoverTrigger = PopoverPrimitive.Trigger;
 const PopoverAnchor = PopoverPrimitive.Anchor;
@@ -11,21 +13,43 @@ const PopoverAnchor = PopoverPrimitive.Anchor;
 const PopoverContent = React.forwardRef<
   React.ElementRef<typeof PopoverPrimitive.Content>,
   React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Content>
->(({ className, align = "center", sideOffset = 4, ...props }, ref) => (
-  <PopoverPrimitive.Portal>
+>(({ className, align = "center", sideOffset = 4, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, ...props }, ref) => (
+  <PopoverPortal>
     <PopoverPrimitive.Content
       ref={ref}
       align={align}
       sideOffset={sideOffset}
+      // Radix gives this `role="dialog"`, and a dialog without an accessible name is announced as just
+      // "dialog" — WCAG 4.1.2. Nothing here named it, so every Popover in the library shipped that way:
+      // found by running axe against the surface while it was open, which until this slice nothing did.
+      // The fallback is deliberately only a fallback. A caller who passes `aria-label` or points at a
+      // heading with `aria-labelledby` keeps theirs, and should: "Popover" tells a screen-reader user
+      // what kind of thing opened and nothing about what is in it. It is the floor, not the goal.
+      // Both naming props are destructured OUT of the spread, not read from it. Read from `props` with
+      // `{...props}` trailing, `aria-label={label}` with `label` undefined — the ordinary conditional-prop
+      // spelling — spreads the key back as undefined and deletes the attribute, so the fallback computed
+      // here would be erased and the dialog would ship unnamed again by the very pattern it guards.
+      aria-labelledby={ariaLabelledBy}
+      aria-label={ariaLabel ?? (ariaLabelledBy ? undefined : "Popover")}
       className={cn(
-        "z-overlay w-72 rounded-md border bg-popover p-4 text-popover-foreground shadow-md outline-none font-sans",
-        "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95",
+        // A surface wider than the window is not usable. Measured at 390px with the root font size
+        // doubled: this came out 576px, because `w-72` is rem and doubles with the text, and the
+        // context menu 416px — pushing the page 186px sideways, so a reader who asked for large text
+        // had to scroll horizontally to see a popover. Radix publishes the room it has as
+        // `--radix-popper-available-width`, so the cap is its own measurement rather than a viewport
+        // guess, and it binds only when the surface would otherwise overflow.
+        "z-overlay w-72 max-w-[var(--radix-popper-available-width)] rounded-md border bg-popover p-4 text-popover-foreground shadow-md outline-none font-sans",
+        "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[state=open]:duration-fast data-[state=open]:ease-enter data-[state=closed]:duration-instant data-[state=closed]:ease-exit",
+        // `data-side` is the side Radix RESOLVED the surface onto — it is already physical, having been
+        // flipped for direction and collisions before it reaches the DOM. The slide must therefore stay
+        // physical to travel away from the trigger; a logical class here would invert the animation under
+        // RTL and make the surface fly the wrong way. // rtl-ok
         "data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
         className,
       )}
       {...props}
     />
-  </PopoverPrimitive.Portal>
+  </PopoverPortal>
 ));
 PopoverContent.displayName = PopoverPrimitive.Content.displayName;
 

package/src/components/radio-group.tsx

@@ -6,9 +6,13 @@ import { Circle } from "lucide-react";
 import { cn } from "../lib/utils";
 
 /**
- * RadioGroup — reconciled 1:1 with the KinetixUI design source, node 54863:536.
- * 18px circle, 2px border. Unchecked border = `--input`; checked border + dot =
- * `--primary`. Focus = 2px `--ring` offset. `aria-invalid` → `--destructive`.
+ * RadioGroup — from the KinetixUI design source, node 54863:536: 18px circle, 2px border, checked border +
+ * dot = `--action`, focus = 2px `--ring` offset.
+ *
+ * Each item follows the selection-control state contract (TOKENS.md, "Selection controls"), exactly as
+ * Checkbox does: a `--muted-foreground` unchecked edge that clears 3:1, an 8% `--foreground` state layer on
+ * hover (14% pressed), a dot as the shape cue for checked, `aria-invalid="true"` → `--destructive` edge and
+ * dot, a focus ring no other layer can cover, and no response at all while disabled.
  */
 const RadioGroup = React.forwardRef<
   React.ElementRef<typeof RadioGroupPrimitive.Root>,
@@ -25,17 +29,28 @@ const RadioGroupItem = React.forwardRef<
   <RadioGroupPrimitive.Item
     ref={ref}
     className={cn(
-      "aspect-square size-[18px] rounded-full border-2 border-input text-action outline-none transition-colors",
-      "focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
-      "disabled:cursor-not-allowed disabled:opacity-disabled",
+      // rem rather than px, for the reason spelled out in checkbox.tsx: at a 200% default font size the
+      // 18px dot did not grow while its label did.
+      "aspect-square size-[1.125rem] rounded-full border-2 border-muted-foreground text-action outline-none",
+      "transition-[color,border-color,box-shadow] duration-instant ease-standard",
       "data-[state=checked]:border-action",
-      "aria-invalid:border-destructive",
+      // `aria-[invalid=true]:`, not `aria-invalid:`, which Tailwind 3 does not define (see checkbox.tsx).
+      // `text-` carries the dot, which is `fill-current`.
+      "aria-[invalid=true]:border-destructive aria-[invalid=true]:text-destructive",
+      "[@media(hover:hover)]:enabled:hover:[box-shadow:0_0_0_5px_hsl(var(--foreground)/0.08)]",
+      // Pressed is written twice: bare for touch, and again inside the hover media query, because Tailwind
+      // emits media-wrapped utilities after plain ones and the hover layer would otherwise outrank the press.
+      "enabled:active:[box-shadow:0_0_0_5px_hsl(var(--foreground)/0.14)]",
+      "[@media(hover:hover)]:enabled:active:[box-shadow:0_0_0_5px_hsl(var(--foreground)/0.14)]",
+      "[@media(hover:hover)]:enabled:hover:[&[data-state=unchecked]:not([aria-invalid=true])]:border-foreground",
+      "focus-visible:!ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+      "disabled:cursor-not-allowed disabled:opacity-disabled",
       className,
     )}
     {...props}
   >
     <RadioGroupPrimitive.Indicator className="flex items-center justify-center">
-      <Circle className="size-2.5 fill-action text-action" />
+      <Circle className="size-2.5 fill-current" />
     </RadioGroupPrimitive.Indicator>
   </RadioGroupPrimitive.Item>
 ));

package/src/components/segmented-control.tsx

@@ -13,6 +13,16 @@ import { cn } from "../lib/utils";
  * is fixed, not exposed — a segmented control that could go fully
  * unselected or multi-select isn't the pattern. Gap-fill addition (not in
  * the original Figma source).
+ *
+ * Surfaces follow the surface model (TOKENS.md): the track is an inset well, `--surface-grouped`, and the
+ * chosen segment is a small raised surface on it — `--card`, the Card's half-strength `--border` edge and
+ * `sm` depth. The track used to be `--muted` with a `--background` segment, which in dark mode put the
+ * chosen segment BELOW its track (`--background` is the darkest surface), so it read as a hole.
+ *
+ * States (TOKENS.md, "Selection controls"): an unchosen segment answers the pointer with the same
+ * `--foreground` state layer the other selection controls use (8% hover, 14% pressed) and `--foreground`
+ * text; chosen is surface + edge + depth + `--foreground` text, so it is never colour alone; focus is the
+ * ring; disabled is inert.
  */
 export type SegmentedControlProps = Omit<ToggleGroupPrimitive.ToggleGroupSingleProps, "type">;
 
@@ -23,7 +33,7 @@ const SegmentedControl = React.forwardRef<
   <ToggleGroupPrimitive.Root
     ref={ref}
     type="single"
-    className={cn("inline-flex items-center rounded-lg bg-muted p-1 font-sans", className)}
+    className={cn("inline-flex items-center rounded-lg bg-surface-grouped p-1 font-sans", className)}
     {...props}
   />
 ));
@@ -36,10 +46,16 @@ const SegmentedControlItem = React.forwardRef<
   <ToggleGroupPrimitive.Item
     ref={ref}
     className={cn(
-      "inline-flex flex-1 items-center justify-center whitespace-nowrap rounded-md px-3 py-1 text-label-md font-medium text-muted-foreground transition-all",
-      "outline-none focus-visible:ring-2 focus-visible:ring-ring",
+      "inline-flex flex-1 items-center justify-center whitespace-nowrap rounded-md px-3 py-1 text-label-md font-medium text-muted-foreground",
+      "transition-[color,background-color,box-shadow] duration-fast ease-standard",
+      "[@media(hover:hover)]:enabled:hover:data-[state=off]:bg-foreground/[0.08] [@media(hover:hover)]:enabled:hover:data-[state=off]:text-foreground",
+      // Pressed is written twice: bare for touch, and again inside the hover media query, because Tailwind
+      // emits media-wrapped utilities after plain ones and the hover layer would otherwise outrank the press.
+      "enabled:active:data-[state=off]:bg-foreground/[0.14] enabled:active:data-[state=off]:text-foreground",
+      "[@media(hover:hover)]:enabled:active:data-[state=off]:bg-foreground/[0.14] [@media(hover:hover)]:enabled:active:data-[state=off]:text-foreground",
+      "data-[state=on]:bg-card data-[state=on]:text-foreground data-[state=on]:[box-shadow:inset_0_0_0_1px_hsl(var(--border)/0.5),var(--shadow-sm)]",
+      "outline-none focus-visible:!ring-2 focus-visible:ring-ring",
       "disabled:pointer-events-none disabled:opacity-disabled",
-      "data-[state=on]:bg-background data-[state=on]:text-foreground data-[state=on]:shadow-sm",
       className,
     )}
     {...props}

package/src/components/select.tsx

@@ -4,12 +4,16 @@ import * as React from "react";
 import * as SelectPrimitive from "@radix-ui/react-select";
 import { Check, ChevronDown, ChevronUp } from "lucide-react";
 import { cn } from "../lib/utils";
+import { withDirectionalPortal } from "./direction-provider";
 
 /**
  * Select — reconciled 1:1 with the KinetixUI design source, node 54855:13882.
- * The trigger mirrors Input: `rounded-sm`, `border-input`, `--spacing-3` pad,
- * Body Medium text, a soft `--shadow-focus` glow, `--destructive` on aria-invalid.
+ * The trigger mirrors Input: `rounded-sm`, `--spacing-3` pad, Body Medium text, a soft `--shadow-focus`
+ * glow, `--destructive` on aria-invalid — and Input's text-entry state contract (TOKENS.md, "Text entry and
+ * navigation"): an 80% `--muted-foreground` edge at rest, full strength under a hovering pointer, and hover
+ * never over focus, an open list, invalid or disabled. Select has no read-only state.
  */
+const SelectPortal = withDirectionalPortal(SelectPrimitive.Portal);
 const Select = SelectPrimitive.Root;
 const SelectGroup = SelectPrimitive.Group;
 const SelectValue = SelectPrimitive.Value;
@@ -21,10 +25,23 @@ const SelectTrigger = React.forwardRef<
   <SelectPrimitive.Trigger
     ref={ref}
     className={cn(
-      "flex min-h-[44px] w-full items-center justify-between rounded-sm border border-input bg-background px-3 py-3",
+      "flex min-h-[44px] w-full items-center justify-between rounded-sm border border-muted-foreground/80 bg-background px-3 py-3",
       "font-sans text-body-md text-foreground",
-      "data-[placeholder]:text-muted-foreground [&>span]:line-clamp-1",
-      "outline-none transition-colors",
+      // The value wraps rather than being clamped to one line. `line-clamp-1` was invisible while the
+      // type scale was px — the value always fitted — but once text follows the reader's setting a
+      // two-line value is cut off at 200% with no ellipsis (measured: span needs 80px, gets 40px, and
+      // computed `text-overflow` is `clip`, not `ellipsis`), so "Select a fruit" rendered as "Select a".
+      // The trigger is already `min-h`, so letting it grow is what it was built for, and it matches how
+      // Input and Textarea absorb their own text. WCAG 1.4.4 asks for no loss of content at 200%.
+      //
+      // `min-w-0` and `overflow-wrap: anywhere` are what make that safe. A flex child keeps its
+      // min-content width by default, so a value with no break opportunity — an identifier, a URL with
+      // no separators — would simply not shrink: measured at 282px inside a 220px trigger, overflowing
+      // it and pushing the chevron outside. `line-clamp-1` had been hiding that by clipping. Breaking
+      // the token is the behaviour that keeps both the value and the chevron inside the control.
+      "data-[placeholder]:text-muted-foreground [&>span]:min-w-0 [&>span]:[overflow-wrap:anywhere]",
+      "outline-none transition-[border-color,box-shadow,background-color] duration-instant ease-standard",
+      "[@media(hover:hover)]:enabled:hover:[&:not(:focus):not([aria-invalid=true]):not([data-state=open])]:border-muted-foreground",
       "focus:border-action focus:shadow-focus",
       "data-[state=open]:border-action",
       "aria-[invalid=true]:border-destructive aria-[invalid=true]:focus:border-destructive aria-[invalid=true]:focus:shadow-focus-destructive",
@@ -47,13 +64,13 @@ const SelectContent = React.forwardRef<
   React.ElementRef<typeof SelectPrimitive.Content>,
   React.ComponentPropsWithoutRef<typeof SelectPrimitive.Content>
 >(({ className, children, position = "popper", ...props }, ref) => (
-  <SelectPrimitive.Portal>
+  <SelectPortal>
     <SelectPrimitive.Content
       ref={ref}
       position={position}
       className={cn(
         "relative z-overlay max-h-96 min-w-[8rem] overflow-hidden rounded-md border bg-popover text-popover-foreground shadow-md font-sans",
-        "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95",
+        "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[state=open]:duration-fast data-[state=open]:ease-enter data-[state=closed]:duration-instant data-[state=closed]:ease-exit",
         position === "popper" && "data-[side=bottom]:translate-y-1 data-[side=top]:-translate-y-1",
         className,
       )}
@@ -71,7 +88,7 @@ const SelectContent = React.forwardRef<
         <ChevronDown className="size-4" />
       </SelectPrimitive.ScrollDownButton>
     </SelectPrimitive.Content>
-  </SelectPrimitive.Portal>
+  </SelectPortal>
 ));
 SelectContent.displayName = SelectPrimitive.Content.displayName;
 

package/src/components/sheet.tsx

@@ -5,11 +5,12 @@ import * as SheetPrimitive from "@radix-ui/react-dialog";
 import { cva, type VariantProps } from "class-variance-authority";
 import { X } from "lucide-react";
 import { cn } from "../lib/utils";
+import { withDirectionalPortal } from "./direction-provider";
 
 const Sheet = SheetPrimitive.Root;
 const SheetTrigger = SheetPrimitive.Trigger;
 const SheetClose = SheetPrimitive.Close;
-const SheetPortal = SheetPrimitive.Portal;
+const SheetPortal = withDirectionalPortal(SheetPrimitive.Portal);
 
 const SheetOverlay = React.forwardRef<
   React.ElementRef<typeof SheetPrimitive.Overlay>,
@@ -18,7 +19,7 @@ const SheetOverlay = React.forwardRef<
   <SheetPrimitive.Overlay
     ref={ref}
     className={cn(
-      "fixed inset-0 z-overlay bg-foreground/40 backdrop-blur-sm data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+      "fixed inset-0 z-overlay bg-scrim backdrop-blur-sm data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=open]:duration-fast data-[state=open]:ease-enter data-[state=closed]:duration-instant data-[state=closed]:ease-exit",
       className,
     )}
     {...props}
@@ -73,7 +74,7 @@ const SheetHeader = ({ className, ...props }: React.HTMLAttributes<HTMLDivElemen
 SheetHeader.displayName = "SheetHeader";
 
 const SheetFooter = ({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) => (
-  <div className={cn("flex flex-col-reverse sm:flex-row sm:justify-end sm:space-x-2", className)} {...props} />
+  <div className={cn("flex flex-col-reverse gap-2 sm:flex-row sm:justify-end", className)} {...props} />
 );
 SheetFooter.displayName = "SheetFooter";
 

package/src/components/spinner.tsx

@@ -9,7 +9,7 @@ import { cn } from "../lib/utils";
  * dependency; `size` sets the diameter, `variant` swaps the indicator
  * colour for on-color surfaces.
  */
-const spinnerVariants = cva("inline-block animate-spin motion-reduce:animate-[spin_3s_linear_infinite] rounded-full border-2 border-current border-t-transparent", {
+const spinnerVariants = cva("inline-block animate-spin motion-reduce:animate-none rounded-full border-2 border-current border-t-transparent forced-colors:border-t-[Canvas]", {
   variants: {
     size: {
       sm: "size-4",

package/src/components/switch.tsx

@@ -5,9 +5,14 @@ import * as SwitchPrimitive from "@radix-ui/react-switch";
 import { cn } from "../lib/utils";
 
 /**
- * Switch — reconciled 1:1 with the KinetixUI design source, node 54855:13984.
- * 48×24 pill track. Off = `--tertiary` (#b0b0b0), on = `--primary`. 20px
- * `--background` thumb, travels 24px. Focus = 2px `--ring` offset.
+ * Switch — from the KinetixUI design source, node 54855:13984: 48×24 pill track, off = `--tertiary`, on =
+ * `--action`, 20px `--background` thumb that travels 24px, focus = 2px `--ring` offset.
+ *
+ * It follows the selection-control state contract (TOKENS.md, "Selection controls"): the same 8% / 14%
+ * `--foreground` state layer as Checkbox and Radio on hover and press, the on track steps to `--action`/90
+ * under the pointer, the thumb's position is the shape cue for on/off, the focus ring cannot be covered by
+ * any other layer, and a disabled switch does not answer the pointer. The off track stays `--tertiary`
+ * (2.6:1, a tracked SC 1.4.11 exception in check-contrast.mjs): the thumb and `aria-checked` carry it.
  */
 const Switch = React.forwardRef<
   React.ElementRef<typeof SwitchPrimitive.Root>,
@@ -16,18 +21,36 @@ const Switch = React.forwardRef<
   <SwitchPrimitive.Root
     ref={ref}
     className={cn(
-      "peer inline-flex h-6 w-12 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent transition-colors",
-      "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
-      "disabled:cursor-not-allowed disabled:opacity-disabled",
+      "peer inline-flex h-6 w-12 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent",
+      "transition-[background-color,box-shadow] duration-instant ease-standard",
       "data-[state=checked]:bg-action data-[state=unchecked]:bg-tertiary",
+      "[@media(hover:hover)]:enabled:hover:[box-shadow:0_0_0_5px_hsl(var(--foreground)/0.08)]",
+      // Pressed is written twice: bare for touch, and again inside the hover media query, because Tailwind
+      // emits media-wrapped utilities after plain ones and the hover layer would otherwise outrank the press.
+      "enabled:active:[box-shadow:0_0_0_5px_hsl(var(--foreground)/0.14)]",
+      "[@media(hover:hover)]:enabled:active:[box-shadow:0_0_0_5px_hsl(var(--foreground)/0.14)]",
+      "[@media(hover:hover)]:enabled:hover:data-[state=checked]:bg-action/90",
+      "focus-visible:outline-none focus-visible:!ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+      "disabled:cursor-not-allowed disabled:opacity-disabled",
       className,
     )}
     {...props}
   >
     <SwitchPrimitive.Thumb
       className={cn(
-        "pointer-events-none block size-5 rounded-full bg-background shadow-lg ring-0 transition-transform",
-        "data-[state=checked]:translate-x-6 data-[state=unchecked]:translate-x-0",
+        "pointer-events-none relative block size-5 rounded-full bg-background shadow-lg ring-0",
+        // The thumb travels along the INLINE axis of the switch's own direction: `inset-inline-start` is
+        // logical, so the browser resolves start against the direction the switch is laid out in — the
+        // nearest `dir`, in an LTR section of an RTL page as much as anywhere else. It used to be a physical
+        // `translate-x` flipped by `rtl:`, and Tailwind 3's `rtl:` is `[dir=rtl] *` — ANY rtl ancestor — so
+        // a switch in an LTR section of an RTL page was flipped too and its thumb landed 22px outside the
+        // track, over its own focus ring (check:selection-visual, "direction"). `:dir()` would have been the
+        // selector answer, but Vite 8's Lightning CSS lowers `:dir(ltr)` for its default targets to a
+        // `:not(:lang(ar, he, …))` guess about the page's LANGUAGE, which broke every RTL switch in the built
+        // Storybook — a consumer's toolchain can do the same. A logical property needs no selector at all.
+        // The offset is relative, so nothing around the switch reflows while it moves.
+        "transition-[inset-inline-start] duration-instant ease-standard",
+        "start-0 data-[state=checked]:start-6",
       )}
     />
   </SwitchPrimitive.Root>