@sixthshift/design-system 0.3.0 → 0.5.0

package/src/components/Message/Message.tsx

@@ -6,27 +6,48 @@ import { MessageDescription } from "./components/MessageDescription";
 import { MessageIcon } from "./components/MessageIcon";
 import { MessageTitle } from "./components/MessageTitle";
 
-export const messageVariants = cva("flex gap-3 rounded-lg border p-4 text-sm [&>svg]:shrink-0", {
-  variants: {
-    intent: {
-      neutral: "border-border-normal bg-bg-normal text-fg-normal",
-      success: "border-border-success bg-bg-success-subtle text-fg-on-success-subtle",
-      warning: "border-border-warning bg-bg-warning-subtle text-fg-on-warning-subtle",
-      danger: "border-border-danger bg-bg-danger-subtle text-fg-on-danger-subtle",
+/**
+ * Geometry only, plus the three `--message-*` component tokens.
+ *
+ * Every colour reads a `--message-*` component token whose value is decided by
+ * src/theme/recipes/message.css. That file is the mapping from `intent` to a
+ * semantic token — the layer that used to be the `intent` entry in `variants`
+ * here, compiled into class-name literals and unreachable from outside.
+ * `size` stays here: it is pure geometry (padding, gap, font-size), not
+ * colour, so it has no reason to move.
+ */
+export const messageVariants = cva(
+  // One literal, deliberately: `useSortedClasses --unsafe` strips the trailing
+  // space before a `+`, silently welding the last class of one fragment to the
+  // first of the next. A single string means the sorter has nothing to break.
+  "message border-(color:--message-border) flex gap-3 rounded-lg border bg-(--message-bg) p-4 text-(--message-fg) text-sm [&>svg]:shrink-0",
+  {
+    variants: {
+      size: {
+        md: "p-4",
+        sm: "gap-2 p-3 text-xs",
+      },
     },
-    size: {
-      default: "p-4",
-      sm: "gap-2 p-3 text-xs",
+    defaultVariants: {
+      size: "md",
     },
-  },
-  defaultVariants: {
-    intent: "neutral",
-    size: "default",
-  },
-});
+  }
+);
+
+/**
+ * Widened deliberately, same reasoning as `ButtonIntent` in Button.tsx: adding
+ * an intent is a CSS change in the consuming app (a new `.message[data-intent=…]`
+ * cell in message.css), not a release here, so the type has to admit values
+ * this file has never heard of while still autocompleting the ones it ships.
+ */
+type Loose<T extends string> = T | (string & {});
+
+export type MessageIntentName = "neutral" | "success" | "warning" | "danger";
+export type MessageIntent = Loose<MessageIntentName>;
 
 export type MessageProps = React.HTMLAttributes<HTMLDivElement> &
   VariantProps<typeof messageVariants> & {
+    intent?: MessageIntent | undefined;
     /** Simple API: Optional title displayed above children */
     title?: React.ReactNode;
     /** Simple API: Optional icon displayed on the left */
@@ -41,14 +62,43 @@ export type MessageProps = React.HTMLAttributes<HTMLDivElement> &
  * success confirmation or a static "Note" callout stamped as `alert` trains
  * users to ignore the role that actually matters. Consumers can override by
  * passing their own `role` — `props` is spread after this.
+ *
+ * `intent` is widened to admit values this file has never heard of (see
+ * `MessageIntent` above), so this is deliberately not a lookup keyed by the
+ * closed union: an unrecognised intent has no entry and must fall through to
+ * `"status"` rather than resolving to `undefined`, which would render with no
+ * live-region role at all.
  */
-const intentRole = {
-  neutral: "status",
-  success: "status",
-  warning: "status",
-  danger: "alert",
-} as const;
+const ALERT_INTENTS: ReadonlySet<string> = new Set<MessageIntentName>(["danger"]);
+function intentRole(intent: MessageIntent): "status" | "alert" {
+  return ALERT_INTENTS.has(intent) ? "alert" : "status";
+}
 
+/**
+ * An inline feedback banner — info, success, warning, or error — that
+ * renders wherever the caller places it and stays until the caller removes
+ * it. Reach for `Message` over `Toast` when the feedback belongs in the
+ * page's own layout (form validation, an in-card load error); reach for
+ * `Toast` when it should float above the page and disappear on its own.
+ * `Toast` itself renders a `Message` internally.
+ *
+ * `intent` (`"neutral"` (default) | `"success"` | `"warning"` | `"danger"`,
+ * widened to accept any string) drives both the color, via `--message-*`
+ * component tokens, and the ARIA live-region role: `"danger"` is the only
+ * intent that gets `role="alert"` (assertive — cuts off whatever a screen
+ * reader was announcing); every other intent, including one this library has
+ * never heard of, gets `role="status"` (polite — announced at the next
+ * natural pause). An unrecognised intent still falls through to
+ * `role="status"` rather than resolving to no role at all. `role` can be
+ * overridden directly if a specific case needs it. `size` (`"md"` | `"sm"`)
+ * is geometry only (padding/gap/font-size) and carries no color.
+ *
+ * Two ways to give it content: the simple API (`title` + `icon` props, with
+ * `children` as the description), or compound children (`Message.Icon`,
+ * `Message.Body`, `Message.Title`, `Message.Description`) for layouts the
+ * 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) =>
@@ -57,7 +107,7 @@ export const Message = React.forwardRef<HTMLDivElement, MessageProps>(({ classNa
   );
 
   return (
-    <div ref={ref} role={intentRole[intent ?? "neutral"]} className={cn(messageVariants({ intent, size, className }))} {...props}>
+    <div ref={ref} role={intentRole(intent)} data-intent={intent} className={cn(messageVariants({ size, className }))} {...props}>
       {hasCompoundChildren ? (
         children
       ) : (

package/src/components/Message/index.ts

@@ -6,5 +6,5 @@ export type { MessageIconProps } from "./components/MessageIcon";
 export { MessageIcon } from "./components/MessageIcon";
 export type { MessageTitleProps } from "./components/MessageTitle";
 export { MessageTitle } from "./components/MessageTitle";
-export type { MessageProps } from "./Message";
+export type { MessageIntent, MessageIntentName, MessageProps } from "./Message";
 export { Message, messageVariants } from "./Message";

package/src/components/Modal/Modal.tsx

@@ -126,7 +126,10 @@ const ModalRoot = forwardRef<HTMLDivElement, ModalProps>(
 
     return (
       <FloatingFocusManager context={context} modal>
-        <FloatingOverlay lockScroll className={cn("fixed inset-0 z-modal bg-bg-overlay", isEntering && "animate-fade-in", isExiting && "animate-fade-out")}>
+        <FloatingOverlay
+          lockScroll
+          className={cn("modal-overlay fixed inset-0 z-modal bg-(--modal-overlay-bg)", isEntering && "animate-fade-in", isExiting && "animate-fade-out")}
+        >
           <div
             ref={mergedRef}
             role="dialog"
@@ -137,8 +140,8 @@ const ModalRoot = forwardRef<HTMLDivElement, ModalProps>(
             tabIndex={-1}
             data-state={state}
             className={cn(
-              "fixed flex flex-col overflow-hidden outline-hidden",
-              "rounded-xl border border-border-normal bg-bg-normal",
+              "modal fixed flex flex-col overflow-hidden outline-hidden",
+              "border-(color:--modal-border) rounded-xl border bg-(--modal-bg)",
               // Size
               sizeClasses[size],
               // Cap height so ModalBody scrolls instead of overflowing the viewport
@@ -171,6 +174,42 @@ ModalRoot.displayName = "Modal";
 // Compound Component Export
 // =============================================================================
 
+/**
+ * A centered, backdrop-dimmed dialog that fully interrupts the page — the
+ * background stays visually present but the user can't reach it. Reach for
+ * `Modal` when the interruption should own the user's attention completely
+ * (a confirmation, a focused form); reach for `Sheet` when the page behind
+ * should stay visible and interactive, or `Popover` when there's no need for
+ * a backdrop at all.
+ *
+ * `size` (`"sm" | "md" | "lg" | "full"`, default `"md"`) sets the desktop
+ * width — every size slides up full-width from the bottom on mobile.
+ * `align` positions the desktop dialog `"center"` (default) or `"top"`.
+ * `dismissable` (default `true`) governs outside-press only: clicking the
+ * backdrop closes the modal unless set to `false`. `closable` shows an X
+ * button in `Modal.Header`.
+ *
+ * Modal is mount-driven — a parent (or `useModal`'s stack) decides whether it
+ * renders at all, so there's no `open` prop. `onOpenChange` still exists,
+ * firing only with `false` on dismissal, so every overlay in this library
+ * shares one open/close shape. Escape is *not* wired inside Modal itself:
+ * `OverlayProvider` owns it globally so a stack of modals closes
+ * topmost-first. That means Escape only closes a Modal opened through
+ * `useModal()` — one a parent mounts directly from its own boolean state
+ * won't respond to Escape unless the app wires that separately.
+ *
+ * Focus moves into the modal on mount and is trapped there
+ * (`FloatingFocusManager modal`) until it unmounts, then returns to whatever
+ * triggered it. The dialog carries `role="dialog"` and `aria-modal="true"`,
+ * and names itself from `Modal.Header` via `aria-labelledby` unless the
+ * caller passes their own `aria-label`. It stays mounted through its
+ * fade-out exit animation (`usePresence`), so `onOpenChange(false)` fires
+ * only after the animation completes.
+ *
+ * Compound: `Modal.Header` (title + optional close button), `Modal.Body`
+ * (scrolls internally so the modal itself never grows past the viewport),
+ * `Modal.Footer` (action buttons). None are required.
+ */
 export const Modal = Object.assign(ModalRoot, {
   Header: ModalHeader,
   Body: ModalBody,

package/src/components/Modal/components/ModalHeader.tsx

@@ -30,7 +30,7 @@ export const ModalHeader = React.forwardRef<HTMLDivElement, ModalHeaderProps>(({
           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="modal-close absolute top-4 right-4 cursor-pointer rounded-md p-1 text-(--modal-close-fg) transition-colors hover:bg-(--modal-close-bg-hovered) hover:text-(--modal-close-fg-hovered)"
         >
           <X size={16} />
         </button>

package/src/components/Popover/Popover.tsx

@@ -68,6 +68,35 @@ const PopoverRoot = ({ open: controlledOpen, onOpenChange, defaultOpen = false,
   return <PopoverContext.Provider value={contextValue}>{children}</PopoverContext.Provider>;
 };
 
+/**
+ * A click-triggered floating panel anchored to a trigger element, with no
+ * backdrop. Reach for `Popover` over `Modal`/`Sheet` when the content is a
+ * menu, a small edit form, or info-on-demand that should stay tethered to
+ * whatever the user clicked, rather than taking over the page. Reach for
+ * `HoverCard` instead when the panel should open passively on hover/focus
+ * rather than a click, and for `Tooltip` when it's a short text label rather
+ * than a panel with real content.
+ *
+ * Works both controlled (`open` + `onOpenChange`) and uncontrolled
+ * (`defaultOpen`) via `useControllableState`. `placement` (default
+ * `"bottom"`) and `offsetPx` (default `8`) position it relative to the
+ * trigger through floating-ui's `offset → flip → shift` middleware, which
+ * repositions automatically on scroll/resize (`autoUpdate`).
+ *
+ * Opens via `useClick` and dismisses via `useDismiss` — outside-press and
+ * Escape both close it, handled directly by floating-ui rather than
+ * `OverlayProvider`, since a Popover isn't part of the modal stack.
+ * `Popover.Body` renders in a `FloatingPortal` to `document.body` and hard
+ * unmounts (`return null`) when closed — there's no exit animation. It
+ * carries `role="dialog"` and, since there's no title slot to read from,
+ * names itself from `Popover.Trigger` via `aria-labelledby` unless the
+ * caller passes their own `aria-label`/`aria-labelledby`.
+ *
+ * Compound: `Popover.Trigger` (`asChild` to render the child element as the
+ * trigger instead of wrapping it in a `<button>`), `Popover.Body`,
+ * `Popover.Close` (a button that calls `onOpenChange(false)` — for a close
+ * affordance inside the panel's own content).
+ */
 export const Popover = Object.assign(PopoverRoot, {
   Trigger: PopoverTrigger,
   Body: PopoverBody,

package/src/components/ProgressBar/ProgressBar.tsx

@@ -11,6 +11,20 @@ export type ProgressBarProps = {
   className?: string;
 };
 
+/**
+ * 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

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

@@ -337,10 +337,9 @@ const SelectRoot = forwardRef(function SelectRoot<T extends string = string>(pro
 SelectRoot.displayName = "Select";
 
 /**
- * The trigger is the ref target: `register` from a form library and
- * scroll-into-view both want it, and it is a `<div>` in both the button and the
- * searchable variants. It does swap nodes when the searchable trigger replaces
- * the button one, so a callback ref sees null and then the new element — normal
- * for conditional rendering, but worth knowing if you cache the node.
+ * 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

@@ -66,13 +66,16 @@ export const SelectDropdown = <T extends string>({
       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}
@@ -84,6 +87,10 @@ export const SelectDropdown = <T extends string>({
               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
@@ -93,18 +100,15 @@ export const SelectDropdown = <T extends string>({
               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

@@ -41,7 +41,7 @@ export const SelectTriggerButton = ({
   const showClear = showClearButton && !collapsed;
 
   return (
-    <div ref={rootRef} className="relative w-full">
+    <div ref={rootRef} className="select-trigger relative w-full">
       <button
         ref={setReference}
         type="button"
@@ -49,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
@@ -67,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>
           </>
         )}
@@ -77,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" />
@@ -128,7 +128,7 @@ export const SelectTriggerSearch = ({
       if (typeof rootRef === "function") rootRef(node);
       else if (rootRef) (rootRef as WritableRefObject<HTMLDivElement | null>).current = node;
     }}
-    className={cn("relative flex w-full items-center", className)}
+    className={cn("select-trigger relative flex w-full items-center", className)}
   >
     <input
       ref={inputRef as React.RefObject<HTMLInputElement>}
@@ -139,7 +139,7 @@ export const SelectTriggerSearch = ({
       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}
@@ -148,6 +148,6 @@ export const SelectTriggerSearch = ({
       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>
 );

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

@@ -128,8 +128,8 @@ const SheetRoot = forwardRef<HTMLDivElement, SheetProps>(
           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",
+            "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",
@@ -154,6 +154,12 @@ 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/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

@@ -24,7 +24,7 @@ export const SheetHeader = React.forwardRef<HTMLDivElement, SheetHeaderProps>(({
     <div
       ref={ref}
       id={id ?? context?.titleId}
-      className={cn("flex flex-col space-y-1.5 border-border-normal border-b p-6", closable && "pr-12", className)}
+      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}
@@ -33,7 +33,7 @@ export const SheetHeader = React.forwardRef<HTMLDivElement, SheetHeaderProps>(({
           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

@@ -51,6 +51,17 @@ function buildPath(points: { x: number; y: number }[], interpolation: Interpolat
   return parts.join(" ");
 }
 
+/**
+ * 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;