@designtools/docs 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @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
+
+- a8e0eee: Editorial pages can be components: `body` takes React, with `markdown` for agents, and `DocsSection`, `Prose` and `Live` are exported for composing them. `Live` marks the project's own components inside the docs, and the docs' CSS never matches inside it: the docs' utilities no longer beat a project's responsive utilities on its components (a hero's `hidden lg:flex`), and a project's utilities no longer beat the docs' on their own elements, whichever stylesheet loads last. A legacy `:before` in the scoped CSS no longer invalidates its rule.
+  
+  The overview explains the system instead of listing every component: each part, why it exists, its count and a glimpse of it, then "Why this is agentic" for client and design leads (`overview` in the config tunes or drops it).
+  
+  Layout: the colour page drops its nested cards for open rows with a panel per mode; rules have an index and a two-column layout with the check beside the statement; pattern pages show the compositions first, status in the header and "Made of" below; variants sit on one stage without grid lines; vocabulary and voice share a calm term row (say, not, why) with a quiet search and a correction callout; navigation links read as links and group headings recede; section numbers align to their titles; the page header loses its rule; previous and next come before where the page came from, which is last; the phone drawer has room above its first item; the props tooltip is ink and opens at once.
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -76,13 +76,35 @@ pnpm add -D @designtools/manifest
 | `registry` | The generated registry from `designtools-docs map` |
 | `manifest` | The manifest files, as imported JSON |
 | `hero` | A full-bleed introduction across the top of the overview; without it the overview has a plain header and `lead` |
-| `editorial` | Pages people write, in markdown, each with its author and status, in the brand, foundations or standards group |
+| `editorial` | Pages people write, each with its author and status, in the brand, foundations or standards group: markdown, or components (below) |
 | `workbench` | Per component: starting `props`, text `children`, richer `content` (a Card's parts), and a `wrap` element for the provider or root it needs |
 | `demonstrations` | Per rule id: an element shown on the rule, for one that needs persuading |
 | `baselines`, `adherence`, `provenance` | The standards page's targets, the adherence report, and the line naming the version and commit |
+| `overview` | `{ agentic: false }` drops the overview's "Why this is agentic"; `agenticLead` rewrites its opening line |
 | `hide` | Built-in pages to leave out |
 | `blocks` | Blocks replaced by the project's own (see Eject) |
 
+## Editorial pages with components
+
+A page that has to show rather than tell (the brand on two surfaces, the status colours in their real jobs) takes React as its `body`, with `markdown` for agents:
+
+```tsx
+import { DocsSection, Live, Prose } from "@designtools/docs/next";
+
+editorial: [{
+  slug: "foundations/two-surfaces", section: "foundations", title: "One system, two surfaces", by,
+  body: (
+    <DocsSection title="Side by side">
+      <Prose text="The same tokens and components, set for two jobs." />
+      <Live><MarketingSlice /><AppSlice /></Live>
+    </DocsSection>
+  ),
+  markdown: "## Side by side\n\nThe same tokens and components, set for two jobs.",
+}]
+```
+
+`DocsSection` and `Prose` give the page the docs' own sections and type. Wrap the project's components in `Live`: the docs' styles never reach inside it, so the components look exactly as they do in the product. `markdown` is what the page's `.md` carries.
+
 ## Theming
 
 The docs read the project's own variables, so a project on [`@designtools/tokens`](../tokens) is themed with nothing to set. Any other project sets these on the docs (or anywhere above them):
@@ -101,7 +123,7 @@ The docs read the project's own variables, so a project on [`@designtools/tokens
 
 Text sizes, leading, tracking, weights, shadows, control sizes and motion follow the project's `--text-*`, `--leading-*`, `--tracking-*`, `--font-weight-*`, `--shadow-*`, `--size-*`, `--duration-*` and `--ease-*` where it has them. Every value has a fallback, so the docs render on a project with none of it.
 
-The CSS is scoped to `[data-designtools]` with `:where()`, so it styles the docs and nothing else and adds no specificity. Where the project's components render (stages, examples, the workbench), they take the project's own type, not the docs'.
+The CSS is scoped to `[data-designtools]`, so it styles the docs and nothing else. It never matches inside `Live` (`[data-docs-content]`), which marks everywhere the project's components render: examples, the workbench, variants, anatomy, rule demonstrations, the hero and the logo. There only the project's CSS applies, responsive utilities included. On the docs' own elements its rules carry one attribute more than a project utility of the same name, so neither side's utilities leak into the other, whichever stylesheet loads last.
 
 ## Eject
 

package/dist/anatomy.js

@@ -1,5 +1,6 @@
 "use client";
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Live } from "./lib/live.js";
 import { Layers } from "lucide-react";
 import { useEffect, useId, useRef, useState } from "react";
 import { cx, target } from "./lib/cx.js";
@@ -32,7 +33,7 @@ export function Anatomy({ entry, children, }) {
     const Component = lookup.componentFor(entry);
     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 ? _jsx(Component, { children: entry.name }) : null);
+    const example = children ?? (module && first ? renderExample(module[first], first) : Component ? (_jsx(Live, { children: _jsx(Component, { children: entry.name }) })) : null);
     const shown = entry.slots.filter((slot) => counts[slot]).length;
     return (_jsxs(Frame, { "data-slot": "anatomy", children: [active && (_jsx("style", { children: `[data-anatomy="${id}"] [data-slot="${active.replace(/"/g, '\\"')}"] { outline: 2px solid var(--ring); outline-offset: 3px; border-radius: var(--radius-sm); background-color: color-mix(in oklch, var(--ring) 10%, transparent); }` })), _jsxs("div", { className: "grid lg:grid-cols-[minmax(0,1fr)_17rem]", children: [_jsxs("div", { className: "flex min-w-0 flex-col", children: [_jsx(Toolbar, { children: _jsxs("span", { className: "flex items-center gap-2 pl-2 text-xs font-medium text-muted-foreground", children: [_jsx(Layers, { "aria-hidden": true, className: "size-(--dt-size-xs)" }), entry.slots.length, " ", entry.slots.length === 1 ? "part" : "parts", shown < entry.slots.length && ` · ${shown} in this example`] }) }), _jsx(Stage, { className: "min-h-64 flex-1", children: _jsx("div", { ref: box, "data-anatomy": id, "data-slot": "anatomy-example", className: "min-w-0", children: example }) })] }), _jsxs("div", { className: "flex flex-col gap-2 border-t border-border p-3 lg:border-t-0 lg:border-l", children: [_jsx("p", { className: "px-2 pt-1 text-xs text-muted-foreground", children: "Point at a part to find it." }), _jsx("ol", { "data-slot": "anatomy-parts", className: "flex flex-col gap-0.5 text-sm", onMouseLeave: () => setActive(null), children: entry.slots.map((slot, i) => (_jsx("li", { children: _jsxs("button", { type: "button", onMouseEnter: () => setActive(slot), onFocus: () => setActive(slot), onBlur: () => setActive(null), onClick: () => setActive(slot), className: cx(target, "group flex w-full items-center gap-3 rounded-lg px-2 text-left hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring", active === slot && "bg-muted", !counts[slot] && "text-muted-foreground"), children: [_jsx("span", { "aria-hidden": true, className: cx("flex size-6 shrink-0 items-center justify-center rounded-full border border-border font-mono text-xs", active === slot && "border-transparent bg-primary text-primary-foreground"), children: i + 1 }), _jsx("code", { className: "min-w-0 flex-1 truncate font-mono text-xs", children: slot }), _jsx("span", { className: "text-xs text-muted-foreground", children: counts[slot] ? `×${counts[slot]}` : "not shown" })] }) }, slot))) }), entry.variants?.parts && (_jsxs("p", { className: "mt-auto px-2 pt-2 text-xs text-muted-foreground", children: ["Styled in ", _jsx("code", { className: "font-mono", children: entry.variants.config }), ": ", entry.variants.parts.join(", ")] }))] })] })] }));
 }

