@designtools/docs 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @designtools/docs
 
+## 0.2.1
+
+### Patch Changes
+
+- a6d3829: The colour page gives its samples room: no panels round them, one hairline in each sample's own colour, the mode named once over each column, surfaces and utility colours as one row each with their full names and ratios, and the on-the-page table's verdicts as one quiet line (an icon, the ratio, the word) instead of wrapping pills.
+
 ## 0.2.0
 
 ### Minor Changes

package/dist/styles.css

@@ -751,6 +751,11 @@
     height: 2.25rem;
   }
 
+  :where([data-designtools]) .size-10:not([data-docs-content] *), .size-10:where([data-designtools]):not([data-docs-content] *) {
+    width: 2.5rem;
+    height: 2.5rem;
+  }
+
   :where([data-designtools]) .size-14:not([data-docs-content] *), .size-14:where([data-designtools]):not([data-docs-content] *) {
     width: 3.5rem;
     height: 3.5rem;
@@ -818,6 +823,10 @@
     height: 3rem;
   }
 
+  :where([data-designtools]) .h-14:not([data-docs-content] *), .h-14:where([data-designtools]):not([data-docs-content] *) {
+    height: 3.5rem;
+  }
+
   :where([data-designtools]) .h-16:not([data-docs-content] *), .h-16:where([data-designtools]):not([data-docs-content] *) {
     height: 4rem;
   }
@@ -906,14 +915,14 @@
     min-height: 3rem;
   }
 
-  :where([data-designtools]) .min-h-20:not([data-docs-content] *), .min-h-20:where([data-designtools]):not([data-docs-content] *) {
-    min-height: 5rem;
-  }
-
   :where([data-designtools]) .min-h-28:not([data-docs-content] *), .min-h-28:where([data-designtools]):not([data-docs-content] *) {
     min-height: 7rem;
   }
 
+  :where([data-designtools]) .min-h-36:not([data-docs-content] *), .min-h-36:where([data-designtools]):not([data-docs-content] *) {
+    min-height: 9rem;
+  }
+
   :where([data-designtools]) .min-h-40:not([data-docs-content] *), .min-h-40:where([data-designtools]):not([data-docs-content] *) {
     min-height: 10rem;
   }
@@ -970,14 +979,14 @@
     width: 2.75rem;
   }
 
-  :where([data-designtools]) .w-14:not([data-docs-content] *), .w-14:where([data-designtools]):not([data-docs-content] *) {
-    width: 3.5rem;
-  }
-
   :where([data-designtools]) .w-28:not([data-docs-content] *), .w-28:where([data-designtools]):not([data-docs-content] *) {
     width: 7rem;
   }
 
+  :where([data-designtools]) .w-32:not([data-docs-content] *), .w-32:where([data-designtools]):not([data-docs-content] *) {
+    width: 8rem;
+  }
+
   :where([data-designtools]) .w-48:not([data-docs-content] *), .w-48:where([data-designtools]):not([data-docs-content] *) {
     width: 12rem;
   }
@@ -1070,8 +1079,8 @@
     min-width: 36rem;
   }
 
-  :where([data-designtools]) .min-w-\[40rem\]:not([data-docs-content] *), .min-w-\[40rem\]:where([data-designtools]):not([data-docs-content] *) {
-    min-width: 40rem;
+  :where([data-designtools]) .min-w-\[46rem\]:not([data-docs-content] *), .min-w-\[46rem\]:where([data-designtools]):not([data-docs-content] *) {
+    min-width: 46rem;
   }
 
   :where([data-designtools]) .min-w-\[var\(--docs-target\,2\.75rem\)\]:not([data-docs-content] *), .min-w-\[var\(--docs-target\,2\.75rem\)\]:where([data-designtools]):not([data-docs-content] *) {
@@ -1090,6 +1099,10 @@
     flex-shrink: 0;
   }
 
+  :where([data-designtools]) .table-fixed:not([data-docs-content] *), .table-fixed:where([data-designtools]):not([data-docs-content] *) {
+    table-layout: fixed;
+  }
+
   :where([data-designtools]) .border-collapse:not([data-docs-content] *), .border-collapse:where([data-designtools]):not([data-docs-content] *) {
     border-collapse: collapse;
   }
@@ -1507,10 +1520,6 @@
     border-style: solid;
   }
 
