@sixthshift/design-system 0.2.1 → 0.4.0

package/src/components/Select/useSelectKeyboard.ts

@@ -1,4 +1,4 @@
-import { useEffect } from "react";
+import { useCallback } from "react";
 import type { SelectOption } from "./Select";
 
 interface UseSelectKeyboardOptions<T extends string> {
@@ -14,6 +14,20 @@ interface UseSelectKeyboardOptions<T extends string> {
   focusTrigger: () => void;
 }
 
+/**
+ * Returns the keydown handler for an open Select. It is attached to the element
+ * that actually holds focus — the listbox, or the search input in searchable
+ * mode — rather than to `document`.
+ *
+ * A document-level listener fired for every keystroke on the page while any
+ * Select was open, which meant a Select could swallow Escape or an arrow key
+ * from an overlay stacked above it, and two open Selects raced each other. It
+ * also decoupled key handling from focus, so nothing guaranteed the element the
+ * user was typing into was the one being navigated. Scoping the handler to the
+ * focused element makes both problems structurally impossible and is what lets
+ * `aria-activedescendant` mean something: the focused element owns the active
+ * option.
+ */
 export function useSelectKeyboard<T extends string>({
   open,
   searchable,
@@ -26,8 +40,8 @@ export function useSelectKeyboard<T extends string>({
   handleSelect,
   focusTrigger,
 }: UseSelectKeyboardOptions<T>) {
-  useEffect(() => {
-    const handleKeyDown = (event: KeyboardEvent) => {
+  return useCallback(
+    (event: React.KeyboardEvent<HTMLElement>) => {
       if (!open) return;
 
       const isTyping = searchable && event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey;
@@ -101,11 +115,7 @@ export function useSelectKeyboard<T extends string>({
             }
           }
       }
-    };
-
-    if (open) {
-      document.addEventListener("keydown", handleKeyDown);
-      return () => document.removeEventListener("keydown", handleKeyDown);
-    }
-  }, [open, searchable, searchValue, highlightedIndex, displayOptions, setOpen, setHighlightedIndex, setSearchValue, handleSelect, focusTrigger]);
+    },
+    [open, searchable, searchValue, highlightedIndex, displayOptions, setOpen, setHighlightedIndex, setSearchValue, handleSelect, focusTrigger]
+  );
 }

package/src/components/Separator/Separator.tsx

@@ -6,6 +6,16 @@ export type SeparatorProps = React.HTMLAttributes<HTMLDivElement> & {
   decorative?: boolean;
 };
 
+/**
+ * Thin dividing line, horizontal or vertical (`orientation`, default
+ * `"horizontal"`). Renders a `<div>`, not `<hr>`.
+ *
+ * `decorative` (default `true`) controls whether it is exposed to assistive
+ * tech: decorative renders `role="none"` and no `aria-orientation`, so it is
+ * invisible to a screen reader; set `decorative={false}` for a divider that
+ * is actually part of the content's structure (e.g. between menu sections),
+ * which renders `role="separator"` and `aria-orientation` instead.
+ */
 const Separator = React.forwardRef<HTMLDivElement, SeparatorProps>(({ className, orientation = "horizontal", decorative = true, ...props }, ref) => (
   <div
     ref={ref}

package/src/components/Sheet/Sheet.tsx

@@ -1,14 +1,14 @@
 import { FloatingFocusManager, useDismiss, useFloating, useInteractions, useRole } from "@floating-ui/react";
 import { useMergedFloatingRef, usePresence } from "@sixthshift/design-system/hooks";
 import { cn } from "@sixthshift/design-system/utils";
-import { type HTMLAttributes, type ReactNode, useCallback, useEffect, useMemo } from "react";
+import { forwardRef, type HTMLAttributes, type ReactNode, useCallback, useEffect, useId, useMemo, useState } from "react";
 import { SheetBody, SheetContext, SheetFooter, SheetHeader } from "./components";
 
 // =============================================================================
 // Types
 // =============================================================================
 
-export type SheetProps = Pick<HTMLAttributes<HTMLDivElement>, "className" | "style"> & {
+export type SheetProps = Pick<HTMLAttributes<HTMLDivElement>, "className" | "style" | "aria-label" | "aria-labelledby" | "aria-describedby"> & {
   /** Whether the sheet is open. Sheet owns its own mount lifecycle so exit animations can play. */
   open: boolean;
   /** Called when the sheet requests a state change (Esc, outside press, X button). */
@@ -41,94 +41,125 @@ const sizeClasses = {
 // Sheet
 // =============================================================================
 
-const SheetRoot = ({
-  open,
-  onOpenChange,
-  side = "right",
-  size = "md",
-  dismissable = true,
-  dismissOnOutsidePress = false,
-  closable,
-  className,
-  style,
-  children,
-}: SheetProps) => {
-  const { ref: presenceRef, state, isMounted, show, hide } = usePresence();
-
-  // Drive presence from the controlled `open` prop.
-  // When `open` flips to false, we play the exit animation, then unmount.
-  useEffect(() => {
-    if (open) {
-      show();
-    } else if (isMounted) {
-      hide();
-    }
-  }, [open, isMounted, show, hide]);
-
-  const requestClose = useCallback(() => {
-    onOpenChange(false);
-  }, [onOpenChange]);
-
-  const { refs, context } = useFloating({
-    open,
-    onOpenChange: (nextOpen) => {
-      if (!nextOpen) requestClose();
+const SheetRoot = forwardRef<HTMLDivElement, SheetProps>(
+  (
+    {
+      open,
+      onOpenChange,
+      side = "right",
+      size = "md",
+      dismissable = true,
+      dismissOnOutsidePress = false,
+      closable,
+      className,
+      style,
+      children,
+      "aria-label": ariaLabel,
+      "aria-labelledby": ariaLabelledBy,
+      "aria-describedby": ariaDescribedBy,
     },
-  });
-
-  const mergedRef = useMergedFloatingRef(refs, presenceRef);
-
-  const dismiss = useDismiss(context, {
-    enabled: dismissable,
-    escapeKey: true,
-    outsidePress: dismissOnOutsidePress,
-    outsidePressEvent: "mousedown",
-  });
-
-  const role = useRole(context, { role: "dialog" });
-
-  const { getFloatingProps } = useInteractions([dismiss, role]);
-
-  const sheetContextValue = useMemo(() => ({ onClose: requestClose, closable }), [requestClose, closable]);
-
-  if (!isMounted) return null;
-
-  const isEntering = state === "entering";
-  const isExiting = state === "exiting";
-
-  return (
-    <FloatingFocusManager context={context} modal={false}>
-      <div
-        ref={mergedRef}
-        tabIndex={-1}
-        data-state={state}
-        data-side={side}
-        className={cn(
-          "fixed top-0 bottom-0 z-sheet flex flex-col overflow-hidden bg-bg-normal outline-hidden",
-          "border-border-normal shadow-lg",
-          side === "right" ? "right-0 border-l" : "left-0 border-r",
-          sizeClasses[size],
-          "max-sm:inset-x-0",
-          isEntering && side === "right" && "animate-slide-right-in",
-          isExiting && side === "right" && "animate-slide-right-out",
-          isEntering && side === "left" && "animate-slide-left-in",
-          isExiting && side === "left" && "animate-slide-left-out",
-          className
-        )}
-        style={style}
-        {...getFloatingProps({})}
-      >
-        <SheetContext.Provider value={sheetContextValue}>{children}</SheetContext.Provider>
-      </div>
-    </FloatingFocusManager>
-  );
-};
+    ref
+  ) => {
+    const { ref: presenceRef, state, isMounted, show, hide } = usePresence();
+
+    // Drive presence from the controlled `open` prop.
+    // When `open` flips to false, we play the exit animation, then unmount.
+    useEffect(() => {
+      if (open) {
+        show();
+      } else if (isMounted) {
+        hide();
+      }
+    }, [open, isMounted, show, hide]);
+
+    const requestClose = useCallback(() => {
+      onOpenChange(false);
+    }, [onOpenChange]);
+
+    const { refs, context } = useFloating({
+      open,
+      onOpenChange: (nextOpen) => {
+        if (!nextOpen) requestClose();
+      },
+    });
+
+    const mergedRef = useMergedFloatingRef<HTMLDivElement>(refs, presenceRef, ref);
+
+    const dismiss = useDismiss(context, {
+      enabled: dismissable,
+      escapeKey: true,
+      outsidePress: dismissOnOutsidePress,
+      outsidePressEvent: "mousedown",
+    });
+
+    const role = useRole(context, { role: "dialog" });
+
+    const { getFloatingProps } = useInteractions([dismiss, role]);
+
+    // Named from its header, same contract as Modal — see SheetContext.
+    const titleId = useId();
+    const [hasTitle, setHasTitle] = useState(false);
+    const registerTitle = useCallback((present: boolean) => setHasTitle(present), []);
+
+    // `aria-labelledby` beats `aria-label` in the name computation, so a caller
+    // who passes a label must not also be pointed at the header — they would
+    // never see their own string win.
+    const labelledBy = ariaLabelledBy ?? (ariaLabel || !hasTitle ? undefined : titleId);
+
+    const sheetContextValue = useMemo(() => ({ onClose: requestClose, closable, titleId, registerTitle }), [requestClose, closable, titleId, registerTitle]);
+
+    if (!isMounted) return null;
+
+    const isEntering = state === "entering";
+    const isExiting = state === "exiting";
+
+    return (
+      <FloatingFocusManager context={context} modal={false}>
+        <div
+          ref={mergedRef}
+          // Explicit, though `getFloatingProps` also supplies it from `useRole`:
+          // the ARIA attributes below are only valid on a dialog, and static
+          // analysis cannot see a role that arrives through a spread. Matches Modal.
+          role="dialog"
+          aria-label={ariaLabel}
+          aria-labelledby={labelledBy}
+          aria-describedby={ariaDescribedBy}
+          tabIndex={-1}
+          data-state={state}
+          data-side={side}
+          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",
+            side === "right" ? "right-0 border-l" : "left-0 border-r",
+            sizeClasses[size],
+            "max-sm:inset-x-0",
+            isEntering && side === "right" && "animate-slide-right-in",
+            isExiting && side === "right" && "animate-slide-right-out",
+            isEntering && side === "left" && "animate-slide-left-in",
+            isExiting && side === "left" && "animate-slide-left-out",
+            className
+          )}
+          style={style}
+          {...getFloatingProps({})}
+        >
+          <SheetContext.Provider value={sheetContextValue}>{children}</SheetContext.Provider>
+        </div>
+      </FloatingFocusManager>
+    );
+  }
+);
 SheetRoot.displayName = "Sheet";
 
 // =============================================================================
 // Compound Component Export
 // =============================================================================
 
+/**
+ * NOTE: Storybook shows the copy in Sheet.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 Sheet = Object.assign(SheetRoot, {
   Header: SheetHeader,
   Body: SheetBody,

package/src/components/Sheet/components/SheetContext.tsx

@@ -5,6 +5,16 @@ export type OnClose = (event?: MouseEvent<Element> | KeyboardEvent<Element>) =>
 interface SheetContextValue {
   onClose: OnClose;
   closable?: boolean | undefined;
+  /**
+   * The id `Sheet.Header` stamps on itself so the dialog can name itself from
+   * its own title instead of being announced as a bare "dialog".
+   */
+  titleId?: string;
+  /**
+   * The header reports its presence — a headerless sheet must not point
+   * `aria-labelledby` at an element that never rendered.
+   */
+  registerTitle?: (present: boolean) => void;
 }
 
 export const SheetContext = createContext<SheetContextValue | null>(null);

package/src/components/Sheet/components/SheetFooter.tsx

@@ -4,6 +4,6 @@ import * as React from "react";
 export type SheetFooterProps = React.HTMLAttributes<HTMLDivElement>;
 
 export const SheetFooter = React.forwardRef<HTMLDivElement, SheetFooterProps>(({ className, ...props }, ref) => (
-  <div ref={ref} className={cn("flex items-center border-border-normal border-t p-4", className)} {...props} />
+  <div ref={ref} className={cn("sheet-footer border-(color:--sheet-footer-border) flex items-center border-t p-4", className)} {...props} />
 ));
 SheetFooter.displayName = "SheetFooter";

package/src/components/Sheet/components/SheetHeader.tsx

@@ -5,20 +5,35 @@ import { SheetContext } from "./SheetContext";
 
 export type SheetHeaderProps = React.HTMLAttributes<HTMLDivElement>;
 
-export const SheetHeader = React.forwardRef<HTMLDivElement, SheetHeaderProps>(({ className, children, ...props }, ref) => {
+export const SheetHeader = React.forwardRef<HTMLDivElement, SheetHeaderProps>(({ className, children, id, ...props }, ref) => {
   const context = React.useContext(SheetContext);
   const closable = context?.closable;
   const onClose = context?.onClose;
+  const registerTitle = context?.registerTitle;
+
+  // Report the title to the sheet so it can name itself, and withdraw it on
+  // unmount. A caller-supplied `id` wins over the generated one — which the
+  // sheet can no longer resolve, so it is told there is no title to point at.
+  const ownsTitleId = id === undefined;
+  React.useEffect(() => {
+    registerTitle?.(ownsTitleId);
+    return () => registerTitle?.(false);
+  }, [registerTitle, ownsTitleId]);
 
   return (
-    <div ref={ref} className={cn("flex flex-col space-y-1.5 border-border-normal border-b p-6", closable && "pr-12", className)} {...props}>
+    <div
+      ref={ref}
+      id={id ?? context?.titleId}
+      className={cn("sheet-header border-(color:--sheet-header-border) flex flex-col space-y-1.5 border-b p-6", closable && "pr-12", className)}
+      {...props}
+    >
       {children}
       {closable && (
         <button
           type="button"
           onClick={onClose}
           aria-label="Close"
-          className="absolute top-4 right-4 cursor-pointer rounded-md p-1 text-fg-subtle transition-colors hover:bg-bg-subtle hover:text-fg-normal"
+          className="sheet-close absolute top-4 right-4 cursor-pointer rounded-md p-1 text-(--sheet-close-fg) transition-colors hover:bg-(--sheet-close-bg-hovered) hover:text-(--sheet-close-fg-hovered)"
         >
           <X size={16} />
         </button>

package/src/components/Sparkline/Sparkline.tsx

@@ -1,6 +1,6 @@
 import type { Interpolation } from "@sixthshift/design-system/line-chart";
 import { cn } from "@sixthshift/design-system/utils";
-import type * as React from "react";
+import * as React from "react";
 
 export type SparklineProps = React.HTMLAttributes<HTMLSpanElement> & {
   data: number[];
@@ -51,43 +51,47 @@ function buildPath(points: { x: number; y: number }[], interpolation: Interpolat
   return parts.join(" ");
 }
 
-export const Sparkline = ({
-  data,
-  width = 80,
-  height = 24,
-  color = "var(--fg-brand)",
-  fillArea = false,
-  interpolation = "monotone",
-  strokeWidth = 1.5,
-  className,
-  ...rest
-}: SparklineProps) => {
-  if (data.length < 2) return null;
+/**
+ * A minimal inline trend line for embedding in a table cell or card — an
+ * `<svg>` inside an `inline-block` `<span>`, sized to `width`/`height` rather
+ * than a chart that lays out its own labels or axes.
+ *
+ * Requires at least 2 data points; with fewer it renders nothing (`null`).
+ * `color` is a single CSS color string (default `var(--fg-brand)`), and
+ * `interpolation` reuses the same `Interpolation` type as `LineChart`. The
+ * accessible name is a static `aria-label="Trend line"` — it does not
+ * describe the actual values.
+ */
+export const Sparkline = React.forwardRef<HTMLSpanElement, SparklineProps>(
+  ({ data, width = 80, height = 24, color = "var(--fg-brand)", fillArea = false, interpolation = "monotone", strokeWidth = 1.5, className, ...rest }, ref) => {
+    if (data.length < 2) return null;
 
-  const min = Math.min(...data);
-  const max = Math.max(...data);
-  const range = max - min || 1;
+    const min = Math.min(...data);
+    const max = Math.max(...data);
+    const range = max - min || 1;
 
-  const padY = 2;
-  const padX = 1;
-  const innerW = width - padX * 2;
-  const innerH = height - padY * 2;
+    const padY = 2;
+    const padX = 1;
+    const innerW = width - padX * 2;
+    const innerH = height - padY * 2;
 
-  const points = data.map((v, i) => ({
-    x: padX + (i / (data.length - 1)) * innerW,
-    y: padY + innerH - ((v - min) / range) * innerH,
-  }));
+    const points = data.map((v, i) => ({
+      x: padX + (i / (data.length - 1)) * innerW,
+      y: padY + innerH - ((v - min) / range) * innerH,
+    }));
 
-  const path = buildPath(points, interpolation);
+    const path = buildPath(points, interpolation);
 
-  return (
-    <span {...rest} className={cn("inline-block align-middle", className)}>
-      <svg width={width} height={height} viewBox={`0 0 ${width} ${height}`} role="img" aria-label="Trend line">
-        {fillArea && path && (
-          <path d={`${path} L ${points[points.length - 1]!.x} ${height - padY} L ${points[0]!.x} ${height - padY} Z`} fill={color} opacity={0.12} />
-        )}
-        <path d={path} fill="none" stroke={color} strokeWidth={strokeWidth} strokeLinecap="round" strokeLinejoin="round" />
-      </svg>
-    </span>
-  );
-};
+    return (
+      <span ref={ref} {...rest} className={cn("inline-block align-middle", className)}>
+        <svg width={width} height={height} viewBox={`0 0 ${width} ${height}`} role="img" aria-label="Trend line">
+          {fillArea && path && (
+            <path d={`${path} L ${points[points.length - 1]!.x} ${height - padY} L ${points[0]!.x} ${height - padY} Z`} fill={color} opacity={0.12} />
+          )}
+          <path d={path} fill="none" stroke={color} strokeWidth={strokeWidth} strokeLinecap="round" strokeLinejoin="round" />
+        </svg>
+      </span>
+    );
+  }
+);
+Sparkline.displayName = "Sparkline";

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/TabsList.tsx

@@ -1,6 +1,6 @@
 import { cn } from "@sixthshift/design-system/utils";
 import type * as React from "react";
-import { useCallback, useRef } from "react";
+import { forwardRef, useCallback, useRef } from "react";
 import { useTabsContext } from "./TabsContext";
 import { TabsTrigger } from "./TabsTrigger";
 
@@ -11,7 +11,7 @@ export type TabsListProps = {
   className?: string;
 };
 
-export const TabsList = ({ orientation = "horizontal", className }: TabsListProps) => {
+export const TabsList = forwardRef<HTMLDivElement, TabsListProps>(({ orientation = "horizontal", className }, ref) => {
   const { items, value, onValueChange } = useTabsContext();
   const triggerRefs = useRef<(HTMLButtonElement | null)[]>([]);
 
@@ -78,6 +78,7 @@ export const TabsList = ({ orientation = "horizontal", className }: TabsListProp
 
   return (
     <div
+      ref={ref}
       role="tablist"
       aria-orientation={orientation}
       className={cn("inline-flex gap-1", orientation === "vertical" ? "flex-col" : "flex-row items-center", className)}
@@ -95,4 +96,5 @@ export const TabsList = ({ orientation = "horizontal", className }: TabsListProp
       ))}
     </div>
   );
-};
+});
+TabsList.displayName = "TabsList";

package/src/components/Tabs/components/TabsPanels.tsx

@@ -1,4 +1,5 @@
 import { cn } from "@sixthshift/design-system/utils";
+import { forwardRef } from "react";
 import { useTabsContext } from "./TabsContext";
 
 export type TabsPanelsProps = {
@@ -6,7 +7,7 @@ export type TabsPanelsProps = {
   className?: string;
 };
 
-export const TabsPanels = ({ className }: TabsPanelsProps) => {
+export const TabsPanels = forwardRef<HTMLDivElement, TabsPanelsProps>(({ className }, ref) => {
   const { items, value, baseId } = useTabsContext();
 
   const activeItem = items.find((item) => item.value === value);
@@ -19,8 +20,9 @@ export const TabsPanels = ({ className }: TabsPanelsProps) => {
   const content = typeof activeItem.content === "function" ? activeItem.content() : activeItem.content;
 
   return (
-    <div id={panelId} role="tabpanel" aria-labelledby={triggerId} className={cn("focus-visible:outline-hidden", className)}>
+    <div ref={ref} id={panelId} role="tabpanel" aria-labelledby={triggerId} className={cn("focus-visible:outline-hidden", className)}>
       {content}
     </div>
   );
-};
+});
+TabsPanels.displayName = "TabsPanels";