package/dist/cli.js

@@ -19,7 +19,7 @@ var BLOCKS = [
   { name: "props-table", file: "props-table.tsx", exports: ["PropsTable"], description: "Props as an API reference" },
   { name: "preview-frame", file: "preview-frame.tsx", exports: ["PreviewFrame"], description: "An example at device widths, in a browser window" },
   { name: "pattern", file: "pattern.tsx", exports: ["Pattern"], description: "A screen composition, live, with what it is made of" },
-  { name: "rule", file: "rule.tsx", exports: ["Rule"], description: "A rule for people and as an agent reads it, with its check" },
+  { name: "rule", file: "rule.tsx", exports: ["Rule", "RuleIndex"], description: "A rule for people and as an agent reads it, with its check, and the index of every rule" },
   { name: "swatches", file: "swatches.tsx", exports: ["SemanticSwatches", "PageContrast", "RampSwatches"], description: "Colour: each pair measured, each colour on each background, the ramps" },
   { name: "type-ramp", file: "type-ramp.tsx", exports: ["TypeRamp"], description: "Type: families, the scale, weights, leading and tracking" },
   { name: "scale", file: "scale.tsx", exports: ["Scale"], description: "Space, size, radius, elevation and motion" },

package/dist/glossary.d.ts

@@ -1,5 +1,5 @@
 import type { TermEntry } from "./lib/manifest-types.js";
-/** 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 declare function Glossary({ terms }: {
     terms: TermEntry[];
 }): import("react").JSX.Element;

package/dist/glossary.js

@@ -1,14 +1,21 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { Search } from "lucide-react";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ArrowRight, Search } from "lucide-react";
 import { useId, useState } from "react";
-import { inline } from "./lib/text.js";
-/** Every name in the system, searchable by its wrong forms too, so a wrong name finds the right one. */
+import { TermRow } from "./lib/terms.js";
+/** 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 }) {
     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;
-    return (_jsxs("div", { "data-slot": "glossary", className: "flex flex-col gap-5", children: [_jsxs("div", { className: "flex flex-col gap-2", children: [_jsx("label", { htmlFor: id, className: "sr-only", children: "Find a term" }), _jsxs("div", { className: "relative max-w-xl", children: [_jsx(Search, { "aria-hidden": true, className: "pointer-events-none absolute top-1/2 left-4 size-(--dt-size-sm) -translate-y-1/2 text-muted-foreground" }), _jsx("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" })] }), _jsx("p", { "aria-live": "polite", className: "text-sm text-muted-foreground", children: corrected ? (_jsxs(_Fragment, { children: ["The system calls \u201C", query.trim(), "\u201D ", _jsx("strong", { className: "text-canvas-foreground", children: corrected.name }), "."] })) : q ? (`${matches.length} ${matches.length === 1 ? "term" : "terms"}`) : (`${terms.length} terms`) })] }), _jsx("dl", { "data-slot": "glossary-list", className: "grid gap-x-12 sm:grid-cols-2", children: matches.map((t) => (_jsxs("div", { className: "flex flex-col gap-1.5 border-t border-border py-4", children: [_jsxs("dt", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: "text-lg", children: t.name }), _jsx("span", { className: "font-mono text-xs text-muted-foreground", children: t.kind })] }), _jsxs("dd", { className: "flex flex-col gap-1 text-sm text-muted-foreground", children: [t.wrong?.length ? (_jsxs("span", { className: "flex flex-wrap items-center gap-1", children: ["Not", t.wrong.map((w) => (_jsx("s", { className: "decoration-destructive", children: w }, w)))] })) : null, t.note && _jsx("span", { children: inline(t.note) }), t.ref && _jsx("code", { className: "font-mono text-xs", children: t.ref })] })] }, `${t.kind}:${t.name}`))) })] }));
+    const letters = new Map();
+    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 (_jsxs("div", { "data-slot": "glossary", className: "flex flex-col gap-10", children: [_jsxs("div", { className: "flex max-w-3xl flex-col gap-4", children: [_jsx("label", { htmlFor: id, className: "sr-only", children: "Find a term" }), _jsxs("div", { className: "relative", children: [_jsx(Search, { "aria-hidden": true, className: "pointer-events-none absolute top-1/2 left-0 size-(--dt-size-md) -translate-y-1/2 text-muted-foreground" }), _jsx("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-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" })] }), _jsx("div", { "aria-live": "polite", children: corrected ? (_jsxs("p", { "data-slot": "glossary-correction", className: "flex flex-wrap items-center gap-2 rounded-xl bg-muted/60 px-5 py-4 text-lg", children: ["Say ", _jsx("strong", { className: "font-semibold", children: corrected.name }), _jsx(ArrowRight, { "aria-hidden": true, className: "size-4 text-muted-foreground" }), _jsxs("span", { className: "text-muted-foreground", children: ["not \u201C", query.trim(), "\u201D"] })] })) : (_jsx("p", { className: "text-sm text-muted-foreground", children: q ? `${matches.length} ${matches.length === 1 ? "term" : "terms"}` : `${terms.length} terms, A to Z. Search by the right name or a wrong one.` })) })] }), _jsx("div", { "data-slot": "glossary-list", className: "flex flex-col gap-8", children: [...letters].map(([letter, list]) => (_jsxs("section", { "aria-label": letter, className: "grid gap-x-8 lg:grid-cols-[3rem_minmax(0,1fr)]", children: [_jsx("h3", { className: "pt-5 text-2xl tracking-tight text-muted-foreground lg:sticky lg:top-24 lg:self-start", children: letter }), _jsx("div", { children: _jsx("dl", { children: list.map((t) => (_jsx(TermRow, { term: t, kind: true }, `${t.kind}:${t.name}`))) }) })] }, letter))) })] }));
 }

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/lib/live.d.ts

@@ -0,0 +1,10 @@
+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 declare function Live({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/lib/live.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * 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 }) {
+    return (_jsx("div", { "data-docs-content": "", style: { display: "contents" }, children: children }));
+}

package/dist/lib/lookup.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Live } from "./live.js";
 import { createElement, isValidElement } from "react";
 import { componentKey } from "./manifest.js";
 import { useRegistry } from "./registry.js";
@@ -34,8 +35,8 @@ export function Missing({ name, what = "component" }) {
 /** An example export is a component that takes no props, or an element. */
 export function renderExample(value, name) {
     if (isValidElement(value))
-        return value;
+        return _jsx(Live, { children: value });
     if (typeof value === "function")
-        return createElement(value);
+        return _jsx(Live, { children: createElement(value) });
     return _jsxs("span", { className: "text-xs text-muted-foreground", children: [name, " is not a component or an element."] });
 }

package/dist/lib/status.d.ts

@@ -1,7 +1,6 @@
-type Any = "stable" | "emerging" | "deprecated" | "confirmed" | "assumption" | "measured" | "draft" | "published";
+export type Status = "stable" | "emerging" | "deprecated" | "confirmed" | "assumption" | "measured" | "draft" | "published";
 /** A status, everywhere one is shown: components, patterns, rules and editorial pages. Unset says so. */
 export declare function StatusBadge({ status, className }: {
-    status?: Any;
+    status?: Status;
     className?: string;
 }): import("react").JSX.Element;
-export {};

package/dist/lib/terms.d.ts

@@ -0,0 +1,15 @@
+import type { TermEntry } from "./manifest-types.js";
+/** The wrong forms of a term: quiet chips, each with a cross, so "not this" reads without shouting. */
+export declare function WrongForms({ wrong }: {
+    wrong?: string[];
+}): import("react").JSX.Element;
+/**
+ * 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 declare function TermRow({ term, kind }: {
+    term: TermEntry;
+    kind?: boolean;
+}): import("react").JSX.Element;
+/** The column labels over a list of `TermRow`s, on a wide screen. */
+export declare function TermHead(): import("react").JSX.Element;

package/dist/lib/terms.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { X } from "lucide-react";
+import { inline } from "./text.js";
+/** The wrong forms of a term: quiet chips, each with a cross, so "not this" reads without shouting. */
+export function WrongForms({ wrong }) {
+    if (!wrong?.length)
+        return _jsx("span", { className: "text-sm text-muted-foreground", children: "None" });
+    return (_jsxs("span", { className: "flex flex-wrap gap-1.5", children: [_jsx("span", { className: "sr-only", children: "Not " }), wrong.map((w) => (_jsxs("span", { "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", children: [_jsx(X, { "aria-hidden": true, className: "size-3 shrink-0" }), _jsx("span", { className: "line-through decoration-current/40", children: w })] }, w)))] }));
+}
+/**
+ * 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 }) {
+    return (_jsxs("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", children: [_jsxs("dt", { className: "flex items-baseline gap-2", children: [_jsx("span", { className: "text-xl leading-snug tracking-tight", children: term.name }), kind && _jsx("span", { className: "font-mono text-xs text-muted-foreground", children: term.kind }), _jsx("span", { className: "sr-only", children: ", say this" })] }), _jsx("dd", { children: _jsx(WrongForms, { wrong: term.wrong }) }), _jsxs("dd", { className: "text-sm leading-relaxed text-muted-foreground", children: [term.note ? inline(term.note) : term.kind !== "product" ? `The ${term.kind}'s name in the code.` : null, term.ref && _jsx("code", { className: "ml-1 font-mono text-xs", children: term.ref })] })] }));
+}
+/** The column labels over a list of `TermRow`s, on a wide screen. */
+export function TermHead() {
+    return (_jsxs("div", { "aria-hidden": true, 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)]", children: [_jsx("span", { children: "Say" }), _jsx("span", { children: "Not" }), _jsx("span", { children: "Why" })] }));
+}

package/dist/next/config.d.ts

@@ -1,13 +1,24 @@
 import type { ComponentType, ReactElement, ReactNode } from "react";
 import type { AdherenceReport } from "../lib/adherence-types.js";
-/** 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;
@@ -50,6 +61,14 @@ 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;
@@ -83,3 +102,4 @@ export interface DocsConfig {
      */
     blocks?: Partial<Record<string, ComponentType<any>>>;
 }
+export {};

package/dist/next/index.d.ts

@@ -2,7 +2,10 @@ import "../styles.css";
 import type { Metadata } from "next";
 import type { ReactNode } from "react";
 import type { DocsConfig } from "./config.js";
+export { Live } from "../lib/live.js";
+export { DocsSection } from "../shell.js";
 export type { BuiltInPage, DocsConfig, EditorialPage, WorkbenchSetup } from "./config.js";
+export { Markdown as Prose } from "./prose.js";
 export { markdownFor } from "./markdown.js";
 export { docsMatcher, docsProxy, prefersMarkdown } from "./proxy.js";
 type SlugParams = {

package/dist/next/index.js

@@ -7,6 +7,9 @@ import { DocsShell } from "../shell.js";
 import { manifestFiles, manifestRoute, markdownRoute } from "./markdown.js";
 import { DocsPageView } from "./pages.js";
 import { allSlugs, metaOf, navOf, resolve, siteOf } from "./site.js";
+export { Live } from "../lib/live.js";
+export { DocsSection } from "../shell.js";
+export { Markdown as Prose } from "./prose.js";
 export { markdownFor } from "./markdown.js";
 export { docsMatcher, docsProxy, prefersMarkdown } from "./proxy.js";
 /**

package/dist/next/markdown.js

@@ -37,7 +37,7 @@ export function markdownFor(site, path) {
             ].join("\n"));
         }
         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")) +
                 "\n" +

package/dist/next/pages.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { ArrowRight, ArrowUpRight } from "lucide-react";
 import Link from "next/link";
+import { cx, display } from "../lib/cx.js";
 import { AdherenceSummary } from "../adherence-summary.js";
 import { Anatomy } from "../anatomy.js";
 import { Examples } from "../examples.js";
@@ -13,7 +14,7 @@ import { PageActions } from "../page-actions.js";
 import { Pattern } from "../pattern.js";
 import { PreviewFrame } from "../preview-frame.js";
 import { PropsTable } from "../props-table.js";
-import { Rule } from "../rule.js";
+import { Rule, RuleIndex } from "../rule.js";
 import { Scale } from "../scale.js";
 import { DocsFooter, DocsHeader, DocsSection } from "../shell.js";
 import { Standards } from "../standards.js";
@@ -39,6 +40,7 @@ const DEFAULT_BLOCKS = {
     PropsTable,
     RampSwatches,
     Rule,
+    RuleIndex,
     Scale,
     SemanticSwatches,
     Standards,
@@ -61,7 +63,7 @@ export function DocsPageView({ site, page }) {
         case "overview":
             return _jsx(Overview, { site: site });
         case "editorial":
-            return (_jsxs(_Fragment, { children: [header(page.page.title, page.page.lead), _jsx(Markdown, { text: page.page.body }), _jsx(DocsFooter, { editorial: page.page.by })] }));
+            return (_jsxs(_Fragment, { children: [header(page.page.title, page.page.lead), typeof page.page.body === "string" ? _jsx(Markdown, { text: page.page.body }) : page.page.body, _jsx(DocsFooter, { editorial: page.page.by })] }));
         case "logo":
             return (_jsxs(_Fragment, { children: [header(COPY.logo.title, COPY.logo.lead), _jsx(B.LogoUsage, { assets: site.assets.assets, rules: site.rules.rules, rulesHref: `${base}/rules` }), footer] }));
         case "imagery":
@@ -75,7 +77,7 @@ export function DocsPageView({ site, page }) {
         case "scale":
             return (_jsxs(_Fragment, { children: [header(COPY.scale.title, COPY.scale.lead), _jsx(B.Scale, { tokens: site.tokens }), footer] }));
         case "rules":
-            return (_jsxs(_Fragment, { children: [header(COPY.rules.title, COPY.rules.lead), ["brand", "interface"].map((kind) => {
+            return (_jsxs(_Fragment, { children: [header(COPY.rules.title, COPY.rules.lead), _jsx(DocsSection, { title: "Every rule", lead: "A line each: what it covers, how settled it is, and how it is checked.", children: _jsx(B.RuleIndex, { rules: [...site.rules.rules].sort((a, b) => a.kind.localeCompare(b.kind)) }) }), ["brand", "interface"].map((kind) => {
                         const rules = site.rules.rules.filter((r) => r.kind === kind);
                         return rules.length ? (_jsx(DocsSection, { title: kind === "brand" ? "Brand" : "Interface", children: rules.map((r) => (_jsx(B.Rule, { rule: r, children: config.demonstrations?.[r.id] }, r.id))) }, kind)) : null;
                     }), footer] }));
@@ -84,7 +86,7 @@ export function DocsPageView({ site, page }) {
         case "vocabulary":
             return (_jsxs(_Fragment, { children: [header(COPY.vocabulary.title, COPY.vocabulary.lead), _jsx(B.Glossary, { terms: site.taxonomy.terms }), footer] }));
         case "pattern":
-            return (_jsxs(_Fragment, { children: [header(page.pattern.name, page.pattern.description), _jsx(B.Pattern, { pattern: page.pattern, manifest: site.components, basePath: base }), _jsx(DocsFooter, { source: page.pattern.source, provenance: config.provenance })] }));
+            return (_jsxs(_Fragment, { children: [_jsx(DocsHeader, { title: page.pattern.name, lead: page.pattern.description, status: page.pattern.status, children: _jsx(PageActions, { basePath: base }) }), _jsx(B.Pattern, { pattern: page.pattern, manifest: site.components, basePath: base }), _jsx(DocsFooter, { source: page.pattern.source, provenance: config.provenance })] }));
         case "component":
             return _jsx(ComponentPage, { site: site, blocks: B, entry: page.entry });
     }
@@ -103,20 +105,84 @@ function ComponentPage({ site, blocks: B, entry }) {
     const backgrounds = site.tokens.tokens.map((t) => t.name.slice(2)).filter((n) => /^surface-[a-z]/.test(n) && !n.endsWith("-foreground"));
     return (_jsxs(_Fragment, { children: [_jsx(DocsHeader, { title: entry.name, lead: entry.description, children: _jsx(PageActions, { basePath: base }) }), _jsx(DocsSection, { title: "Usage", children: _jsx(B.Usage, { entry: entry, manifest: site.components, basePath: base }) }), _jsx(B.Workbench, { entry: entry, props: setup.props, content: setup.content, wrap: setup.wrap, backgrounds: backgrounds, previewHref: first && `${preview}/${first}`, children: setup.children }), _jsx(DocsSection, { title: "Anatomy", children: _jsx(B.Anatomy, { entry: entry }) }), _jsx(DocsSection, { title: "Examples", lead: "The usual use first, then each do beside its don't. Every one is the real component.", children: _jsx(B.Examples, { entry: entry, previewHref: preview }) }), !!entry.variants?.axes.length && (_jsx(DocsSection, { title: "Variants", lead: `Every combination, from the ${entry.variants.from === "props" ? "props' types" : `${entry.variants.from}() config`}, then each state.`, children: _jsx(B.VariantMatrix, { entry: entry, props: setup.props, children: setup.children === "" ? undefined : (setup.content ?? entry.name) }) })), first && (_jsx(DocsSection, { title: "At each width", children: _jsx(B.PreviewFrame, { src: `${preview}/${first}`, title: `${entry.name}: ${first}` }) })), _jsx(DocsFooter, { source: entry.source, provenance: config.provenance })] }));
 }
-const row = "group flex h-full flex-col gap-2 border-t border-border py-5 focus-visible:outline-2 focus-visible:outline-ring";
-/** The overview: where to start, then every component by category. Below the hero when there is one. */
+/** The overview, below the hero when there is one: each part of the system and why it exists, then why it is agentic. */
 function Overview({ site }) {
     const { base, config } = site;
     const families = groupFamilies(site.components);
     const count = families.reduce((n, g) => n + g.families.length, 0);
-    const brandFirst = site.editorial.find((p) => (p.section ?? "brand") === "brand");
-    const starts = [
-        brandFirst || site.shows("logo") ? { title: "Brand", href: `${base}/${brandFirst?.slug ?? "brand/logo"}`, line: "Principles, the logo, imagery and the words we use." } : null,
-        { title: "Foundations", href: `${base}/colour`, line: "Colour, type and the scale, rendered from the tokens." },
-        site.rules.rules.length ? { title: "Rules", href: `${base}/rules`, line: `${site.rules.rules.length} rules, brand and interface, each with its check.` } : null,
-        site.patterns.patterns.length
-            ? { title: "Patterns", href: `${base}/patterns/${site.patterns.patterns[0].id}`, line: `${site.patterns.patterns.length} recurring screens, made of the real components.` }
-            : null,
-    ].filter((s) => !!s);
-    return (_jsxs(_Fragment, { children: [!config.hero && (_jsx(DocsHeader, { title: site.title, lead: config.lead ?? "The brand and the design system in one place, for the people who make the product and the agents that build it with them.", children: _jsx(PageActions, { basePath: base }) })), _jsx("ol", { className: "flex max-w-3xl flex-col", children: starts.map(({ title, href, line }, n) => (_jsx("li", { className: "border-t border-border first:border-t-0", children: _jsxs(Link, { href: href, className: "group grid grid-cols-[3rem_minmax(0,1fr)_auto] items-baseline gap-x-4 py-6 focus-visible:outline-2 focus-visible:outline-ring sm:grid-cols-[4rem_minmax(0,1fr)_auto]", children: [_jsx("span", { className: "text-lg text-muted-foreground tabular-nums", children: String(n + 1).padStart(2, "0") }), _jsxs("span", { className: "flex flex-col gap-2", children: [_jsx("span", { className: "text-2xl leading-snug tracking-tight underline-offset-[6px] group-hover:underline md:text-3xl", children: title }), _jsx("span", { className: "text-lg leading-relaxed text-muted-foreground", children: line })] }), _jsx(ArrowUpRight, { "aria-hidden": true, className: "size-5 self-center text-muted-foreground transition-transform duration-(--dt-duration-fast) group-hover:translate-x-0.5 group-hover:-translate-y-0.5" })] }) }, title))) }), site.shows("components") && (_jsx(DocsSection, { title: "Components", lead: `${count} components, grouped as the navigation groups them. Each page has its usage, a workbench, anatomy, examples and variants.`, children: _jsx("div", { className: "flex flex-col gap-12", children: families.map((group) => (_jsxs("div", { className: "flex flex-col gap-1", children: [_jsx("h3", { className: "text-xs font-medium tracking-wide text-muted-foreground uppercase", children: group.category }), _jsx("ul", { className: "grid gap-x-10 sm:grid-cols-2 xl:grid-cols-3", children: group.families.map(({ head: c, parts }) => (_jsx("li", { children: _jsxs(Link, { href: `${base}/components/${slugOf(c)}`, className: row, children: [_jsxs("span", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: "text-xl tracking-tight underline-offset-4 group-hover:underline", children: c.name }), _jsx(StatusBadge, { status: c.status })] }), c.description && _jsx("span", { className: "line-clamp-2 text-sm text-muted-foreground", children: c.description }), parts.length > 0 && _jsxs("span", { className: "mt-auto font-mono text-xs text-muted-foreground", children: ["with ", parts.map((p) => p.name).join(", ")] })] }) }, c.source + c.export))) })] }, group.category))) }) })), _jsx(DocsFooter, { provenance: config.provenance })] }));
+    const brandPages = site.editorial.filter((p) => (p.section ?? "brand") === "brand");
+    const brandFirst = brandPages[0];
+    const products = site.taxonomy.terms.filter((t) => t.kind === "product" && t.wrong?.length);
+    const example = products[0] ?? site.taxonomy.terms.find((t) => t.wrong?.length);
+    const fills = ["--primary", "--neutral", "--success", "--warning", "--destructive"].filter((n) => site.tokens.tokens.some((t) => t.name === n));
+    const share = config.adherence?.summary.share;
+    // each section of the system, why it exists, how much is in it, and a glimpse of it, live from the manifest
+    const sections = [];
+    if (brandFirst || site.shows("logo"))
+        sections.push({
+            title: "Brand",
+            href: `${base}/${brandFirst?.slug ?? "brand/logo"}`,
+            why: "What the brand believes, how it sounds and how it looks, so every screen and sentence comes from the same place.",
+            count: `${brandPages.length + (site.assets.assets.some((a) => a.kind === "logo") ? 1 : 0)} pages`,
+            preview: config.logo ? _jsx("span", { className: "flex h-10 items-center [&_img]:h-8 [&_svg]:h-8", children: config.logo }) : null,
+        });
+    sections.push({
+        title: "Foundations",
+        href: `${base}/colour`,
+        why: "Colour, type and the scale, generated from the tokens and measured in both modes, so nothing is a guess.",
+        count: `${site.tokens.tokens.length} tokens`,
+        preview: (_jsxs("span", { className: "flex items-center gap-4", children: [_jsx("span", { className: "flex -space-x-1.5", children: fills.map((n) => (_jsx("span", { "aria-hidden": true, className: "size-8 rounded-full ring-2 ring-canvas", style: { background: `var(${n})` } }, n))) }), _jsx("span", { "aria-hidden": true, className: cx(display, "text-3xl leading-none tracking-tight"), children: "Aa" })] })),
+    });
+    if (site.rules.rules.length)
+        sections.push({
+            title: "Rules",
+            href: `${base}/rules`,
+            why: "The lines the brand and the interface hold, each written for people, with the check that proves it.",
+            count: `${site.rules.rules.length} rules, ${site.rules.rules.filter((r) => r.status === "confirmed").length} confirmed`,
+            preview: (_jsx("span", { className: "flex flex-col gap-1.5 text-sm", children: site.rules.rules
+                    .filter((r) => r.kind === "brand")
+                    .slice(0, 2)
+                    .map((r) => (_jsxs("span", { className: "flex items-center gap-2", children: [_jsx(StatusBadge, { status: r.status }), _jsx("span", { className: "truncate", children: r.title })] }, r.id))) })),
+        });
+    if (site.shows("components") && count)
+        sections.push({
+            title: "Components",
+            href: `${base}/components/${slugOf(families[0].families[0].head)}`,
+            why: "The real components the product is built from, each with when to use it, a live workbench and an accessibility report.",
+            count: `${count} components`,
+            preview: (_jsx("span", { className: "flex flex-wrap gap-1.5", children: families.slice(0, 6).map((g) => (_jsxs("span", { className: "inline-flex min-h-7 items-center rounded-md bg-muted px-2 text-xs", children: [g.category, " ", _jsx("span", { className: "ml-1.5 text-muted-foreground tabular-nums", children: g.families.length })] }, g.category))) })),
+        });
+    if (site.patterns.patterns.length)
+        sections.push({
+            title: "Patterns",
+            href: `${base}/patterns/${site.patterns.patterns[0].id}`,
+            why: "The screens the product keeps making, composed of the components, so a recurring problem is solved once.",
+            count: `${site.patterns.patterns.length} patterns`,
+            preview: _jsx("span", { className: "text-sm text-muted-foreground", children: site.patterns.patterns.slice(0, 3).map((p) => p.name).join(" · ") }),
+        });
+    if (site.shows("standards") && (config.baselines || config.adherence))
+        sections.push({
+            title: "Standards",
+            href: `${base}/standards`,
+            why: "The bar the product is held to, and how closely it follows the system today, reported on every change.",
+            count: share == null ? "Baselines agreed" : `${Math.round(share * 100)}% of the product on the system`,
+            preview: share == null ? null : (_jsxs("span", { className: "flex w-full max-w-56 items-center gap-3", children: [_jsx("span", { className: "h-1.5 flex-1 overflow-hidden rounded-full bg-muted", children: _jsx("span", { className: "block h-full rounded-full bg-canvas-foreground", style: { width: `${Math.round(share * 100)}%` } }) }), _jsxs("span", { className: "text-sm tabular-nums", children: [Math.round(share * 100), "%"] })] })),
+        });
+    if (site.shows("vocabulary") && site.taxonomy.terms.length)
+        sections.push({
+            title: "Vocabulary",
+            href: `${base}/vocabulary`,
+            why: "One name for each thing, and the names people reach for instead, so people and agents mean the same thing.",
+            count: `${site.taxonomy.terms.length} terms`,
+            preview: example ? (_jsxs("span", { className: "text-sm", children: ["Say ", _jsx("strong", { className: "font-semibold", children: example.name }), ", ", _jsx("span", { className: "text-muted-foreground line-through decoration-current/40", children: example.wrong?.[0] })] })) : null,
+        });
+    const loop = [
+        ["Written once", "The components, tokens and rules live in the product's own code. Nobody keeps a second copy in a slide deck or a wiki."],
+        ["Generated, never drifting", "This site is built from that code on every change, so it cannot fall out of date."],
+        ["Read by people and agents", "Every page is also plain markdown, and coding agents are pointed at the same source, so they build with the real components and rules."],
+        ["Checked", "Each rule names the check that proves it. Stale docs stop a commit; everything else is reported."],
+        ["Measured", "A report on every change shows how closely the product follows the system. It informs the conversation; it never blocks the work."],
+    ];
+    return (_jsxs(_Fragment, { children: [!config.hero && (_jsx(DocsHeader, { title: site.title, lead: config.lead ?? "The brand and the design system in one place, for the people who make the product and the agents that build it with them.", children: _jsx(PageActions, { basePath: base }) })), _jsx(DocsSection, { title: "What's here, and why", lead: "Each part of the system has one job. Together they mean the product, its people and its agents work from the same source.", children: _jsx("ul", { "data-slot": "overview-sections", className: "grid gap-x-12 md:grid-cols-2", children: sections.map((sec) => (_jsx("li", { className: "border-t border-border", children: _jsxs(Link, { href: sec.href, className: "group flex h-full flex-col gap-4 py-7 focus-visible:outline-2 focus-visible:outline-ring", children: [_jsxs("span", { className: "flex items-baseline justify-between gap-4", children: [_jsx("span", { className: "text-2xl leading-tight tracking-tight underline-offset-[6px] group-hover:underline", children: sec.title }), _jsx("span", { className: "shrink-0 text-xs text-muted-foreground tabular-nums", children: sec.count })] }), _jsx("span", { className: "max-w-md text-base leading-relaxed text-muted-foreground", children: sec.why }), sec.preview && _jsx("span", { className: "mt-auto flex min-h-10 items-center pt-2", children: sec.preview })] }) }, sec.title))) }) }), config.overview?.agentic !== false && (_jsxs(DocsSection, { title: "Why this is agentic", lead: config.overview?.agenticLead ??
+                    "A design system used to be a document people were asked to follow. This one is the source the product, its people and its AI agents all work from, and it checks itself.", children: [_jsx("ol", { "data-slot": "overview-loop", className: "grid gap-x-6 gap-y-8 sm:grid-cols-2 xl:grid-cols-5", children: loop.map(([title, body], i) => (_jsxs("li", { className: "relative flex flex-col gap-3 xl:pr-2", children: [_jsxs("span", { className: "flex items-center gap-3", children: [_jsx("span", { className: "grid size-8 shrink-0 place-items-center rounded-full bg-canvas-foreground text-sm font-medium text-canvas tabular-nums", children: i + 1 }), i < loop.length - 1 && _jsx("span", { "aria-hidden": true, className: "hidden h-px flex-1 bg-border xl:block" })] }), _jsx("span", { className: "text-lg leading-snug tracking-tight", children: title }), _jsx("span", { className: "text-sm leading-relaxed text-muted-foreground", children: body })] }, title))) }), _jsxs("p", { className: "flex flex-wrap items-center gap-x-2 gap-y-1 text-sm text-muted-foreground", children: ["See it the way an agent does:", _jsxs("a", { href: `${base}.md`, className: "inline-flex items-center gap-1 font-medium text-canvas-foreground underline underline-offset-4 hover:decoration-2", children: ["this page as markdown ", _jsx(ArrowUpRight, { "aria-hidden": true, className: "size-3.5" })] })] })] })), _jsx(DocsFooter, { provenance: config.provenance })] }));
 }