-  :where([data-designtools]) .border-\(--border\):not([data-docs-content] *), .border-\(--border\):where([data-designtools]):not([data-docs-content] *) {
-    border-color: var(--border);
-  }
-
   :where([data-designtools]) .border-border:not([data-docs-content] *), .border-border:where([data-designtools]):not([data-docs-content] *) {
     border-color: var(--border, #e2e4e8);
   }
@@ -1896,10 +1905,6 @@
     padding-top: 1.5rem;
   }
 
-  :where([data-designtools]) .pt-8:not([data-docs-content] *), .pt-8:where([data-designtools]):not([data-docs-content] *) {
-    padding-top: 2rem;
-  }
-
   :where([data-designtools]) .pt-10:not([data-docs-content] *), .pt-10:where([data-designtools]):not([data-docs-content] *) {
     padding-top: 2.5rem;
   }
@@ -1960,6 +1965,10 @@
     padding-bottom: 1rem;
   }
 
+  :where([data-designtools]) .pb-5:not([data-docs-content] *), .pb-5:where([data-designtools]):not([data-docs-content] *) {
+    padding-bottom: 1.25rem;
+  }
+
   :where([data-designtools]) .pb-20:not([data-docs-content] *), .pb-20:where([data-designtools]):not([data-docs-content] *) {
     padding-bottom: 5rem;
   }
@@ -1996,6 +2005,10 @@
     vertical-align: middle;
   }
 
+  :where([data-designtools]) .align-top:not([data-docs-content] *), .align-top:where([data-designtools]):not([data-docs-content] *) {
+    vertical-align: top;
+  }
+
   :where([data-designtools]) .\[font-family\:var\(--docs-display\,var\(--font-display\,var\(--font-sans\)\)\)\]:not([data-docs-content] *), .\[font-family\:var\(--docs-display\,var\(--font-display\,var\(--font-sans\)\)\)\]:where([data-designtools]):not([data-docs-content] *) {
     font-family: var(--docs-display, var(--font-display, var(--font-sans)));
   }
@@ -2326,8 +2339,8 @@
     opacity: .7;
   }
 
-  :where([data-designtools]) .opacity-75:not([data-docs-content] *), .opacity-75:where([data-designtools]):not([data-docs-content] *) {
-    opacity: .75;
+  :where([data-designtools]) .opacity-80:not([data-docs-content] *), .opacity-80:where([data-designtools]):not([data-docs-content] *) {
+    opacity: .8;
   }
 
   :where([data-designtools]) .shadow:not([data-docs-content] *), .shadow:where([data-designtools]):not([data-docs-content] *) {
@@ -2415,6 +2428,20 @@
     box-shadow: var(--tw-inset-shadow), var(--tw-inset-ring-shadow), var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow);
   }
 
