@designtools/docs 0.0.0-stage → 0.2.0

package/src/styles.css

@@ -0,0 +1,157 @@
+/*
+ * The docs' styles, compiled at build and scoped to `[data-designtools]`, so they
+ * style the docs and nothing else on the page. They never match inside the
+ * project's own components shown in the docs (`Live`, `[data-docs-content]`), and
+ * on the docs' own elements they carry one attribute more than a project utility,
+ * so neither side's utilities leak into the other, whichever loads last.
+ *
+ * Themed by the project's own variables. Colours are @designtools/tokens'
+ * semantic names (--canvas, --surface, --primary, …), so a project on our tokens
+ * needs nothing; any other project sets those names on the docs. Fonts take
+ * --docs-font-sans / --docs-font-mono, else the project's --font-sans and
+ * --font-mono; headings --docs-display, else --font-display. Sizes, radii,
+ * shadows, leading and tracking follow the project's scale where it has one.
+ * Every value has a fallback, so the docs render on a project with none of it.
+ */
+@layer theme, base, components, utilities;
+@import "tailwindcss/theme.css" layer(theme) theme(inline reference);
+@import "tailwindcss/preflight.css" layer(base);
+@import "tailwindcss/utilities.css" layer(utilities);
+
+@source "./";
+@source not "./lib/adherence-types.ts";
+
+@theme inline reference {
+  --color-*: initial;
+  --color-white: #fff;
+  --color-black: #000;
+  --color-current: currentColor;
+  --color-transparent: transparent;
+
+  --color-canvas: var(--canvas, #ffffff);
+  --color-canvas-foreground: var(--canvas-foreground, #1c1f26);
+  --color-surface: var(--surface, #ffffff);
+  --color-surface-foreground: var(--surface-foreground, #1c1f26);
+  --color-overlay: var(--overlay, #ffffff);
+  --color-overlay-foreground: var(--overlay-foreground, #1c1f26);
+  --color-muted: var(--muted, #f4f5f7);
+  --color-muted-foreground: var(--muted-foreground, #5a606b);
+  --color-border: var(--border, #e2e4e8);
+  --color-input: var(--input, #8a909b);
+  --color-ring: var(--ring, #2b5ce6);
+  --color-shadow: var(--shadow, #0b0d12);
+
+  --color-primary: var(--primary, #2b5ce6);
+  --color-primary-foreground: var(--primary-foreground, #ffffff);
+  --color-primary-subdued: var(--primary-subdued, #eef2fd);
+  --color-primary-subdued-foreground: var(--primary-subdued-foreground, #1d40a8);
+  --color-primary-hover: var(--primary-hover, #2149c2);
+  --color-neutral: var(--neutral, #5a606b);
+  --color-neutral-foreground: var(--neutral-foreground, #ffffff);
+  --color-success: var(--success, #23823f);
+  --color-success-foreground: var(--success-foreground, #ffffff);
+  --color-success-subdued: var(--success-subdued, #e9f6ed);
+  --color-success-subdued-foreground: var(--success-subdued-foreground, #1b6631);
+  --color-destructive: var(--destructive, #c7302f);
+  --color-destructive-foreground: var(--destructive-foreground, #ffffff);
+  --color-destructive-subdued: var(--destructive-subdued, #fcecec);
+  --color-destructive-subdued-foreground: var(--destructive-subdued-foreground, #9b2221);
+  --color-warning: var(--warning, #ed8a3c);
+  --color-warning-foreground: var(--warning-foreground, #1c1f26);
+  --color-warning-subdued: var(--warning-subdued, #fdf0e3);
+  --color-warning-subdued-foreground: var(--warning-subdued-foreground, #6b3a10);
+
+  --default-font-family: var(--docs-font-sans, var(--font-sans, ui-sans-serif, system-ui, sans-serif));
+  --default-mono-font-family: var(--docs-font-mono, var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace));
+  --font-sans: var(--docs-font-sans, var(--font-sans, ui-sans-serif, system-ui, sans-serif));
+  --font-mono: var(--docs-font-mono, var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace));
+
+  --text-xs: var(--text-xs, 0.75rem);
+  --text-xs--line-height: var(--text-xs--line-height, 1rem);
+  --text-sm: var(--text-sm, 0.875rem);
+  --text-sm--line-height: var(--text-sm--line-height, 1.25rem);
+  --text-base: var(--text-base, 1rem);
+  --text-base--line-height: var(--text-base--line-height, 1.5rem);
+  --text-lg: var(--text-lg, 1.125rem);
+  --text-lg--line-height: var(--text-lg--line-height, 1.75rem);
+  --text-xl: var(--text-xl, 1.25rem);
+  --text-xl--line-height: var(--text-xl--line-height, 1.75rem);
+  --text-2xl: var(--text-2xl, 1.5rem);
+  --text-2xl--line-height: var(--text-2xl--line-height, 2rem);
+  --text-3xl: var(--text-3xl, 1.875rem);
+  --text-3xl--line-height: var(--text-3xl--line-height, 2.25rem);
+  --text-4xl: var(--text-4xl, 2.25rem);
+  --text-4xl--line-height: var(--text-4xl--line-height, 2.5rem);
+  --text-5xl: var(--text-5xl, 3rem);
+  --text-5xl--line-height: var(--text-5xl--line-height, 1);
+  --text-6xl: var(--text-6xl, 3.75rem);
+  --text-6xl--line-height: var(--text-6xl--line-height, 1);
+  --text-7xl: var(--text-7xl, 4.5rem);
+  --text-7xl--line-height: var(--text-7xl--line-height, 1);
+  --text-8xl: var(--text-8xl, 6rem);
+  --text-8xl--line-height: var(--text-8xl--line-height, 1);
+
+  --font-weight-light: var(--font-weight-light, 300);
+  --font-weight-normal: var(--font-weight-normal, 400);
+  --font-weight-medium: var(--font-weight-medium, 500);
+  --font-weight-semibold: var(--font-weight-semibold, 600);
+  --font-weight-bold: var(--font-weight-bold, 700);
+
+  --leading-none: var(--leading-none, 1);
+  --leading-tight: var(--leading-tight, 1.25);
+  --leading-snug: var(--leading-snug, 1.375);
+  --leading-normal: var(--leading-normal, 1.5);
+  --leading-relaxed: var(--leading-relaxed, 1.625);
+
+  --tracking-tighter: var(--tracking-tighter, -0.04em);
+  --tracking-tight: var(--tracking-tight, -0.02em);
+  --tracking-normal: var(--tracking-normal, 0em);
+  --tracking-wide: var(--tracking-wide, 0.04em);
+  --tracking-widest: var(--tracking-widest, 0.16em);
+
+  --radius-xs: var(--docs-radius-xs, var(--radius-xs, 0.125rem));
+  --radius-sm: var(--docs-radius-sm, var(--radius-sm, 0.25rem));
+  --radius-md: var(--docs-radius-md, var(--radius-md, 0.375rem));
+  --radius-lg: var(--docs-radius-lg, var(--radius-lg, 0.5rem));
+  --radius-xl: var(--docs-radius-xl, var(--radius-xl, 0.75rem));
+  --radius-2xl: var(--docs-radius-2xl, var(--radius-2xl, 1rem));
+
+  --shadow-xs: var(--shadow-xs, 0 1px 2px 0 color-mix(in oklch, var(--shadow, #0b0d12) 6%, transparent));
+  --shadow-sm: var(--shadow-sm, 0 1px 3px 0 color-mix(in oklch, var(--shadow, #0b0d12) 10%, transparent));
+  --shadow-md: var(--shadow-md, 0 4px 12px -2px color-mix(in oklch, var(--shadow, #0b0d12) 12%, transparent));
+  --shadow-lg: var(--shadow-lg, 0 12px 28px -6px color-mix(in oklch, var(--shadow, #0b0d12) 16%, transparent));
+  --shadow-xl: var(--shadow-xl, 0 24px 48px -12px color-mix(in oklch, var(--shadow, #0b0d12) 20%, transparent));
+
+  /* the docs' own geometry: a 4px step, whatever the project's */
+  --spacing: 0.25rem;
+}
+
+/* The scale the blocks size and time themselves with: the project's, where it has one */
+@layer base {
+  [data-designtools] {
+    --dt-size-xs: var(--size-xs, 1rem);
+    --dt-size-sm: var(--size-sm, 1.25rem);
+    --dt-size-md: var(--size-md, 1.5rem);
+    --dt-size-lg: var(--size-lg, 2rem);
+    --dt-size-xl: var(--size-xl, 2.5rem);
+    --dt-size-2xl: var(--size-2xl, 3rem);
+    --dt-size-3xl: var(--size-3xl, 4rem);
+    --dt-duration-fast: var(--duration-fast, 120ms);
+    --dt-duration-base: var(--duration-base, 200ms);
+    --dt-duration-slow: var(--duration-slow, 320ms);
+    --dt-ease-out: var(--ease-out, cubic-bezier(0.2, 0, 0, 1));
+    --dt-ease-in: var(--ease-in, cubic-bezier(0.4, 0, 1, 1));
+    --dt-ease-in-out: var(--ease-in-out, cubic-bezier(0.4, 0, 0.2, 1));
+    background: var(--canvas, #fff);
+    color: var(--canvas-foreground, #1c1f26);
+  }
+  /* Where the project's components render, they inherit the project's type, not the docs' */
+  [data-designtools] [data-docs-stage] {
+    font-family: var(--font-sans, inherit);
+    line-height: var(--leading-normal, 1.5);
+  }
+  /* Tailwind v4 puts buttons back to the arrow; anything pressable in the docs gets the pointer */
+  [data-designtools] :is(button:not(:disabled), [role="button"]:not([aria-disabled="true"]), summary) {
+    cursor: pointer;
+  }
+}

package/src/swatches.tsx

@@ -0,0 +1,298 @@
+"use client";
+
+import { 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.
+ */
+export function SemanticSwatches({
+  tokens,
+  modes = ["light", "dark"],
+}: {
+  tokens: TokensManifest;
+  modes?: Mode[];
+}) {
+  const colours = semanticColours(tokens);
+  const byName = new Map(colours.map((c) => [c.name, c]));
+  const families = colours.filter((c) => byName.has(`${c.name}-subdued`)).map((c) => c.name);
+  const inFamily = new Set(families.flatMap((f) => [f, `${f}-subdued`, `${f}-hover`, `${f}-active`]));
+  const surfaces = colours.filter((c) => !inFamily.has(c.name) && c.foreground).map((c) => c.name);
+  const utility = colours.filter((c) => !inFamily.has(c.name) && !c.foreground).map((c) => c.name);
+  const step = (name: string, mode: Mode) => {
+    const token = byName.get(name)?.background;
+    return token && pointsAt(valueIn(token, mode));
+  };
+
+  // one level of framing: a panel per mode (the dark one has to be dark), chips inside it, and nothing around the family
+  const panel = (mode: Mode) =>
+    cx("flex flex-col gap-3 rounded-2xl bg-canvas p-4 text-canvas-foreground", mode === "light" && "ring-1 ring-border ring-inset");
+  const modeLabel = (mode: Mode) => <span className="text-xs font-medium text-muted-foreground capitalize">{mode}</span>;
+  const row = (title: string, meta: ReactNode, body: ReactNode, key?: string) => (
+    <div key={key ?? title} data-slot="swatch-row" className="grid gap-x-10 gap-y-5 border-t border-border pt-8 first:border-t-0 first:pt-0 lg:grid-cols-[11rem_minmax(0,1fr)]">
+      <div className="flex flex-col gap-1.5">
+        <h3 className="text-2xl leading-tight tracking-tight">{title}</h3>
+        {meta}
+      </div>
+      {body}
+    </div>
+  );
+
+  return (
+    <div data-slot="swatches" className="flex flex-col gap-10">
+      {families.map((f) =>
+        row(
+          (([first, ...rest]) => first.toUpperCase() + rest.join(""))(f.slice(2).replace(/-/g, " ")),
+          <code className="font-mono text-xs text-muted-foreground">{f}</code>,
+          <div className={cx("grid gap-4", modes.length > 1 && "md:grid-cols-2")}>
+            {modes.map((mode) => (
+              <div key={mode} data-theme={mode} data-slot="swatch-family" className={panel(mode)}>
+                {modeLabel(mode)}
+                <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>
+              </div>
+            ))}
+          </div>,
+          f,
+        ),
+      )}
+
+      {surfaces.length > 0 &&
+        row(
+          "Surfaces",
+          <p className="text-sm text-muted-foreground">The page, panels and popups, each with its text.</p>,
+          <div className={cx("grid gap-4", modes.length > 1 && "md:grid-cols-2")}>
+            {modes.map((mode) => (
+              <div key={mode} data-theme={mode} className={panel(mode)}>
+                {modeLabel(mode)}
+                <div className="grid grid-cols-2 gap-2 xl:grid-cols-3">
+                  {surfaces.map((name) => (
+                    <Chip key={name} name={name} label={name.slice(2)} step={step(name, mode)} outlined />
+                  ))}
+                </div>
+              </div>
+            ))}
+          </div>,
+        )}
+
+      {utility.length > 0 &&
+        row(
+          "Lines, focus and shadow",
+          <p className="text-sm text-muted-foreground">Borders, input edges, the focus ring and the shadow colour.</p>,
+          <div className={cx("grid gap-4", modes.length > 1 && "md:grid-cols-2")}>
+            {modes.map((mode) => (
+              <div key={mode} data-theme={mode} className={panel(mode)}>
+                {modeLabel(mode)}
+                <ul className="grid grid-cols-2 gap-x-4 gap-y-3">
+                  {utility.map((name) => (
+                    <li key={name} data-slot="swatch" className="flex items-center gap-3">
+                      <span aria-hidden className="size-9 shrink-0 rounded-lg 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>
+  );
+}
+
+/** `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);
+  if (m) return m[1];
+  return value?.startsWith("oklch(") ? "generated" : value;
+}
+
+/**
+ * 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.
+ */
+function Chip({
+  name,
+  foreground = `${name}-foreground`,
+  label,
+  step,
+  size = "md",
+  outlined,
+}: {
+  name: string;
+  foreground?: string;
+  label: string;
+  step?: string;
+  size?: "md" | "lg";
+  outlined?: boolean;
+}) {
+  const chip = useRef<HTMLDivElement>(null);
+  const [ratio, setRatio] = useState<number | null>(null);
+  useEffect(() => {
+    const node = chip.current;
+    if (!node) return;
+    const style = getComputedStyle(node);
+    setRatio(contrastRatio(style.color, style.backgroundColor));
+  }, [name, foreground]);
+  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>
+          )}
+        </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>
+          )
+        )}
+      </span>
+    </div>
+  );
+}
+
+/**
+ * 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.
+ * Measured on what the browser paints, inside each mode's `data-theme`.
+ */
+export function PageContrast({ tokens, modes = ["light", "dark"] }: { tokens: TokensManifest; modes?: Mode[] }) {
+  const names = new Set(semanticColours(tokens).map((c) => c.name));
+  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-12">
+      {modes.map((mode) => (
+        <PageGrid key={mode} mode={mode} colours={colours} grounds={grounds} />
+      ))}
+    </div>
+  );
+}
+
+function PageGrid({ mode, colours, grounds }: { mode: Mode; colours: string[]; grounds: string[] }) {
+  const probe = useRef<HTMLDivElement>(null);
+  const [ratios, setRatios] = useState<Record<string, number | null>>({});
+  useEffect(() => {
+    const node = probe.current;
+    if (!node) return;
+    const paint = (v: string) => {
+      node.style.color = `var(${v})`;
+      return getComputedStyle(node).color;
+    };
+    const painted = Object.fromEntries([...colours, ...grounds].map((v) => [v, paint(v)]));
+    const out: Record<string, number | null> = {};
+    for (const c of colours) for (const g of grounds) out[`${c}|${g}`] = contrastRatio(painted[c], painted[g]);
+    setRatios(out);
+  }, [colours, grounds]);
+  return (
+    <div className="-mx-1 overflow-x-auto px-1" 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-[40rem] border-collapse text-left text-sm">
+        <caption className="pb-4 text-left text-lg font-medium capitalize">{mode}</caption>
+        <thead>
+          <tr className="text-xs text-muted-foreground">
+            <th scope="col" className="pr-4 pb-3 font-medium">Colour</th>
+            {grounds.map((g) => (
+              <th key={g} scope="col" className="px-3 pb-3 font-mono font-normal">{g.slice(2)}</th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {colours.map((c) => (
+            <tr key={c} className="border-t border-border">
+              <th scope="row" className="py-3.5 pr-4 font-mono text-xs font-medium">{c.slice(2)}</th>
+              {grounds.map((g) => {
+                const r = ratios[`${c}|${g}`];
+                const mark = r == null ? "" : r >= 4.5 ? "text" : r >= 3 ? "shape" : "none";
+                return (
+                  <td key={g} className="px-3 py-3.5">
+                    <div className="flex items-center gap-2.5">
+                      {/* only the sample takes the mode; the number is read on the page */}
+                      <span data-theme={mode} className="flex h-10 w-14 items-center justify-center rounded-lg border border-(--border) text-base font-bold" style={{ background: `var(${g})`, color: `var(${c})` }} aria-hidden>
+                        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>
+                      )}
+                    </div>
+                  </td>
+                );
+              })}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
+/** The primitive ramps, one row per colour family, each step painted from its own token. */
+export function RampSwatches({ tokens }: { tokens: TokensManifest }) {
+  return (
+    <div data-slot="ramps" className="flex flex-col gap-5 overflow-x-auto" tabIndex={0} role="region" aria-label="Ramps">
+      {ramps(tokens).map((ramp) => (
+        <div key={ramp.family} data-slot="ramp" className="grid min-w-[36rem] grid-cols-[6rem_1fr] items-center gap-4">
+          <p className="font-mono text-xs font-medium capitalize">{ramp.family}</p>
+          <ol className="grid grid-flow-col auto-cols-fr gap-1">
+            {ramp.steps.map(({ step, token }) => (
+              <li key={step} data-slot="ramp-step" title={`${token.name}: ${token.values.default ?? ""}`} className="flex flex-col gap-1.5">
+                <span aria-hidden className="h-12 rounded-md ring-1 ring-border ring-inset" style={{ background: `var(${token.name})` }} />
+                <span className="text-center font-mono text-xs text-muted-foreground">{step}</span>
+              </li>
+            ))}
+          </ol>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/theme-switch.tsx

@@ -0,0 +1,90 @@
+"use client";
+import { Monitor, Moon, Sun } from "lucide-react";
+import { useServerInsertedHTML } from "next/navigation";
+import { useEffect, useRef, useState } from "react";
+import { cx } from "./lib/cx";
+
+type Mode = "system" | "light" | "dark";
+const MODES = [
+  { mode: "system", label: "System", Icon: Monitor },
+  { mode: "light", label: "Light", Icon: Sun },
+  { mode: "dark", label: "Dark", Icon: Moon },
+] as const;
+const KEY = "docs-theme";
+
+/**
+ * Runs before the first paint, so a saved choice never flashes the other mode. It
+ * sets `data-theme` on <html>, which the generated tokens read, so give <html>
+ * `suppressHydrationWarning`. System sets nothing and leaves it to the media query.
+ */
+export const themeScript = `try{var t=localStorage.getItem("${KEY}");if(t==="light"||t==="dark")document.documentElement.dataset.theme=t}catch(e){}`;
+
+/**
+ * Writes `themeScript` into the server's HTML, once, ahead of the page. Through
+ * Next's `useServerInsertedHTML`, because React will not run a <script> a client
+ * component renders, and says so. The shell calls it; call it once yourself if the
+ * switch lives somewhere else.
+ */
+export function useThemeScript() {
+  const done = useRef(false);
+  useServerInsertedHTML(() => {
+    if (done.current) return null;
+    done.current = true;
+    // biome-ignore lint/security/noDangerouslySetInnerHtml: a fixed string, written here, with nothing from the request in it
+    return <script dangerouslySetInnerHTML={{ __html: themeScript }} />;
+  });
+}
+
+function apply(mode: Mode) {
+  const root = document.documentElement;
+  if (mode === "system") delete root.dataset.theme;
+  else root.dataset.theme = mode;
+  try {
+    if (mode === "system") localStorage.removeItem(KEY);
+    else localStorage.setItem(KEY, mode);
+  } catch {
+    // private windows and blocked storage: the choice lasts for this page only
+  }
+}
+
+/**
+ * System, light or dark for the whole site, as three icons in a track. Kept per
+ * viewer. Each is a 44px target however small it is drawn.
+ */
+export function ThemeSwitch({ className }: { className?: string }) {
+  const [mode, setMode] = useState<Mode>("system");
+  useEffect(() => {
+    const t = document.documentElement.dataset.theme;
+    if (t === "light" || t === "dark") setMode(t);
+  }, []);
+
+  return (
+    <div role="group" aria-label="Colour mode" data-slot="docs-theme-switch" className={cx("flex items-center rounded-full bg-muted p-0.5", className)}>
+      {MODES.map(({ mode: m, label, Icon }) => (
+        <button
+          key={m}
+          type="button"
+          aria-pressed={mode === m}
+          aria-label={label}
+          title={label}
+          onClick={() => {
+            setMode(m);
+            apply(m);
+          }}
+          // drawn at 32px; the transparent ring of padding makes each a 44px target
+          className="relative -my-1.5 inline-flex size-(--docs-target,2.75rem) cursor-pointer items-center justify-center rounded-full p-1.5 text-muted-foreground transition-colors duration-(--dt-duration-fast) first:-ml-1.5 last:-mr-1.5 hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring aria-pressed:text-canvas-foreground"
+        >
+          <span
+            aria-hidden
+            className={cx(
+              "flex size-full items-center justify-center rounded-full transition-colors duration-(--dt-duration-fast)",
+              mode === m && "bg-surface shadow-xs ring-1 ring-border",
+            )}
+          >
+            <Icon className="size-(--dt-size-xs)" />
+          </span>
+        </button>
+      ))}
+    </div>
+  );
+}