@designtools/docs 0.1.0 → 0.2.0

package/src/rule.tsx

@@ -1,24 +1,26 @@
 "use client";
 
+import { Live } from "./lib/live";
 import { Bot, Eye, Hash, ShieldCheck } from "lucide-react";
-import type { ReactNode } from "react";
+import { type ReactNode, useState } from "react";
 import { CodeView } from "./code-view";
 import { cx } from "./lib/cx";
 import { ruleMarkdown } from "./lib/markdown";
 import type { RuleEntry } from "./lib/manifest-types";
 import { StatusBadge } from "./lib/status";
 import { inline, Prose } from "./lib/text";
-import { Eyebrow, Segmented, SegmentedList, SegmentedPanel, Stage } from "./lib/ui";
+import { Eyebrow } from "./lib/ui";
 
 const CHECK: Record<string, string> = { test: "Tested", lint: "Linted", audit: "Audited", manual: "Checked by a person" };
 
 /**
- * One rule, brand or interface, written for people: the statement set large, the
- * line it draws, what it applies to and the check that proves it, then why. A
- * switch shows the same rule as an agent reads it. Pass a demonstration as
- * children where the rule needs persuading; it is shown on a stage.
+ * One rule, brand or interface, written for people. On a wide screen, its name, status and the check
+ * that proves it hold the left column while the right reads: the statement set large, the
+ * demonstration (pass it as children, for a rule that needs persuading), the facts, then why. A small
+ * switch shows the same rule as an agent reads it.
  */
 export function Rule({ rule, children }: { rule: RuleEntry; children?: ReactNode }) {
+  const [view, setView] = useState<"people" | "agents">("people");
   const chips = (items: string[], mono = false) => (
     <span className="flex flex-wrap gap-1.5">
       {items.map((t) => (
@@ -33,46 +35,75 @@ export function Rule({ rule, children }: { rule: RuleEntry; children?: ReactNode
   if (rule.appliesTo?.length) facts.push(["Applies to", chips(rule.appliesTo)]);
   if (rule.exceptions?.length) facts.push(["Exceptions", <span key="e">{rule.exceptions.join("; ")}</span>]);
   if (rule.tokens?.length) facts.push(["Tokens", chips(rule.tokens, true)]);
+  const toggle = (value: "people" | "agents", label: string, Icon: typeof Eye) => (
+    <button
+      type="button"
+      aria-pressed={view === value}
+      onClick={() => setView(value)}
+      className={cx(
+        "inline-flex min-h-8 cursor-pointer items-center gap-1.5 rounded-md px-2 text-xs font-medium transition-colors duration-(--dt-duration-fast) focus-visible:outline-2 focus-visible:outline-ring",
+        view === value ? "bg-muted text-canvas-foreground" : "text-muted-foreground hover:text-canvas-foreground",
+      )}
+    >
+      <Icon aria-hidden className="size-3.5" />
+      {label}
+    </button>
+  );
 
   return (
-    <article id={rule.id} data-slot="rule" className="scroll-mt-24 border-t border-border pt-8">
-      <Segmented defaultValue="rendered">
-        <header className="flex flex-wrap items-start justify-between gap-3">
-          <div className="flex min-w-0 flex-col gap-2">
-            <span className="flex flex-wrap items-center gap-2">
-              <StatusBadge status={rule.status} />
-              <span className="text-xs font-medium text-muted-foreground">{rule.kind === "brand" ? "Brand rule" : "Interface rule"}</span>
+    <article id={rule.id} data-slot="rule" className="grid scroll-mt-24 gap-x-12 gap-y-6 border-t border-border pt-10 xl:grid-cols-[15rem_minmax(0,1fr)]">
+      <header data-slot="rule-header" className="flex flex-col gap-4 xl:sticky xl:top-24 xl:self-start">
+        <div className="flex flex-col gap-2.5">
+          <span className="text-xs font-medium text-muted-foreground">{rule.kind === "brand" ? "Brand rule" : "Interface rule"}</span>
+          <h3 className="group flex items-start gap-1 text-2xl leading-tight tracking-tight">
+            {rule.title}
+            <a
+              href={`#${rule.id}`}
+              aria-label={`Link to ${rule.title}`}
+              className="relative mt-0.5 inline-flex size-7 shrink-0 items-center justify-center rounded-md text-muted-foreground opacity-0 group-hover:opacity-100 hover:bg-muted focus-visible:opacity-100 focus-visible:outline-2 focus-visible:outline-ring after:absolute after:-inset-2 after:content-['']"
+            >
+              <Hash aria-hidden className="size-4" />
+            </a>
+          </h3>
+          <span>
+            <StatusBadge status={rule.status} />
+          </span>
+        </div>
+        {rule.check && (
+          <p data-slot="rule-check" className="flex items-start gap-2 text-sm">
+            <ShieldCheck aria-hidden className="mt-0.5 size-(--dt-size-xs) shrink-0 text-muted-foreground" />
+            <span className="flex flex-col gap-0.5">
+              <span className="font-medium">
+                {CHECK[rule.check.kind] ?? rule.check.kind}
+                {rule.check.ref && (
+                  <>
+                    {" "}
+                    by <code className="font-mono text-xs">{rule.check.ref}</code>
+                  </>
+                )}
+              </span>
+              {rule.check.description && <span className="text-muted-foreground">{inline(rule.check.description)}</span>}
             </span>
-            <h3 className="group flex items-center gap-2 text-3xl tracking-tight">
-              {rule.title}
-              <a
-                href={`#${rule.id}`}
-                aria-label={`Link to ${rule.title}`}
-                className="relative inline-flex size-7 items-center justify-center rounded-md text-muted-foreground opacity-0 group-hover:opacity-100 hover:bg-muted focus-visible:opacity-100 focus-visible:outline-2 focus-visible:outline-ring after:absolute after:-inset-2 after:content-['']"
-              >
-                <Hash aria-hidden className="size-4" />
-              </a>
-            </h3>
-          </div>
-          <SegmentedList
-            label={`${rule.title}, two ways`}
-            items={[
-              { value: "rendered", label: "For people", icon: Eye },
-              { value: "agent", label: "For agents", icon: Bot },
-            ]}
-          />
-        </header>
-        <SegmentedPanel value="rendered" className="flex flex-col gap-6 pt-4">
-          <p data-slot="rule-statement" className="max-w-3xl text-xl leading-snug tracking-tight">
+          </p>
+        )}
+        <div role="group" aria-label={`Read ${rule.title}`} className="-ml-2 flex gap-1">
+          {toggle("people", "For people", Eye)}
+          {toggle("agents", "For agents", Bot)}
+        </div>
+      </header>
+
+      {view === "people" ? (
+        <div data-slot="rule-body" className="flex min-w-0 flex-col gap-8">
+          <p data-slot="rule-statement" className="max-w-3xl text-2xl leading-snug tracking-tight">
             {inline(rule.statement)}
           </p>
           {children && (
-            <div data-slot="rule-demonstration" className="overflow-hidden rounded-xl border border-border">
-              <Stage className="min-h-40">{children}</Stage>
+            <div data-slot="rule-demonstration" data-docs-stage="" className="flex min-h-40 items-center justify-center rounded-2xl bg-muted/60 p-8 sm:p-10">
+              <Live>{children}</Live>
             </div>
           )}
           {facts.length > 0 && (
-            <dl className="grid gap-x-10 gap-y-5 sm:grid-cols-2">
+            <dl className="grid max-w-3xl gap-x-10 gap-y-4 sm:grid-cols-2">
               {facts.map(([term, detail]) => (
                 <div key={term} className="flex flex-col gap-1.5">
                   <dt className="text-xs font-medium text-muted-foreground">{term}</dt>
@@ -81,36 +112,54 @@ export function Rule({ rule, children }: { rule: RuleEntry; children?: ReactNode
               ))}
             </dl>
           )}
-          {rule.check && (
-            <div className="flex items-start gap-2.5 text-sm">
-              <ShieldCheck aria-hidden className="mt-0.5 size-(--dt-size-xs) shrink-0 text-muted-foreground" />
-              <p className="flex flex-col gap-0.5">
-                <span className="font-medium">
-                  {CHECK[rule.check.kind] ?? rule.check.kind}
-                  {rule.check.ref && (
-                    <>
-                      {" "}
-                      by <code className="font-mono text-xs">{rule.check.ref}</code>
-                    </>
-                  )}
-                </span>
-                {rule.check.description && <span className="text-muted-foreground">{inline(rule.check.description)}</span>}
-              </p>
-            </div>
-          )}
           {rule.rationale && (
             <div className="flex max-w-3xl flex-col gap-2">
               <Eyebrow>Why</Eyebrow>
-              <div className="flex flex-col gap-2 text-sm text-muted-foreground">
+              <div className="flex flex-col gap-2 text-base leading-relaxed text-muted-foreground">
                 <Prose text={rule.rationale} />
               </div>
             </div>
           )}
-        </SegmentedPanel>
-        <SegmentedPanel value="agent" className="pt-4">
+        </div>
+      ) : (
+        <div className="min-w-0">
           <CodeView code={ruleMarkdown(rule)} lang="markdown" label={`${rule.id}.md`} wrap />
-        </SegmentedPanel>
-      </Segmented>
+        </div>
+      )}
     </article>
   );
 }
+
+/** Every rule on one screen, a line each, linking to the rule: what it is, how settled, how it is checked. */
+export function RuleIndex({ rules }: { rules: RuleEntry[] }) {
+  return (
+    <div data-slot="rule-index" className="-mx-1 overflow-x-auto px-1">
+      <table className="w-full min-w-[34rem] border-collapse text-left text-sm">
+        <thead>
+          <tr className="text-xs text-muted-foreground">
+            <th scope="col" className="pr-4 pb-3 font-medium">Rule</th>
+            <th scope="col" className="px-4 pb-3 font-medium">Kind</th>
+            <th scope="col" className="px-4 pb-3 font-medium">Status</th>
+            <th scope="col" className="pb-3 pl-4 font-medium">Checked</th>
+          </tr>
+        </thead>
+        <tbody>
+          {rules.map((r) => (
+            <tr key={r.id} className="border-t border-border">
+              <th scope="row" className="py-3 pr-4 font-normal">
+                <a href={`#${r.id}`} className="font-medium underline-offset-4 hover:underline focus-visible:outline-2 focus-visible:outline-ring">
+                  {r.title}
+                </a>
+              </th>
+              <td className="px-4 py-3 text-muted-foreground capitalize">{r.kind}</td>
+              <td className="px-4 py-3">
+                <StatusBadge status={r.status} />
+              </td>
+              <td className="py-3 pl-4 text-muted-foreground">{r.check ? (CHECK[r.check.kind] ?? r.check.kind) : "Not yet"}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}

package/src/shell.tsx

@@ -6,7 +6,9 @@ import { ArrowLeft, ArrowRight, BookOpen, ChevronRight, Component, Gauge, House,
 import Link from "next/link";
 import { usePathname } from "next/navigation";
 import { createContext, type ReactNode, useContext, useEffect, useMemo, useState } from "react";
+import { Live } from "./lib/live";
 import { accent, cx, display, target } from "./lib/cx";
+import { type Status, StatusBadge } from "./lib/status";
 import { groupFamilies, slugOf } from "./lib/manifest";
 import type { ComponentsManifest, PatternsManifest, RulesManifest, TaxonomyManifest } from "./lib/manifest-types";
 import { searchIndex } from "./lib/search";
@@ -157,7 +159,7 @@ export function DocsShell({
     <Link href={basePath} data-slot="docs-title" className={cx(target, "flex min-w-0 items-center gap-3 rounded-md focus-visible:outline-2 focus-visible:outline-ring")}>
       {logo && (
         <span data-slot="docs-logo" className="shrink-0">
-          {logo}
+          <Live>{logo}</Live>
         </span>
       )}
       <span className={cx(logo ? "sr-only" : "truncate text-base font-semibold tracking-tight")}>{title}</span>
@@ -207,7 +209,7 @@ export function DocsShell({
                       <X aria-hidden className="size-(--dt-size-sm)" />
                     </Dialog.Close>
                   </div>
-                  <Nav sections={sections} current={current} title={title} />
+                  <Nav sections={sections} current={current} title={title} className="pt-4" />
                   {themeSwitch && (
                     <div className="flex items-center justify-between gap-3 border-t border-border px-4 py-3">
                       <span className="text-xs font-medium text-muted-foreground">Appearance</span>
@@ -224,7 +226,7 @@ export function DocsShell({
 
           {hero && current === basePath && (
             <div data-slot="docs-hero" className="w-full">
-              {hero}
+              <Live>{hero}</Live>
             </div>
           )}
           <div className="mx-auto flex w-full max-w-[90rem] gap-16 px-5 pt-12 pb-20 sm:px-8 lg:px-12 lg:pt-20 xl:px-20">
@@ -244,7 +246,7 @@ const iconButton =
   "inline-flex size-(--docs-target,2.75rem) shrink-0 cursor-pointer items-center justify-center rounded-md text-muted-foreground hover:bg-muted hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring";
 
 /** The sections, each a link or a fold that opens where the current page is. */
-function Nav({ sections, current, title }: { sections: Section[]; current: string; title: string }) {
+function Nav({ sections, current, title, className }: { sections: Section[]; current: string; title: string; className?: string }) {
   const holds = (s: Section) => s.groups.some((g) => g.links.some((l) => l.href === current || l.children?.some((c) => c.href === current)));
   const [open, setOpen] = useState<Record<string, boolean>>(() => Object.fromEntries(sections.map((s) => [s.id, holds(s)])));
   // moving to a page opens its section; nothing closes on its own
@@ -255,7 +257,7 @@ function Nav({ sections, current, title }: { sections: Section[]; current: strin
   }, [current, sections]);
 
   return (
-    <nav aria-label={title} data-slot="docs-nav" className="min-h-0 flex-1 overflow-y-auto px-3 pb-4 text-sm">
+    <nav aria-label={title} data-slot="docs-nav" className={cx("min-h-0 flex-1 overflow-y-auto px-3 pb-4 text-sm", className)}>
       <ul className="flex flex-col gap-0.5">
         {sections.map((s) => {
           const Icon = s.icon;
@@ -294,7 +296,7 @@ function Nav({ sections, current, title }: { sections: Section[]; current: strin
                     {s.groups.map((g, i) => (
                       <div key={g.heading ?? i} className="flex flex-col">
                         {g.heading && (
-                          <p data-slot="docs-nav-heading" className="px-2.5 pt-1 pb-1 text-xs font-medium tracking-wide text-muted-foreground uppercase">
+                          <p data-slot="docs-nav-heading" className="px-2.5 pt-3 pb-1.5 text-[0.6875rem] font-semibold tracking-[0.08em] text-muted-foreground uppercase first:pt-1">
                             {g.heading}
                           </p>
                         )}
@@ -339,7 +341,7 @@ function NavLink({ link, current }: { link: DocsLink; current: string }) {
       data-slot="docs-nav-link"
       className={cx(
         target,
-        "relative flex items-center rounded-md px-2.5 text-muted-foreground hover:bg-muted hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-ring",
+        "relative flex items-center rounded-md px-2.5 text-canvas-foreground/80 hover:bg-muted hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-ring",
         active && "bg-muted font-medium text-canvas-foreground",
       )}
     >
@@ -416,7 +418,7 @@ function Pager({ prev, next }: { prev?: DocsLink; next?: DocsLink }) {
     "group flex flex-col gap-1 rounded-lg border border-border p-5 transition-colors duration-(--dt-duration-fast) hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring",
   );
   return (
-    <nav aria-label="Previous and next" data-slot="docs-pager" className="grid gap-3 border-t border-border pt-10 sm:grid-cols-2">
+    <nav aria-label="Previous and next" data-slot="docs-pager" className="-mt-4 grid gap-3 sm:grid-cols-2 lg:-mt-8">
       {prev ? (
         <Link href={prev.href} className={card}>
           <span className="flex items-center gap-1.5 text-xs text-muted-foreground">
@@ -448,24 +450,32 @@ export function DocsHeader({
   title,
   lead,
   eyebrow,
+  status,
   children,
 }: {
   title: string;
   lead?: string;
   /** Above the title. Defaults to the section the page sits in. */
   eyebrow?: string;
+  /** How settled the thing the page documents is, beside the eyebrow: a pattern's status. */
+  status?: Status;
   /** The page's actions, beside the title: `PageActions`. */
   children?: ReactNode;
 }) {
   const { section } = useContext(DocsPage);
   const over = eyebrow ?? (section && section !== title ? section : undefined);
   return (
-    <header data-slot="docs-header" className="flex flex-col gap-6 border-b border-border pb-12 lg:pb-16">
+    <header data-slot="docs-header" className="flex flex-col gap-6">
       <div className="flex flex-wrap items-center justify-between gap-4">
-        {over ? (
-          <p data-slot="docs-eyebrow" className="text-xs font-medium tracking-[var(--tracking-widest,0.16em)] text-muted-foreground uppercase">
-            {over}
-          </p>
+        {over || status ? (
+          <span className="flex flex-wrap items-center gap-3">
+            {over && (
+              <p data-slot="docs-eyebrow" className="text-xs font-medium tracking-[var(--tracking-widest,0.16em)] text-muted-foreground uppercase">
+                {over}
+              </p>
+            )}
+            {status && <StatusBadge status={status} />}
+          </span>
         ) : (
           <span />
         )}
@@ -508,7 +518,11 @@ export function DocsFooter({
 }) {
   if (!provenance && !editorial && !source) return null;
   return (
-    <footer data-slot="docs-footer" className="flex flex-wrap items-center gap-x-6 gap-y-2 text-xs text-muted-foreground">
+    // order-last: the page renders its footer before the shell adds the pager, and where a page comes from is the last thing on it
+    <footer
+      data-slot="docs-footer"
+      className="order-last -mt-8 flex flex-wrap items-center gap-x-6 gap-y-2 border-t border-border pt-6 text-xs text-muted-foreground lg:-mt-14"
+    >
       {(provenance || editorial) && (
         <p data-slot="docs-provenance" className="flex items-center gap-2">
           <span
@@ -539,11 +553,11 @@ export function DocsSection({ title, lead, children }: { title: string; lead?: s
     <section data-slot="docs-section" aria-labelledby={id} className="grid gap-x-10 gap-y-8 [counter-increment:docs-section] xl:grid-cols-[5rem_minmax(0,1fr)]">
       <span
         aria-hidden
-        className="pt-2 font-mono text-xs tracking-[var(--tracking-widest,0.16em)] text-muted-foreground before:content-[counter(docs-section,decimal-leading-zero)]"
+        className="font-mono text-xs tracking-[var(--tracking-widest,0.16em)] text-muted-foreground [text-box:trim-both_cap_alphabetic] before:content-[counter(docs-section,decimal-leading-zero)]"
       />
       <div className="flex min-w-0 flex-col gap-10">
         <div className="flex flex-col gap-4">
-          <h2 id={id} data-slot="docs-section-title" className={cx(display, "scroll-mt-24 text-4xl leading-[1.1] tracking-tight md:text-5xl")}>
+          <h2 id={id} data-slot="docs-section-title" className={cx(display, "scroll-mt-24 text-4xl leading-[1.1] tracking-tight [text-box:trim-both_cap_alphabetic] md:text-5xl")}>
             {title}
           </h2>
           {lead && <p className="max-w-2xl text-lg leading-relaxed text-muted-foreground">{lead}</p>}

package/src/styles.css

@@ -1,7 +1,9 @@
 /*
  * The docs' styles, compiled at build and scoped to `[data-designtools]`, so they
- * style the docs and nothing else on the page, and add no specificity: a
- * project's own CSS always wins a tie.
+ * 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

package/src/swatches.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useEffect, useRef, useState } from "react";
+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";
@@ -31,61 +31,73 @@ export function SemanticSwatches({
     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">
-      <div className="grid gap-4 xl:grid-cols-2">
-        {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>
-              <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")}>
-              {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>
+      {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>
-          </article>
-        ))}
-      </div>
+              </div>
+            ))}
+          </div>,
+          f,
+        ),
+      )}
 
-      {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")}>
+      {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="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">
+              <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>
-        </div>
-      )}
+          </div>,
+        )}
 
-      {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")}>
+      {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="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">
+              <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-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})` }} />
+                    <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>
@@ -95,9 +107,8 @@ export function SemanticSwatches({
                 </ul>
               </div>
             ))}
-          </div>
-        </div>
-      )}
+          </div>,
+        )}
     </div>
   );
 }
@@ -191,7 +202,7 @@ 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-12">
       {modes.map((mode) => (
         <PageGrid key={mode} mode={mode} colours={colours} grounds={grounds} />
       ))}
@@ -215,30 +226,30 @@ 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" 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-[40rem] border-collapse text-left text-sm">
+        <caption className="pb-4 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="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-3 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-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-4 py-2.5">
-                    <div className="flex items-center gap-2">
+                  <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-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} 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 && (