+  :where([data-designtools]) .ring-\(--border\):not([data-docs-content] *), .ring-\(--border\):where([data-designtools]):not([data-docs-content] *) {
+    --tw-ring-color: var(--border);
+  }
+
+  :where([data-designtools]) .ring-\(--canvas-foreground\)\/15:not([data-docs-content] *), .ring-\(--canvas-foreground\)\/15:where([data-designtools]):not([data-docs-content] *) {
+    --tw-ring-color: var(--canvas-foreground);
+  }
+
+  @supports (color: color-mix(in lab, red, red)) {
+    :where([data-designtools]) .ring-\(--canvas-foreground\)\/15:not([data-docs-content] *), .ring-\(--canvas-foreground\)\/15:where([data-designtools]):not([data-docs-content] *) {
+      --tw-ring-color: color-mix(in oklab, var(--canvas-foreground) 15%, transparent);
+    }
+  }
+
   :where([data-designtools]) .ring-border:not([data-docs-content] *), .ring-border:where([data-designtools]):not([data-docs-content] *) {
     --tw-ring-color: var(--border, #e2e4e8);
   }
@@ -2423,13 +2450,13 @@
     --tw-ring-color: var(--canvas, #fff);
   }
 
-  :where([data-designtools]) .ring-current\/30:not([data-docs-content] *), .ring-current\/30:where([data-designtools]):not([data-docs-content] *) {
+  :where([data-designtools]) .ring-current\/15:not([data-docs-content] *), .ring-current\/15:where([data-designtools]):not([data-docs-content] *) {
     --tw-ring-color: currentcolor;
   }
 
   @supports (color: color-mix(in lab, red, red)) {
-    :where([data-designtools]) .ring-current\/30:not([data-docs-content] *), .ring-current\/30:where([data-designtools]):not([data-docs-content] *) {
-      --tw-ring-color: color-mix(in oklab, currentcolor 30%, transparent);
+    :where([data-designtools]) .ring-current\/15:not([data-docs-content] *), .ring-current\/15:where([data-designtools]):not([data-docs-content] *) {
+      --tw-ring-color: color-mix(in oklab, currentcolor 15%, transparent);
     }
   }
 
@@ -2678,15 +2705,6 @@
     margin-left: -.375rem;
   }
 
-  :where([data-designtools]) .first\:border-t-0:first-child:not([data-docs-content] *), .first\:border-t-0:first-child:where([data-designtools]):not([data-docs-content] *) {
-    border-top-style: var(--tw-border-style);
-    border-top-width: 0;
-  }
-
-  :where([data-designtools]) .first\:pt-0:first-child:not([data-docs-content] *), .first\:pt-0:first-child:where([data-designtools]):not([data-docs-content] *) {
-    padding-top: 0;
-  }
-
   :where([data-designtools]) .first\:pt-1:first-child:not([data-docs-content] *), .first\:pt-1:first-child:where([data-designtools]):not([data-docs-content] *) {
     padding-top: .25rem;
   }
@@ -3040,6 +3058,10 @@
       grid-template-columns: repeat(2, minmax(0, 1fr));
     }
 
+    :where([data-designtools]) .md\:grid-cols-\[9rem_repeat\(var\(--modes\)\,minmax\(0\,1fr\)\)\]:not([data-docs-content] *), .md\:grid-cols-\[9rem_repeat\(var\(--modes\)\,minmax\(0\,1fr\)\)\]:where([data-designtools]):not([data-docs-content] *) {
+      grid-template-columns: 9rem repeat(var(--modes),minmax(0,1fr));
+    }
+
     :where([data-designtools]) .md\:grid-cols-\[11rem_minmax\(0\,1fr\)\]:not([data-docs-content] *), .md\:grid-cols-\[11rem_minmax\(0\,1fr\)\]:where([data-designtools]):not([data-docs-content] *) {
       grid-template-columns: 11rem minmax(0, 1fr);
     }
@@ -3159,10 +3181,6 @@
       grid-template-columns: 3rem minmax(0, 1fr);
     }
 
-    :where([data-designtools]) .lg\:grid-cols-\[11rem_minmax\(0\,1fr\)\]:not([data-docs-content] *), .lg\:grid-cols-\[11rem_minmax\(0\,1fr\)\]:where([data-designtools]):not([data-docs-content] *) {
-      grid-template-columns: 11rem minmax(0, 1fr);
-    }
-
     :where([data-designtools]) .lg\:grid-cols-\[19rem_minmax\(0\,1fr\)\]:not([data-docs-content] *), .lg\:grid-cols-\[19rem_minmax\(0\,1fr\)\]:where([data-designtools]):not([data-docs-content] *) {
       grid-template-columns: 19rem minmax(0, 1fr);
     }

package/dist/swatches.d.ts

