@designtools/docs 0.1.0 → 0.2.1

package/src/swatches.tsx

@@ -1,17 +1,19 @@
 "use client";
 
-import { useEffect, useRef, useState } from "react";
+import { Check, Square, X } from "lucide-react";
+import { type CSSProperties, type ReactNode, useEffect, useRef, useState } from "react";
 import { contrastRatio, wcagGrade } from "./lib/contrast";
 import { cx } from "./lib/cx";
 import { ramps, semanticColours, valueIn, type Mode } from "./lib/manifest";
 import type { TokensManifest } from "./lib/manifest-types";
 
 /**
- * Colour, painted from the tokens rather than restated. Each colour with a
- * subdued pair is a card: its fill, subdued, hover and press, in light and dark
- * side by side. Then the surfaces, then the utility colours. Every sample sits
- * inside its own `data-theme`, so dark is shown as the dark tokens resolve, and
- * every pair's contrast is measured on the colours the browser actually paints.
+ * Colour, painted from the tokens rather than restated. No panels and no cards around the samples:
+ * each sample is its own colour, with one hairline round it, set on the page in a light and a dark
+ * column. Each colour with a subdued pair shows its fill large, then subdued, hover and press; then
+ * the surfaces and the utility colours, one row each. Every sample sits inside its own `data-theme`,
+ * so dark is shown as the dark tokens resolve, and every pair's contrast is measured on the colours
+ * the browser actually paints.
  */
 export function SemanticSwatches({
   tokens,
@@ -30,78 +32,111 @@ export function SemanticSwatches({
     const token = byName.get(name)?.background;
     return token && pointsAt(valueIn(token, mode));
   };
+  const columns = cx("grid gap-x-8 gap-y-6", modes.length > 1 && "md:grid-cols-2");
+  const modeLabel = (mode: Mode) => <p className="text-xs font-medium text-muted-foreground capitalize">{mode}</p>;
+  const title = (text: string) => text.charAt(0).toUpperCase() + text.slice(1);
 
   return (
-    <div data-slot="swatches" className="flex flex-col gap-10">
-      <div className="grid gap-4 xl:grid-cols-2">
+    <div data-slot="swatches" className="flex flex-col gap-16">
+      <div className="flex flex-col gap-14">
         {families.map((f) => (
-          <article key={f} data-slot="swatch-family" className="flex flex-col overflow-hidden rounded-xl border border-border bg-surface text-surface-foreground">
-            <header className="flex items-baseline justify-between gap-3 px-4 py-3">
-              <h3 className="text-lg capitalize">{f.slice(2).replace(/-/g, " ")}</h3>
+          <section key={f} data-slot="swatch-family" className="flex flex-col gap-5">
+            <header className="flex items-baseline gap-3">
+              <h3 className="text-2xl leading-tight tracking-tight">{title(f.slice(2).replace(/-/g, " "))}</h3>
               <code className="font-mono text-xs text-muted-foreground">{f}</code>
             </header>
-            <div className={cx("grid border-t border-border", modes.length > 1 && "sm:grid-cols-2")}>
+            <div className={columns}>
               {modes.map((mode) => (
-                <div key={mode} data-theme={mode} className="flex flex-col gap-2 bg-canvas p-3 text-canvas-foreground not-first:border-t not-first:border-border sm:not-first:border-t-0 sm:not-first:border-l">
-                  <span className="text-xs font-medium text-muted-foreground capitalize">{mode}</span>
-                  <Chip name={f} label="fill" step={step(f, mode)} size="lg" />
-                  <div className="grid grid-cols-3 gap-2">
-                    <Chip name={`${f}-subdued`} label="subdued" step={step(`${f}-subdued`, mode)} />
-                    {byName.has(`${f}-hover`) && <Chip name={`${f}-hover`} foreground={`${f}-foreground`} label="hover" />}
-                    {byName.has(`${f}-active`) && <Chip name={`${f}-active`} foreground={`${f}-foreground`} label="press" />}
+                <div key={mode} className="flex flex-col gap-2.5">
+                  {modeLabel(mode)}
+                  {/* only the samples take the mode; the label is read on the page */}
+                  <div data-theme={mode} className="flex flex-col gap-2.5">
+                    <Chip name={f} label="fill" step={step(f, mode)} size="lg" />
+                    <div className="grid grid-cols-3 gap-2.5">
+                      <Chip name={`${f}-subdued`} label="subdued" step={step(`${f}-subdued`, mode)} />
+                      {byName.has(`${f}-hover`) && <Chip name={`${f}-hover`} foreground={`${f}-foreground`} label="hover" />}
+                      {byName.has(`${f}-active`) && <Chip name={`${f}-active`} foreground={`${f}-foreground`} label="press" />}
+                    </div>
                   </div>
                 </div>
               ))}
             </div>
-          </article>
+          </section>
         ))}
       </div>
 
       {surfaces.length > 0 && (
-        <div className="flex flex-col gap-3">
-          <h3 className="text-2xl tracking-tight">Surfaces</h3>
-          <div className={cx("grid gap-4", modes.length > 1 && "lg:grid-cols-2")}>
-            {modes.map((mode) => (
-              <div key={mode} data-theme={mode} className="flex flex-col gap-2 rounded-xl border border-border bg-canvas p-3 text-canvas-foreground">
-                <span className="text-xs font-medium text-muted-foreground capitalize">{mode}</span>
-                <div className="grid grid-cols-2 gap-2 sm:grid-cols-3">
-                  {surfaces.map((name) => (
-                    <Chip key={name} name={name} label={name.slice(2)} step={step(name, mode)} outlined />
-                  ))}
+        <Rows title="Surfaces" lead="The page, panels and popups, and the brand's own backgrounds, each with its text." modes={modes}>
+          {surfaces.map((name) => (
+            <Row key={name} name={name.slice(2)} modes={modes}>
+              {(mode) => (
+                <div data-theme={mode}>
+                  <Chip name={name} label={step(name, mode) ?? ""} size="wide" />
                 </div>
-              </div>
-            ))}
-          </div>
-        </div>
+              )}
+            </Row>
+          ))}
+        </Rows>
       )}
 
       {utility.length > 0 && (
-        <div className="flex flex-col gap-3">
-          <h3 className="text-2xl tracking-tight">Lines, focus and shadow</h3>
-          <div className={cx("grid gap-4", modes.length > 1 && "lg:grid-cols-2")}>
-            {modes.map((mode) => (
-              <div key={mode} data-theme={mode} className="flex flex-col gap-2 rounded-xl border border-border bg-canvas p-3 text-canvas-foreground">
-                <span className="text-xs font-medium text-muted-foreground capitalize">{mode}</span>
-                <ul className="grid grid-cols-2 gap-2">
-                  {utility.map((name) => (
-                    <li key={name} data-slot="swatch" className="flex items-center gap-2 rounded-lg bg-surface p-2 text-surface-foreground">
-                      <span aria-hidden className="size-8 shrink-0 rounded-md border border-border" style={{ background: `var(${name})` }} />
-                      <span className="flex min-w-0 flex-col font-mono text-xs">
-                        <span className="truncate font-medium">{name.slice(2)}</span>
-                        <span className="truncate text-muted-foreground">{step(name, mode)}</span>
-                      </span>
-                    </li>
-                  ))}
-                </ul>
-              </div>
-            ))}
-          </div>
-        </div>
+        <Rows title="Lines, focus and shadow" lead="Borders, input edges, the focus ring and the shadow colour." modes={modes}>
+          {utility.map((name) => (
+            <Row key={name} name={name.slice(2)} modes={modes}>
+              {(mode) => (
+                <span className="flex h-14 items-center gap-3">
+                  <span data-theme={mode} aria-hidden className="size-10 shrink-0 rounded-lg ring-1 ring-(--canvas-foreground)/15 ring-inset" style={{ background: `var(${name})` }} />
+                  <span className="font-mono text-xs text-muted-foreground">{step(name, mode)}</span>
+                </span>
+              )}
+            </Row>
+          ))}
+        </Rows>
       )}
     </div>
   );
 }
 
+/** A titled list of rows, with the mode names once over the columns. */
+function Rows({ title, lead, modes, children }: { title: string; lead: string; modes: Mode[]; children: ReactNode }) {
+  return (
+    <section className="flex flex-col gap-5">
+      <header className="flex flex-col gap-1.5">
+        <h3 className="text-2xl leading-tight tracking-tight">{title}</h3>
+        <p className="text-sm text-muted-foreground">{lead}</p>
+      </header>
+      <div>
+        <div aria-hidden className="hidden gap-x-8 pb-3 text-xs font-medium text-muted-foreground md:grid md:grid-cols-[9rem_repeat(var(--modes),minmax(0,1fr))]" style={{ "--modes": modes.length } as CSSProperties}>
+          <span />
+          {modes.map((m) => (
+            <span key={m} className="capitalize">
+              {m}
+            </span>
+          ))}
+        </div>
+        {children}
+      </div>
+    </section>
+  );
+}
+
+function Row({ name, modes, children }: { name: string; modes: Mode[]; children: (mode: Mode) => ReactNode }) {
+  return (
+    <div
+      className="grid items-center gap-x-8 gap-y-2 border-t border-border py-3 md:grid-cols-[9rem_repeat(var(--modes),minmax(0,1fr))]"
+      style={{ "--modes": modes.length } as CSSProperties}
+    >
+      <code className="font-mono text-sm">{name}</code>
+      {modes.map((mode) => (
+        <div key={mode} className="flex flex-col gap-1">
+          <span className="text-xs text-muted-foreground capitalize md:hidden">{mode}</span>
+          {children(mode)}
+        </div>
+      ))}
+    </div>
+  );
+}
+
 /** `var(--color-primary-500)` → `primary-500`: the step it points at, which is what a person compares. */
 function pointsAt(value: string | undefined): string | undefined {
   const m = value && /^var\(--color-([\w-]+)\)$/.exec(value);
@@ -110,9 +145,9 @@ function pointsAt(value: string | undefined): string | undefined {
 }
 
 /**
- * One background with its foreground on it, labelled in that foreground, with the
- * contrast measured on what the browser paints. It reads its mode from the nearest
- * `data-theme` around it.
+ * One background with its foreground on it, labelled in that foreground, with the contrast measured on
+ * what the browser paints. It reads its mode from the nearest `data-theme` around it. One hairline round
+ * it, so a white sample shows on a white page, and nothing else.
  */
 function Chip({
   name,
@@ -120,14 +155,12 @@ function Chip({
   label,
   step,
   size = "md",
-  outlined,
 }: {
   name: string;
   foreground?: string;
   label: string;
   step?: string;
-  size?: "md" | "lg";
-  outlined?: boolean;
+  size?: "md" | "lg" | "wide";
 }) {
   const chip = useRef<HTMLDivElement>(null);
   const [ratio, setRatio] = useState<number | null>(null);
@@ -140,40 +173,45 @@ function Chip({
   const grade = ratio === null ? null : wcagGrade(ratio);
   const fails = grade === "Fail";
   const measured = grade && ratio !== null ? `${ratio.toFixed(1)}:1 ${grade}` : undefined;
-  return (
-    <div
-      ref={chip}
-      data-slot="swatch"
-      title={`${name} with ${foreground}${step ? ` · ${step}` : ""}${measured ? ` · ${measured}` : ""}`}
-      className={cx("flex min-w-0 flex-col justify-between gap-3 rounded-lg p-3", size === "lg" ? "min-h-28" : "min-h-20", outlined && "border border-border")}
-      style={{ background: `var(${name})`, color: `var(${foreground})` }}
-    >
-      {size === "lg" ? (
-        <span className="flex items-start justify-between gap-2">
-          <span className="text-3xl leading-none tracking-tight">Aa</span>
-          {measured && (
-            <span
-              data-slot="swatch-contrast"
-              className={cx("rounded-full px-2 py-0.5 font-mono text-xs whitespace-nowrap", fails ? "bg-destructive font-medium text-destructive-foreground" : "ring-1 ring-current/30")}
-            >
-              {measured}
-            </span>
-          )}
+  const contrast = measured && (
+    <span data-slot="swatch-contrast" className={cx("font-mono text-xs whitespace-nowrap", fails ? "rounded-sm bg-destructive px-1.5 py-0.5 font-medium text-destructive-foreground" : "opacity-80")}>
+      {measured}
+    </span>
+  );
+  const paint = { background: `var(${name})`, color: `var(${foreground})` };
+  // a hairline in the sample's own text colour: it shows a white sample on a white page and disappears into a strong fill
+  const base = "min-w-0 rounded-xl ring-1 ring-current/15 ring-inset";
+  const tip = `${name} with ${foreground}${step ? ` · ${step}` : ""}${measured ? ` · ${measured}` : ""}`;
+
+  if (size === "wide")
+    return (
+      <div ref={chip} data-slot="swatch" title={tip} className={cx(base, "flex h-14 items-center justify-between gap-4 px-4")} style={paint}>
+        <span className="flex min-w-0 items-baseline gap-3">
+          <span className="text-xl leading-none font-medium">Aa</span>
+          <span className="font-mono text-xs opacity-80">{label}</span>
         </span>
-      ) : (
-        <span className="text-base leading-none font-medium">Aa</span>
-      )}
-      <span className="flex min-w-0 flex-col font-mono text-xs leading-snug">
-        <span className="truncate font-medium">{label}</span>
-        {size === "lg" ? (
-          step && <span className="truncate opacity-75">{step}</span>
-        ) : (
-          measured && (
-            <span data-slot="swatch-contrast" className={cx("truncate", fails ? "w-fit rounded-sm bg-destructive px-1 text-destructive-foreground" : "opacity-75")}>
-              {measured}
-            </span>
-          )
-        )}
+        {contrast}
+      </div>
+    );
+  if (size === "lg")
+    return (
+      <div ref={chip} data-slot="swatch" title={tip} className={cx(base, "flex min-h-36 flex-col justify-between gap-6 p-5")} style={paint}>
+        <span className="flex items-start justify-between gap-3">
+          <span className="text-5xl leading-none tracking-tight">Aa</span>
+          {contrast}
+        </span>
+        <span className="flex flex-col gap-0.5 text-sm leading-snug">
+          <span className="font-medium">{label}</span>
+          {step && <span className="font-mono text-xs opacity-80">{step}</span>}
+        </span>
+      </div>
+    );
+  return (
+    <div ref={chip} data-slot="swatch" title={tip} className={cx(base, "flex min-h-28 flex-col justify-between gap-4 p-4")} style={paint}>
+      <span className="text-2xl leading-none font-medium">Aa</span>
+      <span className="flex flex-col gap-1 leading-snug">
+        <span className="text-sm font-medium">{label}</span>
+        {contrast}
       </span>
     </div>
   );
@@ -183,7 +221,7 @@ function Chip({
  * Each colour on each background, per mode: a label is measured on its own fill, and this is
  * everything else, red text on the page, a brand fill on a dark section. Backgrounds are the
  * canvas, surface and overlay and every named `--surface-<name>`; colours are each semantic fill
- * and muted text. T: fine as text (4.5:1); S: fine as a shape only (3:1); none: neither.
+ * and muted text. Text: fine as text (4.5:1); shape: fine as a shape only (3:1); none: neither.
  * Measured on what the browser paints, inside each mode's `data-theme`.
  */
 export function PageContrast({ tokens, modes = ["light", "dark"] }: { tokens: TokensManifest; modes?: Mode[] }) {
@@ -191,7 +229,21 @@ export function PageContrast({ tokens, modes = ["light", "dark"] }: { tokens: To
   const colours = [...names].filter((n) => names.has(`${n}-subdued`)).concat(names.has("--muted") ? ["--muted-foreground"] : []);
   const grounds = ["--canvas", "--surface", "--overlay", ...[...names].filter((n) => n.startsWith("--surface-") && !n.endsWith("-foreground") && n !== "--surface-foreground")];
   return (
-    <div data-slot="page-contrast" className="flex flex-col gap-6">
+    <div data-slot="page-contrast" className="flex flex-col gap-14">
+      <p className="flex flex-wrap gap-x-6 gap-y-2 text-sm text-muted-foreground">
+        {(
+          [
+            ["text", "fine as text, 4.5:1"],
+            ["shape", "fine as a shape only, 3:1"],
+            ["none", "neither"],
+          ] as const
+        ).map(([mark, words]) => (
+          <span key={mark} className="inline-flex items-center gap-2">
+            <Verdict mark={mark} />
+            {words}
+          </span>
+        ))}
+      </p>
       {modes.map((mode) => (
         <PageGrid key={mode} mode={mode} colours={colours} grounds={grounds} />
       ))}
@@ -199,6 +251,23 @@ export function PageContrast({ tokens, modes = ["light", "dark"] }: { tokens: To
   );
 }
 
+const VERDICT = {
+  text: { Icon: Check, className: "text-success-subdued-foreground", label: "text" },
+  shape: { Icon: Square, className: "text-muted-foreground", label: "shape" },
+  none: { Icon: X, className: "text-destructive-subdued-foreground", label: "none" },
+} as const;
+
+function Verdict({ mark, ratio }: { mark: keyof typeof VERDICT; ratio?: number }) {
+  const { Icon, className, label } = VERDICT[mark];
+  return (
+    <span className="inline-flex items-center gap-1.5 whitespace-nowrap">
+      <Icon aria-hidden className={cx("size-3.5 shrink-0", className)} strokeWidth={2.5} />
+      {ratio != null && <span className="font-mono text-xs text-canvas-foreground tabular-nums">{ratio.toFixed(1)}</span>}
+      <span className={cx(ratio != null && "text-xs text-muted-foreground")}>{ratio != null ? label : null}</span>
+    </span>
+  );
+}
+
 function PageGrid({ mode, colours, grounds }: { mode: Mode; colours: string[]; grounds: string[] }) {
   const probe = useRef<HTMLDivElement>(null);
   const [ratios, setRatios] = useState<Record<string, number | null>>({});
@@ -215,44 +284,44 @@ function PageGrid({ mode, colours, grounds }: { mode: Mode; colours: string[]; g
     setRatios(out);
   }, [colours, grounds]);
   return (
-    <div className="overflow-x-auto rounded-2xl border border-border bg-surface text-surface-foreground" tabIndex={0} role="region" aria-label={`Colours on each background, ${mode} mode`}>
+    <div className="-mx-1 overflow-x-auto px-1 pb-2" tabIndex={0} role="region" aria-label={`Colours on each background, ${mode} mode`}>
       <div ref={probe} data-theme={mode} hidden />
-      <table className="w-full min-w-[32rem] border-collapse text-left text-sm">
-        <caption className="border-b border-border px-4 py-3 text-left text-sm font-semibold capitalize">{mode}</caption>
+      <table className="w-full min-w-[46rem] table-fixed border-collapse text-left text-sm">
+        <caption className="pb-5 text-left text-lg font-medium capitalize">{mode}</caption>
         <thead>
-          <tr className="border-b border-border bg-muted/50 text-xs text-muted-foreground">
-            <th scope="col" className="px-4 py-2.5 font-medium">Colour</th>
+          <tr className="text-xs text-muted-foreground">
+            <th scope="col" className="w-32 pr-4 pb-3 font-medium">
+              Colour
+            </th>
             {grounds.map((g) => (
-              <th key={g} scope="col" className="px-4 py-2.5 font-mono font-medium">{g.slice(2)}</th>
+              <th key={g} scope="col" className="px-2 pb-3 font-mono font-normal">
+                {g.slice(2)}
+              </th>
             ))}
           </tr>
         </thead>
         <tbody>
           {colours.map((c) => (
-            <tr key={c} className="border-b border-border last:border-b-0">
-              <th scope="row" className="px-4 py-2.5 font-mono text-xs font-medium">{c.slice(2)}</th>
+            <tr key={c} className="border-t border-border">
+              <th scope="row" className="py-4 pr-4 align-top font-mono text-xs font-medium break-words">
+                {c.slice(2)}
+              </th>
               {grounds.map((g) => {
                 const r = ratios[`${c}|${g}`];
-                const mark = r == null ? "" : r >= 4.5 ? "text" : r >= 3 ? "shape" : "none";
+                const mark = r == null ? undefined : r >= 4.5 ? "text" : r >= 3 ? "shape" : "none";
                 return (
-                  <td key={g} className="px-4 py-2.5">
-                    <div className="flex items-center gap-2">
+                  <td key={g} className="px-2 py-4 align-top">
+                    <div className="flex flex-col gap-2">
                       {/* only the sample takes the mode; the number is read on the page */}
-                      <span data-theme={mode} className="flex h-9 w-12 items-center justify-center rounded-lg border border-(--border) text-base font-bold" style={{ background: `var(${g})`, color: `var(${c})` }} aria-hidden>
+                      <span
+                        data-theme={mode}
+                        aria-hidden
+                        className="flex h-12 items-center justify-center rounded-lg text-lg font-bold ring-1 ring-(--border) ring-inset"
+                        style={{ background: `var(${g})`, color: `var(${c})` }}
+                      >
                         Aa
                       </span>
-                      {r != null && (
-                        <span
-                          className={cx(
-                            "inline-flex items-center gap-1 rounded-full px-2 py-0.5 font-mono text-xs",
-                            mark === "text" && "bg-success-subdued text-success-subdued-foreground",
-                            mark === "shape" && "bg-muted text-muted-foreground",
-                            mark === "none" && "bg-destructive-subdued text-destructive-subdued-foreground",
-                          )}
-                        >
-                          {r.toFixed(1)} {mark}
-                        </span>
-                      )}
+                      {mark && r != null && <Verdict mark={mark} ratio={r} />}
                     </div>
                   </td>
                 );

package/src/variant-matrix.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { Live } from "./lib/live";
 import { Grid3x3, Moon, Sun } from "lucide-react";
 import { type ReactNode, useEffect, useState } from "react";
 import { cx } from "./lib/cx";
@@ -36,9 +37,11 @@ export function VariantMatrix({
 
   const content = children ?? entry.name;
   const render = (extra: Record<string, string>) => (
-    <Component {...props} {...coerce(extra)}>
-      {content}
-    </Component>
+    <Live>
+      <Component {...props} {...coerce(extra)}>
+        {content}
+      </Component>
+    </Live>
   );
   const [rows, cols, ...rest] = axes;
   const toggle = (
@@ -51,26 +54,28 @@ export function VariantMatrix({
   );
 
   return (
-    <div data-slot="variant-matrix" className="flex flex-col gap-6">
-      {cols ? (
-        <Frame>
-          <Toolbar>
-            <span className="flex items-center gap-2 pl-2 font-mono text-xs text-muted-foreground">
-              <Grid3x3 aria-hidden className="size-(--dt-size-xs)" />
-              {rows.name} × {cols.name}
-            </span>
-            {toggle}
-          </Toolbar>
-          <div data-docs-stage="" data-theme={theme} className="overflow-x-auto bg-canvas text-canvas-foreground" tabIndex={0} role="region" aria-label="Variants">
+    <Frame data-slot="variant-matrix">
+      <Toolbar>
+        <span className="flex items-center gap-2 pl-2 font-mono text-xs text-muted-foreground">
+          <Grid3x3 aria-hidden className="size-(--dt-size-xs)" />
+          {cols ? `${rows.name} × ${cols.name}` : rows.name}
+          {rest.length > 0 && `, ${rest.map((a) => a.name).join(", ")}`}
+        </span>
+        {toggle}
+      </Toolbar>
+      {/* one stage: the matrix, any further axes and the states, separated by space rather than rules */}
+      <div data-docs-stage="" data-theme={theme} className="flex flex-col gap-12 bg-canvas px-6 py-8 text-canvas-foreground sm:px-8">
+        {cols ? (
+          <div className="overflow-x-auto" tabIndex={0} role="region" aria-label="Variants">
             <table className="w-full border-collapse text-sm">
               <caption className="sr-only">
                 {entry.name}: {rows.name} by {cols.name}
               </caption>
               <thead>
-                <tr className="border-b border-border">
+                <tr>
                   <th scope="col" className="w-0 p-0" />
                   {cols.options.map((c) => (
-                    <th key={c.name} scope="col" title={c.description} className="px-4 py-3 text-center font-mono text-xs font-medium text-muted-foreground">
+                    <th key={c.name} scope="col" title={c.description} className="px-4 pb-4 text-center font-mono text-xs font-normal text-muted-foreground">
                       <OptionName axis={cols} option={c.name} />
                     </th>
                   ))}
@@ -78,12 +83,12 @@ export function VariantMatrix({
               </thead>
               <tbody>
                 {rows.options.map((r) => (
-                  <tr key={r.name} className="border-b border-border last:border-b-0">
-                    <th scope="row" title={r.description} className="border-r border-border px-4 py-5 text-left font-mono text-xs font-medium whitespace-nowrap text-muted-foreground">
+                  <tr key={r.name}>
+                    <th scope="row" title={r.description} className="py-4 pr-6 text-left font-mono text-xs font-normal whitespace-nowrap text-muted-foreground">
                       <OptionName axis={rows} option={r.name} />
                     </th>
                     {cols.options.map((c) => (
-                      <td key={c.name} data-slot="variant-cell" className="px-4 py-5 text-center align-middle">
+                      <td key={c.name} data-slot="variant-cell" className="px-4 py-4 text-center align-middle">
                         <span className="inline-flex justify-center">{render({ [rows.name]: r.name, [cols.name]: c.name })}</span>
                       </td>
                     ))}
@@ -92,15 +97,25 @@ export function VariantMatrix({
               </tbody>
             </table>
           </div>
-        </Frame>
-      ) : (
-        <AxisRow axis={rows} render={render} theme={theme} toggle={toggle} />
-      )}
-      {rest.map((axis) => (
-        <AxisRow key={axis.name} axis={axis} render={render} theme={theme} toggle={toggle} />
-      ))}
-      <States render={render} theme={theme} toggle={toggle} canDisable={"disabled" in entry.props} />
-    </div>
+        ) : (
+          <AxisRow axis={rows} render={render} />
+        )}
+        {rest.map((axis) => (
+          <AxisRow key={axis.name} axis={axis} render={render} />
+        ))}
+        <States render={render} canDisable={"disabled" in entry.props} />
+      </div>
+    </Frame>
+  );
+}
+
+/** A titled row of figures inside the variants stage. */
+function Group({ title, slot, children }: { title: string; slot: string; children: ReactNode }) {
+  return (
+    <section data-slot={slot} className="flex flex-col gap-5">
+      <h3 className="font-mono text-xs text-muted-foreground">{title}</h3>
+      <div className="flex flex-wrap items-end gap-x-10 gap-y-6">{children}</div>
+    </section>
   );
 }
 
@@ -109,17 +124,7 @@ export function VariantMatrix({
  * pressed and disabled, pinned without a pointer or a keyboard, so states are
  * reviewed side by side rather than by mousing over each.
  */
-function States({
-  render,
-  theme,
-  toggle,
-  canDisable,
-}: {
-  render: (extra: Record<string, string>) => ReactNode;
-  theme?: "light" | "dark";
-  toggle: ReactNode;
-  canDisable: boolean;
-}) {
+function States({ render, canDisable }: { render: (extra: Record<string, string>) => ReactNode; canDisable: boolean }) {
   useEffect(() => installPseudoStates(), []);
   const states: { name: string; pseudo?: string; extra?: Record<string, string> }[] = [
     { name: "rest" },
@@ -129,51 +134,29 @@ function States({
     ...(canDisable ? [{ name: "disabled", extra: { disabled: "true" } }] : []),
   ];
   return (
-    <Frame data-slot="variant-states">
-      <Toolbar>
-        <span className="pl-2 font-mono text-xs text-muted-foreground">state</span>
-        {toggle}
-      </Toolbar>
-      <div data-docs-stage="" data-theme={theme} className="flex flex-wrap items-end justify-center gap-x-10 gap-y-6 bg-canvas px-6 py-8 text-canvas-foreground">
-        {states.map((s) => (
-          <figure key={s.name} className="flex flex-col items-center gap-3">
-            <div data-pseudo={s.pseudo}>{render(s.extra ?? {})}</div>
-            <figcaption className="font-mono text-xs text-muted-foreground">{s.name}</figcaption>
-          </figure>
-        ))}
-      </div>
-    </Frame>
+    <Group title="state" slot="variant-states">
+      {states.map((s) => (
+        <figure key={s.name} className="flex flex-col items-center gap-3">
+          <div data-pseudo={s.pseudo}>{render(s.extra ?? {})}</div>
+          <figcaption className="font-mono text-xs text-muted-foreground">{s.name}</figcaption>
+        </figure>
+      ))}
+    </Group>
   );
 }
 
-function AxisRow({
-  axis,
-  render,
-  theme,
-  toggle,
-}: {
-  axis: VariantAxis;
-  render: (extra: Record<string, string>) => ReactNode;
-  theme?: "light" | "dark";
-  toggle: ReactNode;
-}) {
+function AxisRow({ axis, render }: { axis: VariantAxis; render: (extra: Record<string, string>) => ReactNode }) {
   return (
-    <Frame data-slot="variant-axis">
-      <Toolbar>
-        <span className="pl-2 font-mono text-xs text-muted-foreground">{axis.name}</span>
-        {toggle}
-      </Toolbar>
-      <div data-docs-stage="" data-theme={theme} className="flex flex-wrap items-end justify-center gap-x-10 gap-y-6 bg-canvas px-6 py-8 text-canvas-foreground">
-        {axis.options.map((o) => (
-          <figure key={o.name} className="flex flex-col items-center gap-3">
-            {render({ [axis.name]: o.name })}
-            <figcaption className="font-mono text-xs text-muted-foreground" title={o.description}>
-              <OptionName axis={axis} option={o.name} />
-            </figcaption>
-          </figure>
-        ))}
-      </div>
-    </Frame>
+    <Group title={axis.name} slot="variant-axis">
+      {axis.options.map((o) => (
+        <figure key={o.name} className="flex flex-col items-center gap-3">
+          {render({ [axis.name]: o.name })}
+          <figcaption className="font-mono text-xs text-muted-foreground" title={o.description}>
+            <OptionName axis={axis} option={o.name} />
+          </figcaption>
+        </figure>
+      ))}
+    </Group>
   );
 }