@sixthshift/design-system 0.2.1 → 0.4.0

package/src/components/ProgressBar/ProgressBar.tsx

@@ -1,5 +1,6 @@
 import { Caption } from "@sixthshift/design-system/caption";
 import { cn } from "@sixthshift/design-system/utils";
+import * as React from "react";
 
 export type ProgressBarProps = {
   completed: number;
@@ -10,33 +11,50 @@ export type ProgressBarProps = {
   className?: string;
 };
 
-export const ProgressBar = ({ completed, total, showFraction = true, label = "Progress", className }: ProgressBarProps) => {
-  // A caller can hand us anything; the bar must not render an out-of-range
-  // width (a negative `width` is invalid CSS) or report impossible progress.
-  const isMeasurable = total > 0;
-  const clamped = isMeasurable ? Math.min(Math.max(completed, 0), total) : 0;
-  const percentage = isMeasurable ? (clamped / total) * 100 : 0;
+/**
+ * Determinate progress meter: a labelled fill bar plus an optional `n/total`
+ * fraction (`showFraction`, default `true`).
+ *
+ * The bar itself is `role="progressbar"` with `aria-valuemin`/`-valuenow`/
+ * `-valuemax`/`-valuetext`, and `label` (default `"Progress"`) sets its
+ * accessible name — give it something more specific than the default when
+ * more than one bar can appear on a page. `completed` is clamped into
+ * `[0, total]` before it drives the fill width or `aria-valuenow`, so an
+ * out-of-range value (negative, or greater than `total`) can't produce
+ * invalid CSS or an impossible reported value — though the fraction text
+ * still shows the raw, unclamped numbers. When `total` is not positive the
+ * bar renders as indeterminate: no `aria-valuenow`/`aria-valuemax`, 0% fill.
+ */
+export const ProgressBar = React.forwardRef<HTMLDivElement, ProgressBarProps>(
+  ({ completed, total, showFraction = true, label = "Progress", className }, ref) => {
+    // A caller can hand us anything; the bar must not render an out-of-range
+    // width (a negative `width` is invalid CSS) or report impossible progress.
+    const isMeasurable = total > 0;
+    const clamped = isMeasurable ? Math.min(Math.max(completed, 0), total) : 0;
+    const percentage = isMeasurable ? (clamped / total) * 100 : 0;
 
-  return (
-    <div className={cn("flex items-center gap-3", className)}>
-      <div
-        role="progressbar"
-        aria-label={label}
-        aria-valuemin={0}
-        aria-valuemax={isMeasurable ? total : undefined}
-        // An indeterminate progressbar omits aria-valuenow; with no positive
-        // total there is no meaningful progress to report.
-        aria-valuenow={isMeasurable ? clamped : undefined}
-        aria-valuetext={isMeasurable ? `${clamped} of ${total}` : undefined}
-        className="h-2 flex-1 overflow-hidden rounded-full bg-bg-strong"
-      >
-        <div className="h-full rounded-full bg-fg-success transition-all" style={{ width: `${percentage}%` }} />
+    return (
+      <div ref={ref} className={cn("flex items-center gap-3", className)}>
+        <div
+          role="progressbar"
+          aria-label={label}
+          aria-valuemin={0}
+          aria-valuemax={isMeasurable ? total : undefined}
+          // An indeterminate progressbar omits aria-valuenow; with no positive
+          // total there is no meaningful progress to report.
+          aria-valuenow={isMeasurable ? clamped : undefined}
+          aria-valuetext={isMeasurable ? `${clamped} of ${total}` : undefined}
+          className="h-2 flex-1 overflow-hidden rounded-full bg-bg-strong"
+        >
+          <div className="h-full rounded-full bg-fg-success transition-all" style={{ width: `${percentage}%` }} />
+        </div>
+        {showFraction && (
+          <Caption className="shrink-0">
+            {completed}/{total}
+          </Caption>
+        )}
       </div>
-      {showFraction && (
-        <Caption className="shrink-0">
-          {completed}/{total}
-        </Caption>
-      )}
-    </div>
-  );
-};
+    );
+  }
+);
+ProgressBar.displayName = "ProgressBar";

package/src/components/RadioButton/RadioButton.tsx

@@ -23,6 +23,32 @@ const RadioButtonIcon = () => (
   </svg>
 );
 
+/**
+ * A single custom radio option — a button with `role="radio"` rather than
+ * a native `<input type="radio">`, so it can be styled without fighting
+ * native radio rendering.
+ *
+ * Unlike `Checkbox`, it holds no internal state: `checked` is a plain
+ * controlled prop (default `false`, no `defaultChecked`), and clicking an
+ * unselected radio calls `onCheckedChange(true)` — the caller owns tracking
+ * which option in a group is selected. In practice that means using
+ * `RadioButtonGroup` to manage a group's value, or wiring up the shared
+ * selection by hand.
+ *
+ * Clicking an already-selected radio does nothing and reports nothing: a radio
+ * is not a toggle, and the way to deselect one is to select a sibling. That
+ * makes `onCheckedChange` a one-way signal — it is only ever called with
+ * `true`.
+ *
+ * Only participates in native form submission when `name` is set, via a
+ * hidden native `<input type="radio">` rendered alongside the button and
+ * kept in sync (`value` defaults to `"on"`); give every radio in a group the
+ * same `name` to group them for native submission.
+ *
+ * Passing `label` wraps the button and a `<Label>` together and wires
+ * `htmlFor`/`id` between them; without it, you get just the button and must
+ * supply your own accessible name.
+ */
 const RadioButton = React.forwardRef<HTMLButtonElement, RadioButtonProps>(
   ({ className, checked = false, onCheckedChange, disabled, name, value = "on", label, labelClassName, id: idProp, ...props }, ref) => {
     const generatedId = React.useId();
@@ -39,10 +65,15 @@ const RadioButton = React.forwardRef<HTMLButtonElement, RadioButtonProps>(
           data-state={checked ? "checked" : "unchecked"}
           disabled={disabled}
           ref={ref}
-          onClick={() => onCheckedChange?.(!checked)}
+          // A radio is not a toggle: activating the selected option leaves it
+          // selected, and reports nothing, so a caller holding the selection
+          // does not see a spurious change. Deselection happens by selecting a
+          // sibling, which is what `RadioButtonGroup` does.
+          onClick={() => {
+            if (!checked) onCheckedChange?.(true);
+          }}
           className={cn(
-            "peer h-4 w-4 shrink-0 cursor-pointer rounded-full border border-border-brand shadow focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-focus-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
-            checked && "bg-bg-brand text-fg-on-brand",
+            "radio-button peer border-(color:--radio-button-border) focus-visible:ring-(color:--radio-button-ring) h-4 w-4 shrink-0 cursor-pointer rounded-full border bg-(--radio-button-bg) text-(--radio-button-fg) shadow focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
             className
           )}
           {...props}

package/src/components/RadioButtonGroup/RadioButtonGroup.tsx

@@ -37,6 +37,32 @@ export type RadioButtonGroupProps = Omit<React.HTMLAttributes<HTMLDivElement>, "
   onBlur?: () => void;
 };
 
+/**
+ * A set of mutually exclusive radio options sharing one controlled/
+ * uncontrolled `string` selection, via the `value`/`defaultValue`/
+ * `onValueChange` triad (`useControllableState`).
+ *
+ * `variant="default"` (the default) renders one `RadioButton` per option.
+ * `variant="button"` is a separate rendering path — not a re-skinned
+ * `RadioButton` — a row/column of plain buttons with `role="radio"`;
+ * contiguous buttons touch and share borders (`appearance="segmented"`, the
+ * default) or sit apart with their own rounded corners
+ * (`appearance="separate"`).
+ *
+ * Implements the WAI-ARIA radiogroup keyboard pattern: the group is one tab
+ * stop, landing on the checked option (or the first enabled option if none
+ * is checked), and arrow/Home/End keys move focus *and* selection between
+ * enabled options, wrapping at the ends.
+ *
+ * Form submission only happens when `name` is set. In the default variant
+ * that means each underlying `RadioButton` gets `name`, so one hidden
+ * native radio input is rendered per option; in the button variant the
+ * group itself renders a single hidden `<input type="hidden">` carrying the
+ * selected value.
+ *
+ * Renders `role="radiogroup"`; focus leaving the whole group — not just
+ * moving between options — fires `onBlur`.
+ */
 const RadioButtonGroup = React.forwardRef<HTMLDivElement, RadioButtonGroupProps>(
   (
     {
@@ -81,6 +107,12 @@ const RadioButtonGroup = React.forwardRef<HTMLDivElement, RadioButtonGroupProps>
     );
 
     const handleOptionSelect = (optionValue: string) => {
+      // Re-selecting the current option reports nothing, as a native radio does
+      // not. The guard lives here as well as in `RadioButton` because the button
+      // variant is a separate rendering path that never goes through it — and
+      // the two variants must not disagree about this. `ToggleGroup` in
+      // `"single"` mode already works this way.
+      if (optionValue === value) return;
       setValue(optionValue);
     };
 

package/src/components/SearchInput/SearchInput.tsx

@@ -1,4 +1,5 @@
 import { Input } from "@sixthshift/design-system/input";
+import { cn } from "@sixthshift/design-system/utils";
 import { Search, X } from "lucide-react";
 import * as React from "react";
 
@@ -10,6 +11,16 @@ export type SearchInputProps = Omit<React.InputHTMLAttributes<HTMLInputElement>,
   clearLabel?: string;
 };
 
+/**
+ * Text input specialised for search: a search icon fixed on the left and,
+ * once there is a value, a clear button on the right.
+ *
+ * Wraps `Input`, using its `iconLeft`/`iconRight` slots, rather than
+ * reimplementing the field. Always controlled — `value` is required and
+ * there is no `defaultValue`/uncontrolled mode. `onChange` receives the
+ * string value directly, not the change event. Clearing calls `onClear` if
+ * provided, otherwise calls `onChange("")`.
+ */
 const SearchInput = React.forwardRef<HTMLInputElement, SearchInputProps>(
   ({ className, value, onChange, onClear, clearLabel = "Clear search", ...props }, ref) => {
     const handleClear = () => {
@@ -29,12 +40,12 @@ const SearchInput = React.forwardRef<HTMLInputElement, SearchInputProps>(
         iconLeft={<Search />}
         iconRight={
           value ? (
-            <button type="button" onClick={handleClear} aria-label={clearLabel} className="rounded hover:bg-bg-subtle">
+            <button type="button" onClick={handleClear} aria-label={clearLabel} className="rounded hover:bg-(--search-input-clear-bg-hovered)">
               <X />
             </button>
           ) : undefined
         }
-        className={className}
+        className={cn("search-input", className)}
         {...props}
       />
     );

package/src/components/Select/Select.tsx

@@ -1,7 +1,7 @@
 import { autoUpdate, flip, offset, shift, size, useFloating } from "@floating-ui/react";
 import { useControllableState } from "@sixthshift/design-system/hooks";
-import { type HTMLAttributes, useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
-import { SelectDropdown } from "./SelectDropdown";
+import { forwardRef, type HTMLAttributes, type ReactElement, type Ref, useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+import { SelectDropdown, selectOptionId } from "./SelectDropdown";
 import { SelectTriggerButton, SelectTriggerSearch } from "./SelectTrigger";
 import { useSelectKeyboard } from "./useSelectKeyboard";
 
@@ -37,7 +37,13 @@ type SelectMultipleProps<T extends string = string> = SelectBaseProps<T> & {
 
 export type SelectProps<T extends string = string> = SelectSingleProps<T> | SelectMultipleProps<T>;
 
-export const Select = <T extends string = string>(props: SelectProps<T>) => {
+/**
+ * `forwardRef` erases the generic, so the implementation takes the ref as an
+ * ordinary second argument and the exported `Select` re-declares the generic
+ * signature over it. Consumers keep `Select<"a" | "b">` inference *and* get a
+ * ref; without the cast they would have to choose.
+ */
+const SelectRoot = forwardRef(function SelectRoot<T extends string = string>(props: SelectProps<T>, rootRef: Ref<HTMLDivElement>) {
   const {
     options,
     onBlur,
@@ -71,6 +77,11 @@ export const Select = <T extends string = string>(props: SelectProps<T>) => {
   const [highlightedIndex, setHighlightedIndex] = useState(-1);
   const [searchValue, setSearchValue] = useState("");
   const listboxRef = useRef<HTMLDivElement | null>(null);
+  // Also held in state: the listbox is portalled, and FloatingPortal creates its
+  // container in an effect, so the node lands a commit after `open` flips. A ref
+  // alone is still null when the open effect runs — state re-renders us when the
+  // node actually arrives.
+  const [listboxNode, setListboxNode] = useState<HTMLDivElement | null>(null);
   const inputRef = useRef<HTMLInputElement>(null);
   const optionRefs = useRef<Map<number, HTMLButtonElement>>(new Map());
   const wasOpenRef = useRef(false);
@@ -111,6 +122,11 @@ export const Select = <T extends string = string>(props: SelectProps<T>) => {
     whileElementsMounted: autoUpdate,
   });
 
+  const setListbox = useCallback((node: HTMLDivElement | null) => {
+    listboxRef.current = node;
+    setListboxNode(node);
+  }, []);
+
   const focusTrigger = useCallback(() => {
     (refs.reference.current as HTMLElement | null)?.focus();
   }, [refs.reference]);
@@ -142,18 +158,38 @@ export const Select = <T extends string = string>(props: SelectProps<T>) => {
     [isMultiple, setMultiValue, setSingleValue]
   );
 
+  const handleListKeyDown = useSelectKeyboard({
+    open,
+    searchable,
+    searchValue,
+    highlightedIndex,
+    displayOptions: filteredOptions,
+    setOpen,
+    setHighlightedIndex,
+    setSearchValue,
+    handleSelect,
+    focusTrigger,
+  });
+
   const handleTriggerKeyDown = useCallback(
     (event: React.KeyboardEvent<HTMLButtonElement>) => {
       if (disabled || collapsed) return;
       if (!open && (event.key === "ArrowDown" || event.key === "ArrowUp" || event.key === "Enter" || event.key === " ")) {
         event.preventDefault();
         setOpen(true);
+        return;
       }
       if (searchable && !open && event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey) {
         setOpen(true);
+        return;
       }
+      // Focus normally moves into the listbox as it opens, but it can still be
+      // on the trigger — the frame the dropdown mounts in, or after the user
+      // shift-tabs back to it. Handle navigation here too rather than dropping
+      // the keystroke.
+      handleListKeyDown(event);
     },
-    [disabled, collapsed, open, setOpen, searchable]
+    [disabled, collapsed, open, setOpen, searchable, handleListKeyDown]
   );
 
   const handleSearchChange = useCallback((val: string) => {
@@ -186,6 +222,14 @@ export const Select = <T extends string = string>(props: SelectProps<T>) => {
     wasOpenRef.current = open;
   }, [open, filteredOptions, searchable, selectedValues]);
 
+  // Non-searchable: focus the listbox itself, so arrow keys reach the scoped
+  // keydown handler and a screen reader follows aria-activedescendant. The
+  // searchable variant keeps focus in its input instead.
+  useEffect(() => {
+    if (!open || searchable) return;
+    listboxNode?.focus();
+  }, [open, searchable, listboxNode]);
+
   // Scroll highlighted option into view
   useEffect(() => {
     if (open && highlightedIndex >= 0) {
@@ -215,32 +259,28 @@ export const Select = <T extends string = string>(props: SelectProps<T>) => {
     return () => document.removeEventListener("mousedown", handler);
   }, [open, setOpen, refs]);
 
-  useSelectKeyboard({
-    open,
-    searchable,
-    searchValue,
-    highlightedIndex,
-    displayOptions: filteredOptions,
-    setOpen,
-    setHighlightedIndex,
-    setSearchValue,
-    handleSelect,
-    focusTrigger,
-  });
-
   // The listbox id must be unique per instance: it is referenced by
   // aria-controls, and a hardcoded value meant two Selects on one page
   // produced duplicate ids and cross-wired ARIA.
   const listboxId = useId();
+  const activeOptionId = open && highlightedIndex >= 0 && highlightedIndex < filteredOptions.length ? selectOptionId(listboxId, highlightedIndex) : undefined;
 
   // Strip mode from DOM props
   const { mode: _, value: _v, defaultValue: _dv, onValueChange: _oc, ...htmlProps } = restProps as Record<string, unknown>;
 
+  // `role="listbox"` requires an accessible name of its own, and the trigger
+  // can't supply one: its label is the current *value*, and in searchable mode
+  // it is an input whose name would resolve to whatever has been typed. Use the
+  // caller's `aria-label` when there is one, else the placeholder — the closest
+  // thing this component has to a field label.
+  const listboxLabel = typeof htmlProps["aria-label"] === "string" ? (htmlProps["aria-label"] as string) : placeholder;
+
   return (
     <>
       {searchable && open && !collapsed ? (
         <SelectTriggerSearch
           setReference={refs.setReference}
+          rootRef={rootRef}
           inputRef={inputRef}
           searchValue={searchValue}
           disabled={disabled}
@@ -248,12 +288,15 @@ export const Select = <T extends string = string>(props: SelectProps<T>) => {
           open={open}
           className={className}
           onSearchChange={handleSearchChange}
+          onKeyDown={handleListKeyDown}
           listboxId={listboxId}
+          activeOptionId={activeOptionId}
           props={htmlProps as React.InputHTMLAttributes<HTMLInputElement>}
         />
       ) : (
         <SelectTriggerButton
           setReference={refs.setReference}
+          rootRef={rootRef}
           open={open}
           disabled={disabled}
           collapsed={collapsed}
@@ -272,7 +315,9 @@ export const Select = <T extends string = string>(props: SelectProps<T>) => {
         <SelectDropdown
           setFloating={refs.setFloating}
           listboxId={listboxId}
-          listboxRef={listboxRef}
+          setListbox={setListbox}
+          label={listboxLabel}
+          activeOptionId={activeOptionId}
           floatingStyles={floatingStyles}
           displayOptions={filteredOptions}
           highlightedIndex={highlightedIndex}
@@ -282,8 +327,19 @@ export const Select = <T extends string = string>(props: SelectProps<T>) => {
           multiple={isMultiple}
           onSelect={handleSelect}
           onHighlight={setHighlightedIndex}
+          onKeyDown={handleListKeyDown}
         />
       )}
     </>
   );
-};
+});
+
+SelectRoot.displayName = "Select";
+
+/**
+ * NOTE: Storybook shows the copy in Select.stories.tsx
+ * (`parameters.docs.description.component`), not this comment. react-docgen
+ * cannot extract a description from this declaration shape, so keeping a
+ * second copy here would only drift. Edit the stories file.
+ */
+export const Select = SelectRoot as <T extends string = string>(props: SelectProps<T> & { ref?: Ref<HTMLDivElement> }) => ReactElement;

package/src/components/Select/SelectDropdown.tsx

@@ -4,10 +4,22 @@ import { Check } from "lucide-react";
 import type React from "react";
 import type { WritableRefObject } from "../../internal/types";
 
+/**
+ * Options are addressed by id, not by focus: the listbox (or the search input)
+ * keeps focus and points `aria-activedescendant` at the highlighted option, so
+ * both sides need to agree on the id.
+ */
+export const selectOptionId = (listboxId: string, index: number) => `${listboxId}-option-${index}`;
+
 interface SelectDropdownProps<T extends string> {
   setFloating: (node: HTMLElement | null) => void;
   listboxId: string;
-  listboxRef: WritableRefObject<HTMLDivElement | null>;
+  /** Publishes the listbox node upward — Select focuses it and scrolls it. */
+  setListbox: (node: HTMLDivElement | null) => void;
+  /** Names the listbox — a bare `role="listbox"` has no accessible name. */
+  label: string;
+  /** The highlighted option's id, or undefined when nothing is highlighted. */
+  activeOptionId: string | undefined;
   floatingStyles: React.CSSProperties;
   displayOptions: readonly { value: T; label: string }[];
   highlightedIndex: number;
@@ -17,12 +29,15 @@ interface SelectDropdownProps<T extends string> {
   multiple: boolean;
   onSelect: (value: T) => void;
   onHighlight: (index: number) => void;
+  onKeyDown: (event: React.KeyboardEvent<HTMLElement>) => void;
 }
 
 export const SelectDropdown = <T extends string>({
   setFloating,
   listboxId,
-  listboxRef,
+  setListbox,
+  label,
+  activeOptionId,
   floatingStyles,
   displayOptions,
   highlightedIndex,
@@ -32,25 +47,35 @@ export const SelectDropdown = <T extends string>({
   multiple,
   onSelect,
   onHighlight,
+  onKeyDown,
 }: SelectDropdownProps<T>) => (
   <FloatingPortal>
     <div
       ref={(node) => {
         setFloating(node);
-        listboxRef.current = node;
+        setListbox(node);
       }}
       id={listboxId}
       role="listbox"
+      aria-label={label}
       aria-multiselectable={multiple || undefined}
+      aria-activedescendant={activeOptionId}
+      // Focus lands here when the dropdown opens (the searchable variant keeps
+      // it in the input instead), which is what makes `aria-activedescendant`
+      // and the scoped keydown handler work.
       tabIndex={-1}
+      onKeyDown={onKeyDown}
       style={floatingStyles}
-      className="z-popover max-h-60 overflow-y-auto rounded-md border border-border-normal bg-bg-normal shadow-lg"
+      className="select-dropdown border-(color:--select-dropdown-border) z-popover max-h-60 overflow-y-auto rounded-md border bg-(--select-dropdown-bg) shadow-lg"
     >
       {displayOptions.length === 0 ? (
-        <div className="px-3 py-2 text-center text-fg-subtle text-sm">{searchValue ? `No results for "${searchValue}"` : "No options available"}</div>
+        <div className="px-3 py-2 text-center text-(--select-dropdown-empty-fg) text-sm">
+          {searchValue ? `No results for "${searchValue}"` : "No options available"}
+        </div>
       ) : (
         displayOptions.map((option, index) => {
           const isSelected = selectedValues.has(option.value);
+          const isHighlighted = highlightedIndex === index;
           return (
             <button
               key={option.value}
@@ -59,23 +84,31 @@ export const SelectDropdown = <T extends string>({
                 else optionRefs.current.delete(index);
               }}
               type="button"
+              id={selectOptionId(listboxId, index)}
               role="option"
               aria-selected={isSelected}
+              // Surfaces the keyboard/mouse "current" option as an attribute
+              // the select.css recipe selects on, rather than compiling it
+              // straight into a class name — see select.css's header.
+              data-highlighted={isHighlighted ? "true" : undefined}
+              // The options are not tab stops and must not steal focus: the
+              // listbox holds it and delegates via aria-activedescendant, so a
+              // click that moved focus onto the option would strand the keyboard
+              // handler with nothing listening.
+              tabIndex={-1}
+              onMouseDown={(event) => event.preventDefault()}
               onClick={() => onSelect(option.value)}
               onMouseEnter={() => onHighlight(index)}
               className={cn(
-                `flex w-full cursor-pointer items-center px-3 py-2 text-fg-normal text-sm transition-colors`,
+                `select-option flex w-full cursor-pointer items-center bg-(--select-option-bg) px-3 py-2 text-(--select-option-fg) text-sm transition-colors`,
                 multiple && "gap-2",
-                highlightedIndex === index && "bg-bg-subtle",
-                isSelected ? "font-medium text-fg-normal" : "text-fg-subtle"
+                isSelected && "font-medium"
               )}
             >
               {multiple && (
                 <span
-                  className={cn(
-                    "flex h-4 w-4 shrink-0 items-center justify-center rounded-xs border",
-                    isSelected ? "border-border-brand bg-bg-brand text-fg-on-brand" : "border-border-normal"
-                  )}
+                  data-selected={isSelected ? "true" : undefined}
+                  className="select-option-indicator border-(color:--select-option-indicator-border) flex h-4 w-4 shrink-0 items-center justify-center rounded-xs border bg-(--select-option-indicator-bg) text-(--select-option-indicator-fg)"
                 >
                   {isSelected && <Check className="h-3 w-3" />}
                 </span>

package/src/components/Select/SelectTrigger.tsx

@@ -1,9 +1,12 @@
 import { cn } from "@sixthshift/design-system/utils";
 import { ChevronDown, X } from "lucide-react";
-import type { HTMLAttributes } from "react";
+import type { HTMLAttributes, Ref } from "react";
+import type { WritableRefObject } from "../../internal/types";
 
 interface SelectTriggerButtonProps {
   setReference: (node: HTMLElement | null) => void;
+  /** Consumer ref from Select, attached to this trigger's root element. */
+  rootRef?: Ref<HTMLDivElement>;
   listboxId: string;
   open: boolean;
   disabled: boolean;
@@ -19,6 +22,7 @@ interface SelectTriggerButtonProps {
 
 export const SelectTriggerButton = ({
   setReference,
+  rootRef,
   listboxId,
   open,
   disabled,
@@ -37,7 +41,7 @@ export const SelectTriggerButton = ({
   const showClear = showClearButton && !collapsed;
 
   return (
-    <div className="relative w-full">
+    <div ref={rootRef} className="select-trigger relative w-full">
       <button
         ref={setReference}
         type="button"
@@ -45,7 +49,7 @@ export const SelectTriggerButton = ({
         onKeyDown={onKeyDown}
         disabled={disabled}
         className={cn(
-          `flex w-full cursor-pointer items-center gap-2 rounded-md border border-border-normal bg-bg-normal px-3 py-2 font-medium text-fg-normal text-sm transition-colors hover:bg-bg-subtle focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring disabled:cursor-not-allowed disabled:opacity-50`,
+          `border-(color:--select-trigger-border) focus-visible:ring-(color:--select-trigger-ring) flex w-full cursor-pointer items-center gap-2 rounded-md border bg-(--select-trigger-bg) px-3 py-2 font-medium text-(--select-trigger-fg) text-sm transition-colors hover:bg-(--select-trigger-bg-hovered) focus-visible:outline-none focus-visible:ring-2 disabled:cursor-not-allowed disabled:opacity-50`,
           collapsed ? "justify-center" : "justify-between",
           showClear && "pr-9",
           className
@@ -63,7 +67,7 @@ export const SelectTriggerButton = ({
           <>
             <span className="truncate">{displayLabel}</span>
             <span className="flex shrink-0 items-center gap-1">
-              <ChevronDown className={cn("h-4 w-4 text-fg-subtle transition-transform", open && "rotate-180")} />
+              <ChevronDown className={cn("h-4 w-4 text-(--select-trigger-icon-fg) transition-transform", open && "rotate-180")} />
             </span>
           </>
         )}
@@ -73,7 +77,7 @@ export const SelectTriggerButton = ({
           type="button"
           onClick={onClear}
           disabled={disabled}
-          className="absolute top-1/2 right-8 -translate-y-1/2 rounded-sm p-0.5 text-fg-subtle hover:bg-bg-subtle hover:text-fg-normal focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring"
+          className="select-trigger-clear focus-visible:ring-(color:--select-trigger-ring) absolute top-1/2 right-8 -translate-y-1/2 rounded-sm p-0.5 text-(--select-trigger-clear-fg) hover:bg-(--select-trigger-clear-bg-hovered) hover:text-(--select-trigger-clear-fg-hovered) focus-visible:outline-none focus-visible:ring-2"
           aria-label="Clear selection"
         >
           <X className="h-3.5 w-3.5" />
@@ -85,7 +89,11 @@ export const SelectTriggerButton = ({
 
 interface SelectTriggerSearchProps {
   setReference: (node: HTMLElement | null) => void;
+  /** Consumer ref from Select, attached to this trigger's root element. */
+  rootRef?: Ref<HTMLDivElement>;
   listboxId: string;
+  /** Id of the highlighted option — the input keeps focus and delegates to it. */
+  activeOptionId: string | undefined;
   inputRef: React.RefObject<HTMLInputElement | null>;
   searchValue: string;
   disabled: boolean;
@@ -93,12 +101,15 @@ interface SelectTriggerSearchProps {
   open: boolean;
   className: string | undefined;
   onSearchChange: (value: string) => void;
+  onKeyDown: (event: React.KeyboardEvent<HTMLElement>) => void;
   props: React.InputHTMLAttributes<HTMLInputElement>;
 }
 
 export const SelectTriggerSearch = ({
   setReference,
+  rootRef,
   listboxId,
+  activeOptionId,
   inputRef,
   searchValue,
   disabled,
@@ -106,25 +117,37 @@ export const SelectTriggerSearch = ({
   open,
   className,
   onSearchChange,
+  onKeyDown,
   props,
 }: SelectTriggerSearchProps) => (
-  <div ref={setReference} className={cn("relative flex w-full items-center", className)}>
+  // floating-ui anchors to this element and the consumer may also want it, so
+  // both refs run off one callback rather than one silently winning.
+  <div
+    ref={(node) => {
+      setReference(node);
+      if (typeof rootRef === "function") rootRef(node);
+      else if (rootRef) (rootRef as WritableRefObject<HTMLDivElement | null>).current = node;
+    }}
+    className={cn("select-trigger relative flex w-full items-center", className)}
+  >
     <input
       ref={inputRef as React.RefObject<HTMLInputElement>}
       type="text"
       value={searchValue}
       onChange={(e) => onSearchChange(e.target.value)}
+      onKeyDown={onKeyDown}
       placeholder={displayLabel}
       disabled={disabled}
       className={cn(
-        `flex-1 rounded-md border border-border-normal bg-bg-normal px-3 py-2 font-medium text-fg-normal text-sm transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring disabled:cursor-not-allowed disabled:opacity-50`
+        `border-(color:--select-trigger-border) focus-visible:ring-(color:--select-trigger-ring) flex-1 rounded-md border bg-(--select-trigger-bg) px-3 py-2 font-medium text-(--select-trigger-fg) text-sm transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:cursor-not-allowed disabled:opacity-50`
       )}
       role="combobox"
       aria-expanded={open}
       aria-controls={listboxId}
+      aria-activedescendant={activeOptionId}
       aria-autocomplete="list"
       {...props}
     />
-    <ChevronDown className="pointer-events-none absolute right-3 h-4 w-4 text-fg-subtle" />
+    <ChevronDown className="pointer-events-none absolute right-3 h-4 w-4 text-(--select-trigger-icon-fg)" />
   </div>
 );