@sixthshift/design-system 0.4.0 → 0.5.0

package/README.md

@@ -4,6 +4,8 @@ Personal design system: design tokens, theme pipeline, and a React component lib
 
 A single package, `@sixthshift/design-system`: ~80 components (primitives, overlays, forms, pickers, charts, typography) + a JSON-driven token/theme pipeline + Tailwind config. Built on [shadcn/ui](https://ui.shadcn.com) patterns.
 
+Browse the components: **[sixthshift.github.io/design-system](https://sixthshift.github.io/design-system/)** — Storybook, rebuilt from `main` by `.github/workflows/pages.yml`.
+
 ## Orientation
 
 **Owns:** The component library — 80+ exports via subpath imports, design tokens, theme system (JSON-driven CSS generation), Tailwind config, and Storybook stories. Components span primitives, composites, typography, charts, and overlays.

package/dist/components/Card/Card.d.ts

@@ -1,5 +1,44 @@
+import { type VariantProps } from "class-variance-authority";
 import * as React from "react";
-export type CardProps = Omit<React.HTMLAttributes<HTMLDivElement>, "title"> & {
+/**
+ * Geometry only, plus the five `--card-*` component tokens.
+ *
+ * Every colour reads a `--card-*` token whose value is decided by
+ * src/theme/recipes/card.css. `size` stays here: it is pure geometry
+ * (padding, header gap, corner radius), not colour, so it has no reason to
+ * move — the same split Message.tsx documents.
+ *
+ * The ramp is a density axis, not a padding setting. `md` is the middle and
+ * the default at 16px, which is also where MUI's `CardContent` and
+ * Bootstrap's `.card-body` sit; two steps exist below it for surfaces that
+ * repeat dozens of times, and two above for surfaces that are the page.
+ *
+ *   xs  8px   dense data — table-row cards, compact tiles, many at once
+ *   sm  12px  list rows and secondary cards; a line or two of content
+ *   md  16px  a standalone content card. The one to reach for by default
+ *   lg  24px  primary or feature cards — a main panel, a form container
+ *   xl  32px  hero, empty-state and marketing surfaces
+ *
+ * Steps are 8 · 12 · 16 · 24 · 32, alternating x1.5 and x1.33; 20px is
+ * skipped deliberately as the value that breaks that rhythm.
+ *
+ * Radius scales with padding and never exceeds it — at `xs` a 12px corner
+ * against 8px of padding visibly crowds the content. The header gap flattens
+ * at both ends instead of tracking padding: it separates a title from an
+ * action control, so it has a usability floor and nothing to gain above 16px.
+ *
+ * Type is deliberately absent from the ramp. Message's `size` carries
+ * `text-xs` because Message knows what it holds; Card is a container for
+ * arbitrary children, `Heading` and `Body` included, so setting type here
+ * would fight the typography ramp at every call site. Containers set
+ * spacing; content components set type.
+ */
+export declare const cardVariants: (props?: ({
+    size?: "xs" | "sm" | "md" | "lg" | "xl" | null | undefined;
+    interactive?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export type CardSize = NonNullable<VariantProps<typeof cardVariants>["size"]>;
+export type CardProps = Omit<React.HTMLAttributes<HTMLDivElement>, "title"> & Pick<VariantProps<typeof cardVariants>, "size"> & {
     /** Optional header title - string or ReactNode */
     title?: React.ReactNode;
     /** Optional action element displayed on the right side of the header */
@@ -8,7 +47,11 @@ export type CardProps = Omit<React.HTMLAttributes<HTMLDivElement>, "title"> & {
 /**
  * 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.
+ * optional header row when `title` and/or `headerAction` is passed.
+ *
+ * `size` is a density axis covering padding, header spacing and corner
+ * radius; `md` (16px) is the default. See `cardVariants` above for what each
+ * step is for and why type is not part of it.
  *
  * Passing `onClick` turns the whole card into a button: it gets
  * `role="button"`, `tabIndex={0}`, and both Enter and Space activate it, not
@@ -18,7 +61,10 @@ export type CardProps = Omit<React.HTMLAttributes<HTMLDivElement>, "title"> & {
  * the same seam Button and Badge use — so a consumer can re-point them
  * without a release.
  */
-export declare const Card: React.ForwardRefExoticComponent<Omit<React.HTMLAttributes<HTMLDivElement>, "title"> & {
+export declare const Card: React.ForwardRefExoticComponent<Omit<React.HTMLAttributes<HTMLDivElement>, "title"> & Pick<VariantProps<(props?: ({
+    size?: "xs" | "sm" | "md" | "lg" | "xl" | null | undefined;
+    interactive?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string>, "size"> & {
     /** Optional header title - string or ReactNode */
     title?: React.ReactNode;
     /** Optional action element displayed on the right side of the header */

package/dist/components/Card/Card.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Card.d.ts","sourceRoot":"","sources":["../../../src/components/Card/Card.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC,GAAG;IAC5E,kDAAkD;IAClD,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACxB,wEAAwE;IACxE,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAChC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,IAAI;IAnBf,kDAAkD;YAC1C,KAAK,CAAC,SAAS;IACvB,wEAAwE;mBACzD,KAAK,CAAC,SAAS;wCAmD9B,CAAC"}
+{"version":3,"file":"Card.d.ts","sourceRoot":"","sources":["../../../src/components/Card/Card.tsx"],"names":[],"mappings":"AACA,OAAO,EAAO,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,YAAY;;;8EAwBxB,CAAC;AA0BF,MAAM,MAAM,QAAQ,GAAG,WAAW,CAAC,YAAY,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;AAE9E,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC,GACzE,IAAI,CAAC,YAAY,CAAC,OAAO,YAAY,CAAC,EAAE,MAAM,CAAC,GAAG;IAChD,kDAAkD;IAClD,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACxB,wEAAwE;IACxE,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAChC,CAAC;AAEJ;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,IAAI;;;;IAvBb,kDAAkD;YAC1C,KAAK,CAAC,SAAS;IACvB,wEAAwE;mBACzD,KAAK,CAAC,SAAS;wCAkDhC,CAAC"}

package/dist/components/Card/Card.js

@@ -1,10 +1,94 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cn } from "@sixthshift/design-system/utils";
+import { cva } from "class-variance-authority";
 import * as React from "react";
+/**
+ * Geometry only, plus the five `--card-*` component tokens.
+ *
+ * Every colour reads a `--card-*` token whose value is decided by
+ * src/theme/recipes/card.css. `size` stays here: it is pure geometry
+ * (padding, header gap, corner radius), not colour, so it has no reason to
+ * move — the same split Message.tsx documents.
+ *
+ * The ramp is a density axis, not a padding setting. `md` is the middle and
+ * the default at 16px, which is also where MUI's `CardContent` and
+ * Bootstrap's `.card-body` sit; two steps exist below it for surfaces that
+ * repeat dozens of times, and two above for surfaces that are the page.
+ *
+ *   xs  8px   dense data — table-row cards, compact tiles, many at once
+ *   sm  12px  list rows and secondary cards; a line or two of content
+ *   md  16px  a standalone content card. The one to reach for by default
+ *   lg  24px  primary or feature cards — a main panel, a form container
+ *   xl  32px  hero, empty-state and marketing surfaces
+ *
+ * Steps are 8 · 12 · 16 · 24 · 32, alternating x1.5 and x1.33; 20px is
+ * skipped deliberately as the value that breaks that rhythm.
+ *
+ * Radius scales with padding and never exceeds it — at `xs` a 12px corner
+ * against 8px of padding visibly crowds the content. The header gap flattens
+ * at both ends instead of tracking padding: it separates a title from an
+ * action control, so it has a usability floor and nothing to gain above 16px.
+ *
+ * Type is deliberately absent from the ramp. Message's `size` carries
+ * `text-xs` because Message knows what it holds; Card is a container for
+ * arbitrary children, `Heading` and `Body` included, so setting type here
+ * would fight the typography ramp at every call site. Containers set
+ * spacing; content components set type.
+ */
+export const cardVariants = 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.
+"card border-(color:--card-border) border bg-(--card-bg) text-(--card-fg) shadow", {
+    variants: {
+        size: {
+            xs: "rounded-md p-2",
+            sm: "rounded-lg p-3",
+            md: "rounded-xl p-4",
+            lg: "rounded-xl p-6",
+            xl: "rounded-2xl p-8",
+        },
+        interactive: {
+            true: "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",
+            false: "",
+        },
+    },
+    defaultVariants: {
+        size: "md",
+        interactive: false,
+    },
+});
+/**
+ * Header geometry per size: the gap between title and action, and the space
+ * below it.
+ *
+ * A `<div>`, not a `<header>`. A `<header>` whose nearest sectioning ancestor
+ * is the body becomes a `banner` landmark, so two titled cards on one page
+ * produced two banners — axe's `landmark-no-duplicate-banner`. A card's header
+ * is not the page's banner, and the element bought nothing else here.
+ */
+const headerVariants = cva("flex items-start justify-between", {
+    variants: {
+        size: {
+            xs: "mb-2 gap-2",
+            sm: "mb-3 gap-2",
+            md: "mb-4 gap-3",
+            lg: "mb-4 gap-4",
+            xl: "mb-6 gap-4",
+        },
+    },
+    defaultVariants: {
+        size: "md",
+    },
+});
 /**
  * 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.
+ * optional header row when `title` and/or `headerAction` is passed.
+ *
+ * `size` is a density axis covering padding, header spacing and corner
+ * radius; `md` (16px) is the default. See `cardVariants` above for what each
+ * step is for and why type is not part of it.
  *
  * Passing `onClick` turns the whole card into a button: it gets
  * `role="button"`, `tabIndex={0}`, and both Enter and Space activate it, not
@@ -14,7 +98,7 @@ import * as React from "react";
  * the same seam Button and Badge use — so a consumer can re-point them
  * without a release.
  */
-export const Card = React.forwardRef(({ className, title, headerAction, children, onClick, onKeyDown, ...props }, ref) => {
+export const Card = React.forwardRef(({ className, size, title, headerAction, children, onClick, onKeyDown, ...props }, ref) => {
     const isInteractive = !!onClick;
     const handleKeyDown = (e) => {
         if (isInteractive && (e.key === "Enter" || e.key === " ")) {
@@ -25,8 +109,7 @@ export const Card = React.forwardRef(({ className, title, headerAction, children
     };
     return (
     // biome-ignore lint/a11y/noStaticElementInteractions: role="button" + tabIndex are added dynamically when onClick is present
-    _jsxs("div", { ref: ref, className: cn("card border-(color:--card-border) rounded-xl border bg-(--card-bg) p-6 text-(--card-fg) shadow", isInteractive &&
-            "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, onKeyDown: handleKeyDown, ...(isInteractive && { role: "button", tabIndex: 0 }), ...props, children: [(title || headerAction) && (_jsxs("header", { className: "mb-4 flex items-start justify-between gap-4", children: [title && _jsx("div", { className: "font-semibold", children: title }), headerAction && _jsx("div", { className: "shrink-0", children: headerAction })] })), children] }));
+    _jsxs("div", { ref: ref, className: cn(cardVariants({ size, interactive: isInteractive }), className), onClick: onClick, onKeyDown: handleKeyDown, ...(isInteractive && { role: "button", tabIndex: 0 }), ...props, children: [(title || headerAction) && (_jsxs("div", { className: headerVariants({ size }), children: [title && _jsx("div", { className: "font-semibold", children: title }), headerAction && _jsx("div", { className: "shrink-0", children: headerAction })] })), children] }));
 });
 Card.displayName = "Card";
 //# sourceMappingURL=Card.js.map

package/dist/components/Card/Card.js.map

@@ -1 +1 @@
-{"version":3,"file":"Card.js","sourceRoot":"","sources":["../../../src/components/Card/Card.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,iCAAiC,CAAC;AACrD,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAS/B;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,KAAK,CAAC,UAAU,CAA4B,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,GAAG,EAAE,EAAE;IAClJ,MAAM,aAAa,GAAG,CAAC,CAAC,OAAO,CAAC;IAEhC,MAAM,aAAa,GAAG,CAAC,CAAsC,EAAE,EAAE;QAC/D,IAAI,aAAa,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,OAAO,IAAI,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,EAAE,CAAC;YAC1D,CAAC,CAAC,cAAc,EAAE,CAAC;YACnB,OAAO,EAAE,CAAC,CAAgD,CAAC,CAAC;QAC9D,CAAC;QACD,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC;IACjB,CAAC,CAAC;IAEF,OAAO;IACL,6HAA6H;IAC7H,eACE,GAAG,EAAE,GAAG,EACR,SAAS,EAAE,EAAE,CACX,gGAAgG,EAChG,aAAa;YACX,8KAA8K,EAChL,SAAS,CACV,EACD,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,aAAa,KACpB,CAAC,aAAa,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,KAClD,KAAK,aAER,CAAC,KAAK,IAAI,YAAY,CAAC,IAAI,CAC1B,kBAAQ,SAAS,EAAC,6CAA6C,aAC5D,KAAK,IAAI,cAAK,SAAS,EAAC,eAAe,YAAE,KAAK,GAAO,EACrD,YAAY,IAAI,cAAK,SAAS,EAAC,UAAU,YAAE,YAAY,GAAO,IACxD,CACV,EACA,QAAQ,IACL,CACP,CAAC;AACJ,CAAC,CAAC,CAAC;AACH,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC"}
+{"version":3,"file":"Card.js","sourceRoot":"","sources":["../../../src/components/Card/Card.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,iCAAiC,CAAC;AACrD,OAAO,EAAE,GAAG,EAAqB,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG;AAC7B,6EAA6E;AAC7E,6EAA6E;AAC7E,4EAA4E;AAC5E,iFAAiF,EACjF;IACE,QAAQ,EAAE;QACR,IAAI,EAAE;YACJ,EAAE,EAAE,gBAAgB;YACpB,EAAE,EAAE,gBAAgB;YACpB,EAAE,EAAE,gBAAgB;YACpB,EAAE,EAAE,gBAAgB;YACpB,EAAE,EAAE,iBAAiB;SACtB;QACD,WAAW,EAAE;YACX,IAAI,EAAE,8KAA8K;YACpL,KAAK,EAAE,EAAE;SACV;KACF;IACD,eAAe,EAAE;QACf,IAAI,EAAE,IAAI;QACV,WAAW,EAAE,KAAK;KACnB;CACF,CACF,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,cAAc,GAAG,GAAG,CAAC,kCAAkC,EAAE;IAC7D,QAAQ,EAAE;QACR,IAAI,EAAE;YACJ,EAAE,EAAE,YAAY;YAChB,EAAE,EAAE,YAAY;YAChB,EAAE,EAAE,YAAY;YAChB,EAAE,EAAE,YAAY;YAChB,EAAE,EAAE,YAAY;SACjB;KACF;IACD,eAAe,EAAE;QACf,IAAI,EAAE,IAAI;KACX;CACF,CAAC,CAAC;AAYH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,KAAK,CAAC,UAAU,CAA4B,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,GAAG,EAAE,EAAE;IACxJ,MAAM,aAAa,GAAG,CAAC,CAAC,OAAO,CAAC;IAEhC,MAAM,aAAa,GAAG,CAAC,CAAsC,EAAE,EAAE;QAC/D,IAAI,aAAa,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,OAAO,IAAI,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,EAAE,CAAC;YAC1D,CAAC,CAAC,cAAc,EAAE,CAAC;YACnB,OAAO,EAAE,CAAC,CAAgD,CAAC,CAAC;QAC9D,CAAC;QACD,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC;IACjB,CAAC,CAAC;IAEF,OAAO;IACL,6HAA6H;IAC7H,eACE,GAAG,EAAE,GAAG,EACR,SAAS,EAAE,EAAE,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,aAAa,EAAE,CAAC,EAAE,SAAS,CAAC,EAC5E,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,aAAa,KACpB,CAAC,aAAa,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,KAClD,KAAK,aAER,CAAC,KAAK,IAAI,YAAY,CAAC,IAAI,CAC1B,eAAK,SAAS,EAAE,cAAc,CAAC,EAAE,IAAI,EAAE,CAAC,aACrC,KAAK,IAAI,cAAK,SAAS,EAAC,eAAe,YAAE,KAAK,GAAO,EACrD,YAAY,IAAI,cAAK,SAAS,EAAC,UAAU,YAAE,YAAY,GAAO,IAC3D,CACP,EACA,QAAQ,IACL,CACP,CAAC;AACJ,CAAC,CAAC,CAAC;AACH,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC"}

package/dist/components/Card/index.d.ts

@@ -1,2 +1,2 @@
-export { Card, type CardProps } from "./Card.js";
+export { Card, type CardProps, type CardSize, cardVariants } from "./Card.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/components/Card/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/Card/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,KAAK,SAAS,EAAE,MAAM,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/Card/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,KAAK,SAAS,EAAE,KAAK,QAAQ,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC"}

package/dist/components/Card/index.js

@@ -1,2 +1,2 @@
-export { Card } from "./Card.js";
+export { Card, cardVariants } from "./Card.js";
 //# sourceMappingURL=index.js.map

package/dist/components/Card/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/components/Card/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAkB,MAAM,QAAQ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/components/Card/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAiC,YAAY,EAAE,MAAM,QAAQ,CAAC"}

package/dist/lib/contexts/OverlayContext/OverlayContext.d.ts

@@ -14,9 +14,9 @@ type OverlayStackItem = StackItem & {
     onClose?: (() => void) | undefined;
 };
 type OverlayContextType = {
-    modalRoot: FloatingPortalProps["root"];
+    modalRoot?: FloatingPortalProps["root"];
     modalStack: ReturnType<typeof useStack<OverlayStackItem>>;
-    toastRoot: FloatingPortalProps["root"];
+    toastRoot?: FloatingPortalProps["root"];
     toastStack: ReturnType<typeof useStack<OverlayStackItem>>;
 };
 export declare const useOverlayContext: () => OverlayContextType;

package/dist/lib/contexts/OverlayContext/OverlayContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OverlayContext.d.ts","sourceRoot":"","sources":["../../../../src/lib/contexts/OverlayContext/OverlayContext.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,KAAK,SAAS,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAC3E,OAAO,EAAiB,KAAK,iBAAiB,EAAE,KAAK,iBAAiB,EAAkC,MAAM,OAAO,CAAC;AAEtH,KAAK,mBAAmB,GAAG;IACzB,KAAK,CAAC,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAC;IACpC,KAAK,CAAC,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAC;CACrC,CAAC;AAEF,sEAAsE;AACtE,KAAK,gBAAgB,GAAG,SAAS,GAAG;IAElC,SAAS,EAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC;IAClC,qDAAqD;IACrD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,4CAA4C;IAC5C,OAAO,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;CACpC,CAAC;AAEF,KAAK,kBAAkB,GAAG;IACxB,SAAS,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAC;IACvC,UAAU,EAAE,UAAU,CAAC,OAAO,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAC1D,SAAS,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAC;IACvC,UAAU,EAAE,UAAU,CAAC,OAAO,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC;CAC3D,CAAC;AAGF,eAAO,MAAM,iBAAiB,0BAAmC,CAAC;AAElE,eAAO,MAAM,eAAe,qDAAsD,iBAAiB,CAAC,mBAAmB,CAAC,gCA+DvH,CAAC"}
+{"version":3,"file":"OverlayContext.d.ts","sourceRoot":"","sources":["../../../../src/lib/contexts/OverlayContext/OverlayContext.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,KAAK,SAAS,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAC3E,OAAO,EAAiB,KAAK,iBAAiB,EAAE,KAAK,iBAAiB,EAAkC,MAAM,OAAO,CAAC;AAEtH,KAAK,mBAAmB,GAAG;IACzB,KAAK,CAAC,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAC;IACpC,KAAK,CAAC,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAC;CACrC,CAAC;AAEF,sEAAsE;AACtE,KAAK,gBAAgB,GAAG,SAAS,GAAG;IAElC,SAAS,EAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC;IAClC,qDAAqD;IACrD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,4CAA4C;IAC5C,OAAO,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;CACpC,CAAC;AAEF,KAAK,kBAAkB,GAAG;IACxB,SAAS,CAAC,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAC;IACxC,UAAU,EAAE,UAAU,CAAC,OAAO,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAC1D,SAAS,CAAC,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAC;IACxC,UAAU,EAAE,UAAU,CAAC,OAAO,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC;CAC3D,CAAC;AAWF,eAAO,MAAM,iBAAiB,0BAAmC,CAAC;AAElE,eAAO,MAAM,eAAe,qDAAsD,iBAAiB,CAAC,mBAAmB,CAAC,gCAkEvH,CAAC"}

package/dist/lib/contexts/OverlayContext/OverlayContext.js

@@ -2,11 +2,22 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { FloatingPortal } from "@floating-ui/react";
 import { useStack } from "@sixthshift/design-system/hooks";
 import { createContext, useContext, useEffect, useMemo } from "react";
+/**
+ * `root` omitted when the caller gave none, rather than passed as `undefined`
+ * or `null`. The distinction is load-bearing: `FloatingPortal` bails out of
+ * creating its portal node entirely on an explicit `null` ("wait for the root
+ * to exist"), and only a missing `root` falls through to `document.body`.
+ */
+const rootProp = (root) => (root === undefined ? {} : { root });
 const OverlayContext = createContext(undefined);
 export const useOverlayContext = () => useContext(OverlayContext);
 export const OverlayProvider = ({ modal: modalRoot, toast: toastRoot, children }) => {
-    const resolvedModalRoot = modalRoot ?? document.body;
-    const resolvedToastRoot = toastRoot ?? document.body;
+    // The roots pass through unresolved, deliberately. Defaulting them to
+    // `document.body` here read the DOM during render, which threw the whole
+    // tree under SSR — and it bought nothing: `FloatingPortal` already falls
+    // back to `document.body` when no `root` is given, on the client, where a
+    // body exists. Both portals below are behind a non-empty stack, and both
+    // stacks start empty, so nothing portals on the server either way.
     const modalStack = useStack([]);
     const toastStack = useStack([]);
     const [modals] = modalStack;
@@ -26,11 +37,11 @@ export const OverlayProvider = ({ modal: modalRoot, toast: toastRoot, children }
     }, [modals]);
     // Memoize context value to prevent unnecessary re-renders in consumers
     const contextValue = useMemo(() => ({
-        modalRoot: resolvedModalRoot,
+        modalRoot,
         modalStack,
-        toastRoot: resolvedToastRoot,
+        toastRoot,
         toastStack,
-    }), [resolvedModalRoot, modalStack, resolvedToastRoot, toastStack]);
-    return (_jsxs(OverlayContext.Provider, { value: contextValue, children: [children, modals.length > 0 && (_jsx(FloatingPortal, { root: resolvedModalRoot, children: modals.map(({ id, component: Component, data }) => (_jsx(Component, { data: data }, id))) })), toasts.length > 0 && (_jsx(FloatingPortal, { root: resolvedToastRoot, children: _jsx("div", { className: "pointer-events-none fixed bottom-6 left-1/2 z-toast flex -translate-x-1/2 flex-col-reverse items-center gap-3", children: toasts.map(({ id, component: Component, onClose, ...props }) => (_jsx("div", { className: "pointer-events-auto", children: _jsx(Component, { onClose: onClose, ...props }) }, id))) }) }))] }));
+    }), [modalRoot, modalStack, toastRoot, toastStack]);
+    return (_jsxs(OverlayContext.Provider, { value: contextValue, children: [children, modals.length > 0 && (_jsx(FloatingPortal, { ...rootProp(modalRoot), children: modals.map(({ id, component: Component, data }) => (_jsx(Component, { data: data }, id))) })), toasts.length > 0 && (_jsx(FloatingPortal, { ...rootProp(toastRoot), children: _jsx("div", { className: "pointer-events-none fixed bottom-6 left-1/2 z-toast flex -translate-x-1/2 flex-col-reverse items-center gap-3", children: toasts.map(({ id, component: Component, onClose, ...props }) => (_jsx("div", { className: "pointer-events-auto", children: _jsx(Component, { onClose: onClose, ...props }) }, id))) }) }))] }));
 };
 //# sourceMappingURL=OverlayContext.js.map

package/dist/lib/contexts/OverlayContext/OverlayContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"OverlayContext.js","sourceRoot":"","sources":["../../../../src/lib/contexts/OverlayContext/OverlayContext.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,cAAc,EAA4B,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAkB,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAkD,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAwBtH,MAAM,cAAc,GAAG,aAAa,CAAqB,SAA0C,CAAC,CAAC;AACrG,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,EAAE,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AAElE,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAA0C,EAAE,EAAE;IAC1H,MAAM,iBAAiB,GAAG,SAAS,IAAI,QAAQ,CAAC,IAAI,CAAC;IACrD,MAAM,iBAAiB,GAAG,SAAS,IAAI,QAAQ,CAAC,IAAI,CAAC;IAErD,MAAM,UAAU,GAAG,QAAQ,CAAmB,EAAE,CAAC,CAAC;IAClD,MAAM,UAAU,GAAG,QAAQ,CAAmB,EAAE,CAAC,CAAC;IAElD,MAAM,CAAC,MAAM,CAAC,GAAG,UAAU,CAAC;IAC5B,MAAM,CAAC,MAAM,CAAC,GAAG,UAAU,CAAC;IAE5B,mDAAmD;IACnD,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAEhC,MAAM,YAAY,GAAG,CAAC,KAAoB,EAAE,EAAE;YAC5C,IAAI,KAAK,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;gBAC3B,MAAM,QAAQ,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC/B,QAAQ,EAAE,OAAO,EAAE,EAAE,CAAC;YACxB,CAAC;QACH,CAAC,CAAC;QAEF,QAAQ,CAAC,gBAAgB,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;QACnD,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,mBAAmB,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IACrE,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAEb,uEAAuE;IACvE,MAAM,YAAY,GAAG,OAAO,CAC1B,GAAG,EAAE,CAAC,CAAC;QACL,SAAS,EAAE,iBAAiB;QAC5B,UAAU;QACV,SAAS,EAAE,iBAAiB;QAC5B,UAAU;KACX,CAAC,EACF,CAAC,iBAAiB,EAAE,UAAU,EAAE,iBAAiB,EAAE,UAAU,CAAC,CAC/D,CAAC;IAEF,OAAO,CACL,MAAC,cAAc,CAAC,QAAQ,IAAC,KAAK,EAAE,YAAY,aACzC,QAAQ,EAGR,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,CACpB,KAAC,cAAc,IAAC,IAAI,EAAE,iBAAiB,YACpC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAClD,KAAC,SAAS,IAAU,IAAI,EAAE,IAAI,IAAd,EAAE,CAAgB,CACnC,CAAC,GACa,CAClB,EAGA,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,CACpB,KAAC,cAAc,IAAC,IAAI,EAAE,iBAAiB,YACrC,cAAK,SAAS,EAAC,+GAA+G,YAC3H,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,KAAK,EAAE,EAAE,EAAE,CAAC,CAC/D,cAAc,SAAS,EAAC,qBAAqB,YAC3C,KAAC,SAAS,IAAC,OAAO,EAAE,OAAO,KAAM,KAAK,GAAI,IADlC,EAAE,CAEN,CACP,CAAC,GACE,GACS,CAClB,IACuB,CAC3B,CAAC;AACJ,CAAC,CAAC"}
+{"version":3,"file":"OverlayContext.js","sourceRoot":"","sources":["../../../../src/lib/contexts/OverlayContext/OverlayContext.tsx"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sixthshift/design-system",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Personal design system - tokens, theme, and component library",
   "license": "MIT",
   "publishConfig": {
@@ -322,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",

package/src/components/Card/Card.tsx

@@ -1,17 +1,108 @@
 import { cn } from "@sixthshift/design-system/utils";
+import { cva, type VariantProps } from "class-variance-authority";
 import * as React from "react";
 
-export type CardProps = Omit<React.HTMLAttributes<HTMLDivElement>, "title"> & {
-  /** Optional header title - string or ReactNode */
-  title?: React.ReactNode;
-  /** Optional action element displayed on the right side of the header */
-  headerAction?: React.ReactNode;
-};
+/**
+ * Geometry only, plus the five `--card-*` component tokens.
+ *
+ * Every colour reads a `--card-*` token whose value is decided by
+ * src/theme/recipes/card.css. `size` stays here: it is pure geometry
+ * (padding, header gap, corner radius), not colour, so it has no reason to
+ * move — the same split Message.tsx documents.
+ *
+ * The ramp is a density axis, not a padding setting. `md` is the middle and
+ * the default at 16px, which is also where MUI's `CardContent` and
+ * Bootstrap's `.card-body` sit; two steps exist below it for surfaces that
+ * repeat dozens of times, and two above for surfaces that are the page.
+ *
+ *   xs  8px   dense data — table-row cards, compact tiles, many at once
+ *   sm  12px  list rows and secondary cards; a line or two of content
+ *   md  16px  a standalone content card. The one to reach for by default
+ *   lg  24px  primary or feature cards — a main panel, a form container
+ *   xl  32px  hero, empty-state and marketing surfaces
+ *
+ * Steps are 8 · 12 · 16 · 24 · 32, alternating x1.5 and x1.33; 20px is
+ * skipped deliberately as the value that breaks that rhythm.
+ *
+ * Radius scales with padding and never exceeds it — at `xs` a 12px corner
+ * against 8px of padding visibly crowds the content. The header gap flattens
+ * at both ends instead of tracking padding: it separates a title from an
+ * action control, so it has a usability floor and nothing to gain above 16px.
+ *
+ * Type is deliberately absent from the ramp. Message's `size` carries
+ * `text-xs` because Message knows what it holds; Card is a container for
+ * arbitrary children, `Heading` and `Body` included, so setting type here
+ * would fight the typography ramp at every call site. Containers set
+ * spacing; content components set type.
+ */
+export const cardVariants = 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.
+  "card border-(color:--card-border) border bg-(--card-bg) text-(--card-fg) shadow",
+  {
+    variants: {
+      size: {
+        xs: "rounded-md p-2",
+        sm: "rounded-lg p-3",
+        md: "rounded-xl p-4",
+        lg: "rounded-xl p-6",
+        xl: "rounded-2xl p-8",
+      },
+      interactive: {
+        true: "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",
+        false: "",
+      },
+    },
+    defaultVariants: {
+      size: "md",
+      interactive: false,
+    },
+  }
+);
+
+/**
+ * Header geometry per size: the gap between title and action, and the space
+ * below it.
+ *
+ * A `<div>`, not a `<header>`. A `<header>` whose nearest sectioning ancestor
+ * is the body becomes a `banner` landmark, so two titled cards on one page
+ * produced two banners — axe's `landmark-no-duplicate-banner`. A card's header
+ * is not the page's banner, and the element bought nothing else here.
+ */
+const headerVariants = cva("flex items-start justify-between", {
+  variants: {
+    size: {
+      xs: "mb-2 gap-2",
+      sm: "mb-3 gap-2",
+      md: "mb-4 gap-3",
+      lg: "mb-4 gap-4",
+      xl: "mb-6 gap-4",
+    },
+  },
+  defaultVariants: {
+    size: "md",
+  },
+});
+
+export type CardSize = NonNullable<VariantProps<typeof cardVariants>["size"]>;
+
+export type CardProps = Omit<React.HTMLAttributes<HTMLDivElement>, "title"> &
+  Pick<VariantProps<typeof cardVariants>, "size"> & {
+    /** Optional header title - string or ReactNode */
+    title?: React.ReactNode;
+    /** Optional action element displayed on the right side of the header */
+    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.
+ * optional header row when `title` and/or `headerAction` is passed.
+ *
+ * `size` is a density axis covering padding, header spacing and corner
+ * radius; `md` (16px) is the default. See `cardVariants` above for what each
+ * step is for and why type is not part of it.
  *
  * Passing `onClick` turns the whole card into a button: it gets
  * `role="button"`, `tabIndex={0}`, and both Enter and Space activate it, not
@@ -21,7 +112,7 @@ export type CardProps = Omit<React.HTMLAttributes<HTMLDivElement>, "title"> & {
  * 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) => {
+export const Card = React.forwardRef<HTMLDivElement, CardProps>(({ className, size, title, headerAction, children, onClick, onKeyDown, ...props }, ref) => {
   const isInteractive = !!onClick;
 
   const handleKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
@@ -36,22 +127,17 @@ export const Card = React.forwardRef<HTMLDivElement, CardProps>(({ className, ti
     // biome-ignore lint/a11y/noStaticElementInteractions: role="button" + tabIndex are added dynamically when onClick is present
     <div
       ref={ref}
-      className={cn(
-        "card border-(color:--card-border) rounded-xl border bg-(--card-bg) p-6 text-(--card-fg) shadow",
-        isInteractive &&
-          "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
-      )}
+      className={cn(cardVariants({ size, interactive: isInteractive }), className)}
       onClick={onClick}
       onKeyDown={handleKeyDown}
       {...(isInteractive && { role: "button", tabIndex: 0 })}
       {...props}
     >
       {(title || headerAction) && (
-        <header className="mb-4 flex items-start justify-between gap-4">
+        <div className={headerVariants({ size })}>
           {title && <div className="font-semibold">{title}</div>}
           {headerAction && <div className="shrink-0">{headerAction}</div>}
-        </header>
+        </div>
       )}
       {children}
     </div>

package/src/components/Card/index.ts

@@ -1 +1 @@
-export { Card, type CardProps } from "./Card";
+export { Card, type CardProps, type CardSize, cardVariants } from "./Card";

package/src/lib/contexts/OverlayContext/OverlayContext.tsx

@@ -18,19 +18,30 @@ type OverlayStackItem = StackItem & {
 };
 
 type OverlayContextType = {
-  modalRoot: FloatingPortalProps["root"];
+  modalRoot?: FloatingPortalProps["root"];
   modalStack: ReturnType<typeof useStack<OverlayStackItem>>;
-  toastRoot: FloatingPortalProps["root"];
+  toastRoot?: FloatingPortalProps["root"];
   toastStack: ReturnType<typeof useStack<OverlayStackItem>>;
 };
 
+/**
+ * `root` omitted when the caller gave none, rather than passed as `undefined`
+ * or `null`. The distinction is load-bearing: `FloatingPortal` bails out of
+ * creating its portal node entirely on an explicit `null` ("wait for the root
+ * to exist"), and only a missing `root` falls through to `document.body`.
+ */
+const rootProp = (root: FloatingPortalProps["root"] | undefined) => (root === undefined ? {} : { root });
+
 const OverlayContext = createContext<OverlayContextType>(undefined as unknown as OverlayContextType);
 export const useOverlayContext = () => useContext(OverlayContext);
 
 export const OverlayProvider = ({ modal: modalRoot, toast: toastRoot, children }: PropsWithChildren<OverlayContextProps>) => {
-  const resolvedModalRoot = modalRoot ?? document.body;
-  const resolvedToastRoot = toastRoot ?? document.body;
-
+  // The roots pass through unresolved, deliberately. Defaulting them to
+  // `document.body` here read the DOM during render, which threw the whole
+  // tree under SSR — and it bought nothing: `FloatingPortal` already falls
+  // back to `document.body` when no `root` is given, on the client, where a
+  // body exists. Both portals below are behind a non-empty stack, and both
+  // stacks start empty, so nothing portals on the server either way.
   const modalStack = useStack<OverlayStackItem>([]);
   const toastStack = useStack<OverlayStackItem>([]);
 
@@ -55,12 +66,12 @@ export const OverlayProvider = ({ modal: modalRoot, toast: toastRoot, children }
   // Memoize context value to prevent unnecessary re-renders in consumers
   const contextValue = useMemo(
     () => ({
-      modalRoot: resolvedModalRoot,
+      modalRoot,
       modalStack,
-      toastRoot: resolvedToastRoot,
+      toastRoot,
       toastStack,
     }),
-    [resolvedModalRoot, modalStack, resolvedToastRoot, toastStack]
+    [modalRoot, modalStack, toastRoot, toastStack]
   );
 
   return (
@@ -69,7 +80,7 @@ export const OverlayProvider = ({ modal: modalRoot, toast: toastRoot, children }
 
       {/* Modal stack - rendered in portal */}
       {modals.length > 0 && (
-        <FloatingPortal root={resolvedModalRoot}>
+        <FloatingPortal {...rootProp(modalRoot)}>
           {modals.map(({ id, component: Component, data }) => (
             <Component key={id} data={data} />
           ))}
@@ -78,7 +89,7 @@ export const OverlayProvider = ({ modal: modalRoot, toast: toastRoot, children }
 
       {/* Toast stack - rendered in portal */}
       {toasts.length > 0 && (
-        <FloatingPortal root={resolvedToastRoot}>
+        <FloatingPortal {...rootProp(toastRoot)}>
           <div className="pointer-events-none fixed bottom-6 left-1/2 z-toast flex -translate-x-1/2 flex-col-reverse items-center gap-3">
             {toasts.map(({ id, component: Component, onClose, ...props }) => (
               <div key={id} className="pointer-events-auto">

package/src/theme/recipes/card.css

@@ -1,11 +1,16 @@
 /**
  * Card recipe — the component-token layer for Card.
  *
- * Card has no variant/intent axis — every instance uses the same fixed
+ * Card has no colour-bearing variant — every instance uses the same fixed
  * semantic tokens the old plain class string named directly. This file just
  * gives those tokens a name, so a consumer can re-point a cell or scope a
  * change to a subtree without a release.
  *
+ * Card's `size` axis is pure geometry (padding, header gap, radius) and stays
+ * in Card.tsx's `cva` call; nothing here concerns it. Same split as
+ * message.css — this layer is colour, and a consumer wanting a different
+ * spacing rhythm re-points Tailwind's `--spacing`, not a token here.
+ *
  * The grammar is `--card-{context}[-{state}]`, context in {bg, fg, border,
  * ring} — the same words the semantic layer uses. `--card-ring` backs the
  * `outline-*` utilities on the interactive (clickable) variant: it plays the