@sixthshift/design-system 0.3.0 → 0.4.0

package/src/components/Badge/Badge.tsx

@@ -2,58 +2,95 @@ import { cn } from "@sixthshift/design-system/utils";
 import { cva, type VariantProps } from "class-variance-authority";
 import * as React from "react";
 
+/**
+ * Geometry and behaviour only.
+ *
+ * Every colour reads a `--badge-*` component token whose value is decided by
+ * src/theme/recipes/badge.css. That file is the mapping from
+ * `(variant, intent)` to a semantic token — the layer that used to be
+ * `compoundVariants` here, where it was compiled into class-name literals and
+ * unreachable from outside. Nothing in this file names a colour, which is the
+ * point: the semantics are now configurable without a release.
+ */
 const badgeVariants = cva(
-  "inline-flex items-center rounded-md border px-2.5 py-0.5 font-semibold text-xs transition-colors focus:outline-hidden focus:ring-2 focus:ring-border-brand focus:ring-offset-2",
-  {
-    variants: {
-      variant: {
-        solid: "border-transparent shadow",
-        soft: "border-transparent",
-        outline: "",
-      },
-      intent: {
-        neutral: "",
-        primary: "",
-        danger: "",
-        success: "",
-        warning: "",
-        muted: "",
-      },
-    },
-    compoundVariants: [
-      // Solid variants
-      { variant: "solid", intent: "neutral", className: "bg-bg-strong text-fg-on-strong" },
-      { variant: "solid", intent: "primary", className: "bg-bg-brand text-fg-on-brand" },
-      { variant: "solid", intent: "danger", className: "bg-bg-danger text-fg-on-danger" },
-      { variant: "solid", intent: "success", className: "bg-bg-success text-fg-on-success" },
-      { variant: "solid", intent: "warning", className: "bg-bg-warning text-fg-on-warning" },
-      { variant: "solid", intent: "muted", className: "bg-bg-subtle text-fg-subtle" },
-      // Soft variants
-      { variant: "soft", intent: "neutral", className: "bg-bg-subtle text-fg-normal" },
-      { variant: "soft", intent: "primary", className: "bg-bg-brand-subtle text-fg-on-brand-subtle" },
-      { variant: "soft", intent: "danger", className: "bg-bg-danger-subtle text-fg-on-danger-subtle" },
-      { variant: "soft", intent: "success", className: "bg-bg-success-subtle text-fg-on-success-subtle" },
-      { variant: "soft", intent: "warning", className: "bg-bg-warning-subtle text-fg-on-warning-subtle" },
-      { variant: "soft", intent: "muted", className: "bg-bg-subtle text-fg-subtle" },
-      // Outline variants
-      { variant: "outline", intent: "neutral", className: "border-border-normal bg-bg-normal text-fg-normal" },
-      { variant: "outline", intent: "primary", className: "border-border-brand bg-bg-normal text-fg-brand" },
-      { variant: "outline", intent: "danger", className: "border-border-danger bg-bg-normal text-fg-danger" },
-      { variant: "outline", intent: "success", className: "border-border-success bg-bg-normal text-fg-success" },
-      { variant: "outline", intent: "warning", className: "border-border-warning bg-bg-normal text-fg-warning" },
-      { variant: "outline", intent: "muted", className: "border-border-normal bg-bg-normal text-fg-subtle" },
-    ],
-    defaultVariants: {
-      variant: "solid",
-      intent: "primary",
-    },
-  }
+  // 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. The screenshots catch it, but a single string means the
+  // sorter has nothing to break.
+  "badge border-(color:--badge-border) focus:ring-(color:--badge-ring) inline-flex items-center rounded-md border bg-(--badge-bg) px-2.5 py-0.5 font-semibold text-(--badge-fg) text-xs transition-colors focus:outline-hidden focus:ring-2 focus:ring-offset-2",
+  { variants: {} }
 );
 
-export type BadgeProps = React.HTMLAttributes<HTMLSpanElement> & VariantProps<typeof badgeVariants>;
+/**
+ * The non-colour half of `variant` — elevation only, for Badge. A plain
+ * lookup rather than a CVA variant so an unrecognised variant stays a legal
+ * value that contributes no structure, leaving a consumer's CSS free to
+ * define it. `intent` needs no equivalent: it was never anything but colour.
+ */
+const variantStructure: Record<string, string> = {
+  solid: "shadow",
+  soft: "",
+  outline: "",
+};
 
