@sixthshift/design-system 0.3.0 → 0.4.0

package/src/components/Spinner/Spinner.tsx

@@ -2,22 +2,47 @@ import { cn } from "@sixthshift/design-system/utils";
 import { cva, type VariantProps } from "class-variance-authority";
 import * as React from "react";
 
-const spinnerVariants = cva("animate-spin text-fg-subtle", {
+/**
+ * Geometry (size) plus the one `--spinner-fg` component token.
+ *
+ * The colour used to be `text-fg-subtle`, a semantic token named directly in
+ * the class string — the one thing a consumer could not do was recolour a
+ * spinner without fighting `className` against it. `--spinner-fg` in
+ * src/theme/recipes/spinner.css is now that seam: a consumer overrides the
+ * variable, scoped to whatever subtree they like, instead of overriding a
+ * class.
+ */
+const spinnerVariants = cva("spinner animate-spin text-(--spinner-fg)", {
   variants: {
     size: {
       sm: "h-4 w-4",
-      default: "h-6 w-6",
+      md: "h-6 w-6",
       lg: "h-8 w-8",
       xl: "h-12 w-12",
     },
   },
   defaultVariants: {
-    size: "default",
+    size: "md",
   },
 });
 
 export type SpinnerProps = React.SVGAttributes<SVGElement> & VariantProps<typeof spinnerVariants>;
 
+/**
+ * Animated loading indicator — an inline `<svg>`, `size` scales it (`sm` |
+ * `md` | `lg` | `xl`). Use it for a fetching-more state at the bottom
+ * of an already-rendered list, and for an initial load inside a container that
+ * already reserves its final height, so resolving the load does not jump the
+ * layout (see docs/states.md).
+ *
+ * It is `aria-hidden="true"` unconditionally — it announces nothing to
+ * assistive tech on its own, so pair it with visible or `sr-only` text (or a
+ * live region) if the loading state needs to be announced.
+ *
+ * Colour reads the `--spinner-fg` component token
+ * (src/theme/recipes/spinner.css) rather than a class name, so a consumer
+ * can recolour a spinner scoped to a subtree without fighting `className`.
+ */
 const Spinner = React.forwardRef<SVGSVGElement, SpinnerProps>(({ className, size, ...props }, ref) => (
   <svg
     ref={ref}

package/src/components/Switch/Switch.tsx

@@ -22,6 +22,24 @@ export type SwitchProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "o
   labelClassName?: string;
 };
 
+/**
+ * A boolean on/off control rendered as a track with a sliding thumb.
+ *
+ * Controlled via `checked`/`defaultChecked`/`onCheckedChange`
+ * (`useControllableState`). Renders `role="switch"` with `aria-checked`, plus
+ * a `data-state="checked" | "unchecked"` attribute the theme recipe
+ * (`switch.css`) styles off of.
+ *
+ * `pending` shows a spinner in the thumb and blocks clicks without disabling
+ * the control — it sets `aria-busy` rather than `disabled`, so the switch
+ * stays perceivable and focusable while the change is in flight.
+ *
+ * Pass `label` to wrap the switch in a `<Label>` linked to it by `id`;
+ * without one, the caller is responsible for its own accessible name (e.g.
+ * `aria-label`). Pass `name` to also render a hidden, read-only checkbox
+ * input so the value participates in native form submission (`value`
+ * defaults to `"on"`).
+ */
 const Switch = React.forwardRef<HTMLButtonElement, SwitchProps>(
   (
     {
@@ -63,8 +81,7 @@ const Switch = React.forwardRef<HTMLButtonElement, SwitchProps>(
           ref={ref}
           onClick={() => !pending && setChecked(!checked)}
           className={cn(
-            "peer inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent shadow-xs transition-colors focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-focus-ring focus-visible:ring-offset-2 focus-visible:ring-offset-bg-normal disabled:cursor-not-allowed disabled:opacity-50",
-            checked ? "bg-bg-brand" : "bg-bg-subtle",
+            "switch peer focus-visible:ring-(color:--switch-ring) inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent bg-(--switch-bg) shadow-xs transition-colors focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-offset-bg-normal disabled:cursor-not-allowed disabled:opacity-50",
             pending && "cursor-default",
             className
           )}
@@ -72,12 +89,18 @@ const Switch = React.forwardRef<HTMLButtonElement, SwitchProps>(
         >
           <span
             className={cn(
-              "pointer-events-none flex h-4 w-4 items-center justify-center rounded-full bg-bg-normal shadow-lg ring-0 transition-transform",
+              "switch-thumb pointer-events-none flex h-4 w-4 items-center justify-center rounded-full bg-(--switch-thumb-bg) shadow-lg ring-0 transition-transform",
               checked ? "translate-x-4" : "translate-x-0"
             )}
           >
             {pending && (
-              <svg className="h-2.5 w-2.5 animate-spin text-fg-subtle" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" aria-hidden="true">
+              <svg
+                className="h-2.5 w-2.5 animate-spin text-(--switch-thumb-fg)"
+                xmlns="http://www.w3.org/2000/svg"
+                fill="none"
+                viewBox="0 0 24 24"
+                aria-hidden="true"
+              >
                 <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
                 <path
                   className="opacity-75"

package/src/components/Tabs/Tabs.tsx

@@ -41,6 +41,12 @@ const TabsRoot = ({ items, value: controlledValue, defaultValue, onValueChange,
   return <TabsContext.Provider value={contextValue}>{children}</TabsContext.Provider>;
 };
 
+/**
+ * NOTE: Storybook shows the copy in Tabs.stories.tsx
+ * (`parameters.docs.description.component`), not this comment. react-docgen
+ * cannot extract a description from an `Object.assign` / cast export, so a
+ * second copy here would only drift. Edit the stories file.
+ */
 export const Tabs = Object.assign(TabsRoot, {
   List: TabsList,
   Panels: TabsPanels,

package/src/components/Tabs/components/TabsTrigger.tsx

@@ -4,16 +4,32 @@ import { cva } from "class-variance-authority";
 import { forwardRef } from "react";
 import { type TabItem, useTabsContext } from "./TabsContext";
 
+/**
+ * Geometry and behaviour only.
+ *
+ * Colour reads `--tabs-trigger-bg` / `--tabs-trigger-fg` component tokens
+ * (each with a `-hovered` state) whose values are decided by
+ * src/theme/recipes/tabs.css. That file is the mapping from `selected` to a
+ * semantic token — the layer that used to be the two branches of a `cva`
+ * `selected` variant here, compiled into class-name literals and unreachable
+ * from outside. Nothing in this file names a colour, which is the point: the
+ * semantics are now configurable without a release.
+ */
 const tabsTriggerVariants = cva(
-  `inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md
-  px-3 py-1.5 text-sm font-medium cursor-pointer transition-colors focus-visible:outline-hidden
-  focus-visible:ring-2 focus-visible:ring-focus-ring
+  `tabs-trigger inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md
+  px-3 py-1.5 text-sm font-medium cursor-pointer transition-colors bg-(--tabs-trigger-bg)
+  text-(--tabs-trigger-fg) hover:bg-(--tabs-trigger-bg-hovered) hover:text-(--tabs-trigger-fg-hovered)
+  focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-(color:--tabs-trigger-ring)
   focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50`,
   {
     variants: {
+      // No longer carries colour — see the recipe file. Kept as a variant
+      // (rather than dropped) purely so `data-selected` and the exported
+      // `tabsTriggerVariants` shape stay symmetric with the `isSelected` prop
+      // callers already pass.
       selected: {
-        true: "bg-bg-brand-pressed text-fg-on-brand-pressed",
-        false: "text-fg-subtle hover:bg-bg-subtle-hovered hover:text-fg-normal",
+        true: "",
+        false: "",
       },
     },
     defaultVariants: {
@@ -53,6 +69,7 @@ export const TabsTrigger = forwardRef<HTMLButtonElement, TabsTriggerProps>(({ it
       tabIndex={isSelected ? 0 : -1}
       disabled={item.disabled}
       data-index={index}
+      data-selected={isSelected}
       className={cn(tabsTriggerVariants({ selected: isSelected }))}
       onClick={handleClick}
     >

package/src/components/TagChip/TagChip.tsx

@@ -3,26 +3,28 @@ import { cn } from "@sixthshift/design-system/utils";
 import { X } from "lucide-react";
 import * as React from "react";
 
-/**
- * One tag, rendered prettily. A `namespace:value` tag (`project:website`)
- * shows the namespace muted; a plain tag (`urgent`) renders as-is.
- *
- * Pure presentation. Entity-reference tags (`person:per_…`) are NOT rendered
- * here — the web `TagRef` intercepts those and resolves them to a name chip
- * (identity-rendering.md); TagChip never shows a raw id.
- *
- * Two disjoint modes: navigable (no `onRemove`; the caller wraps it in a link)
- * or removable (`onRemove` renders an × — used by `TagInput` and edit surfaces).
- */
 export type TagChipProps = {
   tag: string;
   /** When set, renders an × affordance. Omit for read-only / navigable chips. */
   onRemove?: () => void;
-  /** `sm` (default) for rows; `default` for detail pages. */
-  size?: "sm" | "default";
+  /** `sm` (default) for rows; `md` for detail pages. */
+  size?: "sm" | "md";
   className?: string;
 };
 
+/**
+ * One tag, rendered prettily. A `namespace:value` tag (`project:website`)
+ * shows the namespace muted; a plain tag (`urgent`) renders as-is.
+ *
+ * Pure presentation. Entity-reference tags (`person:per_…`) are NOT rendered
+ * here — the consuming app is expected to intercept those and resolve them to
+ * a name chip; TagChip never shows a raw id.
+ *
+ * Two disjoint modes, chosen by whether `onRemove` is passed: navigable (no
+ * `onRemove`; the caller wraps it in a link) or removable (`onRemove` renders
+ * an × — used by `TagInput` and edit surfaces). Built on `Badge`
+ * (`variant="outline" intent="muted"`).
+ */
 export const TagChip = React.forwardRef<HTMLSpanElement, TagChipProps>(({ tag, onRemove, size = "sm", className }, ref) => {
   const sep = tag.indexOf(":");
   const namespace = sep > 0 ? tag.slice(0, sep) : null;
@@ -33,16 +35,16 @@ export const TagChip = React.forwardRef<HTMLSpanElement, TagChipProps>(({ tag, o
       ref={ref}
       variant="outline"
       intent="muted"
-      className={cn("gap-1 font-normal", size === "sm" ? "px-1.5 py-0 text-[10px]" : "px-2 py-0.5 text-xs", className)}
+      className={cn("tag-chip gap-1 font-normal", size === "sm" ? "px-1.5 py-0 text-[10px]" : "px-2 py-0.5 text-xs", className)}
     >
-      {namespace && <span className="text-fg-subtle">{namespace}:</span>}
+      {namespace && <span className="text-(--tag-chip-namespace-fg)">{namespace}:</span>}
       <span>{value}</span>
       {onRemove && (
         <button
           type="button"
           onClick={onRemove}
           aria-label={`Remove ${tag}`}
-          className="-mr-0.5 ml-0.5 rounded-sm text-fg-subtle hover:text-fg-normal focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-focus-ring"
+          className="focus-visible:ring-(color:--tag-chip-remove-ring) -mr-0.5 ml-0.5 rounded-sm text-(--tag-chip-remove-fg) hover:text-(--tag-chip-remove-fg-hovered) focus-visible:outline-none focus-visible:ring-2"
         >
           <X className="h-3 w-3" />
         </button>

package/src/components/TagInput/TagInput.tsx

@@ -2,14 +2,6 @@ import { TagChip } from "@sixthshift/design-system/tag-chip";
 import { cn } from "@sixthshift/design-system/utils";
 import { forwardRef, type KeyboardEvent, useState } from "react";
 
-/**
- * Token input for tags: existing tags render as removable chips, typing plus
- * Enter or comma commits a new one, Backspace on an empty field removes the
- * last. Duplicates are ignored. Controlled — the parent owns `value`.
- *
- * The chrome matches `Input` (same border/focus tokens) so it sits naturally
- * among other form fields.
- */
 export type TagInputProps = {
   value: string[];
   onChange: (tags: string[]) => void;
@@ -18,6 +10,17 @@ export type TagInputProps = {
   className?: string;
 };
 
+/**
+ * Token input for tags: existing tags render as removable `TagChip`s, typing
+ * plus Enter or comma commits a new one, Backspace on an empty field removes
+ * the last. Duplicates are ignored. Controlled only — there is no
+ * `defaultValue`, the parent always owns `value`.
+ *
+ * The chrome matches `Input` (same border/focus tokens) so it sits naturally
+ * among other form fields; the field has no visible label of its own, so
+ * give it an accessible name via a `<label htmlFor={id}>` (pass `id`) or
+ * `aria-label`.
+ */
 export const TagInput = forwardRef<HTMLDivElement, TagInputProps>(({ value, onChange, placeholder = "Add a tag…", id, className }, ref) => {
   const [draft, setDraft] = useState("");
 

package/src/components/Text/Text.tsx

@@ -22,6 +22,15 @@ export type TextProps = React.HTMLAttributes<HTMLElement> & {
   as?: TextElement;
 };
 
+/**
+ * The polymorphic base every typography preset (`Heading`, `Body`,
+ * `Emphasis`, ...) is built on: renders as `as` (default `span`) and applies
+ * no styling of its own beyond `className`.
+ *
+ * Reach for a preset first — the typographic ramp (docs/visual-hierarchy.md)
+ * is what keeps text sizing and color consistent across the app. Use `Text`
+ * directly only for one-off text that doesn't fit an existing preset.
+ */
 const Text = React.forwardRef<HTMLElement, TextProps>(({ as: Comp = "span", className, ...props }, ref) => (
   <Comp
     // biome-ignore lint/suspicious/noExplicitAny: polymorphic ref requires any

package/src/components/TextInline/TextInline.tsx

@@ -27,6 +27,17 @@ const textInlineVariants = cva("inline-flex items-center", {
 
 export type TextInlineProps = React.HTMLAttributes<HTMLSpanElement> & VariantProps<typeof textInlineVariants>;
 
+/**
+ * Lays out several inline fragments — typically `Text` nodes, but any inline
+ * content works — in a single flex row with a consistent gap and cross-axis
+ * alignment, so a label/value pair or a value/badge pair doesn't need one-off
+ * spacing classes at every call site.
+ *
+ * Renders a single `<span>`. `gap` (default `sm`) and `align` (default
+ * `baseline`) are the only two axes; there's no `as` polymorphism, and this
+ * is not a variant of `Text` — `TextInline` is about spacing *between*
+ * inline children, not about styling the text itself.
+ */
 const TextInline = React.forwardRef<HTMLSpanElement, TextInlineProps>(({ className, gap, align, ...props }, ref) => (
   <span ref={ref} className={cn(textInlineVariants({ gap, align }), className)} {...props} />
 ));

package/src/components/Textarea/Textarea.tsx

@@ -3,11 +3,23 @@ import * as React from "react";
 
 export type TextareaProps = React.TextareaHTMLAttributes<HTMLTextAreaElement>;
 
+/**
+ * Multi-line text input for longer free-form text.
+ *
+ * A thin styled wrapper around `<textarea>` — no custom props beyond
+ * `React.TextareaHTMLAttributes`, no auto-resize, and no maximum-length UI of
+ * its own. Height comes from a `min-h-[60px]` default plus whatever `rows`
+ * or `className` the caller passes; growing with content is the caller's
+ * responsibility. Controlled or uncontrolled exactly like a native textarea.
+ *
+ * Meant to be wrapped by `FormField` for label, description and validation
+ * wiring.
+ */
 const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(({ className, ...props }, ref) => {
   return (
     <textarea
       className={cn(
-        "flex min-h-[60px] w-full rounded-md border border-border-normal bg-transparent px-3 py-2 text-sm shadow-xs placeholder:text-fg-subtle focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-focus-ring disabled:cursor-not-allowed disabled:opacity-50",
+        "textarea border-(color:--textarea-border) focus-visible:ring-(color:--textarea-ring) flex min-h-[60px] w-full rounded-md border bg-transparent px-3 py-2 text-sm shadow-xs placeholder:text-(--textarea-placeholder-fg) focus-visible:outline-hidden focus-visible:ring-2 disabled:cursor-not-allowed disabled:opacity-50",
         className
       )}
       ref={ref}

package/src/components/TimePicker/TimeColumn.tsx

@@ -7,9 +7,25 @@ export type TimeColumnProps = {
   onSelect: (value: number) => void;
   formatValue?: (value: number) => string;
   disabled?: (value: number) => boolean;
+  /**
+   * Move DOM focus to the selected option on mount.
+   *
+   * Off by default: a column that grabs focus when it appears is wrong for a
+   * pointer user who clicked a trigger. `TimePicker` turns it on only when the
+   * popover was opened from the keyboard (`Alt+ArrowDown`), where the whole
+   * point of opening it was to pick an hour.
+   */
+  autoFocusSelected?: boolean;
 };
 
-export const TimeColumn = ({ values, selected, onSelect, formatValue = (v) => String(v).padStart(2, "0"), disabled }: TimeColumnProps) => {
+export const TimeColumn = ({
+  values,
+  selected,
+  onSelect,
+  formatValue = (v) => String(v).padStart(2, "0"),
+  disabled,
+  autoFocusSelected = false,
+}: TimeColumnProps) => {
   const containerRef = useRef<HTMLDivElement>(null);
   const selectedRef = useRef<HTMLButtonElement>(null);
 
@@ -25,6 +41,13 @@ export const TimeColumn = ({ values, selected, onSelect, formatValue = (v) => St
     }
   }, []);
 
+  // Seed focus once, when the caller asked for it. Keyed on the flag alone:
+  // `selected` changes as the user picks, and re-running then would drag focus
+  // back to the option they started from.
+  useEffect(() => {
+    if (autoFocusSelected) selectedRef.current?.focus();
+  }, [autoFocusSelected]);
+
   return (
     <div ref={containerRef} role="listbox" className="h-48 w-14 overflow-y-auto overscroll-contain rounded-lg border border-border-subtle bg-bg-subtle/50">
       {/* Top spacer for centering first items */}

package/src/components/TimePicker/TimePicker.tsx

@@ -1,16 +1,17 @@
 import { autoUpdate, FloatingPortal, flip, offset, shift, useClick, useDismiss, useFloating, useInteractions } from "@floating-ui/react";
 import { useControllableState } from "@sixthshift/design-system/hooks";
 import { cn } from "@sixthshift/design-system/utils";
-import { Clock, X } from "lucide-react";
+import { Clock } from "lucide-react";
 import * as React from "react";
 import { useCallback, useId, useMemo, useState } from "react";
 import { fromISOTime, fromISOTimeOrUndefined, type Temporal, toISOTimeOrUndefined } from "../../date-time";
+import { PickerField } from "../../internal";
 import { Button } from "../Button";
 import { Separator } from "../Separator";
 import { PeriodSelector } from "./PeriodSelector";
 import { TimeColumn } from "./TimeColumn";
+import { TimeSegments } from "./TimeSegments";
 import {
-  formatTimeDisplay,
   generateHours,
   generateMinutes,
   generateSeconds,
@@ -26,6 +27,38 @@ import type { ParsedTime, TimePeriod, TimePickerProps, TimePresetOption } from "
 
 export type { TimePickerProps };
 
+/**
+ * A typeable time field and a popover of scrollable hour/minute(/second)
+ * columns, as one control. The value is an `ISOTime` string — `"09:30"` and
+ * `"09:30:00"` are both accepted as input, and `onChange` always emits the
+ * canonical `HH:MM:SS` form regardless of `format`. There is no timezone
+ * conversion: the value is a plain time, not an instant.
+ *
+ * The field is spinbutton segments rather than a text box, and is built to be
+ * typed straight through: `0230p` is half past two in the afternoon, `345` in a
+ * 24-hour field is 03:45 (there is no 30th hour, so the digit rolls into the
+ * minute). `a`/`p` set the meridiem, arrows step any segment, `Alt+ArrowDown`
+ * opens the columns and moves focus to the hour, and `Enter` is Apply. See
+ * `SegmentedField` for the full keyboard model. `minuteStep` sets the column's
+ * increment and deliberately does not constrain typing.
+ *
+ * Typing and picking move one value: the segments show the draft while the
+ * popover is open and the committed value while it is closed. A partial time is
+ * never reported — clearing a segment reports `undefined`.
+ *
+ * Supports both controlled (`value`/`onChange`) and uncontrolled
+ * (`defaultValue`) use. Opening the popover seeds the draft columns from the
+ * committed value (or the current time, if none); scrolling the columns only
+ * updates the draft, and the footer's Apply commits it and closes, Cancel
+ * discards it. A "Now" button resets the draft to the current time without
+ * closing the popover.
+ *
+ * `format` (`"HH:mm" | "HH:mm:ss"`) shows or hides the seconds column;
+ * `clockFormat` (`"12h" | "24h"`) shows or hides the AM/PM selector.
+ * `minTime`/`maxTime` bound the selectable time inclusively — Apply is a
+ * no-op while the draft falls outside them. `minuteStep` controls the minute
+ * column's increment. `presets` renders a sidebar of quick picks.
+ */
 export const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>((props, ref) => {
   const {
     value,
@@ -37,7 +70,6 @@ export const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>((pro
     minTime,
     maxTime,
     presets,
-    placeholder = "Select time",
     name,
     isDisabled = false,
     isInvalid = false,
@@ -84,10 +116,20 @@ export const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>((pro
     return "AM";
   });
 
+  // Whether the hour column should take focus when the popover mounts — true
+  // only when it was opened from the keyboard. See `openWithColumnFocus`.
+  const [autoFocusHour, setAutoFocusHour] = useState(false);
+  // The draft is three numbers, so it cannot represent "no time". This does:
+  // clearing a segment while the popover is open has to stick rather than being
+  // instantly resynced back from the draft.
+  const [draftCleared, setDraftCleared] = useState(false);
+
   // Sync draft when popup opens
   const handleOpenChange = useCallback(
     (newOpen: boolean) => {
+      if (!newOpen) setAutoFocusHour(false);
       if (newOpen) {
+        setDraftCleared(false);
         if (committedValue) {
           const parsed = temporalToParsed(committedValue);
           setDraftHour(clockFormat === "12h" ? to12Hour(parsed.hour).hour12 : parsed.hour);
@@ -121,6 +163,11 @@ export const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>((pro
 
   // Apply changes
   const handleApply = useCallback(() => {
+    if (draftCleared) {
+      setCommittedValue(undefined);
+      setOpen(false);
+      return;
+    }
     const parsed = getDraftTime();
     const temporalTime = parsedToTemporal(parsed);
 
@@ -131,7 +178,7 @@ export const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>((pro
 
     setCommittedValue(temporalTime);
     setOpen(false);
-  }, [getDraftTime, temporalMinTime, temporalMaxTime, setCommittedValue]);
+  }, [draftCleared, getDraftTime, temporalMinTime, temporalMaxTime, setCommittedValue]);
 
   // Cancel changes
   const handleCancel = useCallback(() => {
@@ -202,9 +249,55 @@ export const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>((pro
   const inputId = `timepicker-input-${id}`;
 
   // Display value
-  const displayValue = committedValue ? formatTimeDisplay(committedValue, clockFormat, format) : "";
   const hasValue = Boolean(committedValue);
 
+  // ---------------------------------------------------------------------------
+  // The typeable field.
+  //
+  // One value, two ways to move it: the segments show the draft while the
+  // popover is open and the committed value while it is closed, so typing a time
+  // moves the columns and scrolling a column shows up in the segments. The
+  // commit contract stays single — open means Apply/Cancel owns it, closed means
+  // a complete time commits as soon as it is complete.
+  // ---------------------------------------------------------------------------
+
+  const draftTime = parsedToTemporal(getDraftTime());
+  const segmentValue = open ? (draftCleared ? undefined : draftTime) : committedValue;
+
+  // A typed time can fall outside `minTime`/`maxTime`, which the columns would
+  // refuse. The field says so rather than silently clamping. See DatePicker.
+  const outOfBounds = segmentValue !== undefined && isTimeDisabled(segmentValue, temporalMinTime, temporalMaxTime);
+
+  const handleSegmentsChange = useCallback(
+    (time: Temporal.PlainTime | undefined) => {
+      if (!open) {
+        setCommittedValue(time);
+        return;
+      }
+      if (!time) {
+        setDraftCleared(true);
+        return;
+      }
+      setDraftCleared(false);
+      setDraftHour(clockFormat === "12h" ? to12Hour(time.hour).hour12 : time.hour);
+      setDraftMinute(time.minute);
+      setDraftSecond(time.second);
+      setDraftPeriod(to12Hour(time.hour).period);
+    },
+    [clockFormat, open, setCommittedValue]
+  );
+
+  /** `Alt+ArrowDown` from a segment: open the columns *and* go there. */
+  const openWithColumnFocus = useCallback(() => {
+    setAutoFocusHour(true);
+    handleOpenChange(true);
+  }, [handleOpenChange]);
+
+  /** `Enter` in a segment commits the draft, matching the popover's Apply. */
+  const handleFieldSubmit = useCallback(() => {
+    if (open) handleApply();
+  }, [handleApply, open]);
+
   // Generate column values
   const hours = generateHours(clockFormat);
   const minutes = generateMinutes(minuteStep);
@@ -214,38 +307,32 @@ export const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>((pro
     <>
       {/* Trigger Input */}
       <div ref={ref} className="relative flex items-center">
-        <Clock className="pointer-events-none absolute left-3 h-4 w-4 text-fg-subtle" />
-        <input
-          ref={refs.setReference as React.Ref<HTMLInputElement>}
-          id={inputId}
-          type="text"
-          readOnly
-          value={displayValue}
-          placeholder={placeholder}
-          disabled={isDisabled}
-          role="combobox"
-          aria-invalid={isInvalid}
-          aria-haspopup="dialog"
-          aria-expanded={open}
-          aria-controls={open ? contentId : undefined}
-          className={cn(
-            `flex h-9 w-full cursor-pointer rounded-md border border-border-normal bg-transparent py-1 pl-9 text-sm shadow-xs transition-colors placeholder:text-fg-subtle focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-focus-ring disabled:cursor-not-allowed disabled:opacity-50`,
-            hasValue ? "pr-9" : "pr-3",
-            isInvalid && "border-border-danger",
-            className
-          )}
-          {...getReferenceProps()}
-        />
-        {hasValue && !isDisabled && (
-          <button
-            type="button"
-            onClick={handleClear}
-            className="absolute right-3 rounded-sm p-0.5 text-fg-subtle hover:bg-bg-subtle hover:text-fg-normal focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-focus-ring"
-            aria-label="Clear time"
-          >
-            <X className="h-3.5 w-3.5" />
-          </button>
-        )}
+        <PickerField
+          ref={refs.setReference as React.Ref<HTMLDivElement>}
+          className={cn("w-full min-w-45", className)}
+          icon={<Clock className="h-4 w-4" />}
+          toggleLabel="Open time picker"
+          toggleProps={getReferenceProps()}
+          isOpen={open}
+          contentId={contentId}
+          isDisabled={isDisabled}
+          isInvalid={isInvalid || outOfBounds}
+          onClear={hasValue && !isDisabled ? handleClear : undefined}
+          clearLabel="Clear time"
+        >
+          <TimeSegments
+            className="h-full flex-1"
+            id={inputId}
+            value={segmentValue}
+            onChange={handleSegmentsChange}
+            format={format}
+            clockFormat={clockFormat}
+            isDisabled={isDisabled}
+            isInvalid={isInvalid || outOfBounds}
+            onOpenRequest={openWithColumnFocus}
+            onSubmit={handleFieldSubmit}
+          />
+        </PickerField>
 
         {/* Hidden input for form submission */}
         {name && committedValue && <input type="hidden" name={name} value={temporalTimeToISO(committedValue, format)} />}
@@ -258,7 +345,7 @@ export const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>((pro
             ref={refs.setFloating}
             id={contentId}
             role="dialog"
-            aria-modal="true"
+            aria-label="Choose time"
             style={floatingStyles}
             className="z-popover rounded-xl border border-border-normal bg-bg-normal p-4 shadow-lg"
             {...getFloatingProps()}
@@ -302,6 +389,7 @@ export const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>((pro
                     selected={draftHour}
                     onSelect={setDraftHour}
                     formatValue={clockFormat === "12h" ? (v) => String(v) : (v) => String(v).padStart(2, "0")}
+                    autoFocusSelected={autoFocusHour}
                   />
 
                   {/* Minutes */}
@@ -325,7 +413,7 @@ export const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>((pro
                     <Button type="button" variant="ghost" size="sm" onClick={handleCancel}>
                       Cancel
                     </Button>
-                    <Button type="button" variant="solid" size="sm" onClick={handleApply}>
+                    <Button type="button" variant="solid" intent="brand" size="sm" onClick={handleApply}>
                       Apply
                     </Button>
                   </div>