@designtools/docs 0.1.0 → 0.2.0

package/dist/swatches.js

@@ -22,7 +22,13 @@ export function SemanticSwatches({ tokens, modes = ["light", "dark"], }) {
         const token = byName.get(name)?.background;
         return token && pointsAt(valueIn(token, mode));
     };
-    return (_jsxs("div", { "data-slot": "swatches", className: "flex flex-col gap-10", children: [_jsx("div", { className: "grid gap-4 xl:grid-cols-2", children: families.map((f) => (_jsxs("article", { "data-slot": "swatch-family", className: "flex flex-col overflow-hidden rounded-xl border border-border bg-surface text-surface-foreground", children: [_jsxs("header", { className: "flex items-baseline justify-between gap-3 px-4 py-3", children: [_jsx("h3", { className: "text-lg capitalize", children: f.slice(2).replace(/-/g, " ") }), _jsx("code", { className: "font-mono text-xs text-muted-foreground", children: f })] }), _jsx("div", { className: cx("grid border-t border-border", modes.length > 1 && "sm:grid-cols-2"), children: modes.map((mode) => (_jsxs("div", { "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", children: [_jsx("span", { className: "text-xs font-medium text-muted-foreground capitalize", children: 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 && (_jsxs("div", { className: "flex flex-col gap-3", children: [_jsx("h3", { className: "text-2xl tracking-tight", children: "Surfaces" }), _jsx("div", { className: cx("grid gap-4", modes.length > 1 && "lg:grid-cols-2"), children: modes.map((mode) => (_jsxs("div", { "data-theme": mode, className: "flex flex-col gap-2 rounded-xl border border-border bg-canvas p-3 text-canvas-foreground", children: [_jsx("span", { className: "text-xs font-medium text-muted-foreground capitalize", children: mode }), _jsx("div", { className: "grid grid-cols-2 gap-2 sm: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 && (_jsxs("div", { className: "flex flex-col gap-3", children: [_jsx("h3", { className: "text-2xl tracking-tight", children: "Lines, focus and shadow" }), _jsx("div", { className: cx("grid gap-4", modes.length > 1 && "lg:grid-cols-2"), children: modes.map((mode) => (_jsxs("div", { "data-theme": mode, className: "flex flex-col gap-2 rounded-xl border border-border bg-canvas p-3 text-canvas-foreground", children: [_jsx("span", { className: "text-xs font-medium text-muted-foreground capitalize", children: mode }), _jsx("ul", { className: "grid grid-cols-2 gap-2", children: utility.map((name) => (_jsxs("li", { "data-slot": "swatch", className: "flex items-center gap-2 rounded-lg bg-surface p-2 text-surface-foreground", children: [_jsx("span", { "aria-hidden": true, className: "size-8 shrink-0 rounded-md 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))) })] }))] }));
+    // 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))) }))] }));
 }
 /** `var(--color-primary-500)` → `primary-500`: the step it points at, which is what a person compares. */
 function pointsAt(value) {
@@ -62,7 +68,7 @@ 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-6", children: modes.map((mode) => (_jsx(PageGrid, { mode: mode, colours: colours, grounds: grounds }, mode))) }));
+    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))) }));
 }
 function PageGrid({ mode, colours, grounds }) {
     const probe = useRef(null);
@@ -82,10 +88,10 @@ function PageGrid({ mode, colours, grounds }) {
                 out[`${c}|${g}`] = contrastRatio(painted[c], painted[g]);
         setRatios(out);
     }, [colours, grounds]);
-    return (_jsxs("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`, children: [_jsx("div", { ref: probe, "data-theme": mode, hidden: true }), _jsxs("table", { className: "w-full min-w-[32rem] border-collapse text-left text-sm", children: [_jsx("caption", { className: "border-b border-border px-4 py-3 text-left text-sm font-semibold capitalize", children: mode }), _jsx("thead", { children: _jsxs("tr", { className: "border-b border-border bg-muted/50 text-xs text-muted-foreground", children: [_jsx("th", { scope: "col", className: "px-4 py-2.5 font-medium", children: "Colour" }), grounds.map((g) => (_jsx("th", { scope: "col", className: "px-4 py-2.5 font-mono font-medium", children: g.slice(2) }, g)))] }) }), _jsx("tbody", { children: colours.map((c) => (_jsxs("tr", { className: "border-b border-border last:border-b-0", children: [_jsx("th", { scope: "row", className: "px-4 py-2.5 font-mono text-xs font-medium", children: c.slice(2) }), grounds.map((g) => {
+    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) => {
                                     const r = ratios[`${c}|${g}`];
                                     const mark = r == null ? "" : r >= 4.5 ? "text" : r >= 3 ? "shape" : "none";
-                                    return (_jsx("td", { className: "px-4 py-2.5", children: _jsxs("div", { className: "flex items-center gap-2", children: [_jsx("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": 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));
+                                    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));
                                 })] }, c))) })] })] }));
 }
 /** The primitive ramps, one row per colour family, each step painted from its own token. */

package/dist/variant-matrix.js

@@ -1,5 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Live } from "./lib/live.js";
 import { Grid3x3, Moon, Sun } from "lucide-react";
 import { useEffect, useState } from "react";
 import { cx } from "./lib/cx.js";