-export const Badge = React.forwardRef<HTMLSpanElement, BadgeProps>(({ className, variant, intent, ...props }, ref) => {
-  return <span ref={ref} className={cn(badgeVariants({ variant, intent }), className)} {...props} />;
+/**
+ * Widened deliberately. Adding a variant or an intent is a CSS change in the
+ * consuming app, 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 BadgeVariantName = "solid" | "soft" | "outline";
+/**
+ * `primary` was this component's name for the brand colour, and nothing else in
+ * the system used it — the token is `--bg-brand`, and
+ * docs/modals.md already told callers to write `intent="brand"`. It is off the
+ * closed union as of this release but still resolves, via an aliased selector in
+ * badge.css; `BadgeIntent` is widened, so it also still type-checks.
+ */
+export type BadgeIntentName = "neutral" | "brand" | "danger" | "success" | "warning" | "muted";
+export type BadgeVariant = Loose<BadgeVariantName>;
+export type BadgeIntent = Loose<BadgeIntentName>;
+
+export type BadgeRecipeProps = VariantProps<typeof badgeVariants> & {
+  variant?: BadgeVariant | undefined;
+  intent?: BadgeIntent | undefined;
+  className?: string | undefined;
+};
+
+/**
+ * The class string plus the two attributes the recipe selects on.
+ */
+export function badgeRecipe({ variant = "solid", intent = "brand", className }: BadgeRecipeProps) {
+  return {
+    className: cn(variantStructure[variant], badgeVariants({ className })),
+    "data-variant": variant,
+    "data-intent": intent,
+  };
+}
+
+export type BadgeProps = React.HTMLAttributes<HTMLSpanElement> & {
+  variant?: BadgeVariant | undefined;
+  intent?: BadgeIntent | undefined;
+};
+
+/**
+ * Small label for status, category, or count.
+ *
+ * Two independent axes, same split as Button: `variant` is the fill
+ * (`solid`, `soft`, `outline`), `intent` is what it signals (`neutral`,
+ * `brand`, `danger`, `success`, `warning`, `muted`) — `muted` has no
+ * Button equivalent, for de-emphasized metadata rather than a status.
+ * Renders a `<span>`; purely presentational, so give it visible text — it
+ * does not manage an accessible name of its own.
+ *
+ * Colour is not decided here: each `(variant, intent)` pairing resolves
+ * through a `--badge-*` component token (src/theme/recipes/badge.css), the
+ * same seam Button uses, so a consumer can re-point a cell without a
+ * release.
+ */
+export const Badge = React.forwardRef<HTMLSpanElement, BadgeProps>(({ className, variant = "solid", intent = "brand", ...props }, ref) => {
+  return <span ref={ref} {...badgeRecipe({ variant, intent, className })} {...props} />;
 });
 Badge.displayName = "Badge";
 

package/src/components/Badge/index.ts

@@ -1 +1,10 @@
-export { Badge, type BadgeProps, badgeVariants } from "./Badge";
+export {
+  Badge,
+  type BadgeIntent,
+  type BadgeIntentName,
+  type BadgeProps,
+  type BadgeVariant,
+  type BadgeVariantName,
+  badgeRecipe,
+  badgeVariants,
+} from "./Badge";

package/src/components/BarChart/BarChart.tsx

@@ -17,6 +17,18 @@ export type BarChartProps = React.HTMLAttributes<HTMLDivElement> & {
 
 const DEFAULT_COLORS = ["var(--fg-brand)", "var(--fg-success)", "var(--fg-warning)", "var(--fg-danger)", "var(--fg-subtle)"];
 
+/**
+ * Horizontal bar chart, rendered as plain `<div>` bars rather than SVG — each
+ * row is a label, a track, and a colored fill sized to the item's percentage
+ * of `maxValue` (auto-detected from the data when omitted).
+ *
+ * Colour is per-item: pass a CSS color string via `color` on a
+ * `BarChartItem` (typically a `var(--fg-*)` token), or omit it to cycle
+ * through the built-in `DEFAULT_COLORS` list by index. There is no
+ * chart-level accessible name — the only text exposed to assistive tech is
+ * the visible label and, when `showValues` is true (the default), the
+ * formatted value next to each bar.
+ */
 export const BarChart = React.forwardRef<HTMLDivElement, BarChartProps>(
   ({ data, showValues = true, maxValue: maxValueProp, formatValue = (v) => String(v), barHeight = 24, className, ...rest }, ref) => {
     const maxValue = maxValueProp ?? Math.max(...data.map((d) => d.value), 1);

package/src/components/Button/Button.tsx

@@ -3,136 +3,159 @@ import { cva, type VariantProps } from "class-variance-authority";
 import * as React from "react";
 import { Slot } from "../../internal/Slot";
 
+/**
+ * Geometry and behaviour only.
+ *
+ * Every colour reads a `--button-*` component token whose value is decided by
+ * src/theme/recipes/button.css. That file is the mapping from
+ * `(variant, intent, state)` to a semantic token — the layer that used to be
+ * `compoundVariants` here, where it was compiled into class-name literals and
+ * unreachable from outside. Nothing in this file names a colour, which is the
+ * point: the semantics are now configurable without a release.
+ */
 const buttonVariants = cva(
-  "inline-flex cursor-pointer items-center justify-center gap-2 whitespace-nowrap rounded-md font-medium text-sm transition-colors focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-focus-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
+  // 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. The screenshots catch it, but a single string means the
+  // sorter has nothing to break.
+  "btn border-(color:--button-border) focus-visible:ring-(color:--button-ring) inline-flex cursor-pointer items-center justify-center gap-2 whitespace-nowrap rounded-md bg-(--button-bg) font-medium text-(--button-fg) text-sm transition-colors hover:bg-(--button-bg-hovered) focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-offset-2 active:bg-(--button-bg-pressed) disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
   {
     variants: {
-      variant: {
-        solid: "shadow",
-        outline: "border bg-bg-normal shadow-xs",
-        ghost: "",
-        link: "underline-offset-4 hover:underline",
-      },
-      intent: {
-        neutral: "",
-        danger: "",
-        success: "",
-        warning: "",
-      },
       size: {
-        default: "h-9 px-4 py-2",
         xs: "h-7 rounded-md px-2 text-xs",
         sm: "h-8 rounded-md px-3 text-xs",
+        md: "h-9 px-4 py-2",
         lg: "h-10 rounded-md px-8",
         xl: "h-12 rounded-md px-10 text-base",
-        icon: "h-9 w-9",
       },
     },
-    compoundVariants: [
-      // Solid variants
-      {
-        variant: "solid",
-        intent: "neutral",
-        className: "bg-bg-brand text-fg-on-brand hover:bg-bg-brand-hovered active:bg-bg-brand-pressed",
-      },
-      {
-        variant: "solid",
-        intent: "danger",
-        className: "bg-bg-danger text-fg-on-danger hover:bg-bg-danger-hovered active:bg-bg-danger-pressed",
-      },
-      {
-        variant: "solid",
-        intent: "success",
-        className: "bg-bg-success text-fg-on-success hover:bg-bg-success-hovered active:bg-bg-success-pressed",
-      },
-      {
-        variant: "solid",
-        intent: "warning",
-        className: "bg-bg-warning text-fg-on-warning hover:bg-bg-warning-hovered active:bg-bg-warning-pressed",
-      },
-      // Outline variants
-      {
-        variant: "outline",
-        intent: "neutral",
-        className: "border-border-normal text-fg-normal hover:bg-bg-subtle-hovered active:bg-bg-subtle-pressed",
-      },
-      {
-        variant: "outline",
-        intent: "danger",
-        className: "border-border-danger text-fg-danger hover:bg-bg-danger-subtle-hovered active:bg-bg-danger-subtle-pressed",
-      },
-      {
-        variant: "outline",
-        intent: "success",
-        className: "border-border-success text-fg-success hover:bg-bg-success-subtle-hovered active:bg-bg-success-subtle-pressed",
-      },
-      {
-        variant: "outline",
-        intent: "warning",
-        className: "border-border-warning text-fg-warning hover:bg-bg-warning-subtle-hovered active:bg-bg-warning-subtle-pressed",
-      },
-      // Ghost variants
-      {
-        variant: "ghost",
-        intent: "neutral",
-        className: "text-fg-normal hover:bg-bg-subtle-hovered active:bg-bg-subtle-pressed",
-      },
-      {
-        variant: "ghost",
-        intent: "danger",
-        className: "text-fg-danger hover:bg-bg-danger-subtle-hovered active:bg-bg-danger-subtle-pressed",
-      },
-      {
-        variant: "ghost",
-        intent: "success",
-        className: "text-fg-success hover:bg-bg-success-subtle-hovered active:bg-bg-success-subtle-pressed",
-      },
-      {
-        variant: "ghost",
-        intent: "warning",
-        className: "text-fg-warning hover:bg-bg-warning-subtle-hovered active:bg-bg-warning-subtle-pressed",
-      },
-      // Link variants
-      {
-        variant: "link",
-        intent: "neutral",
-        className: "text-fg-brand",
-      },
-      {
-        variant: "link",
-        intent: "danger",
-        className: "text-fg-danger",
-      },
-      {
-        variant: "link",
-        intent: "success",
-        className: "text-fg-success",
-      },
-      {
-        variant: "link",
-        intent: "warning",
-        className: "text-fg-warning",
-      },
-    ],
     defaultVariants: {
-      variant: "solid",
-      intent: "neutral",
-      size: "default",
+      size: "md",
     },
   }
 );
 
+/**
+ * The non-colour half of `variant` — border width, elevation, underline.
+ *
+ * A plain lookup rather than a CVA variant so an unrecognised variant stays a
+ * legal value that contributes no structure, leaving a consumer's CSS free to
+ * define it. `intent` needs no equivalent: it was never anything but colour.
+ */
+const variantStructure: Record<string, string> = {
+  solid: "shadow",
+  outline: "border shadow-xs",
+  ghost: "",
+  link: "underline-offset-4 hover:underline",
+};
+
+/**
+ * Squares the box at whatever size is set, and drops the horizontal padding.
+ *
+ * Shape, kept off the size union deliberately. A single axis carrying both a
+ * scale and a shape cannot express a *small* icon button, which is what a fixed
+ * `icon: "h-9 w-9"` size amounted to. Keyed by size rather than folded into the
+ * size classes so the two stay orthogonal; `cn` (tailwind-merge) resolves
+ * `px-0` against the size's own `px-*`, last write winning.
+ */
+const iconOnlyGeometry: Record<string, string> = {
+  xs: "w-7 px-0",
+  sm: "w-8 px-0",
+  md: "w-9 px-0",
+  lg: "w-10 px-0",
+  xl: "w-12 px-0",
+};
+
+/**
+ * Widened deliberately. Adding a variant or an intent is a CSS change in the
+ * consuming app, not a release here — so the type has to admit values this file
+ * has never heard of, while still autocompleting the ones it ships.
+ *
+ * The closed unions are exported alongside, because widening a type gives up the
+ * ability to narrow it downstream: once `string` is in the union,
+ * `Exclude<ButtonVariant, "link">` can no longer remove `link`. ToggleGroup
+ * relies on exactly that exclusion, so it builds on the closed names.
+ */
+type Loose<T extends string> = T | (string & {});
+
+export type ButtonVariantName = "solid" | "outline" | "ghost" | "link";
+export type ButtonIntentName = "neutral" | "brand" | "danger" | "success" | "warning";
+export type ButtonVariant = Loose<ButtonVariantName>;
+export type ButtonIntent = Loose<ButtonIntentName>;
+
+export type ButtonRecipeProps = VariantProps<typeof buttonVariants> & {
+  variant?: ButtonVariant | undefined;
+  intent?: ButtonIntent | undefined;
+  iconOnly?: boolean | undefined;
+  className?: string | undefined;
+};
+
+/**
+ * The class string plus the two attributes the recipe selects on.
+ *
+ * Shared with Toggle and ToggleGroupItem, which are built on Button's look. The
+ * data attributes are half the contract now, so anything reusing that look has
+ * to emit them as well or it lands on the recipe's floor instead of a cell.
+ */
+export function buttonRecipe({ variant = "solid", intent = "neutral", size, iconOnly = false, className }: ButtonRecipeProps) {
+  return {
+    className: cn(
+      variantStructure[variant],
+      // `className` stays last so a caller still outranks the icon geometry.
+      buttonVariants({ size, className: cn(iconOnly ? iconOnlyGeometry[size ?? "md"] : undefined, className) })
+    ),
+    "data-variant": variant,
+    "data-intent": intent,
+  };
+}
+
 export type ButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> &
   VariantProps<typeof buttonVariants> & {
+    variant?: ButtonVariant | undefined;
+    intent?: ButtonIntent | undefined;
+    /** Square the button at its current size, for an icon with no label. */
+    iconOnly?: boolean;
     asChild?: boolean;
     loading?: boolean;
   };
 
+/**
+ * A single action the user can take.
+ *
+ * Appearance is three independent axes, so every combination is expressible:
+ * `variant` is the fill and shape (`solid`, `outline`, `ghost`, `link`),
+ * `intent` is what the action *means* (`brand` — the default — plus `neutral`,
+ * `danger`, `success`, `warning`), and `size` is the height scale. Reach for
+ * `intent="danger"` on a destructive action rather than a red `variant` — that
+ * is the distinction that keeps "outline danger" possible.
+ *
+ * `neutral` means *no colour family*: a grey button, the same thing the word
+ * means on Badge and Message. A brand-coloured button is
+ * `intent="brand"` — an affirmative choice, which is why `neutral` is the
+ * default: omitting the prop means "no particular meaning", so it should not
+ * quietly hand back the brand colour. Button used to spell brand as `neutral`
+ * for `solid` and `link` while `outline` and `ghost` were already grey, so a
+ * primary action now needs `intent="brand"` said out loud.
+ *
+ * Colour is not decided here. Each pairing resolves through a `--button-*`
+ * component token, so a consumer can re-point any cell — or add an intent this
+ * library never shipped — from their own stylesheet. See the Component tokens
+ * story below.
+ *
+ * `iconOnly` squares the box at whatever `size` is set and drops the
+ * horizontal padding, for a button whose whole content is an icon — give it an
+ * `aria-label`, since there is no text to name it. It is a separate prop rather
+ * than a size, so `size="sm" iconOnly` is expressible.
+ *
+ * `asChild` renders the child element with Button's styling instead of a
+ * `<button>`, for links that should look like buttons. `loading` shows a spinner
+ * and disables the control, so it does not need `disabled` as well.
+ */
 const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
-  ({ className, variant, intent, size, asChild = false, loading = false, children, disabled, ...props }, ref) => {
+  ({ className, variant = "solid", intent = "neutral", size, iconOnly = false, asChild = false, loading = false, children, disabled, ...props }, ref) => {
     const Comp = asChild ? Slot : "button";
     return (
-      <Comp className={cn(buttonVariants({ variant, intent, size, className }))} ref={ref} disabled={disabled || loading} {...props}>
+      <Comp {...buttonRecipe({ variant, intent, size, iconOnly, className })} ref={ref} disabled={disabled || loading} {...props}>
         {loading ? (
           <>
             <svg className="animate-spin" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" aria-hidden="true">

package/src/components/Button/index.ts

@@ -1 +1,10 @@
-export { Button, type ButtonProps, buttonVariants } from "./Button";
+export {
+  Button,
+  type ButtonIntent,
+  type ButtonIntentName,
+  type ButtonProps,
+  type ButtonVariant,
+  type ButtonVariantName,
+  buttonRecipe,
+  buttonVariants,
+} from "./Button";

package/src/components/Calendar/Calendar.tsx

@@ -1,19 +1,3 @@
-/**
- * Calendar — the public, ISO-string-typed calendar.
- *
- * A thin adapter over {@link CalendarView}: it parses incoming ISO strings and
- * serialises outgoing selections. All the behaviour lives in CalendarView.
- *
- * Every conversion is memoised on the string it came from, and every handler is
- * stable. Temporal objects have no value identity — `PlainDate.from("2026-08-26")`
- * is never `===` another PlainDate for the same day — and CalendarView keys
- * `useMemo`/`useCallback` on these values directly, so converting unmemoised
- * would invalidate the whole grid on every render.
- *
- * Props are read with `"key" in props` rather than destructured per mode,
- * because every hook here has to run unconditionally.
- */
-
 import * as React from "react";
 import { useCallback, useMemo } from "react";
 import {
@@ -33,6 +17,35 @@ import type { CalendarProps, CalendarViewProps, DateRangeValue, PresetOption } f
 
 export type { CalendarProps };
 
+/**
+ * Inline month grid for picking one date, a range, or several dates — the
+ * building block `DatePicker` puts behind a popover trigger. Reach for
+ * `Calendar` directly when the grid should be always visible rather than
+ * opened on demand.
+ *
+ * `mode` (`"single" | "range" | "multiple"`) decides the shape of `value` and
+ * `onSelect`: an `ISODate` string, an `ISODateRange` (`{ from?, to? }`), or an
+ * `ISODate[]` respectively. There is no uncontrolled form — `value` and
+ * `onSelect` are both required, so the caller always owns the selection.
+ *
+ * `minDate`/`maxDate` bound the selectable range inclusively; `disabled` takes
+ * a single date, a list, or a declarative matcher (before/after/range/weekday)
+ * or predicate — see `DisabledDates`. Day cells form a roving-tabindex grid:
+ * arrow keys move by day, Home/End jump to the start/end of the week, and
+ * PageUp/PageDown request a month change.
+ *
+ * A thin adapter over {@link CalendarView}: it parses incoming ISO strings and
+ * serialises outgoing selections. All the behaviour lives in CalendarView.
+ *
+ * Every conversion is memoised on the string it came from, and every handler is
+ * stable. Temporal objects have no value identity — `PlainDate.from("2026-08-26")`
+ * is never `===` another PlainDate for the same day — and CalendarView keys
+ * `useMemo`/`useCallback` on these values directly, so converting unmemoised
+ * would invalidate the whole grid on every render.
+ *
+ * Props are read with `"key" in props` rather than destructured per mode,
+ * because every hook here has to run unconditionally.
+ */
 export const Calendar = React.forwardRef<HTMLDivElement, CalendarProps>((props, ref) => {
   const { mode, month, onMonthChange, minDate, maxDate, disabled, weekStartsOn, showFooter, showToday, onApply, onCancel, className } = props;
 

package/src/components/Calendar/CalendarView.tsx

@@ -72,6 +72,7 @@ export const CalendarView = React.forwardRef<HTMLDivElement, CalendarViewProps>(
     maxDate,
     disabled,
     weekStartsOn = 0,
+    autoFocusDay = false,
     showFooter = false,
     showToday = true,
     onApply,
@@ -274,6 +275,14 @@ export const CalendarView = React.forwardRef<HTMLDivElement, CalendarViewProps>(
     gridRef.current?.querySelector<HTMLButtonElement>(`[data-date="${temporalToISO(focusedDate)}"]`)?.focus();
   }, [focusedDate]);
 
+  // Seed that focus once when the caller asked for it. Deliberately keyed on
+  // `autoFocusDay` alone: `activeDate` changes as the user navigates, and
+  // re-running then would drag focus back to where it started.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: see above
+  useEffect(() => {
+    if (autoFocusDay) setFocusedDate((current) => current ?? activeDate);
+  }, [autoFocusDay]);
+
   // useCalendarDays always returns 42 days, so this is always 6 rows of 7.
   const weeks = useMemo(() => {
     const chunked: (typeof days)[] = [];
@@ -430,7 +439,7 @@ export const CalendarView = React.forwardRef<HTMLDivElement, CalendarViewProps>(
                   </Button>
                 )}
                 {onApply && (
-                  <Button type="button" variant="solid" size="sm" onClick={onApply}>
+                  <Button type="button" variant="solid" intent="brand" size="sm" onClick={onApply}>
                     Apply
                   </Button>
                 )}

package/src/components/Calendar/calendar.types.ts

@@ -124,6 +124,16 @@ type CalendarViewBaseProps = {
   /** First day of week (0 = Sunday, 1 = Monday) */
   weekStartsOn?: WeekStartsOn | undefined;
 
+  /**
+   * Move DOM focus into the day grid on mount.
+   *
+   * Off by default: a grid that grabs focus when it appears is wrong for a
+   * pointer user who clicked a trigger. `DatePicker` turns it on only when the
+   * popover was opened from the keyboard (`Alt+ArrowDown`), where the whole
+   * point of opening it was to navigate days.
+   */
+  autoFocusDay?: boolean | undefined;
+
   /** Show footer with Today/Cancel/Apply buttons */
   showFooter?: boolean | undefined;
   /** Show Today button (only if showFooter=true) */

package/src/components/Card/Card.tsx

@@ -8,6 +8,19 @@ export type CardProps = Omit<React.HTMLAttributes<HTMLDivElement>, "title"> & {
   headerAction?: React.ReactNode;
 };
 
+/**
+ * Bordered, elevated container — the "this contains data" building block
+ * (see docs/visual-hierarchy.md's Elevated tier). Renders a `<div>`, with an
+ * optional `<header>` when `title` and/or `headerAction` is passed.
+ *
+ * Passing `onClick` turns the whole card into a button: it gets
+ * `role="button"`, `tabIndex={0}`, and both Enter and Space activate it, not
+ * just a pointer click. Omit `onClick` for a purely presentational card.
+ *
+ * Colour reads `--card-*` component tokens (src/theme/recipes/card.css) —
+ * the same seam Button and Badge use — so a consumer can re-point them
+ * without a release.
+ */
 export const Card = React.forwardRef<HTMLDivElement, CardProps>(({ className, title, headerAction, children, onClick, onKeyDown, ...props }, ref) => {
   const isInteractive = !!onClick;
 
@@ -24,9 +37,9 @@ export const Card = React.forwardRef<HTMLDivElement, CardProps>(({ className, ti
     <div
       ref={ref}
       className={cn(
-        "rounded-xl border border-border-normal bg-bg-normal p-6 text-fg-normal shadow",
+        "card border-(color:--card-border) rounded-xl border bg-(--card-bg) p-6 text-(--card-fg) shadow",
         isInteractive &&
-          "cursor-pointer transition-colors hover:border-border-strong focus-visible:outline-2 focus-visible:outline-border-strong focus-visible:outline-offset-2",
+          "hover:border-(color:--card-border-hovered) focus-visible:outline-(color:--card-ring) cursor-pointer transition-colors focus-visible:outline-2 focus-visible:outline-offset-2",
         className
       )}
       onClick={onClick}

package/src/components/Checkbox/Checkbox.tsx

@@ -51,6 +51,27 @@ const IndeterminateIcon = () => (
   </svg>
 );
 
+/**
+ * A single boolean, or tri-state, toggle — a custom button with
+ * `role="checkbox"` rather than a native `<input type="checkbox">`, so it
+ * can be styled without fighting native checkbox rendering.
+ *
+ * Controlled or uncontrolled via the `checked`/`defaultChecked`/
+ * `onCheckedChange` triad (`useControllableState`). `checked` also accepts
+ * `"indeterminate"`, which sets `aria-checked="mixed"` and swaps in a dash
+ * icon instead of the check — for a "select all" checkbox whose children are
+ * only partially selected. Clicking an indeterminate checkbox always
+ * resolves it to `true`, never back to indeterminate.
+ *
+ * Only participates in native form submission when `name` is set: a hidden
+ * native `<input type="checkbox">` is rendered alongside the button and
+ * kept in sync, carrying `value` (default `"on"`). Without `name`, state
+ * lives only in React and nothing is submitted.
+ *
+ * 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 Checkbox = React.forwardRef<HTMLButtonElement, CheckboxProps>(
   (
     {
@@ -93,8 +114,7 @@ const Checkbox = React.forwardRef<HTMLButtonElement, CheckboxProps>(
           ref={ref}
           onClick={() => setChecked(!isChecked)}
           className={cn(
-            "peer h-4 w-4 shrink-0 cursor-pointer rounded-xs 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",
-            (isChecked || isIndeterminate) && "bg-bg-brand text-fg-on-brand",
+            "checkbox peer border-(color:--checkbox-border) focus-visible:ring-(color:--checkbox-ring) h-4 w-4 shrink-0 cursor-pointer rounded-xs border bg-(--checkbox-bg) text-(--checkbox-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/CheckboxGroup/CheckboxGroup.tsx

@@ -36,6 +36,28 @@ export type CheckboxGroupProps = Omit<React.HTMLAttributes<HTMLDivElement>, "onC
   onBlur?: () => void;
 };
 
+/**
+ * A set of related checkboxes sharing one controlled/uncontrolled `string[]`
+ * selection, via the `value`/`defaultValue`/`onValueChange` triad
+ * (`useControllableState`).
+ *
+ * `variant="default"` (the default) renders one `Checkbox` per option, each
+ * with its own visible label, laid out in a column or row per
+ * `orientation`. `variant="button"` is a separate rendering path — not a
+ * re-skinned `Checkbox` — a row/column of plain buttons with
+ * `role="checkbox"` and no separate label; contiguous buttons touch and
+ * share borders (`appearance="segmented"`, the default) or sit apart with
+ * their own rounded corners (`appearance="separate"`).
+ *
+ * Form submission only happens when `name` is set. In the default variant
+ * that means each underlying `Checkbox` gets `name`, so one hidden native
+ * checkbox input is rendered per option; in the button variant the group
+ * itself renders one hidden `<input type="checkbox">` per *currently
+ * selected* value.
+ *
+ * Renders `role="group"`; focus leaving the whole group — not just moving
+ * between options — fires `onBlur`.
+ */
 const CheckboxGroup = React.forwardRef<HTMLDivElement, CheckboxGroupProps>(
   (
     {