@sixthshift/design-system 0.3.0 → 0.5.0

package/src/components/DateTimeRangePicker/DateTimeRangePicker.tsx

@@ -1,9 +1,9 @@
 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 { Calendar as CalendarIcon, X } from "lucide-react";
+import { Calendar as CalendarIcon } from "lucide-react";
 import * as React from "react";
-import { useCallback, useId, useMemo, useState } from "react";
+import { useCallback, useId, useMemo, useRef, useState } from "react";
 import {
   adaptDisabledDates,
   fromISODateOrUndefined,
@@ -17,9 +17,12 @@ import {
   toISOInstantRange,
 } from "../../date-time";
 
+import { PickerField } from "../../internal";
 import { Button } from "../Button";
 import { CalendarView } from "../Calendar/CalendarView";
+import { isDateDisabled } from "../Calendar/calendar.hooks";
 import type { DateRangeValue } from "../Calendar/calendar.types";
+import { DateTimeSegments } from "../DateTimePicker/DateTimeSegments";
 import { Separator } from "../Separator";
 import { PeriodSelector } from "../TimePicker/PeriodSelector";
 import { TimeColumn } from "../TimePicker/TimeColumn";
@@ -36,59 +39,6 @@ import {
 import type { ParsedTime, TimePeriod } from "../TimePicker/timepicker.types";
 import type { DateTimeRangePickerProps, DateTimeRangePresetOption, DateTimeRangeValue } from "./datetimerangepicker.types";
 
-/**
- * Format an Instant for display
- */
-function formatInstantDisplay(instant: Temporal.Instant, clockFormat: "12h" | "24h", showSeconds: boolean, timeZone?: string): string {
-  const tz = timeZone ?? Temporal.Now.timeZoneId();
-  const zoned = instant.toZonedDateTimeISO(tz);
-  const plainDateTime = zoned.toPlainDateTime();
-
-  // Format date part
-  const datePart = plainDateTime.toLocaleString("en-US", {
-    month: "long",
-    day: "numeric",
-    year: "numeric",
-  });
-
-  // Format time part based on props
-  const timeOptions: Intl.DateTimeFormatOptions = {
-    hour: "numeric",
-    minute: "2-digit",
-    hour12: clockFormat === "12h",
-  };
-
-  if (showSeconds) {
-    timeOptions.second = "2-digit";
-  }
-
-  const timePart = plainDateTime.toLocaleString("en-US", timeOptions);
-
-  return `${datePart}, ${timePart}`;
-}
-
-/**
- * Format an Instant range for display.
- *
- * Takes the internal Temporal range, not the public ISO shape — display runs
- * below the boundary.
- */
-function formatRangeDisplay(range: TemporalInstantRange | undefined, clockFormat: "12h" | "24h", showSeconds: boolean): string {
-  if (!range?.from && !range?.to) {
-    return "";
-  }
-
-  if (range.from && !range.to) {
-    return `${formatInstantDisplay(range.from, clockFormat, showSeconds)} – ...`;
-  }
-
-  if (!range.from && range.to) {
-    return `... – ${formatInstantDisplay(range.to, clockFormat, showSeconds)}`;
-  }
-
-  return `${formatInstantDisplay(range.from!, clockFormat, showSeconds)} – ${formatInstantDisplay(range.to!, clockFormat, showSeconds)}`;
-}
-
 /**
  * Default preset ranges for DateTimeRangePicker
  *
@@ -144,8 +94,34 @@ function getDefaultPresets(): DateTimeRangePresetOption[] {
 /**
  * DateTimeRangePicker - A component for selecting a datetime range
  *
- * Combines date range selection with separate time pickers for start and end times.
- * All values cross the boundary as canonical UTC instant strings.
+ * Combines a single range calendar with two sets of time columns — Start Time
+ * and End Time — shown side by side below it. Like `DateTimePicker`, it is
+ * not a composition of other picker components: it builds directly on the
+ * same internal calendar grid and time-column primitives `TimePicker` and
+ * `DateTimePicker` use.
+ *
+ * The trigger is two typeable fields, one per end — each a full date-and-time
+ * (`1520260900a` is January 5th 2026 at 9am), each with its own clear button,
+ * sharing one popover that anchors to whichever half is being edited. A typed
+ * end that falls outside `minDate`/`maxDate`/`minTime`/`maxTime` is flagged
+ * rather than clamped. See `SegmentedField` for the keyboard model.
+ *
+ * The value is an `ISOInstantRange` (`{ from?: ISOInstant, to?: ISOInstant }`,
+ * exported as `DateTimeRangeValue` for historical reasons) — both ends
+ * absolute instants, always UTC and ending in `Z`. Each end is edited in the
+ * viewer's local timezone and converted to/from UTC at the boundary. Supports
+ * controlled (`value`/`onChange`) and uncontrolled (`defaultValue`) use.
+ *
+ * Opening the popover seeds date-range and time drafts from the committed
+ * value; the footer's Apply combines them into an instant range and commits,
+ * Cancel discards the draft. `minDate`/`maxDate` and `disabledDates` bound the
+ * date grid. `minTime`/`maxTime` are wall-clock bounds that apply to **both**
+ * the start and end time columns identically — they do not mean "start no
+ * earlier than X, end no later than Y" relative to each other, and they say
+ * nothing about the resulting instants (a `maxTime` of `17:00` still allows an
+ * end date after the start date). `presets` (a zero-arg-function value, like
+ * `DateRangePicker`) replaces the built-in preset list; `showPresets={false}`
+ * hides the sidebar.
  */
 export const DateTimeRangePicker = React.forwardRef<HTMLDivElement, DateTimeRangePickerProps>((props, ref) => {
   const {
@@ -161,8 +137,8 @@ export const DateTimeRangePicker = React.forwardRef<HTMLDivElement, DateTimeRang
     maxTime,
     minuteStep = 1,
     clockFormat = "12h",
+    segmentOrder = "mdy",
     showSeconds = false,
-    placeholder = "Select datetime range...",
     weekStartsOn = 0,
     name,
     isDisabled = false,
@@ -174,6 +150,8 @@ export const DateTimeRangePicker = React.forwardRef<HTMLDivElement, DateTimeRang
 
   // Open state
   const [open, setOpen] = useState(false);
+  // The day grid takes focus only when the popover was opened from the keyboard.
+  const [autoFocusDay, setAutoFocusDay] = useState(false);
 
   // ---------------------------------------------------------------------------
   // The ISO boundary.
@@ -413,14 +391,6 @@ export const DateTimeRangePicker = React.forwardRef<HTMLDivElement, DateTimeRang
   }, [committedValue, clockFormat]);
 
   // Clear value
-  const handleClear = useCallback(
-    (e: React.MouseEvent) => {
-      e.stopPropagation();
-      e.preventDefault();
-      setCommittedValue(undefined);
-    },
-    [setCommittedValue]
-  );
 
   // Apply preset
   const _handlePresetClick = useCallback(
@@ -447,11 +417,149 @@ export const DateTimeRangePicker = React.forwardRef<HTMLDivElement, DateTimeRang
   // IDs for accessibility
   const id = useId();
   const contentId = `datetimerangepicker-content-${id}`;
-  const inputId = `datetimerangepicker-input-${id}`;
 
   // Display value (from committed value)
-  const displayValue = committedValue ? formatRangeDisplay(committedValue, clockFormat, showSeconds) : "";
-  const hasValue = Boolean(committedValue?.from || committedValue?.to);
+
+  // ---------------------------------------------------------------------------
+  // Two typeable fields, one per end.
+  //
+  // A range is two instants, and typing one should not require knowing where the
+  // other ends. Each half is its own segmented field with its own clear button;
+  // they share the one popover, which anchors to whichever half is being edited.
+  // While it is open the fields show the draft, so picking in the grid or the
+  // columns shows up in the segments and vice versa.
+  // ---------------------------------------------------------------------------
+
+  const draftRange = getDraftRange();
+  const shownFor = (end: "from" | "to") => (open ? draftRange[end] : committedValue?.[end]);
+
+  /**
+   * A typed end can fall outside what the grid and columns allow. The field
+   * flags it rather than clamping; see `DatePicker` for why.
+   */
+  const outOfBounds = (instant: Temporal.Instant | undefined) => {
+    if (!instant) return false;
+    const zoned = instant.toZonedDateTimeISO(userTimeZone);
+    return (
+      isDateDisabled(zoned.toPlainDate(), temporalDisabledDates, temporalMinDate, temporalMaxDate) ||
+      isTimeDisabled(zoned.toPlainTime(), temporalMinTime, temporalMaxTime)
+    );
+  };
+
+  const setRangeEnd = useCallback(
+    (end: "from" | "to", instant: Temporal.Instant | undefined) => {
+      if (!open) {
+        const next = { from: end === "from" ? instant : committedValue?.from, to: end === "to" ? instant : committedValue?.to };
+        setCommittedValue(next.from || next.to ? next : undefined);
+        return;
+      }
+
+      if (!instant) {
+        setDraftDateRange((current) => ({ from: end === "from" ? undefined : current?.from, to: end === "to" ? undefined : current?.to }));
+        return;
+      }
+
+      const zoned = instant.toZonedDateTimeISO(userTimeZone);
+      const parsed = temporalToParsed(zoned.toPlainTime());
+      setDraftDateRange((current) => ({
+        from: end === "from" ? zoned.toPlainDate() : current?.from,
+        to: end === "to" ? zoned.toPlainDate() : current?.to,
+      }));
+      if (end === "from") {
+        setDraftStartHour(clockFormat === "12h" ? to12Hour(parsed.hour).hour12 : parsed.hour);
+        setDraftStartMinute(parsed.minute);
+        setDraftStartSecond(parsed.second);
+        setDraftStartPeriod(to12Hour(parsed.hour).period);
+      } else {
+        setDraftEndHour(clockFormat === "12h" ? to12Hour(parsed.hour).hour12 : parsed.hour);
+        setDraftEndMinute(parsed.minute);
+        setDraftEndSecond(parsed.second);
+        setDraftEndPeriod(to12Hour(parsed.hour).period);
+      }
+    },
+    [clockFormat, committedValue, open, setCommittedValue, userTimeZone]
+  );
+
+  const clearRangeEnd = useCallback(
+    (end: "from" | "to") => (event: React.MouseEvent) => {
+      event.stopPropagation();
+      event.preventDefault();
+      const next = { from: end === "from" ? undefined : committedValue?.from, to: end === "to" ? undefined : committedValue?.to };
+      // Clearing the last remaining end clears the range itself.
+      setCommittedValue(next.from || next.to ? next : undefined);
+    },
+    [committedValue, setCommittedValue]
+  );
+
+  const rangeHalves = useRef<Record<"from" | "to", HTMLDivElement | null>>({ from: null, to: null });
+  const anchorToHalf = useCallback(
+    (end: "from" | "to") => {
+      const node = rangeHalves.current[end];
+      if (node) refs.setPositionReference(node);
+    },
+    [refs]
+  );
+
+  /** `Alt+ArrowDown` from a segment: open the popover *and* go to the grid. */
+  const openWithGridFocus = useCallback(
+    (end: "from" | "to") => () => {
+      anchorToHalf(end);
+      setAutoFocusDay(true);
+      handleOpenChange(true);
+    },
+    [anchorToHalf, handleOpenChange]
+  );
+
+  /** `Enter` in a segment commits the draft, matching the popover's Apply. */
+  const handleFieldSubmit = useCallback(() => {
+    if (open) handleApply();
+  }, [handleApply, open]);
+
+  /**
+   * One end of the range. A render function rather than a component so the
+   * fields are not remounted — and focus is not dropped — on every keystroke.
+   */
+  const renderRangeHalf = (end: "from" | "to", label: string) => {
+    const settled = committedValue?.[end];
+
+    return (
+      <PickerField
+        ref={(node) => {
+          rangeHalves.current[end] = node;
+        }}
+        onFocusCapture={() => anchorToHalf(end)}
+        className="min-w-70 flex-1"
+        icon={<CalendarIcon className="h-4 w-4" />}
+        toggleLabel={`Open picker for ${label.toLowerCase()}`}
+        // Both handlers have to run: Floating UI's opens the popover, and ours
+        // points it at this half. Spreading after `onClick` would drop ours on
+        // the floor, which is how the popover ended up anchored to the whole
+        // trigger.
+        toggleProps={getReferenceProps({ onClick: () => anchorToHalf(end) })}
+        isOpen={open}
+        contentId={contentId}
+        isDisabled={isDisabled}
+        isInvalid={isInvalid || outOfBounds(shownFor(end))}
+        onClear={clearable && settled && !isDisabled ? clearRangeEnd(end) : undefined}
+        clearLabel={`Clear ${label.toLowerCase()}`}
+      >
+        <DateTimeSegments
+          className="h-full flex-1"
+          label={label}
+          value={shownFor(end)}
+          onChange={(instant) => setRangeEnd(end, instant)}
+          timeZone={userTimeZone}
+          order={segmentOrder}
+          clockFormat={clockFormat}
+          showSeconds={showSeconds}
+          isDisabled={isDisabled}
+          isInvalid={isInvalid || outOfBounds(shownFor(end))}
+          onOpenRequest={openWithGridFocus(end)}
+          onSubmit={handleFieldSubmit}
+        />
+      </PickerField>
+    );
+  };
 
   // Time selection handlers - Start time
   const handleStartHourChange = (hour: number) => setDraftStartHour(hour);
@@ -486,39 +594,21 @@ export const DateTimeRangePicker = React.forwardRef<HTMLDivElement, DateTimeRang
   return (
     <>
       {/* Trigger Input */}
-      <div ref={ref} className="relative flex min-w-125 items-center">
-        <CalendarIcon 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 min-w-125 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`,
-            clearable && hasValue ? "pr-9" : "pr-3",
-            isInvalid && "border-border-danger",
-            className
-          )}
-          {...getReferenceProps()}
-        />
-        {clearable && 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 datetime range"
-          >
-            <X className="h-3.5 w-3.5" />
-          </button>
-        )}
+      <div
+        ref={(node) => {
+          // The container is the interaction reference, so a click in either half
+          // counts as inside; the *position* reference follows the active half.
+          refs.setReference(node);
+          if (typeof ref === "function") ref(node);
+          else if (ref) (ref as React.MutableRefObject<HTMLDivElement | null>).current = node;
+        }}
+        className={cn("relative flex min-w-125 items-center gap-2", className)}
+      >
+        {renderRangeHalf("from", "Start date and time")}
+        <span aria-hidden="true" className="text-fg-subtle">
+          –
+        </span>
+        {renderRangeHalf("to", "End date and time")}
 
         {/* Hidden inputs for form submission */}
         {name && committedValue?.from && <input type="hidden" name={`${name}.from`} value={committedValue.from.toString()} />}
@@ -532,7 +622,7 @@ export const DateTimeRangePicker = React.forwardRef<HTMLDivElement, DateTimeRang
             ref={refs.setFloating}
             id={contentId}
             role="dialog"
-            aria-modal="true"
+            aria-label="Choose date and time range"
             style={floatingStyles}
             className="z-popover rounded-xl border border-border-normal bg-bg-normal p-4 shadow-lg"
             {...getFloatingProps()}
@@ -575,6 +665,7 @@ export const DateTimeRangePicker = React.forwardRef<HTMLDivElement, DateTimeRang
                 disabled={temporalDisabledDates}
                 weekStartsOn={weekStartsOn}
                 showFooter={false}
+                autoFocusDay={autoFocusDay}
               />
             </div>
 
@@ -700,7 +791,7 @@ export const DateTimeRangePicker = React.forwardRef<HTMLDivElement, DateTimeRang
               <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>

package/src/components/DateTimeRangePicker/datetimerangepicker.types.ts

@@ -8,6 +8,7 @@
  */
 
 import type { DisabledDates, ISODate, ISOInstantRange, ISOTime, WeekStartsOn } from "../../date-time";
+import type { DateSegmentOrder } from "../DatePicker/datepicker.types";
 
 /**
  * A datetime range.
@@ -45,10 +46,15 @@ export type DateTimeRangePickerProps = {
 
   // Time format
   clockFormat?: "12h" | "24h"; // Default: "12h"
+
+  /**
+   * Segment order for the date half of each typeable field (default `mdy`).
+   * Never inferred from the locale — `08/09` is a different date under each.
+   */
+  segmentOrder?: DateSegmentOrder;
   showSeconds?: boolean; // Default: false
 
   // Display
-  placeholder?: string;
   weekStartsOn?: WeekStartsOn;
 
   // Form

package/src/components/Field/Field.tsx

@@ -1,23 +1,6 @@
 import { cn } from "@sixthshift/design-system/utils";
 import * as React from "react";
 
-/**
- * The labelled identifier carve-out used by identity-disclosure surfaces
- * (Person Detail's Identifiers card, Calendar Event's per-source provenance).
- *
- * Field exists because identifiers (JIDs, external IDs, OAuth subs) are
- * *content* on these surfaces — they answer "what does PA know about this
- * contact?" The default value rendering is monospaced with `break-all`
- * because a raw JID is the canonical case and it must wrap inside the row.
- *
- * Sibling primitive — not a replacement: `MetricRow` (in `@sixthshift/design-system/metric-list`)
- * carries runtime metrics ("CPU: 12.5%"). Both are label/value pairs but the
- * value semantics differ: a metric is a short readable number; an identifier
- * is a long opaque string. Forcing `MetricRow` to do both would conflate the
- * two and break Identifiers-card wrapping.
- *
- * See: docs/engineering/explanation/concepts/identity-rendering.md
- */
 export type FieldProps = {
   /** The humane label for what the identifier identifies ("WhatsApp", "Email"). */
   label: string;
@@ -39,21 +22,36 @@ export type FieldProps = {
   className?: string;
 };
 
+/**
+ * Read-only label/value pair for displaying an identifier on
+ * identity-disclosure surfaces — a contact's JIDs, external IDs, OAuth
+ * subjects. Not a form control: there is no input and nothing to submit.
+ *
+ * `layout="stacked"` (default) puts the label above the value, for long
+ * identifiers that need width to wrap; `layout="row"` puts label and value
+ * on one line with the value right-aligned. `mono` (default `true`) renders
+ * the value monospaced with `break-all`, since a raw identifier is the
+ * canonical case; set it `false` when the value is itself human-readable.
+ *
+ * Distinct from `FormField`, which is the label + input wrapper for
+ * interactive form controls. Both are label/value pairs, but this one is
+ * read-only: the value is a long opaque identifier, not an editable field.
+ */
 export const Field = React.forwardRef<HTMLDivElement, FieldProps>(({ label, children, layout = "stacked", mono = true, className }, ref) => {
-  const valueClass = cn("text-fg-subtle text-xs", mono && "break-all font-mono");
+  const valueClass = cn("text-(--field-fg) text-xs", mono && "break-all font-mono");
 
   if (layout === "row") {
     return (
-      <div ref={ref} className={cn("flex items-baseline justify-between gap-3", className)}>
-        <span className="shrink-0 text-fg-subtle text-sm">{label}</span>
+      <div ref={ref} className={cn("field flex items-baseline justify-between gap-3", className)}>
+        <span className="shrink-0 text-(--field-fg) text-sm">{label}</span>
         <span className={cn(valueClass, "min-w-0 text-right")}>{children}</span>
       </div>
     );
   }
 
   return (
-    <div ref={ref} className={cn("flex flex-col gap-1", className)}>
-      <span className="text-fg-subtle text-xs uppercase tracking-wide">{label}</span>
+    <div ref={ref} className={cn("field flex flex-col gap-1", className)}>
+      <span className="text-(--field-fg) text-xs uppercase tracking-wide">{label}</span>
       <span className={valueClass}>{children}</span>
     </div>
   );

package/src/components/FormField/FormField.tsx

@@ -16,6 +16,21 @@ export type FormFieldProps = React.HTMLAttributes<HTMLDivElement> & {
   required?: boolean;
 };
 
+/**
+ * Wraps a form control with a label, optional description, and optional
+ * validation feedback — the composition point for `Input`, `Textarea`,
+ * `Select` and similar controls inside a form.
+ *
+ * Generates an `id` (or uses the one passed in) and clones it, plus
+ * `aria-describedby` (pointing at the description and/or feedback text) and
+ * `aria-invalid` (when `feedback.intent` is `"danger"`), onto its child —
+ * so the wrapped control does not need those wired by hand. It expects a
+ * single child control: the same id and aria attributes get cloned onto
+ * every child if more than one is passed.
+ *
+ * Distinct from `Field`, which displays a read-only label/value pair rather
+ * than wrapping an interactive control.
+ */
 const FormField = React.forwardRef<HTMLDivElement, FormFieldProps>(({ className, label, description, feedback, required, children, id, ...props }, ref) => {
   const generatedId = React.useId();
   const fieldId = id ?? generatedId;

package/src/components/HoverCard/HoverCard.tsx

@@ -77,6 +77,12 @@ type HoverCardComponent = typeof HoverCardRoot & {
   Content: typeof HoverCardContent;
 };
 
+/**
+ * NOTE: Storybook shows the copy in HoverCard.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 HoverCard: HoverCardComponent = Object.assign(HoverCardRoot, {
   Trigger: HoverCardTrigger,
   Content: HoverCardContent,

package/src/components/Input/Input.tsx

@@ -6,20 +6,35 @@ export type InputProps = React.InputHTMLAttributes<HTMLInputElement> & {
   iconRight?: React.ReactNode;
 };
 
-const iconSlotStyles = `absolute top-1/2 -translate-y-1/2 text-fg-subtle
+const iconSlotStyles = `absolute top-1/2 -translate-y-1/2 text-(--input-icon-fg)
   [&_svg]:h-4 [&_svg]:w-4
   [&_button]:flex [&_button]:cursor-pointer [&_button]:appearance-none
   [&_button]:border-0 [&_button]:bg-transparent`;
 
+/**
+ * Single-line text input for free-form text entry.
+ *
+ * Renders a plain `<input>` unless `iconLeft` or `iconRight` is supplied, in
+ * which case it wraps the input in a relatively positioned container so an
+ * icon — or an icon-styled button, as `SearchInput` uses for its clear
+ * button — can sit inside the field's padding without affecting layout.
+ *
+ * Controlled or uncontrolled exactly like a native input (`value`/`onChange`
+ * or `defaultValue`), and `type` is forwarded as-is, so `type="password"`,
+ * `type="number"`, etc. all work.
+ *
+ * Meant to be wrapped by `FormField` for label, description and validation
+ * wiring, or by `SearchInput` for a search affordance.
+ */
 const Input = React.forwardRef<HTMLInputElement, InputProps>(({ className, type, iconLeft, iconRight, ...props }, ref) => {
   if (iconLeft || iconRight) {
     return (
-      <div className={cn("relative h-9 w-full text-sm", className)}>
+      <div className={cn("input relative h-9 w-full text-sm", className)}>
         {iconLeft && <span className={cn(iconSlotStyles, "left-3")}>{iconLeft}</span>}
         <input
           type={type}
           className={cn(
-            `flex h-full w-full rounded-md border border-border-normal bg-bg-normal py-1 text-[length:inherit] shadow-xs transition-colors file:border-0 file:bg-bg-normal file:font-medium file:text-fg-normal file:text-sm placeholder:text-fg-subtle focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-focus-ring disabled:cursor-not-allowed disabled:opacity-50`,
+            `input border-(color:--input-border) focus-visible:ring-(color:--input-ring) flex h-full w-full rounded-md border bg-(--input-bg) py-1 text-[length:inherit] shadow-xs transition-colors file:border-0 file:bg-(--input-file-bg) file:font-medium file:text-(--input-file-fg) file:text-sm placeholder:text-(--input-placeholder-fg) focus-visible:outline-hidden focus-visible:ring-2 disabled:cursor-not-allowed disabled:opacity-50`,
             iconLeft ? "pl-9" : "pl-3",
             iconRight ? "pr-9" : "pr-3"
           )}
@@ -35,7 +50,7 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(({ className, type,
     <input
       type={type}
       className={cn(
-        `flex h-9 w-full rounded-md border border-border-normal bg-bg-normal px-3 py-1 text-sm shadow-xs transition-colors file:border-0 file:bg-bg-normal file:font-medium file:text-fg-normal file:text-sm placeholder:text-fg-subtle focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-focus-ring disabled:cursor-not-allowed disabled:opacity-50`,
+        `input border-(color:--input-border) focus-visible:ring-(color:--input-ring) flex h-9 w-full rounded-md border bg-(--input-bg) px-3 py-1 text-sm shadow-xs transition-colors file:border-0 file:bg-(--input-file-bg) file:font-medium file:text-(--input-file-fg) file:text-sm placeholder:text-(--input-placeholder-fg) focus-visible:outline-hidden focus-visible:ring-2 disabled:cursor-not-allowed disabled:opacity-50`,
         className
       )}
       ref={ref}

package/src/components/LineChart/LineChart.tsx

@@ -96,6 +96,23 @@ function buildPath(points: { x: number; y: number }[], interpolation: Interpolat
   return parts.join(" ");
 }
 
+/**
+ * Multi-series line chart, rendered as a single responsive SVG (a `viewBox`,
+ * no fixed pixel size) with one `<path>` per series, plus optional grid
+ * lines, axes, dots, and per-point value labels.
+ *
+ * Colour is per-series: pass a CSS color string via `color` on a
+ * `LineChartSeries` (typically a `var(--fg-*)` token), or omit it to cycle
+ * through the same default palette `BarChart` uses. The y-axis scale is
+ * computed from the data into "nice" round ticks unless `yMin`/`yMax`/
+ * `yTicks` override it.
+ *
+ * The chart has a single static accessible name — `<title>Line
+ * chart</title>` behind `role="img"` — regardless of what's plotted; it does
+ * not describe the series or values. `showTooltip` overlays a `Tooltip` at
+ * each data point, but the trigger is a plain, unfocusable `<span>`, so it
+ * only responds to mouse hover, not keyboard.
+ */
 export const LineChart = React.forwardRef<HTMLDivElement, LineChartProps>(
   (
     {

package/src/components/Markdown/Markdown.tsx

@@ -10,6 +10,23 @@ export type MarkdownProps = {
   className?: string;
 };
 
+/**
+ * Renders a markdown string through the design system's own typography
+ * components (`Heading`, `Body`, `Emphasis`) rather than raw HTML tags, so
+ * markdown content picks up the same type ramp as everything else.
+ *
+ * Built for short, chat/assistant-style content rather than full documents:
+ * it covers headings, paragraphs, emphasis, links, lists, and code, but
+ * heading levels are compressed — `#` renders as `Heading as="h3"`, `##` as
+ * `Heading as="h4"`, and `###` as inline `Emphasis` rather than a heading at
+ * all — and `h4`+ and tables aren't specially handled: there's no
+ * `remark-gfm`, so GFM table syntax doesn't render as a table. Raw HTML
+ * embedded in the source is not rendered.
+ *
+ * `react-markdown` is an optional peer dependency of this package — a
+ * consuming app that imports `Markdown` without installing it will fail at
+ * runtime.
+ */
 export const Markdown = React.forwardRef<HTMLDivElement, MarkdownProps>(({ children, className }, ref) => (
   <div ref={ref} className={cn("flex flex-col", className)}>
     <ReactMarkdown