@@ -1,11 +1,12 @@
 import { type Mode } from "./lib/manifest.js";
 import type { TokensManifest } from "./lib/manifest-types.js";
 /**
- * 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 declare function SemanticSwatches({ tokens, modes, }: {
     tokens: TokensManifest;
@@ -15,7 +16,7 @@ export declare function SemanticSwatches({ tokens, modes, }: {
  * 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 declare function PageContrast({ tokens, modes }: {

package/dist/swatches.js

@@ -1,15 +1,17 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Check, Square, X } from "lucide-react";
 import { useEffect, useRef, useState } from "react";
 import { contrastRatio, wcagGrade } from "./lib/contrast.js";
 import { cx } from "./lib/cx.js";
 import { ramps, semanticColours, valueIn } from "./lib/manifest.js";
 /**
- * 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, modes = ["light", "dark"], }) {
     const colours = semanticColours(tokens);
@@ -22,13 +24,17 @@ export function SemanticSwatches({ tokens, modes = ["light", "dark"], }) {
         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) => 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) => _jsx("span", { className: "text-xs font-medium text-muted-foreground capitalize", children: mode });
-    const row = (title, meta, body, key) => (_jsxs("div", { "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)]", children: [_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsx("h3", { className: "text-2xl leading-tight tracking-tight", children: title }), meta] }), body] }, key ?? title));
-    return (_jsxs("div", { "data-slot": "swatches", className: "flex flex-col gap-10", children: [families.map((f) => row((([first, ...rest]) => first.toUpperCase() + rest.join(""))(f.slice(2).replace(/-/g, " ")), _jsx("code", { className: "font-mono text-xs text-muted-foreground", children: f }), _jsx("div", { className: cx("grid gap-4", modes.length > 1 && "md:grid-cols-2"), children: modes.map((mode) => (_jsxs("div", { "data-theme": mode, "data-slot": "swatch-family", className: panel(mode), children: [modeLabel(mode), _jsx(Chip, { name: f, label: "fill", step: step(f, mode), size: "lg" }), _jsxs("div", { className: "grid grid-cols-3 gap-2", children: [_jsx(Chip, { name: `${f}-subdued`, label: "subdued", step: step(`${f}-subdued`, mode) }), byName.has(`${f}-hover`) && _jsx(Chip, { name: `${f}-hover`, foreground: `${f}-foreground`, label: "hover" }), byName.has(`${f}-active`) && _jsx(Chip, { name: `${f}-active`, foreground: `${f}-foreground`, label: "press" })] })] }, mode))) }), f)), surfaces.length > 0 &&
-                row("Surfaces", _jsx("p", { className: "text-sm text-muted-foreground", children: "The page, panels and popups, each with its text." }), _jsx("div", { className: cx("grid gap-4", modes.length > 1 && "md:grid-cols-2"), children: modes.map((mode) => (_jsxs("div", { "data-theme": mode, className: panel(mode), children: [modeLabel(mode), _jsx("div", { className: "grid grid-cols-2 gap-2 xl:grid-cols-3", children: surfaces.map((name) => (_jsx(Chip, { name: name, label: name.slice(2), step: step(name, mode), outlined: true }, name))) })] }, mode))) })), utility.length > 0 &&
-                row("Lines, focus and shadow", _jsx("p", { className: "text-sm text-muted-foreground", children: "Borders, input edges, the focus ring and the shadow colour." }), _jsx("div", { className: cx("grid gap-4", modes.length > 1 && "md:grid-cols-2"), children: modes.map((mode) => (_jsxs("div", { "data-theme": mode, className: panel(mode), children: [modeLabel(mode), _jsx("ul", { className: "grid grid-cols-2 gap-x-4 gap-y-3", children: utility.map((name) => (_jsxs("li", { "data-slot": "swatch", className: "flex items-center gap-3", children: [_jsx("span", { "aria-hidden": true, className: "size-9 shrink-0 rounded-lg border border-border", style: { background: `var(${name})` } }), _jsxs("span", { className: "flex min-w-0 flex-col font-mono text-xs", children: [_jsx("span", { className: "truncate font-medium", children: name.slice(2) }), _jsx("span", { className: "truncate text-muted-foreground", children: step(name, mode) })] })] }, name))) })] }, mode))) }))] }));
+    const columns = cx("grid gap-x-8 gap-y-6", modes.length > 1 && "md:grid-cols-2");
+    const modeLabel = (mode) => _jsx("p", { className: "text-xs font-medium text-muted-foreground capitalize", children: mode });
+    const title = (text) => text.charAt(0).toUpperCase() + text.slice(1);
+    return (_jsxs("div", { "data-slot": "swatches", className: "flex flex-col gap-16", children: [_jsx("div", { className: "flex flex-col gap-14", children: families.map((f) => (_jsxs("section", { "data-slot": "swatch-family", className: "flex flex-col gap-5", children: [_jsxs("header", { className: "flex items-baseline gap-3", children: [_jsx("h3", { className: "text-2xl leading-tight tracking-tight", children: title(f.slice(2).replace(/-/g, " ")) }), _jsx("code", { className: "font-mono text-xs text-muted-foreground", children: f })] }), _jsx("div", { className: columns, children: modes.map((mode) => (_jsxs("div", { className: "flex flex-col gap-2.5", children: [modeLabel(mode), _jsxs("div", { "data-theme": mode, className: "flex flex-col gap-2.5", children: [_jsx(Chip, { name: f, label: "fill", step: step(f, mode), size: "lg" }), _jsxs("div", { className: "grid grid-cols-3 gap-2.5", children: [_jsx(Chip, { name: `${f}-subdued`, label: "subdued", step: step(`${f}-subdued`, mode) }), byName.has(`${f}-hover`) && _jsx(Chip, { name: `${f}-hover`, foreground: `${f}-foreground`, label: "hover" }), byName.has(`${f}-active`) && _jsx(Chip, { name: `${f}-active`, foreground: `${f}-foreground`, label: "press" })] })] })] }, mode))) })] }, f))) }), surfaces.length > 0 && (_jsx(Rows, { title: "Surfaces", lead: "The page, panels and popups, and the brand's own backgrounds, each with its text.", modes: modes, children: surfaces.map((name) => (_jsx(Row, { name: name.slice(2), modes: modes, children: (mode) => (_jsx("div", { "data-theme": mode, children: _jsx(Chip, { name: name, label: step(name, mode) ?? "", size: "wide" }) })) }, name))) })), utility.length > 0 && (_jsx(Rows, { title: "Lines, focus and shadow", lead: "Borders, input edges, the focus ring and the shadow colour.", modes: modes, children: utility.map((name) => (_jsx(Row, { name: name.slice(2), modes: modes, children: (mode) => (_jsxs("span", { className: "flex h-14 items-center gap-3", children: [_jsx("span", { "data-theme": mode, "aria-hidden": true, className: "size-10 shrink-0 rounded-lg ring-1 ring-(--canvas-foreground)/15 ring-inset", style: { background: `var(${name})` } }), _jsx("span", { className: "font-mono text-xs text-muted-foreground", children: step(name, mode) })] })) }, name))) }))] }));
+}
+/** A titled list of rows, with the mode names once over the columns. */
+function Rows({ title, lead, modes, children }) {
+    return (_jsxs("section", { className: "flex flex-col gap-5", children: [_jsxs("header", { className: "flex flex-col gap-1.5", children: [_jsx("h3", { className: "text-2xl leading-tight tracking-tight", children: title }), _jsx("p", { className: "text-sm text-muted-foreground", children: lead })] }), _jsxs("div", { children: [_jsxs("div", { "aria-hidden": true, 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 }, children: [_jsx("span", {}), modes.map((m) => (_jsx("span", { className: "capitalize", children: m }, m)))] }), children] })] }));
+}
+function Row({ name, modes, children }) {
+    return (_jsxs("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 }, children: [_jsx("code", { className: "font-mono text-sm", children: name }), modes.map((mode) => (_jsxs("div", { className: "flex flex-col gap-1", children: [_jsx("span", { className: "text-xs text-muted-foreground capitalize md:hidden", children: mode }), children(mode)] }, mode)))] }));
 }
 /** `var(--color-primary-500)` → `primary-500`: the step it points at, which is what a person compares. */
 function pointsAt(value) {
@@ -38,11 +44,11 @@ function pointsAt(value) {
     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.
+ * 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, foreground = `${name}-foreground`, label, step, size = "md", outlined, }) {
+function Chip({ name, foreground = `${name}-foreground`, label, step, size = "md", }) {
     const chip = useRef(null);
     const [ratio, setRatio] = useState(null);
     useEffect(() => {
@@ -55,20 +61,42 @@ function Chip({ name, foreground = `${name}-foreground`, label, step, size = "md
     const grade = ratio === null ? null : wcagGrade(ratio);
     const fails = grade === "Fail";
     const measured = grade && ratio !== null ? `${ratio.toFixed(1)}:1 ${grade}` : undefined;
-    return (_jsxs("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})` }, children: [size === "lg" ? (_jsxs("span", { className: "flex items-start justify-between gap-2", children: [_jsx("span", { className: "text-3xl leading-none tracking-tight", children: "Aa" }), measured && (_jsx("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"), children: measured }))] })) : (_jsx("span", { className: "text-base leading-none font-medium", children: "Aa" })), _jsxs("span", { className: "flex min-w-0 flex-col font-mono text-xs leading-snug", children: [_jsx("span", { className: "truncate font-medium", children: label }), size === "lg" ? (step && _jsx("span", { className: "truncate opacity-75", children: step })) : (measured && (_jsx("span", { "data-slot": "swatch-contrast", className: cx("truncate", fails ? "w-fit rounded-sm bg-destructive px-1 text-destructive-foreground" : "opacity-75"), children: measured })))] })] }));
+    const contrast = measured && (_jsx("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"), children: measured }));
+    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 (_jsxs("div", { ref: chip, "data-slot": "swatch", title: tip, className: cx(base, "flex h-14 items-center justify-between gap-4 px-4"), style: paint, children: [_jsxs("span", { className: "flex min-w-0 items-baseline gap-3", children: [_jsx("span", { className: "text-xl leading-none font-medium", children: "Aa" }), _jsx("span", { className: "font-mono text-xs opacity-80", children: label })] }), contrast] }));
+    if (size === "lg")
+        return (_jsxs("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, children: [_jsxs("span", { className: "flex items-start justify-between gap-3", children: [_jsx("span", { className: "text-5xl leading-none tracking-tight", children: "Aa" }), contrast] }), _jsxs("span", { className: "flex flex-col gap-0.5 text-sm leading-snug", children: [_jsx("span", { className: "font-medium", children: label }), step && _jsx("span", { className: "font-mono text-xs opacity-80", children: step })] })] }));
+    return (_jsxs("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, children: [_jsx("span", { className: "text-2xl leading-none font-medium", children: "Aa" }), _jsxs("span", { className: "flex flex-col gap-1 leading-snug", children: [_jsx("span", { className: "text-sm font-medium", children: label }), contrast] })] }));
 }
 /**
  * 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"] }) {
     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 (_jsx("div", { "data-slot": "page-contrast", className: "flex flex-col gap-12", children: modes.map((mode) => (_jsx(PageGrid, { mode: mode, colours: colours, grounds: grounds }, mode))) }));
+    return (_jsxs("div", { "data-slot": "page-contrast", className: "flex flex-col gap-14", children: [_jsx("p", { className: "flex flex-wrap gap-x-6 gap-y-2 text-sm text-muted-foreground", children: [
+                    ["text", "fine as text, 4.5:1"],
+                    ["shape", "fine as a shape only, 3:1"],
+                    ["none", "neither"],
+                ].map(([mark, words]) => (_jsxs("span", { className: "inline-flex items-center gap-2", children: [_jsx(Verdict, { mark: mark }), words] }, mark))) }), modes.map((mode) => (_jsx(PageGrid, { mode: mode, colours: colours, grounds: grounds }, mode)))] }));
+}
+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" },
+};
+function Verdict({ mark, ratio }) {
+    const { Icon, className, label } = VERDICT[mark];
+    return (_jsxs("span", { className: "inline-flex items-center gap-1.5 whitespace-nowrap", children: [_jsx(Icon, { "aria-hidden": true, className: cx("size-3.5 shrink-0", className), strokeWidth: 2.5 }), ratio != null && _jsx("span", { className: "font-mono text-xs text-canvas-foreground tabular-nums", children: ratio.toFixed(1) }), _jsx("span", { className: cx(ratio != null && "text-xs text-muted-foreground"), children: ratio != null ? label : null })] }));
 }
 function PageGrid({ mode, colours, grounds }) {
     const probe = useRef(null);
@@ -88,10 +116,10 @@ function PageGrid({ mode, colours, grounds }) {
                 out[`${c}|${g}`] = contrastRatio(painted[c], painted[g]);
         setRatios(out);
     }, [colours, grounds]);
-    return (_jsxs("div", { className: "-mx-1 overflow-x-auto px-1", tabIndex: 0, role: "region", "aria-label": `Colours on each background, ${mode} mode`, children: [_jsx("div", { ref: probe, "data-theme": mode, hidden: true }), _jsxs("table", { className: "w-full min-w-[40rem] border-collapse text-left text-sm", children: [_jsx("caption", { className: "pb-4 text-left text-lg font-medium capitalize", children: mode }), _jsx("thead", { children: _jsxs("tr", { className: "text-xs text-muted-foreground", children: [_jsx("th", { scope: "col", className: "pr-4 pb-3 font-medium", children: "Colour" }), grounds.map((g) => (_jsx("th", { scope: "col", className: "px-3 pb-3 font-mono font-normal", children: g.slice(2) }, g)))] }) }), _jsx("tbody", { children: colours.map((c) => (_jsxs("tr", { className: "border-t border-border", children: [_jsx("th", { scope: "row", className: "py-3.5 pr-4 font-mono text-xs font-medium", children: c.slice(2) }), grounds.map((g) => {
+    return (_jsxs("div", { className: "-mx-1 overflow-x-auto px-1 pb-2", tabIndex: 0, role: "region", "aria-label": `Colours on each background, ${mode} mode`, children: [_jsx("div", { ref: probe, "data-theme": mode, hidden: true }), _jsxs("table", { className: "w-full min-w-[46rem] table-fixed border-collapse text-left text-sm", children: [_jsx("caption", { className: "pb-5 text-left text-lg font-medium capitalize", children: mode }), _jsx("thead", { children: _jsxs("tr", { className: "text-xs text-muted-foreground", children: [_jsx("th", { scope: "col", className: "w-32 pr-4 pb-3 font-medium", children: "Colour" }), grounds.map((g) => (_jsx("th", { scope: "col", className: "px-2 pb-3 font-mono font-normal", children: g.slice(2) }, g)))] }) }), _jsx("tbody", { children: colours.map((c) => (_jsxs("tr", { className: "border-t border-border", children: [_jsx("th", { scope: "row", className: "py-4 pr-4 align-top font-mono text-xs font-medium break-words", children: c.slice(2) }), grounds.map((g) => {
                                     const r = ratios[`${c}|${g}`];
-                                    const mark = r == null ? "" : r >= 4.5 ? "text" : r >= 3 ? "shape" : "none";
-                                    return (_jsx("td", { className: "px-3 py-3.5", children: _jsxs("div", { className: "flex items-center gap-2.5", children: [_jsx("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": true, children: "Aa" }), r != null && (_jsxs("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"), children: [r.toFixed(1), " ", mark] }))] }) }, g));
+                                    const mark = r == null ? undefined : r >= 4.5 ? "text" : r >= 3 ? "shape" : "none";
+                                    return (_jsx("td", { className: "px-2 py-4 align-top", children: _jsxs("div", { className: "flex flex-col gap-2", children: [_jsx("span", { "data-theme": mode, "aria-hidden": true, 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})` }, children: "Aa" }), mark && r != null && _jsx(Verdict, { mark: mark, ratio: r })] }) }, g));
                                 })] }, c))) })] })] }));
 }
 /** The primitive ramps, one row per colour family, each step painted from its own token. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@designtools/docs",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Design system docs as a package: pages, navigation, search, a workbench per component, rules, patterns, brand pages and markdown for agents, generated from the @designtools/manifest and themed by your tokens. One Next adapter serves them inside your app or as a standalone site.",
   "type": "module",
   "license": "MIT",

package/src/swatches.tsx

@@ -1,17 +1,19 @@
 "use client";
 
-import { type ReactNode, 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,85 +32,107 @@ 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);
 
-  // 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}
+  return (
+    <div data-slot="swatches" className="flex flex-col gap-16">
+      <div className="flex flex-col gap-14">
+        {families.map((f) => (
+          <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={columns}>
+              {modes.map((mode) => (
+                <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>
+          </section>
+        ))}
       </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" />}
+      {surfaces.length > 0 && (
+        <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>,
-          f,
-        ),
+              )}
+            </Row>
+          ))}
+        </Rows>
       )}
 
-      {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 && (
+        <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>
+  );
+}
 
-      {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>,
-        )}
+/** 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>
   );
 }
@@ -121,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,
@@ -131,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);
@@ -151,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>
   );
@@ -194,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[] }) {
@@ -202,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-12">
+    <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} />
       ))}
@@ -210,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>>({});
@@ -226,44 +284,44 @@ function PageGrid({ mode, colours, grounds }: { mode: Mode; colours: string[]; 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 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-[40rem] border-collapse text-left text-sm">
-        <caption className="pb-4 text-left text-lg font-medium 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="text-xs text-muted-foreground">
-            <th scope="col" className="pr-4 pb-3 font-medium">Colour</th>
+            <th scope="col" className="w-32 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>
+              <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-t border-border">
-              <th scope="row" className="py-3.5 pr-4 font-mono text-xs font-medium">{c.slice(2)}</th>
+              <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-3 py-3.5">
-                    <div className="flex items-center gap-2.5">
+                  <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-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>
+                      <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>
                 );