package/dist/next/prose.d.ts

@@ -1,6 +1,6 @@
 /**
- * The few markdown shapes editorial pages use: `##` sections, paragraphs and bullet lists, with bold
- * and code. Each `##` is a docs section, so it reads at the same size as a generated page and is
+ * The few markdown shapes editorial pages use: `##` sections, `###` headings, paragraphs and bullet
+ * lists, with bold, code and links. Each `##` is a docs section, so it reads at the same size as a generated page and is
  * listed in "On this page". A list whose every item opens in bold ("**Say it plainly.** …") is a set
  * of principles, numbered, each a heading over its sentence.
  */

package/dist/next/prose.js

@@ -1,8 +1,8 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { DocsSection } from "../shell.js";
 /**
- * The few markdown shapes editorial pages use: `##` sections, paragraphs and bullet lists, with bold
- * and code. Each `##` is a docs section, so it reads at the same size as a generated page and is
+ * The few markdown shapes editorial pages use: `##` sections, `###` headings, paragraphs and bullet
+ * lists, with bold, code and links. Each `##` is a docs section, so it reads at the same size as a generated page and is
  * listed in "On this page". A list whose every item opens in bold ("**Say it plainly.** …") is a set
  * of principles, numbered, each a heading over its sentence.
  */
@@ -18,6 +18,8 @@ export function Markdown({ text }) {
 }
 function Blocks({ blocks }) {
     return (_jsx("div", { className: "flex flex-col gap-5", children: blocks.map((b, i) => {
+            if (b.startsWith("### "))
+                return (_jsx("h3", { className: "mt-4 max-w-3xl text-2xl leading-snug tracking-tight first:mt-0", children: inline(b.slice(4)) }, i));
             const lines = b.split("\n");
             if (lines.every((l) => l.startsWith("- "))) {
                 const items = lines.map((l) => l.slice(2));
@@ -25,7 +27,7 @@ function Blocks({ blocks }) {
                 if (principles)
                     return (_jsx("ol", { className: "flex max-w-3xl flex-col gap-12", children: items.map((l, n) => {
                             const [, head, rest] = /^\*\*([^*]+)\*\*\s*(.*)$/.exec(l) ?? [];
-                            return (_jsxs("li", { className: "grid grid-cols-[3rem_minmax(0,1fr)] gap-x-4 gap-y-3 sm:grid-cols-[4rem_minmax(0,1fr)]", children: [_jsx("span", { className: "pt-1 text-lg text-muted-foreground tabular-nums", children: String(n + 1).padStart(2, "0") }), _jsxs("span", { className: "flex flex-col gap-3", children: [_jsx("span", { className: "text-2xl leading-snug tracking-tight md:text-3xl", children: head.replace(/\.$/, "") }), _jsx("span", { className: "text-lg leading-relaxed text-canvas-foreground/75", children: inline(rest) })] })] }, l));
+                            return (_jsxs("li", { className: "grid grid-cols-[3rem_minmax(0,1fr)] items-baseline gap-x-4 gap-y-3 sm:grid-cols-[4rem_minmax(0,1fr)]", children: [_jsx("span", { className: "text-lg text-muted-foreground tabular-nums", children: String(n + 1).padStart(2, "0") }), _jsxs("span", { className: "flex flex-col gap-3", children: [_jsx("span", { className: "text-2xl leading-snug tracking-tight md:text-3xl", children: head.replace(/\.$/, "") }), _jsx("span", { className: "text-lg leading-relaxed text-canvas-foreground/75", children: inline(rest) })] })] }, l));
                         }) }, i));
                 return (_jsx("ul", { className: "flex max-w-3xl list-disc flex-col gap-2 pl-5 text-lg leading-relaxed", children: items.map((l) => (_jsx("li", { children: inline(l) }, l))) }, i));
             }
@@ -33,5 +35,5 @@ function Blocks({ blocks }) {
         }) }));
 }
 function inline(text) {
-    return text.split(/(\*\*[^*]+\*\*|`[^`]+`)/).map((part, i) => part.startsWith("**") ? (_jsx("strong", { className: "font-semibold", children: part.slice(2, -2) }, i)) : part.startsWith("`") ? (_jsx("code", { className: "font-mono text-[0.9em]", children: part.slice(1, -1) }, i)) : (part));
+    return text.split(/(\*\*[^*]+\*\*|`[^`]+`|\[[^\]]+\]\([^)\s]+\))/).map((part, i) => part.startsWith("[") ? (_jsx("a", { href: /\(([^)]+)\)$/.exec(part)?.[1], className: "underline decoration-from-font underline-offset-4 hover:decoration-2", children: /^\[([^\]]+)\]/.exec(part)?.[1] }, i)) : part.startsWith("**") ? (_jsx("strong", { className: "font-semibold", children: part.slice(2, -2) }, i)) : part.startsWith("`") ? (_jsx("code", { className: "font-mono text-[0.9em]", children: part.slice(1, -1) }, i)) : (part));
 }

package/dist/pattern.d.ts

@@ -1,5 +1,8 @@
 import type { ComponentsManifest, PatternEntry } from "./lib/manifest-types.js";
-/** A recurring screen composition: what it is made of, then each composition live in its frame, with its code. */
+/**
+ * A recurring screen composition: each composition live in its frame, with its code, then the
+ * components it is made of, each linking to its page. Its status sits in the page header.
+ */
 export declare function Pattern({ pattern, manifest, basePath, }: {
     pattern: PatternEntry;
     /** To link the components it uses to their pages. */