@sixthshift/design-system 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sixthshift/design-system",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Personal design system - tokens, theme, and component library",
   "license": "MIT",
   "publishConfig": {
@@ -103,10 +103,6 @@
       "types": "./dist/components/Badge/index.d.ts",
       "import": "./dist/components/Badge/index.js"
     },
-    "./color-dot": {
-      "types": "./dist/components/ColorDot/index.d.ts",
-      "import": "./dist/components/ColorDot/index.js"
-    },
     "./tag-chip": {
       "types": "./dist/components/TagChip/index.d.ts",
       "import": "./dist/components/TagChip/index.js"
@@ -119,42 +115,18 @@
       "types": "./dist/components/Field/index.d.ts",
       "import": "./dist/components/Field/index.js"
     },
-    "./breadcrumb": {
-      "types": "./dist/components/Breadcrumb/index.d.ts",
-      "import": "./dist/components/Breadcrumb/index.js"
-    },
     "./card": {
       "types": "./dist/components/Card/index.d.ts",
       "import": "./dist/components/Card/index.js"
     },
-    "./avatar": {
-      "types": "./dist/components/Avatar/index.d.ts",
-      "import": "./dist/components/Avatar/index.js"
-    },
     "./separator": {
       "types": "./dist/components/Separator/index.d.ts",
       "import": "./dist/components/Separator/index.js"
     },
-    "./skeleton": {
-      "types": "./dist/components/Skeleton/index.d.ts",
-      "import": "./dist/components/Skeleton/index.js"
-    },
     "./spinner": {
       "types": "./dist/components/Spinner/index.d.ts",
       "import": "./dist/components/Spinner/index.js"
     },
-    "./stats-card": {
-      "types": "./dist/components/StatsCard/index.d.ts",
-      "import": "./dist/components/StatsCard/index.js"
-    },
-    "./metric-list": {
-      "types": "./dist/components/MetricList/index.d.ts",
-      "import": "./dist/components/MetricList/index.js"
-    },
-    "./empty-state": {
-      "types": "./dist/components/EmptyState/index.d.ts",
-      "import": "./dist/components/EmptyState/index.js"
-    },
     "./text": {
       "types": "./dist/components/Text/index.d.ts",
       "import": "./dist/components/Text/index.js"
@@ -231,10 +203,6 @@
       "types": "./dist/components/SearchInput/index.d.ts",
       "import": "./dist/components/SearchInput/index.js"
     },
-    "./pagination": {
-      "types": "./dist/components/Pagination/index.d.ts",
-      "import": "./dist/components/Pagination/index.js"
-    },
     "./code-editor": {
       "types": "./dist/components/Code/Editor/index.d.ts",
       "import": "./dist/components/Code/Editor/index.js"
@@ -243,14 +211,6 @@
       "types": "./dist/components/Code/Workspace/index.d.ts",
       "import": "./dist/components/Code/Workspace/index.js"
     },
-    "./nav-side": {
-      "types": "./dist/components/NavSide/index.d.ts",
-      "import": "./dist/components/NavSide/index.js"
-    },
-    "./nav-bottom": {
-      "types": "./dist/components/NavBottom/index.d.ts",
-      "import": "./dist/components/NavBottom/index.js"
-    },
     "./heading": {
       "types": "./dist/typography/Heading.d.ts",
       "import": "./dist/typography/Heading.js"
@@ -354,10 +314,6 @@
     "./bar-chart": {
       "types": "./dist/components/BarChart/index.d.ts",
       "import": "./dist/components/BarChart/index.js"
-    },
-    "./heat-map": {
-      "types": "./dist/components/HeatMap/index.d.ts",
-      "import": "./dist/components/HeatMap/index.js"
     }
   },
   "scripts": {
@@ -366,9 +322,10 @@
     "build:js": "tsc -p tsconfig.build.json && bun run scripts/fix-extensions.ts",
     "dev": "storybook dev -p 6006 --no-open",
     "build:storybook": "storybook build",
-    "test": "vitest run --project unit --project date-time --reporter=dot",
-    "test:verbose": "vitest run --project unit --project date-time",
-    "test:watch": "vitest --project unit --project date-time",
+    "test": "vitest run --project unit --project date-time --project ssr --reporter=dot",
+    "test:verbose": "vitest run --project unit --project date-time --project ssr",
+    "test:watch": "vitest --project unit --project date-time --project ssr",
+    "test:ssr": "vitest run --project ssr",
     "test:visual": "vitest run --project visual",
     "test:visual:update": "vitest run --project visual --update",
     "test:stories": "vitest run --project storybook --project storybook-dark",
@@ -381,6 +338,8 @@
     "format:check": "biome format .",
     "check": "biome check .",
     "check:fix": "biome check --write .",
+    "check:recipes": "bun run scripts/check-recipes.ts",
+    "check:contrast": "bun run scripts/check-contrast.ts",
     "clean": "rm -rf dist node_modules *.tsbuildinfo",
     "clean:dist": "rm -rf dist"
   },

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>
                 )}