@sixthshift/design-system 0.6.0 → 0.8.0

package/src/components/Message/Message.tsx

@@ -48,6 +48,8 @@ export type MessageIntent = Loose<MessageIntentName>;
 export type MessageProps = React.HTMLAttributes<HTMLDivElement> &
   VariantProps<typeof messageVariants> & {
     intent?: MessageIntent | undefined;
+    /** Name of a brand the theme defines, rendered as `data-brand`. Omitted, the message follows the nearest `data-brand` ancestor. */
+    brand?: string | undefined;
     /** Simple API: Optional title displayed above children */
     title?: React.ReactNode;
     /** Simple API: Optional icon displayed on the left */
@@ -99,27 +101,29 @@ function intentRole(intent: MessageIntent): "status" | "alert" {
  * simple API can't express. Message detects which one is in use by
  * inspecting its children, so the two aren't meant to be mixed.
  */
-export const Message = React.forwardRef<HTMLDivElement, MessageProps>(({ className, intent = "neutral", size, title, icon, children, ...props }, ref) => {
-  const hasCompoundChildren = React.Children.toArray(children).some(
-    (child) =>
-      React.isValidElement(child) &&
-      (child.type === MessageIcon || child.type === MessageBody || child.type === MessageTitle || child.type === MessageDescription)
-  );
+export const Message = React.forwardRef<HTMLDivElement, MessageProps>(
+  ({ className, intent = "neutral", brand, size, title, icon, children, ...props }, ref) => {
+    const hasCompoundChildren = React.Children.toArray(children).some(
+      (child) =>
+        React.isValidElement(child) &&
+        (child.type === MessageIcon || child.type === MessageBody || child.type === MessageTitle || child.type === MessageDescription)
+    );
 
-  return (
-    <div ref={ref} role={intentRole(intent)} data-intent={intent} className={cn(messageVariants({ size, className }))} {...props}>
-      {hasCompoundChildren ? (
-        children
-      ) : (
-        <>
-          {icon && <MessageIcon>{icon}</MessageIcon>}
-          <MessageBody>
-            {title && <MessageTitle>{title}</MessageTitle>}
-            <MessageDescription>{children}</MessageDescription>
-          </MessageBody>
-        </>
-      )}
-    </div>
-  );
-});
+    return (
+      <div ref={ref} role={intentRole(intent)} data-intent={intent} data-brand={brand} className={cn(messageVariants({ size, className }))} {...props}>
+        {hasCompoundChildren ? (
+          children
+        ) : (
+          <>
+            {icon && <MessageIcon>{icon}</MessageIcon>}
+            <MessageBody>
+              {title && <MessageTitle>{title}</MessageTitle>}
+              <MessageDescription>{children}</MessageDescription>
+            </MessageBody>
+          </>
+        )}
+      </div>
+    );
+  }
+);
 Message.displayName = "Message";

package/src/components/Modal/Modal.tsx

@@ -4,6 +4,7 @@ import { FloatingFocusManager, FloatingOverlay, FloatingPortal, useDismiss, useF
 import { useMergedFloatingRef, usePresence } from "@sixthshift/design-system/hooks";
 import { cn } from "@sixthshift/design-system/utils";
 import { forwardRef, type HTMLAttributes, type ReactNode, useCallback, useContext, useEffect, useId, useMemo, useState } from "react";
+import { useOpenerBrand } from "../../internal/brandScope";
 import { hasOpenEscapeLayer, useEscapeDialog } from "../../internal/escapeLayers";
 import { ModalBody, ModalContext, ModalFooter, ModalHeader } from "./components";
 
@@ -35,6 +36,12 @@ export type ModalProps = Pick<HTMLAttributes<HTMLDivElement>, "className" | "sty
   closable?: boolean;
   /** Vertical alignment on desktop. "center" (default) or "top" (anchored near top, content grows down) */
   align?: "center" | "top";
+  /**
+   * Name of a brand the theme defines, rendered as `data-brand` on the dialog.
+   * Omitted, the modal takes the brand scope of the control that opened it
+   * (whatever held focus), since the portal leaves the trigger's scope behind.
+   */
+  brand?: string | undefined;
 };
 
 // =============================================================================
@@ -63,6 +70,7 @@ const ModalRoot = forwardRef<HTMLDivElement, ModalProps>(
       dismissable = true,
       closable,
       align = "center",
+      brand,
       "aria-label": ariaLabel,
       "aria-labelledby": ariaLabelledBy,
       "aria-describedby": ariaDescribedBy,
@@ -81,6 +89,8 @@ const ModalRoot = forwardRef<HTMLDivElement, ModalProps>(
     }, [onOpenChange, contextValue]);
 
     const { ref: presenceRef, state, isMounted, show, hide } = usePresence();
+    // Mount-driven, so the modal is open for as long as it exists.
+    const openerBrand = useOpenerBrand(true);
 
     useEffect(() => {
       show();
@@ -163,6 +173,7 @@ const ModalRoot = forwardRef<HTMLDivElement, ModalProps>(
               aria-describedby={ariaDescribedBy}
               tabIndex={-1}
               data-state={state}
+              data-brand={brand ?? openerBrand}
               className={cn(
                 "modal fixed flex flex-col overflow-hidden outline-hidden",
                 "border-(color:--modal-border) rounded-xl border bg-(--modal-bg)",

package/src/components/NumberStepper/NumberStepper.tsx

@@ -0,0 +1,227 @@
+"use client";
+
+import { useControllableState } from "@sixthshift/design-system/hooks";
+import { cn } from "@sixthshift/design-system/utils";
+import { cva, type VariantProps } from "class-variance-authority";
+import { Minus, Plus } from "lucide-react";
+import * as React from "react";
+
+/**
+ * Geometry only. Every colour reads a `--number-stepper-*` component token
+ * whose value is decided by src/components/NumberStepper/number-stepper.recipe.css.
+ *
+ * `size` tracks Input's and Button's heights (`sm` 32px, `md` 36px, `lg`
+ * 40px) so a stepper sits on the same baseline as the fields beside it.
+ */
+const numberStepperVariants = cva(
+  // One literal, deliberately — see Button.tsx for why a `+` concatenation is a trap.
+  "number-stepper border-(color:--number-stepper-border) focus-within:ring-(color:--number-stepper-ring) inline-flex w-fit items-stretch overflow-hidden rounded-md border bg-(--number-stepper-bg) text-(--number-stepper-fg) shadow-xs transition-colors focus-within:ring-2 data-[disabled=true]:cursor-not-allowed data-[disabled=true]:opacity-50",
+  {
+    variants: {
+      size: {
+        sm: "h-8 text-xs [&_svg]:size-3.5",
+        md: "h-9 text-sm [&_svg]:size-4",
+        lg: "h-10 text-sm [&_svg]:size-4",
+      },
+    },
+    defaultVariants: {
+      size: "md",
+    },
+  }
+);
+
+/** Button width per size — square against the field's height. */
+const buttonGeometry: Record<string, string> = {
+  sm: "w-8",
+  md: "w-9",
+  lg: "w-10",
+};
+
+/** Input width per size — room for three digits before it grows. */
+const inputGeometry: Record<string, string> = {
+  sm: "w-10",
+  md: "w-12",
+  lg: "w-14",
+};
+
+export type NumberStepperSize = NonNullable<VariantProps<typeof numberStepperVariants>["size"]>;
+
+export type NumberStepperProps = Omit<
+  React.InputHTMLAttributes<HTMLInputElement>,
+  "value" | "defaultValue" | "onChange" | "size" | "min" | "max" | "step" | "type"
+> &
+  VariantProps<typeof numberStepperVariants> & {
+    /** Controlled value. */
+    value?: number;
+    /** Initial value in uncontrolled mode. Defaults to `min`, or `0` without one. */
+    defaultValue?: number;
+    /** Called with the new, already-clamped value. */
+    onValueChange?: (value: number) => void;
+    /** Lowest reachable value. Defaults to `0` — quantities are the common case. */
+    min?: number;
+    /** Highest reachable value. Unbounded when omitted. */
+    max?: number;
+    /** Increment for the buttons and arrow keys. `PageUp`/`PageDown` move ten of them. */
+    step?: number;
+    /** Accessible name for the decrement button. */
+    decrementLabel?: string;
+    /** Accessible name for the increment button. */
+    incrementLabel?: string;
+    /** Extra classes for the inner `<input>`; `className` styles the surrounding group. */
+    inputClassName?: string;
+  };
+
+function clamp(value: number, min: number, max: number | undefined): number {
+  const floored = Math.max(min, value);
+  return max === undefined ? floored : Math.min(max, floored);
+}
+
+/**
+ * A whole-number field with decrement and increment buttons — a cart
+ * quantity, a guest count, a per-day capacity.
+ *
+ * Implements the WAI-ARIA spinbutton pattern on the `<input>` itself:
+ * `role="spinbutton"` with `aria-valuenow`/`min`/`max`, `ArrowUp`/`ArrowDown`
+ * step, `PageUp`/`PageDown` step by ten, and `Home`/`End` jump to the bounds
+ * that exist. The two buttons are pointer affordances and stay out of the tab
+ * order, so the field is one tab stop — the same reason RadioButtonGroup is.
+ *
+ * Typing is free-form while focused and committed on blur or `Enter`: the
+ * draft is parsed, rounded to the nearest `step` from `min`, and clamped.
+ * Anything unparseable reverts to the last committed value rather than
+ * reporting `NaN`. Every value `onValueChange` receives is in range.
+ *
+ * Controlled or uncontrolled through the `value`/`defaultValue`/
+ * `onValueChange` triad. `name` submits the committed value with a form, since
+ * the input is a real `<input>`. The ref and every unlisted prop land on that
+ * input — so `FormField`'s `id`/`aria-describedby` wiring reaches the control
+ * — while `className` styles the surrounding group.
+ */
+export const NumberStepper = React.forwardRef<HTMLInputElement, NumberStepperProps>(
+  (
+    {
+      className,
+      inputClassName,
+      size = "md",
+      value: controlledValue,
+      defaultValue,
+      onValueChange,
+      min = 0,
+      max,
+      step = 1,
+      disabled = false,
+      readOnly = false,
+      decrementLabel = "Decrease",
+      incrementLabel = "Increase",
+      onKeyDown,
+      onBlur,
+      onFocus,
+      ...props
+    },
+    ref
+  ) => {
+    const [value, setValue] = useControllableState({
+      value: controlledValue,
+      defaultValue: clamp(defaultValue ?? min, min, max),
+      onChange: onValueChange,
+    });
+
+    // The text being typed, or `null` when the field shows the committed value.
+    const [draft, setDraft] = React.useState<string | null>(null);
+
+    const commit = (next: number) => {
+      const snapped = min + Math.round((next - min) / step) * step;
+      const clamped = clamp(snapped, min, max);
+      if (clamped !== value) setValue(clamped);
+    };
+
+    const commitDraft = () => {
+      if (draft === null) return;
+      const parsed = Number.parseFloat(draft);
+      setDraft(null);
+      if (Number.isFinite(parsed)) commit(parsed);
+    };
+
+    const interactive = !disabled && !readOnly;
+    const atMin = value <= min;
+    const atMax = max !== undefined && value >= max;
+
+    const handleKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
+      onKeyDown?.(event);
+      if (event.defaultPrevented || !interactive) return;
+
+      const moves: Record<string, (() => number) | undefined> = {
+        ArrowUp: () => value + step,
+        ArrowDown: () => value - step,
+        PageUp: () => value + step * 10,
+        PageDown: () => value - step * 10,
+        Home: () => min,
+        End: max === undefined ? undefined : () => max,
+      };
+      const move = moves[event.key];
+
+      if (event.key === "Enter") {
+        commitDraft();
+        return;
+      }
+      if (!move) return;
+
+      event.preventDefault();
+      setDraft(null);
+      commit(move());
+    };
+
+    const handleBlur = (event: React.FocusEvent<HTMLInputElement>) => {
+      commitDraft();
+      onBlur?.(event);
+    };
+
+    const stepBy = (direction: 1 | -1) => {
+      setDraft(null);
+      commit(value + step * direction);
+    };
+
+    const buttonClass = cn(
+      "number-stepper-button flex shrink-0 cursor-pointer items-center justify-center text-(--number-stepper-button-fg) transition-colors enabled:active:bg-(--number-stepper-button-bg-pressed) enabled:hover:bg-(--number-stepper-button-bg-hovered) disabled:cursor-not-allowed disabled:text-(--number-stepper-button-fg-disabled)",
+      buttonGeometry[size ?? "md"]
+    );
+
+    return (
+      // biome-ignore lint/a11y/useSemanticElements: a <fieldset> brings a border, min-width and legend semantics this inline control does not want; role="group" only ties the buttons to the field
+      <div role="group" data-disabled={disabled} className={numberStepperVariants({ size, className })}>
+        <button type="button" tabIndex={-1} aria-label={decrementLabel} disabled={!interactive || atMin} onClick={() => stepBy(-1)} className={buttonClass}>
+          <Minus aria-hidden="true" />
+        </button>
+        <input
+          ref={ref}
+          type="text"
+          inputMode="numeric"
+          role="spinbutton"
+          autoComplete="off"
+          aria-valuenow={value}
+          aria-valuemin={min}
+          aria-valuemax={max}
+          disabled={disabled}
+          readOnly={readOnly}
+          value={draft ?? String(value)}
+          onChange={(event) => setDraft(event.target.value)}
+          onKeyDown={handleKeyDown}
+          onBlur={handleBlur}
+          onFocus={onFocus}
+          className={cn(
+            "border-(color:--number-stepper-divider-border) min-w-0 border-x bg-transparent text-center text-[length:inherit] tabular-nums outline-hidden disabled:cursor-not-allowed",
+            inputGeometry[size ?? "md"],
+            inputClassName
+          )}
+          {...props}
+        />
+        <button type="button" tabIndex={-1} aria-label={incrementLabel} disabled={!interactive || atMax} onClick={() => stepBy(1)} className={buttonClass}>
+          <Plus aria-hidden="true" />
+        </button>
+      </div>
+    );
+  }
+);
+NumberStepper.displayName = "NumberStepper";
+
+export { numberStepperVariants };

package/src/components/NumberStepper/index.ts

@@ -0,0 +1 @@
+export { NumberStepper, type NumberStepperProps, type NumberStepperSize, numberStepperVariants } from "./NumberStepper";

package/src/components/NumberStepper/number-stepper.recipe.css

@@ -0,0 +1,31 @@
+/**
+ * NumberStepper recipe — the component-token layer for NumberStepper.
+ *
+ * No variant/intent axis: a stepper is a form field, and like Input every
+ * colour is a fixed semantic token. The field surface deliberately mirrors
+ * input.css's values (bg-normal, border-normal, focus-ring) so a stepper next
+ * to a text input reads as the same kind of control — but through its own
+ * tokens, so a consumer can re-point one without the other.
+ *
+ * The grammar is `--number-stepper-[{part}-]{context}[-{state}]`. Parts are
+ * `button` (the two step buttons) and `divider` (the rules either side of the
+ * value). `--number-stepper-button-fg-disabled` is the colour a button takes
+ * at a bound; the whole group dims via opacity only when the field itself is
+ * disabled, the same way Input does.
+ *
+ * `@layer components` is load-bearing, not tidiness — see button.css.
+ */
+
+@layer components {
+  .number-stepper {
+    --number-stepper-bg: var(--bg-normal);
+    --number-stepper-fg: var(--fg-normal);
+    --number-stepper-border: var(--border-normal);
+    --number-stepper-ring: var(--focus-ring);
+    --number-stepper-divider-border: var(--border-normal);
+    --number-stepper-button-fg: var(--fg-normal);
+    --number-stepper-button-fg-disabled: var(--fg-normal-disabled);
+    --number-stepper-button-bg-hovered: var(--bg-normal-hovered);
+    --number-stepper-button-bg-pressed: var(--bg-normal-pressed);
+  }
+}

package/src/components/Popover/Popover.tsx

@@ -4,6 +4,7 @@ import { autoUpdate, flip, offset, type Placement, shift, useClick, useDismiss,
 import { useControllableState } from "@sixthshift/design-system/hooks";
 import type * as React from "react";
 import { useId } from "react";
+import { closestBrand } from "../../internal/brandScope";
 import { useEscapeLayer } from "../../internal/escapeLayers";
 import { PopoverBody } from "./components/PopoverBody";
 import { PopoverClose } from "./components/PopoverClose";
@@ -66,6 +67,8 @@ const PopoverRoot = ({ open: controlledOpen, onOpenChange, defaultOpen = false,
       setFloating: refs.setFloating,
     },
     floatingStyles,
+    // Read at render: `domReference` is state, so this updates once the trigger mounts.
+    inheritedBrand: closestBrand(context.elements.domReference),
     getReferenceProps,
     getFloatingProps,
     contentId,

package/src/components/Popover/components/PopoverBody.tsx

@@ -5,10 +5,17 @@ import { cn } from "@sixthshift/design-system/utils";
 import * as React from "react";
 import { usePopoverContext } from "./PopoverContext";
 
-export type PopoverBodyProps = React.HTMLAttributes<HTMLDivElement>;
+export type PopoverBodyProps = React.HTMLAttributes<HTMLDivElement> & {
+  /**
+   * Name of a brand the theme defines, rendered as `data-brand`. Omitted, the
+   * body copies the brand scope of its trigger, which the portal would
+   * otherwise leave behind.
+   */
+  brand?: string | undefined;
+};
 
-export const PopoverBody = React.forwardRef<HTMLDivElement, PopoverBodyProps>(({ className, children, ...props }, forwardedRef) => {
-  const { open, refs, floatingStyles, getFloatingProps, contentId, triggerId } = usePopoverContext();
+export const PopoverBody = React.forwardRef<HTMLDivElement, PopoverBodyProps>(({ className, brand, children, ...props }, forwardedRef) => {
+  const { open, refs, floatingStyles, inheritedBrand, getFloatingProps, contentId, triggerId } = usePopoverContext();
 
   // `aria-labelledby` outranks `aria-label` in the name computation, so the
   // trigger only names the dialog when the caller hasn't named it themselves.
@@ -28,6 +35,7 @@ export const PopoverBody = React.forwardRef<HTMLDivElement, PopoverBodyProps>(({
         role="dialog"
         aria-labelledby={hasOwnLabel ? undefined : triggerId}
         style={floatingStyles}
+        data-brand={brand ?? inheritedBrand}
         className={cn("z-popover rounded-lg border border-border-normal bg-bg-normal p-4 shadow-lg", className)}
         {...getFloatingProps(props)}
       >

package/src/components/Popover/components/PopoverContext.tsx

@@ -10,6 +10,8 @@ export type PopoverContextValue = {
     setFloating: (node: HTMLElement | null) => void;
   };
   floatingStyles: React.CSSProperties;
+  /** The trigger's brand scope, re-stamped on the portalled body. */
+  inheritedBrand: string | undefined;
   getReferenceProps: (props?: React.HTMLProps<HTMLElement>) => Record<string, unknown>;
   getFloatingProps: (props?: React.HTMLProps<HTMLElement>) => Record<string, unknown>;
   contentId: string;

package/src/components/Select/Select.tsx

@@ -3,6 +3,7 @@
 import { autoUpdate, flip, offset, shift, size, useFloating } from "@floating-ui/react";
 import { useControllableState } from "@sixthshift/design-system/hooks";
 import { forwardRef, type HTMLAttributes, type ReactElement, type Ref, useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+import { closestBrand } from "../../internal/brandScope";
 import { useEscapeLayer } from "../../internal/escapeLayers";
 import { SelectDropdown, selectOptionId } from "./SelectDropdown";
 import { SelectTriggerButton, SelectTriggerSearch } from "./SelectTrigger";
@@ -117,7 +118,7 @@ const SelectRoot = forwardRef(function SelectRoot<T extends string = string>(pro
   const showClearButton = clearable && hasValue && !disabled;
 
   // Floating UI
-  const { refs, floatingStyles } = useFloating({
+  const { refs, elements, floatingStyles } = useFloating({
     open,
     onOpenChange: setOpen,
     placement: "bottom-start",
@@ -342,6 +343,7 @@ const SelectRoot = forwardRef(function SelectRoot<T extends string = string>(pro
           label={listboxLabel}
           activeOptionId={activeOptionId}
           floatingStyles={floatingStyles}
+          brand={closestBrand(elements.domReference)}
           displayOptions={filteredOptions}
           highlightedIndex={highlightedIndex}
           selectedValues={selectedValues}

package/src/components/Select/SelectDropdown.tsx

@@ -23,6 +23,8 @@ interface SelectDropdownProps<T extends string> {
   /** The highlighted option's id, or undefined when nothing is highlighted. */
   activeOptionId: string | undefined;
   floatingStyles: React.CSSProperties;
+  /** The trigger's brand scope, re-stamped here because the portal leaves it behind. */
+  brand: string | undefined;
   displayOptions: readonly { value: T; label: string }[];
   highlightedIndex: number;
   selectedValues: Set<T>;
@@ -41,6 +43,7 @@ export const SelectDropdown = <T extends string>({
   label,
   activeOptionId,
   floatingStyles,
+  brand,
   displayOptions,
   highlightedIndex,
   selectedValues,
@@ -68,6 +71,7 @@ export const SelectDropdown = <T extends string>({
       tabIndex={-1}
       onKeyDown={onKeyDown}
       style={floatingStyles}
+      data-brand={brand}
       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 ? (

package/src/components/Sheet/Sheet.tsx

@@ -4,6 +4,7 @@ import { FloatingFocusManager, FloatingPortal, useDismiss, useFloating, useInter
 import { useMergedFloatingRef, usePresence } from "@sixthshift/design-system/hooks";
 import { cn } from "@sixthshift/design-system/utils";
 import { forwardRef, type HTMLAttributes, type ReactNode, useCallback, useEffect, useId, useMemo, useState } from "react";
+import { useOpenerBrand } from "../../internal/brandScope";
 import { hasOpenEscapeDialog, hasOpenEscapeLayer } from "../../internal/escapeLayers";
 import { SheetBody, SheetContext, SheetFooter, SheetHeader } from "./components";
 
@@ -26,6 +27,12 @@ export type SheetProps = Pick<HTMLAttributes<HTMLDivElement>, "className" | "sty
   dismissOnOutsidePress?: boolean;
   /** When true, shows a close (X) button in the header */
   closable?: boolean;
+  /**
+   * Name of a brand the theme defines, rendered as `data-brand` on the sheet.
+   * Omitted, the sheet takes the brand scope of the control that opened it
+   * (whatever held focus), since the portal leaves the trigger's scope behind.
+   */
+  brand?: string | undefined;
   /** Children — use Sheet.Header, Sheet.Body, Sheet.Footer */
   children: ReactNode;
 };
@@ -54,6 +61,7 @@ const SheetRoot = forwardRef<HTMLDivElement, SheetProps>(
       dismissable = true,
       dismissOnOutsidePress = false,
       closable,
+      brand,
       className,
       style,
       children,
@@ -64,6 +72,7 @@ const SheetRoot = forwardRef<HTMLDivElement, SheetProps>(
     ref
   ) => {
     const { ref: presenceRef, state, isMounted, show, hide } = usePresence();
+    const openerBrand = useOpenerBrand(open);
 
     // Drive presence from the controlled `open` prop.
     // When `open` flips to false, we play the exit animation, then unmount.
@@ -141,6 +150,7 @@ const SheetRoot = forwardRef<HTMLDivElement, SheetProps>(
             tabIndex={-1}
             data-state={state}
             data-side={side}
+            data-brand={brand ?? openerBrand}
             className={cn(
               "sheet fixed top-0 bottom-0 z-sheet flex flex-col overflow-hidden bg-(--sheet-bg) outline-hidden",
               "border-(color:--sheet-border) shadow-lg",

package/src/components/Steps/Steps.tsx

@@ -0,0 +1,149 @@
+"use client";
+
+import { cn } from "@sixthshift/design-system/utils";
+import { cva } from "class-variance-authority";
+import { Check } from "lucide-react";
+import * as React from "react";
+
+/**
+ * Geometry only. Every colour reads a `--steps-*` component token whose value
+ * is decided by src/components/Steps/steps.recipe.css, selected by the
+ * `data-state` each item renders (`complete`, `current`, `upcoming`).
+ */
+const stepsVariants = cva("steps flex", {
+  variants: {
+    orientation: {
+      horizontal: "w-full flex-row items-start",
+      vertical: "flex-col",
+    },
+  },
+  defaultVariants: {
+    orientation: "horizontal",
+  },
+});
+
+export type StepsOrientation = "horizontal" | "vertical";
+
+/** Where a step sits relative to `current`. Rendered as `data-state`. */
+export type StepState = "complete" | "current" | "upcoming";
+
+export type StepItem = {
+  /** Visible step name. */
+  label: React.ReactNode;
+  /** Secondary line under the label. */
+  description?: React.ReactNode;
+};
+
+export type StepsProps = Omit<React.OlHTMLAttributes<HTMLOListElement>, "children"> & {
+  /** The steps, in order. */
+  steps: readonly StepItem[];
+  /** Zero-based index of the step in progress. `steps.length` marks every step complete. */
+  current: number;
+  /**
+   * Makes completed steps clickable, for going back in a wizard. Upcoming
+   * steps never are — skipping ahead is the flow's decision, not the
+   * indicator's.
+   */
+  onStepClick?: (index: number) => void;
+  /** Layout direction. `horizontal` collapses labels to the current step's on narrow screens. */
+  orientation?: StepsOrientation;
+};
+
+function stateOf(index: number, current: number): StepState {
+  if (index < current) return "complete";
+  if (index === current) return "current";
+  return "upcoming";
+}
+
+/**
+ * Progress through a fixed sequence — checkout, onboarding, a multi-page
+ * form. Display-only: the step in progress is the `current` prop, owned by
+ * whatever runs the flow, so there is no internal state to control.
+ *
+ * Renders an `<ol>` (pass `aria-label`, e.g. "Checkout progress"); the
+ * current item carries `aria-current="step"`, and each indicator has a
+ * visually hidden status ("completed", "current") so the sequence reads
+ * correctly without the colours.
+ *
+ * With `onStepClick`, completed steps become buttons. Current and upcoming
+ * steps stay plain text: a step indicator that let you jump forward would be
+ * making the flow's validation decisions for it.
+ *
+ * Horizontally, every label shows from `sm` up; below that only the current
+ * step's label does, so four steps still fit a phone.
+ */
+export const Steps = React.forwardRef<HTMLOListElement, StepsProps>(({ className, steps, current, onStepClick, orientation = "horizontal", ...props }, ref) => {
+  const isHorizontal = orientation === "horizontal";
+
+  return (
+    <ol ref={ref} data-orientation={orientation} className={stepsVariants({ orientation, className })} {...props}>
+      {steps.map((step, index) => {
+        const state = stateOf(index, current);
+        const isLast = index === steps.length - 1;
+        const clickable = state === "complete" && onStepClick !== undefined;
+
+        const indicator = (
+          <span className="steps-indicator border-(color:--steps-indicator-border) relative z-10 flex size-8 shrink-0 items-center justify-center rounded-full border-2 bg-(--steps-indicator-bg) font-semibold text-(--steps-indicator-fg) text-sm transition-colors">
+            {state === "complete" ? <Check aria-hidden="true" className="size-4" strokeWidth={3} /> : index + 1}
+          </span>
+        );
+
+        const text = (
+          <span
+            className={cn("flex min-w-0 flex-col", isHorizontal ? "items-center text-center" : "pt-1", isHorizontal && state !== "current" && "max-sm:sr-only")}
+          >
+            <span className="font-medium text-(--steps-label-fg) text-sm">{step.label}</span>
+            {step.description !== undefined && <span className="text-(--steps-description-fg) text-xs">{step.description}</span>}
+            {state !== "upcoming" && <span className="sr-only">{state === "complete" ? "(completed)" : "(current)"}</span>}
+          </span>
+        );
+
+        const body = (
+          <>
+            {indicator}
+            {text}
+          </>
+        );
+
+        const bodyClass = cn("flex gap-2", isHorizontal ? "flex-col items-center" : "flex-row items-start gap-3");
+
+        return (
+          <li
+            // biome-ignore lint/suspicious/noArrayIndexKey: a step is its position — the sequence is fixed and never reorders
+            key={index}
+            data-state={state}
+            aria-current={state === "current" ? "step" : undefined}
+            className={cn("steps-item relative", isHorizontal ? "flex flex-1 justify-center" : "flex pb-6 last:pb-0")}
+          >
+            {!isLast && (
+              <span
+                aria-hidden="true"
+                className={cn(
+                  "steps-connector absolute bg-(--steps-connector-bg)",
+                  isHorizontal ? "top-4 left-1/2 h-0.5 w-full -translate-y-1/2" : "top-8 bottom-0 left-4 w-0.5 -translate-x-1/2"
+                )}
+              />
+            )}
+            {clickable ? (
+              <button
+                type="button"
+                onClick={() => onStepClick(index)}
+                className={cn(
+                  bodyClass,
+                  "focus-visible:ring-(color:--steps-ring) cursor-pointer rounded-md focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-offset-2 [&:hover_.steps-indicator]:bg-(--steps-indicator-bg-hovered)"
+                )}
+              >
+                {body}
+              </button>
+            ) : (
+              <span className={bodyClass}>{body}</span>
+            )}
+          </li>
+        );
+      })}
+    </ol>
+  );
+});
+Steps.displayName = "Steps";
+
+export { stepsVariants };