@@ -22,17 +23,21 @@ export function VariantMatrix({ entry, props = {}, children, axes: only, }) {
     if (axes.length === 0)
         return _jsxs("p", { className: "text-sm text-muted-foreground", children: [entry.name, " has no variants."] });
     const content = children ?? entry.name;
-    const render = (extra) => (_jsx(Component, { ...props, ...coerce(extra), children: content }));
+    const render = (extra) => (_jsx(Live, { children: _jsx(Component, { ...props, ...coerce(extra), children: content }) }));
     const [rows, cols, ...rest] = axes;
     const toggle = (_jsx(IconButton, { icon: theme === "dark" ? Sun : Moon, label: theme === "dark" ? "Show in light mode" : "Show in dark mode", pressed: theme !== undefined, onClick: () => setTheme(theme === "dark" ? "light" : "dark") }));
-    return (_jsxs("div", { "data-slot": "variant-matrix", className: "flex flex-col gap-6", children: [cols ? (_jsxs(Frame, { children: [_jsxs(Toolbar, { children: [_jsxs("span", { className: "flex items-center gap-2 pl-2 font-mono text-xs text-muted-foreground", children: [_jsx(Grid3x3, { "aria-hidden": true, className: "size-(--dt-size-xs)" }), rows.name, " \u00D7 ", cols.name] }), toggle] }), _jsx("div", { "data-docs-stage": "", "data-theme": theme, className: "overflow-x-auto bg-canvas text-canvas-foreground", tabIndex: 0, role: "region", "aria-label": "Variants", children: _jsxs("table", { className: "w-full border-collapse text-sm", children: [_jsxs("caption", { className: "sr-only", children: [entry.name, ": ", rows.name, " by ", cols.name] }), _jsx("thead", { children: _jsxs("tr", { className: "border-b border-border", children: [_jsx("th", { scope: "col", className: "w-0 p-0" }), cols.options.map((c) => (_jsx("th", { scope: "col", title: c.description, className: "px-4 py-3 text-center font-mono text-xs font-medium text-muted-foreground", children: _jsx(OptionName, { axis: cols, option: c.name }) }, c.name)))] }) }), _jsx("tbody", { children: rows.options.map((r) => (_jsxs("tr", { className: "border-b border-border last:border-b-0", children: [_jsx("th", { scope: "row", title: r.description, className: "border-r border-border px-4 py-5 text-left font-mono text-xs font-medium whitespace-nowrap text-muted-foreground", children: _jsx(OptionName, { axis: rows, option: r.name }) }), cols.options.map((c) => (_jsx("td", { "data-slot": "variant-cell", className: "px-4 py-5 text-center align-middle", children: _jsx("span", { className: "inline-flex justify-center", children: render({ [rows.name]: r.name, [cols.name]: c.name }) }) }, c.name)))] }, r.name))) })] }) })] })) : (_jsx(AxisRow, { axis: rows, render: render, theme: theme, toggle: toggle })), rest.map((axis) => (_jsx(AxisRow, { axis: axis, render: render, theme: theme, toggle: toggle }, axis.name))), _jsx(States, { render: render, theme: theme, toggle: toggle, canDisable: "disabled" in entry.props })] }));
+    return (_jsxs(Frame, { "data-slot": "variant-matrix", children: [_jsxs(Toolbar, { children: [_jsxs("span", { className: "flex items-center gap-2 pl-2 font-mono text-xs text-muted-foreground", children: [_jsx(Grid3x3, { "aria-hidden": true, className: "size-(--dt-size-xs)" }), cols ? `${rows.name} × ${cols.name}` : rows.name, rest.length > 0 && `, ${rest.map((a) => a.name).join(", ")}`] }), toggle] }), _jsxs("div", { "data-docs-stage": "", "data-theme": theme, className: "flex flex-col gap-12 bg-canvas px-6 py-8 text-canvas-foreground sm:px-8", children: [cols ? (_jsx("div", { className: "overflow-x-auto", tabIndex: 0, role: "region", "aria-label": "Variants", children: _jsxs("table", { className: "w-full border-collapse text-sm", children: [_jsxs("caption", { className: "sr-only", children: [entry.name, ": ", rows.name, " by ", cols.name] }), _jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", className: "w-0 p-0" }), cols.options.map((c) => (_jsx("th", { scope: "col", title: c.description, className: "px-4 pb-4 text-center font-mono text-xs font-normal text-muted-foreground", children: _jsx(OptionName, { axis: cols, option: c.name }) }, c.name)))] }) }), _jsx("tbody", { children: rows.options.map((r) => (_jsxs("tr", { children: [_jsx("th", { scope: "row", title: r.description, className: "py-4 pr-6 text-left font-mono text-xs font-normal whitespace-nowrap text-muted-foreground", children: _jsx(OptionName, { axis: rows, option: r.name }) }), cols.options.map((c) => (_jsx("td", { "data-slot": "variant-cell", className: "px-4 py-4 text-center align-middle", children: _jsx("span", { className: "inline-flex justify-center", children: render({ [rows.name]: r.name, [cols.name]: c.name }) }) }, c.name)))] }, r.name))) })] }) })) : (_jsx(AxisRow, { axis: rows, render: render })), rest.map((axis) => (_jsx(AxisRow, { axis: axis, render: render }, axis.name))), _jsx(States, { render: render, canDisable: "disabled" in entry.props })] })] }));
+}
+/** A titled row of figures inside the variants stage. */
+function Group({ title, slot, children }) {
+    return (_jsxs("section", { "data-slot": slot, className: "flex flex-col gap-5", children: [_jsx("h3", { className: "font-mono text-xs text-muted-foreground", children: title }), _jsx("div", { className: "flex flex-wrap items-end gap-x-10 gap-y-6", children: children })] }));
 }
 /**
  * The component at its defaults in each state at once: at rest, hovered, focused,
  * pressed and disabled, pinned without a pointer or a keyboard, so states are
  * reviewed side by side rather than by mousing over each.
  */
-function States({ render, theme, toggle, canDisable, }) {
+function States({ render, canDisable }) {
     useEffect(() => installPseudoStates(), []);
     const states = [
         { name: "rest" },
@@ -41,10 +46,10 @@ function States({ render, theme, toggle, canDisable, }) {
         { name: "press", pseudo: "active" },
         ...(canDisable ? [{ name: "disabled", extra: { disabled: "true" } }] : []),
     ];
-    return (_jsxs(Frame, { "data-slot": "variant-states", children: [_jsxs(Toolbar, { children: [_jsx("span", { className: "pl-2 font-mono text-xs text-muted-foreground", children: "state" }), toggle] }), _jsx("div", { "data-docs-stage": "", "data-theme": theme, className: "flex flex-wrap items-end justify-center gap-x-10 gap-y-6 bg-canvas px-6 py-8 text-canvas-foreground", children: states.map((s) => (_jsxs("figure", { className: "flex flex-col items-center gap-3", children: [_jsx("div", { "data-pseudo": s.pseudo, children: render(s.extra ?? {}) }), _jsx("figcaption", { className: "font-mono text-xs text-muted-foreground", children: s.name })] }, s.name))) })] }));
+    return (_jsx(Group, { title: "state", slot: "variant-states", children: states.map((s) => (_jsxs("figure", { className: "flex flex-col items-center gap-3", children: [_jsx("div", { "data-pseudo": s.pseudo, children: render(s.extra ?? {}) }), _jsx("figcaption", { className: "font-mono text-xs text-muted-foreground", children: s.name })] }, s.name))) }));
 }
-function AxisRow({ axis, render, theme, toggle, }) {
-    return (_jsxs(Frame, { "data-slot": "variant-axis", children: [_jsxs(Toolbar, { children: [_jsx("span", { className: "pl-2 font-mono text-xs text-muted-foreground", children: axis.name }), toggle] }), _jsx("div", { "data-docs-stage": "", "data-theme": theme, className: "flex flex-wrap items-end justify-center gap-x-10 gap-y-6 bg-canvas px-6 py-8 text-canvas-foreground", children: axis.options.map((o) => (_jsxs("figure", { className: "flex flex-col items-center gap-3", children: [render({ [axis.name]: o.name }), _jsx("figcaption", { className: "font-mono text-xs text-muted-foreground", title: o.description, children: _jsx(OptionName, { axis: axis, option: o.name }) })] }, o.name))) })] }));
+function AxisRow({ axis, render }) {
+    return (_jsx(Group, { title: axis.name, slot: "variant-axis", children: axis.options.map((o) => (_jsxs("figure", { className: "flex flex-col items-center gap-3", children: [render({ [axis.name]: o.name }), _jsx("figcaption", { className: "font-mono text-xs text-muted-foreground", title: o.description, children: _jsx(OptionName, { axis: axis, option: o.name }) })] }, o.name))) }));
 }
 /** An option's name, with the default marked by a dot and said for screen readers. */
 function OptionName({ axis, option }) {

package/dist/voice-terms.js

@@ -1,13 +1,14 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { inline } from "./lib/text.js";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { TermHead, TermRow } from "./lib/terms.js";
+import { DocsSection } from "./shell.js";
 /** The words to use, beside the ones not to: the product's words first, then the system's names that have wrong forms. */
 export function VoiceTerms({ terms }) {
     const product = terms.filter((t) => t.kind === "product");
     const system = terms.filter((t) => t.kind !== "product" && t.wrong?.length);
     if (product.length + system.length === 0)
         return _jsx("p", { className: "text-sm text-muted-foreground", children: "No terms yet. Add them to the taxonomy file." });
-    return (_jsxs("div", { "data-slot": "voice-terms", className: "flex flex-col gap-12", children: [product.length > 0 && _jsx(Group, { title: "In the product", terms: product }), system.length > 0 && _jsx(Group, { title: "In the system", terms: system })] }));
+    return (_jsxs(_Fragment, { children: [product.length > 0 && (_jsx(DocsSection, { title: "In the product", lead: "The words the product uses with the people it serves, in copy, on screens and in emails.", children: _jsx(Terms, { terms: product }) })), system.length > 0 && (_jsx(DocsSection, { title: "In the system", lead: "The names the design system gives its parts, and the ones people reach for instead.", children: _jsx(Terms, { terms: system }) }))] }));
 }
-function Group({ title, terms }) {
-    return (_jsxs("section", { className: "flex flex-col gap-2", children: [_jsx("h3", { className: "text-xs font-medium tracking-wide text-muted-foreground uppercase", children: title }), _jsx("dl", { className: "grid gap-x-12 sm:grid-cols-2", children: terms.map((t) => (_jsxs("div", { "data-slot": "term", className: "flex flex-col gap-1.5 border-t border-border py-5", children: [_jsxs("dt", { className: "text-3xl tracking-tight", children: [t.name, _jsx("span", { className: "sr-only", children: ", say this" })] }), (t.wrong ?? []).length > 0 && (_jsxs("dd", { className: "flex flex-wrap gap-x-3 text-base text-muted-foreground", children: [_jsx("span", { className: "sr-only", children: "not " }), (t.wrong ?? []).map((w) => (_jsx("s", { className: "decoration-destructive decoration-2", children: w }, w)))] })), (t.note || t.kind !== "product") && (_jsx("dd", { className: "text-sm text-muted-foreground", children: t.note ? inline(t.note) : `The ${t.kind}'s name in the code.` }))] }, `${t.kind}:${t.name}`))) })] }));
+function Terms({ terms }) {
+    return (_jsxs("div", { "data-slot": "voice-terms", children: [_jsx(TermHead, {}), _jsx("dl", { children: terms.map((t) => (_jsx(TermRow, { term: t }, `${t.kind}:${t.name}`))) })] }));
 }

package/dist/workbench.js

@@ -1,5 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Live } from "./lib/live.js";
 import { Tabs } from "@base-ui/react/tabs";
 import { Toggle } from "@base-ui/react/toggle";
 import { ToggleGroup } from "@base-ui/react/toggle-group";
@@ -213,7 +214,7 @@ export function Workbench({ entry, props: base = {}, children: initialText = ent
         ? { background: "repeating-conic-gradient(var(--muted) 0 25%, var(--canvas) 0 50%) 0 0 / 16px 16px", color: "var(--canvas-foreground)" }
         : { background: `var(--${view.bg})`, color: `var(--${view.bg}-foreground, var(--canvas-foreground))` };
     const dotted = view.bg === "canvas";
-    const node = (_jsx(Component, { ...base, ...logged, ...chosen, children: content ?? (text || undefined) }));
+    const node = (_jsx(Live, { children: _jsx(Component, { ...base, ...logged, ...chosen, children: content ?? (text || undefined) }) }));
     const scope = [
         entry.name,
         ...Object.entries(variants).map(([k, v]) => `${k} ${v}`),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@designtools/docs",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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/anatomy.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { Live } from "./lib/live";
 import { Layers } from "lucide-react";
 import { useEffect, useId, useRef, useState, type ReactNode } from "react";
 import { cx, target } from "./lib/cx";
@@ -45,7 +46,11 @@ export function Anatomy({
   const module = lookup.examplesFor(entry);
   const first = entry.examples?.canonical?.name ?? entry.examples?.do[0]?.name ?? entry.examples?.other[0]?.name;
   const example =
-    children ?? (module && first ? renderExample(module[first], first) : Component ? <Component>{entry.name}</Component> : null);
+    children ?? (module && first ? renderExample(module[first], first) : Component ? (
+        <Live>
+          <Component>{entry.name}</Component>
+        </Live>
+      ) : null);
 
   const shown = entry.slots.filter((slot) => counts[slot]).length;
   return (

package/src/glossary.tsx

@@ -1,71 +1,70 @@
 "use client";
 
-import { Search } from "lucide-react";
+import { ArrowRight, Search } from "lucide-react";
 import { useId, useState } from "react";
 import type { TermEntry } from "./lib/manifest-types";
-import { inline } from "./lib/text";
+import { TermRow } from "./lib/terms";
 
-/** Every name in the system, searchable by its wrong forms too, so a wrong name finds the right one. */
+/** Every name in the system, searchable by its wrong forms too, so a wrong name finds the right one. A to Z. */
 export function Glossary({ terms }: { terms: TermEntry[] }) {
   const id = useId();
   const [query, setQuery] = useState("");
   const q = query.trim().toLowerCase();
-  const matches = q ? terms.filter((t) => t.name.toLowerCase().includes(q) || t.wrong?.some((w) => w.toLowerCase().includes(q))) : terms;
+  const matches = (q ? terms.filter((t) => t.name.toLowerCase().includes(q) || t.wrong?.some((w) => w.toLowerCase().includes(q))) : terms)
+    .slice()
+    .sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: "base" }));
   const corrected = q ? terms.find((t) => t.wrong?.some((w) => w.toLowerCase() === q)) : undefined;
+  const letters = new Map<string, TermEntry[]>();
+  for (const t of matches) {
+    const l = /[a-z]/i.test(t.name[0]) ? t.name[0].toUpperCase() : "#";
+    letters.set(l, [...(letters.get(l) ?? []), t]);
+  }
 
   return (
-    <div data-slot="glossary" className="flex flex-col gap-5">
-      <div className="flex flex-col gap-2">
+    <div data-slot="glossary" className="flex flex-col gap-10">
+      <div className="flex max-w-3xl flex-col gap-4">
         <label htmlFor={id} className="sr-only">
           Find a term
         </label>
-        <div className="relative max-w-xl">
-          <Search aria-hidden className="pointer-events-none absolute top-1/2 left-4 size-(--dt-size-sm) -translate-y-1/2 text-muted-foreground" />
+        <div className="relative">
+          <Search aria-hidden className="pointer-events-none absolute top-1/2 left-0 size-(--dt-size-md) -translate-y-1/2 text-muted-foreground" />
           <input
             id={id}
             type="search"
             value={query}
             onChange={(e) => setQuery(e.target.value)}
             placeholder="Find a term, or a name you half remember"
-            className="h-(--dt-size-2xl) w-full rounded-lg border border-border bg-canvas pr-4 pl-12 text-base placeholder:text-muted-foreground hover:border-input focus-visible:outline-2 focus-visible:outline-ring"
+            className="h-16 w-full border-0 border-b border-border bg-transparent pr-2 pl-10 text-2xl tracking-tight placeholder:text-muted-foreground/70 hover:border-input focus-visible:border-b-2 focus-visible:border-canvas-foreground focus-visible:outline-none"
           />
         </div>
-        <p aria-live="polite" className="text-sm text-muted-foreground">
+        <div aria-live="polite">
           {corrected ? (
-            <>
-              The system calls “{query.trim()}” <strong className="text-canvas-foreground">{corrected.name}</strong>.
-            </>
-          ) : q ? (
-            `${matches.length} ${matches.length === 1 ? "term" : "terms"}`
+            <p data-slot="glossary-correction" className="flex flex-wrap items-center gap-2 rounded-xl bg-muted/60 px-5 py-4 text-lg">
+              Say <strong className="font-semibold">{corrected.name}</strong>
+              <ArrowRight aria-hidden className="size-4 text-muted-foreground" />
+              <span className="text-muted-foreground">not “{query.trim()}”</span>
+            </p>
           ) : (
-            `${terms.length} terms`
+            <p className="text-sm text-muted-foreground">
+              {q ? `${matches.length} ${matches.length === 1 ? "term" : "terms"}` : `${terms.length} terms, A to Z. Search by the right name or a wrong one.`}
+            </p>
           )}
-        </p>
+        </div>
       </div>
-      <dl data-slot="glossary-list" className="grid gap-x-12 sm:grid-cols-2">
-        {matches.map((t) => (
-          <div key={`${t.kind}:${t.name}`} className="flex flex-col gap-1.5 border-t border-border py-4">
-            <dt className="flex items-center justify-between gap-2">
-              <span className="text-lg">{t.name}</span>
-              <span className="font-mono text-xs text-muted-foreground">{t.kind}</span>
-            </dt>
-            <dd className="flex flex-col gap-1 text-sm text-muted-foreground">
-              {t.wrong?.length ? (
-                <span className="flex flex-wrap items-center gap-1">
-                  Not
-                  {t.wrong.map((w) => (
-                    <s key={w} className="decoration-destructive">
-                      {w}
-                    </s>
-                  ))}
-                </span>
-              ) : null}
-              {t.note && <span>{inline(t.note)}</span>}
-              {t.ref && <code className="font-mono text-xs">{t.ref}</code>}
-            </dd>
-          </div>
+      <div data-slot="glossary-list" className="flex flex-col gap-8">
+        {[...letters].map(([letter, list]) => (
+          <section key={letter} aria-label={letter} className="grid gap-x-8 lg:grid-cols-[3rem_minmax(0,1fr)]">
+            <h3 className="pt-5 text-2xl tracking-tight text-muted-foreground lg:sticky lg:top-24 lg:self-start">{letter}</h3>
+            <div>
+              <dl>
+                {list.map((t) => (
+                  <TermRow key={`${t.kind}:${t.name}`} term={t} kind />
+                ))}
+              </dl>
+            </div>
+          </section>
         ))}
-      </dl>
+      </div>
     </div>
   );
 }

package/src/index.ts

@@ -17,7 +17,7 @@ export { Pattern } from "./pattern";
 export { Playground } from "./playground";
 export { PreviewComposition, PreviewExample, PreviewFrame, PreviewSurface } from "./preview-frame";
 export { PropsTable } from "./props-table";
-export { Rule } from "./rule";
+export { Rule, RuleIndex } from "./rule";
 export { Scale } from "./scale";
 export { DocsSearch } from "./search";
 export { type DocsLink, DocsFooter, DocsHeader, DocsSection, DocsShell } from "./shell";
@@ -29,6 +29,7 @@ export { Usage } from "./usage";
 export { VariantMatrix } from "./variant-matrix";
 export { VoiceTerms } from "./voice-terms";
 export { Workbench } from "./workbench";
+export { Live } from "./lib/live";
 export { type Registry, RegistryProvider, useRegistry } from "./lib/registry";
 export * from "./lib/manifest-types";
 export type { AdherenceReport } from "./lib/adherence-types";

package/src/lib/live.tsx

@@ -0,0 +1,15 @@
+import type { ReactNode } from "react";
+
+/**
+ * Marks the project's own components inside the docs: an example, a workbench, the hero, a rule's
+ * demonstration. The docs' styles never match inside it, so the project's own CSS, its responsive
+ * utilities included, is all that styles its components, whichever stylesheet loads last. It draws
+ * nothing itself (`display: contents`). Wrap the project's components in it on an editorial page.
+ */
+export function Live({ children }: { children: ReactNode }) {
+  return (
+    <div data-docs-content="" style={{ display: "contents" }}>
+      {children}
+    </div>
+  );
+}

package/src/lib/lookup.tsx

@@ -1,3 +1,4 @@
+import { Live } from "./live";
 import { createElement, isValidElement, type ComponentType, type ReactNode } from "react";
 import { componentKey } from "./manifest";
 import type { AssetEntry, ComponentEntry, PatternEntry } from "./manifest-types";
@@ -43,7 +44,7 @@ export function Missing({ name, what = "component" }: { name: string; what?: str
 
 /** An example export is a component that takes no props, or an element. */
 export function renderExample(value: unknown, name: string): ReactNode {
-  if (isValidElement(value)) return value;
-  if (typeof value === "function") return createElement(value as ComponentType);
+  if (isValidElement(value)) return <Live>{value}</Live>;
+  if (typeof value === "function") return <Live>{createElement(value as ComponentType)}</Live>;
   return <span className="text-xs text-muted-foreground">{name} is not a component or an element.</span>;
 }

package/src/lib/status.tsx

@@ -1,8 +1,8 @@
 import { cx } from "./cx";
 
-type Any = "stable" | "emerging" | "deprecated" | "confirmed" | "assumption" | "measured" | "draft" | "published";
+export type Status = "stable" | "emerging" | "deprecated" | "confirmed" | "assumption" | "measured" | "draft" | "published";
 
-const LOOK: Record<Any, string> = {
+const LOOK: Record<Status, string> = {
   stable: "bg-success-subdued text-success-subdued-foreground",
   confirmed: "bg-success-subdued text-success-subdued-foreground",
   published: "bg-success-subdued text-success-subdued-foreground",
@@ -15,7 +15,7 @@ const LOOK: Record<Any, string> = {
 };
 
 /** A status, everywhere one is shown: components, patterns, rules and editorial pages. Unset says so. */
-export function StatusBadge({ status, className }: { status?: Any; className?: string }) {
+export function StatusBadge({ status, className }: { status?: Status; className?: string }) {
   return (
     <span
       data-slot="status-badge"

package/src/lib/terms.tsx

@@ -0,0 +1,53 @@
+import { X } from "lucide-react";
+import type { TermEntry } from "./manifest-types";
+import { inline } from "./text";
+
+/** The wrong forms of a term: quiet chips, each with a cross, so "not this" reads without shouting. */
+export function WrongForms({ wrong }: { wrong?: string[] }) {
+  if (!wrong?.length) return <span className="text-sm text-muted-foreground">None</span>;
+  return (
+    <span className="flex flex-wrap gap-1.5">
+      <span className="sr-only">Not </span>
+      {wrong.map((w) => (
+        <span key={w} data-slot="term-wrong" className="inline-flex min-h-7 items-center gap-1 rounded-md bg-muted px-2 text-sm text-muted-foreground">
+          <X aria-hidden className="size-3 shrink-0" />
+          <span className="line-through decoration-current/40">{w}</span>
+        </span>
+      ))}
+    </span>
+  );
+}
+
+/**
+ * One term on one row: the word to use, the words not to, and why. Three columns on a wide screen, under
+ * the labels `TermHead` draws; stacked on a phone.
+ */
+export function TermRow({ term, kind }: { term: TermEntry; kind?: boolean }) {
+  return (
+    <div data-slot="term" className="grid gap-x-8 gap-y-2 border-t border-border py-5 md:grid-cols-[minmax(10rem,14rem)_minmax(0,1fr)_minmax(0,1.3fr)] md:items-baseline">
+      <dt className="flex items-baseline gap-2">
+        <span className="text-xl leading-snug tracking-tight">{term.name}</span>
+        {kind && <span className="font-mono text-xs text-muted-foreground">{term.kind}</span>}
+        <span className="sr-only">, say this</span>
+      </dt>
+      <dd>
+        <WrongForms wrong={term.wrong} />
+      </dd>
+      <dd className="text-sm leading-relaxed text-muted-foreground">
+        {term.note ? inline(term.note) : term.kind !== "product" ? `The ${term.kind}'s name in the code.` : null}
+        {term.ref && <code className="ml-1 font-mono text-xs">{term.ref}</code>}
+      </dd>
+    </div>
+  );
+}
+
+/** The column labels over a list of `TermRow`s, on a wide screen. */
+export function TermHead() {
+  return (
+    <div aria-hidden className="hidden gap-x-8 pb-3 text-xs font-medium text-muted-foreground md:grid md:grid-cols-[minmax(10rem,14rem)_minmax(0,1fr)_minmax(0,1.3fr)]">
+      <span>Say</span>
+      <span>Not</span>
+      <span>Why</span>
+    </div>
+  );
+}

package/src/next/config.ts

@@ -1,14 +1,30 @@
 import type { ComponentType, ReactElement, ReactNode } from "react";
 import type { AdherenceReport } from "../lib/adherence-types";
 
-/** A page people write: brand, principles, a design language. Markdown, with its author and how settled it is. */
-export interface EditorialPage {
+/** A page people write: brand, principles, a design language, with its author and how settled it is. */
+export type EditorialPage = EditorialBase &
+  (
+    | {
+        /** Markdown: `##` and `###` sections, paragraphs, bullet lists, bold, code and links; a list whose items open in bold is a set of principles. */
+        body: string;
+        markdown?: undefined;
+      }
+    | {
+        /**
+         * The page as React: real components from the project's system beside the docs' own `DocsSection`
+         * and `Prose`, for a page that has to show rather than tell. Rendered as is, under the page header.
+         */
+        body: ReactNode;
+        /** What agents read instead, at the page's `.md`: the same page, in words. */
+        markdown: string;
+      }
+  );
+
+interface EditorialBase {
   /** Its path under the docs, e.g. `brand` or `brand/accessibility`. */
   slug: string;
   title: string;
   lead?: string;
-  /** Markdown: `##` sections, paragraphs, bullet lists; a list whose items open in bold is a set of principles. */
-  body: string;
   by: { author: string; reviewer?: string; reviewed: string; status: "draft" | "published" };
   /** The navigation group it sits in. Default: brand. */
   section?: "brand" | "foundations" | "standards";
@@ -47,6 +63,11 @@ export interface DocsConfig {
   hero?: ReactNode;
   /** The overview's lead, when there is no hero. */
   lead?: string;
+  /**
+   * The overview after its hero or header: `agentic: false` drops "Why this is agentic", and `agenticLead`
+   * replaces the line that opens it.
+   */
+  overview?: { agentic?: boolean; agenticLead?: string };
   /** The generated registry (`designtools-docs map`): a provider for the project's components, examples and assets. */
   registry: ComponentType<{ children: ReactNode }>;
   /** The manifest, as `designtools-manifest build` writes it. */

package/src/next/index.tsx

@@ -10,7 +10,10 @@ import { manifestFiles, manifestRoute, markdownRoute } from "./markdown";
 import { DocsPageView } from "./pages";
 import { allSlugs, metaOf, navOf, resolve, siteOf } from "./site";
 
+export { Live } from "../lib/live";
+export { DocsSection } from "../shell";
 export type { BuiltInPage, DocsConfig, EditorialPage, WorkbenchSetup } from "./config";
+export { Markdown as Prose } from "./prose";
 export { markdownFor } from "./markdown";
 export { docsMatcher, docsProxy, prefersMarkdown } from "./proxy";
 

package/src/next/markdown.ts

@@ -57,7 +57,7 @@ export function markdownFor(site: Site, path: string): string | undefined {
       );
     }
     case "editorial":
-      return `${editorialHeader(page.page.by)}# ${page.page.title}\n\n${page.page.lead ? `${page.page.lead}\n\n` : ""}${page.page.body}\n`;
+      return `${editorialHeader(page.page.by)}# ${page.page.title}\n\n${page.page.lead ? `${page.page.lead}\n\n` : ""}${typeof page.page.body === "string" ? page.page.body : page.page.markdown}\n`;
     case "logo":
       return generated(
         assetsMarkdown(assets.assets.filter((a) => a.kind === "logo")) +