@designtools/blocks 0.0.0-stage → 0.1.0

package/registry/a11y-panel.tsx

@@ -0,0 +1,99 @@
+"use client";
+
+import { useRef, useState, type ReactNode } from "react";
+import { cx } from "./lib/cx";
+import type { ComponentEntry } from "./lib/manifest-types";
+
+interface Finding {
+  id: string;
+  impact: string | null;
+  help: string;
+  helpUrl: string;
+  nodes: number;
+}
+
+/**
+ * Runs axe-core over what it wraps, on demand. axe loads only when you press
+ * the button, so a docs page never ships it on first load. A clean run is not a
+ * pass: axe catches roughly a third of WCAG problems, and keyboard and screen
+ * reader checks stay with a person.
+ */
+export function A11yPanel({ entry, children }: { entry?: ComponentEntry; children: ReactNode }) {
+  const box = useRef<HTMLDivElement>(null);
+  const [status, setStatus] = useState<"idle" | "running" | "done" | "failed">("idle");
+  const [violations, setViolations] = useState<Finding[]>([]);
+  const [incomplete, setIncomplete] = useState(0);
+
+  const run = async () => {
+    if (!box.current) return;
+    setStatus("running");
+    try {
+      const axe = (await import("axe-core")).default;
+      const result = await axe.run(box.current, { resultTypes: ["violations", "incomplete"] });
+      setViolations(
+        result.violations.map((v) => ({ id: v.id, impact: v.impact ?? null, help: v.help, helpUrl: v.helpUrl, nodes: v.nodes.length })),
+      );
+      setIncomplete(result.incomplete.length);
+      setStatus("done");
+    } catch {
+      setStatus("failed");
+    }
+  };
+
+  return (
+    <div data-slot="a11y-panel" className="flex flex-col gap-4">
+      <div ref={box} data-slot="a11y-target">
+        {children}
+      </div>
+      <div className="flex flex-col gap-3 rounded-lg border border-border p-4 text-sm">
+        <div className="flex flex-wrap items-center justify-between gap-3">
+          <button
+            type="button"
+            onClick={run}
+            disabled={status === "running"}
+            className="rounded-md border border-border px-3 py-1.5 font-medium hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring disabled:opacity-50"
+          >
+            {status === "running" ? "Checking…" : status === "done" ? "Check again" : "Check with axe"}
+          </button>
+          {entry?.aria && (
+            <a href={entry.aria} className="text-xs underline underline-offset-2">
+              ARIA pattern it follows
+            </a>
+          )}
+        </div>
+        <div aria-live="polite" data-slot="a11y-results">
+          {status === "failed" && <p>axe could not run. Is axe-core installed?</p>}
+          {status === "done" && violations.length === 0 && (
+            <p>
+              No violations found
+              {incomplete > 0 && `, and ${incomplete} ${incomplete === 1 ? "check needs" : "checks need"} a person to judge`}.
+            </p>
+          )}
+          {status === "done" && violations.length > 0 && (
+            <ul className="flex flex-col gap-2">
+              {violations.map((v) => (
+                <li key={v.id} data-slot="a11y-violation" className="flex flex-col gap-0.5">
+                  <span>
+                    <span className={cx("mr-2 rounded-sm px-1 text-xs", v.impact === "critical" || v.impact === "serious" ? "bg-destructive text-destructive-foreground" : "bg-muted")}>
+                      {v.impact ?? "unknown"}
+                    </span>
+                    {v.help}
+                  </span>
+                  <span className="text-xs text-muted-foreground">
+                    {v.nodes} {v.nodes === 1 ? "element" : "elements"} ·{" "}
+                    <a href={v.helpUrl} className="underline underline-offset-2">
+                      {v.id}
+                    </a>
+                  </span>
+                </li>
+              ))}
+            </ul>
+          )}
+        </div>
+        <p className="text-xs text-muted-foreground">
+          axe catches roughly a third of WCAG problems. Check keyboard use and a screen reader by hand.
+        </p>
+      </div>
+    </div>
+  );
+}

package/registry/adherence-summary.tsx

@@ -0,0 +1,110 @@
+import type { AdherenceReport, Counts } from "./lib/adherence-types";
+import { cx } from "./lib/cx";
+
+/**
+ * The latest adherence report: how much of what the system could render comes
+ * from it, the classes that bypass the tokens, and where a className fights a
+ * component's variants. It informs; it never blocks.
+ */
+export function AdherenceSummary({ report }: { report: AdherenceReport }) {
+  const s = report.summary;
+  const stats: [string, string][] = [
+    ["From the system", share(s.share)],
+    ["System components used", `${s.componentsUsed} of ${s.componentsUsed + s.componentsUnused.length}`],
+    ["Raw elements a component replaces", String(s.rawElements)],
+    ["Off-system values", String(s.offSystemValues)],
+    ["Overrides", String(s.overrides)],
+  ];
+  return (
+    <div data-slot="adherence-summary" className="flex flex-col gap-6">
+      <dl className="grid grid-cols-2 gap-3 sm:grid-cols-3 lg:grid-cols-5">
+        {stats.map(([label, value]) => (
+          <div key={label} data-slot="adherence-stat" className="flex flex-col gap-1 rounded-lg border border-border p-4">
+            <dt className="text-xs text-muted-foreground">{label}</dt>
+            <dd className="text-2xl font-semibold tabular-nums">{value}</dd>
+          </div>
+        ))}
+      </dl>
+      {s.replaceable.length === 0 && (
+        <p className="text-sm text-muted-foreground">
+          No component declares <code className="font-mono text-xs">@replaces</code>, so raw elements are not counted and the share is
+          not yet meaningful.
+        </p>
+      )}
+      {report.routes.length > 0 && (
+        <div className="overflow-x-auto">
+          <table className="w-full min-w-[32rem] border-collapse text-left text-sm">
+            <caption className="sr-only">Adherence by route</caption>
+            <thead>
+              <tr className="border-b border-border text-xs text-muted-foreground">
+                {["Route", "From the system", "Raw", "Off-system", "Overrides"].map((h) => (
+                  <th key={h} scope="col" className="py-2 pr-4 font-medium">
+                    {h}
+                  </th>
+                ))}
+              </tr>
+            </thead>
+            <tbody>
+              {report.routes.map((r) => (
+                <Row key={r.route} name={r.route} counts={r.counts} />
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+      {report.files.some((f) => f.raw.length || f.offSystem.length || f.overrides.length) && (
+        <details data-slot="adherence-findings" className="rounded-md border border-border">
+          <summary className="cursor-pointer px-3 py-2 text-sm">Findings by file</summary>
+          <ul className="flex flex-col divide-y divide-border border-t border-border text-sm">
+            {report.files
+              .filter((f) => f.raw.length || f.offSystem.length || f.overrides.length)
+              .map((f) => (
+                <li key={f.file} className="flex flex-col gap-1 px-3 py-2">
+                  <code className="font-mono text-xs">{f.file}</code>
+                  <ul className="flex flex-col gap-0.5 text-muted-foreground">
+                    {f.raw.map((r) => (
+                      <li key={`r${r.line}:${r.column}`}>
+                        line {r.line}: a raw <code className="font-mono text-xs">&lt;{r.element}&gt;</code> where {r.replacedBy.join(" or ")} would do
+                      </li>
+                    ))}
+                    {f.offSystem.map((o) => (
+                      <li key={`o${o.line}:${o.column}:${o.class}`}>
+                        line {o.line}: <code className="font-mono text-xs">{o.class}</code> is {o.kind === "palette" ? "a palette step, not a semantic token" : "an arbitrary value"}
+                      </li>
+                    ))}
+                    {f.overrides.map((o) => (
+                      <li key={`v${o.line}:${o.column}`}>
+                        line {o.line}: <code className="font-mono text-xs">{o.classes.map((c) => c.class).join(" ")}</code> on {o.component} changes its{" "}
+                        {[...new Set(o.classes.map((c) => c.kind))].join(" and ")}: is a variant missing?
+                      </li>
+                    ))}
+                  </ul>
+                </li>
+              ))}
+          </ul>
+        </details>
+      )}
+      <p className="text-xs text-muted-foreground">
+        A report, never a gate: {report.generator}, over {s.files} files. Lookalikes (a div styled like a Card) are not detected.
+      </p>
+    </div>
+  );
+}
+
+function Row({ name, counts }: { name: string; counts: Counts }) {
+  return (
+    <tr className="border-b border-border">
+      <th scope="row" className="py-2 pr-4 font-mono text-xs font-normal">
+        {name}
+      </th>
+      <td className={cx("py-2 pr-4 tabular-nums", counts.share !== null && counts.share < 0.9 && "font-medium")}>{share(counts.share)}</td>
+      <td className="py-2 pr-4 tabular-nums">{counts.rawElements}</td>
+      <td className="py-2 pr-4 tabular-nums">{counts.offSystemValues}</td>
+      <td className="py-2 pr-4 tabular-nums">{counts.overrides}</td>
+    </tr>
+  );
+}
+
+function share(value: number | null): string {
+  return value === null ? "n/a" : `${Math.round(value * 1000) / 10}%`;
+}

package/registry/agent-view.tsx

@@ -0,0 +1,57 @@
+"use client";
+
+import { Tabs } from "@base-ui/react/tabs";
+import type { ReactNode } from "react";
+import { CodeView } from "./code-view";
+import { componentMarkdown } from "./lib/markdown";
+import type { ComponentEntry } from "./lib/manifest-types";
+
+/**
+ * What an agent needs to know, as copyable markdown: a component's status,
+ * usage, canonical example, do and don't, props, variants and parts, or any
+ * other block's markdown form. Generated from the manifest; nothing in it is
+ * written twice and nothing is written by a model.
+ */
+export function AgentInstructions({ entry, markdown }: { entry?: ComponentEntry; markdown?: string }) {
+  const code = markdown ?? (entry ? componentMarkdown(entry) : "");
+  return (
+    <div data-slot="agent-instructions" className="flex flex-col gap-2">
+      <CodeView code={code} lang="markdown" label="For agents: paste into a prompt" wrap />
+    </div>
+  );
+}
+
+const tab =
+  "-mb-px border-b-2 border-transparent px-1 pb-2 text-sm text-muted-foreground hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring data-[active]:border-primary data-[active]:font-medium data-[active]:text-canvas-foreground";
+
+/** The same thing two ways: as a person sees it, and as an agent reads it. Pass a component entry, or any block's markdown. */
+export function AgentView({
+  entry,
+  markdown,
+  label,
+  children,
+}: {
+  entry?: ComponentEntry;
+  markdown?: string;
+  label?: string;
+  children: ReactNode;
+}) {
+  return (
+    <Tabs.Root data-slot="agent-view" defaultValue="rendered" className="flex flex-col gap-4">
+      <Tabs.List aria-label={`${label ?? entry?.name ?? "This"}, two ways`} className="flex gap-6 border-b border-border">
+        <Tabs.Tab value="rendered" className={tab}>
+          Rendered
+        </Tabs.Tab>
+        <Tabs.Tab value="agent" className={tab}>
+          For agents
+        </Tabs.Tab>
+      </Tabs.List>
+      <Tabs.Panel value="rendered" className="focus-visible:outline-2 focus-visible:outline-ring">
+        {children}
+      </Tabs.Panel>
+      <Tabs.Panel value="agent" className="focus-visible:outline-2 focus-visible:outline-ring">
+        <AgentInstructions entry={entry} markdown={markdown} />
+      </Tabs.Panel>
+    </Tabs.Root>
+  );
+}

package/registry/anatomy.tsx

@@ -0,0 +1,88 @@
+"use client";
+
+import { useEffect, useId, useRef, useState, type ReactNode } from "react";
+import { cx } from "./lib/cx";
+import { componentFor, examplesFor, renderExample } from "./lib/lookup";
+import type { ComponentEntry } from "./lib/manifest-types";
+
+/**
+ * A component's parts, by `data-slot`. Point at a part to outline every element
+ * carrying it in the example. A part that does not appear may render in a
+ * portal or only in some states.
+ */
+export function Anatomy({
+  entry,
+  children,
+}: {
+  entry: ComponentEntry;
+  /** The example to point into. Defaults to the canonical example, else the bare component. */
+  children?: ReactNode;
+}) {
+  const id = useId();
+  const box = useRef<HTMLDivElement>(null);
+  const [active, setActive] = useState<string | null>(null);
+  const [counts, setCounts] = useState<Record<string, number>>({});
+
+  useEffect(() => {
+    const node = box.current;
+    if (!node) return;
+    const measure = () =>
+      setCounts(Object.fromEntries(entry.slots.map((s) => [s, node.querySelectorAll(`[data-slot="${CSS.escape(s)}"]`).length])));
+    measure();
+    const observer = new MutationObserver(measure);
+    observer.observe(node, { subtree: true, childList: true, attributes: true, attributeFilter: ["data-slot"] });
+    return () => observer.disconnect();
+  }, [entry.slots]);
+
+  if (entry.slots.length === 0) {
+    return <p className="text-sm text-muted-foreground">{entry.name} renders no data-slot parts.</p>;
+  }
+
+  const Component = componentFor(entry);
+  const module = 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);
+
+  return (
+    <div data-slot="anatomy" className="grid gap-6 md:grid-cols-[minmax(0,1fr)_16rem]">
+      {active && (
+        <style>{`[data-anatomy="${id}"] [data-slot="${active.replace(/"/g, '\\"')}"] { outline: 2px solid var(--ring); outline-offset: 2px; }`}</style>
+      )}
+      <div
+        ref={box}
+        data-anatomy={id}
+        data-slot="anatomy-example"
+        className="flex min-h-40 min-w-0 items-center justify-center overflow-auto rounded-lg border border-border bg-surface p-8 text-surface-foreground"
+      >
+        {example}
+      </div>
+      <ul data-slot="anatomy-parts" className="flex flex-col gap-1 text-sm" onMouseLeave={() => setActive(null)}>
+        {entry.slots.map((slot) => (
+          <li key={slot}>
+            {/* pointing, focusing or pressing a part shows it; leaving the list clears it */}
+            <button
+              type="button"
+              onMouseEnter={() => setActive(slot)}
+              onFocus={() => setActive(slot)}
+              onBlur={() => setActive(null)}
+              onClick={() => setActive(slot)}
+              className={cx(
+                "flex w-full items-baseline justify-between gap-3 rounded-md px-2 py-1.5 text-left hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring",
+                active === slot && "bg-muted",
+              )}
+            >
+              <code className="font-mono text-xs">{slot}</code>
+              <span className="text-xs text-muted-foreground">{counts[slot] ? `×${counts[slot]}` : "not shown"}</span>
+            </button>
+          </li>
+        ))}
+        {entry.variants?.parts && (
+          <li className="mt-3 px-2 text-xs text-muted-foreground">
+            Styled parts in <code className="font-mono">{entry.variants.config}</code>: {entry.variants.parts.join(", ")}
+          </li>
+        )}
+      </ul>
+    </div>
+  );
+}

package/registry/ask-claude.tsx

@@ -0,0 +1,71 @@
+"use client";
+
+import { useId, useState } from "react";
+import type { ComponentEntry } from "./lib/manifest-types";
+
+/**
+ * Copies a ready-made prompt for Claude: the component, its source file, the
+ * variant and example in view, and what should change. Paste it into Claude
+ * Code in the project and it starts from the right file.
+ */
+export function AskClaude({
+  entry,
+  variant,
+  example,
+}: {
+  entry: ComponentEntry;
+  /** The variant in view, e.g. `{ intent: "success" }`. */
+  variant?: Record<string, string>;
+  /** The example in view, by export name. */
+  example?: string;
+}) {
+  const id = useId();
+  const [request, setRequest] = useState("");
+  const [copied, setCopied] = useState(false);
+
+  const copy = async () => {
+    await navigator.clipboard.writeText(promptFor(entry, request, variant, example));
+    setCopied(true);
+    setTimeout(() => setCopied(false), 1500);
+  };
+
+  return (
+    <div data-slot="ask-claude" className="flex flex-col gap-2 rounded-lg border border-border p-4">
+      <label htmlFor={id} className="text-sm font-medium">
+        Ask Claude to change {entry.name}
+      </label>
+      <textarea
+        id={id}
+        rows={3}
+        value={request}
+        onChange={(e) => setRequest(e.target.value)}
+        placeholder="What should change?"
+        className="rounded-md border border-border bg-canvas p-2 text-sm focus-visible:outline-2 focus-visible:outline-ring"
+      />
+      <div className="flex items-center justify-between gap-3">
+        <span className="text-xs text-muted-foreground">Copies a prompt naming the file{example ? ", the example" : ""} and the variant.</span>
+        <button
+          type="button"
+          onClick={copy}
+          className="rounded-md bg-primary px-3 py-1.5 text-sm font-medium text-primary-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring"
+        >
+          {copied ? "Copied" : "Copy prompt"}
+        </button>
+      </div>
+      <span className="sr-only" aria-live="polite">
+        {copied ? "Prompt copied" : ""}
+      </span>
+    </div>
+  );
+}
+
+export function promptFor(entry: ComponentEntry, request: string, variant?: Record<string, string>, example?: string): string {
+  const lines = [`Component: ${entry.name}, exported as ${entry.export} from ${entry.source}`];
+  const shown = Object.entries(variant ?? {});
+  if (shown.length) lines.push(`Variant in view: ${shown.map(([k, v]) => `${k}="${v}"`).join(", ")}`);
+  if (example && entry.examples) lines.push(`Example in view: ${example}, from ${entry.examples.source}`);
+  if (entry.status && entry.status !== "stable") lines.push(`Status: ${entry.status}${entry.statusNote ? `. ${entry.statusNote}` : ""}`);
+  if (entry.slots.length) lines.push(`Its parts (data-slot): ${entry.slots.join(", ")}`);
+  lines.push("", request.trim() || "What should change: ");
+  return lines.join("\n");
+}

package/registry/code-view.tsx

@@ -0,0 +1,74 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { cx } from "./lib/cx";
+
+/* Shiki writes both themes as CSS variables; these pick the one for the page's mode. */
+const THEME_CSS = `
+[data-slot="code-view"] .shiki { background: transparent !important; }
+[data-theme="dark"] [data-slot="code-view"] .shiki, [data-theme="dark"] [data-slot="code-view"] .shiki span { color: var(--shiki-dark) !important; }
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) [data-slot="code-view"] .shiki, :root:not([data-theme="light"]) [data-slot="code-view"] .shiki span { color: var(--shiki-dark) !important; }
+}`;
+
+/**
+ * Code, highlighted once Shiki has loaded (it loads on first use, so pages
+ * without code never pay for it) and readable as plain text before then.
+ */
+export function CodeView({
+  code,
+  lang = "tsx",
+  label = "Code",
+  wrap = false,
+}: {
+  code: string;
+  lang?: string;
+  label?: string;
+  /** Wrap long lines, for prose such as markdown, instead of scrolling them. */
+  wrap?: boolean;
+}) {
+  const [html, setHtml] = useState<string | null>(null);
+  const [copied, setCopied] = useState(false);
+
+  useEffect(() => {
+    let live = true;
+    import("shiki")
+      .then(({ codeToHtml }) => codeToHtml(code, { lang, themes: { light: "github-light", dark: "github-dark" } }))
+      .then((out) => live && setHtml(out))
+      .catch(() => live && setHtml(null));
+    return () => {
+      live = false;
+    };
+  }, [code, lang]);
+
+  const copy = async () => {
+    await navigator.clipboard.writeText(code);
+    setCopied(true);
+    setTimeout(() => setCopied(false), 1500);
+  };
+
+  return (
+    <figure data-slot="code-view" className="relative overflow-hidden rounded-lg border border-border bg-muted">
+      <style>{THEME_CSS}</style>
+      <figcaption className="flex items-center justify-between border-b border-border px-4 py-2 text-xs text-muted-foreground">
+        <span>{label}</span>
+        <button type="button" onClick={copy} className="rounded-sm px-2 py-1 hover:bg-canvas focus-visible:outline-2 focus-visible:outline-ring">
+          {copied ? "Copied" : "Copy"}
+        </button>
+      </figcaption>
+      <span className="sr-only" aria-live="polite">
+        {copied ? "Code copied" : ""}
+      </span>
+      {html ? (
+        <div
+          className={cx("overflow-x-auto p-4 font-mono text-xs leading-relaxed", wrap && "[&_pre]:break-words [&_pre]:whitespace-pre-wrap")}
+          dangerouslySetInnerHTML={{ __html: html }}
+        />
+      ) : (
+        <pre className={cx("overflow-x-auto p-4 font-mono text-xs leading-relaxed", wrap && "break-words whitespace-pre-wrap")}>
+          <code>{code}</code>
+        </pre>
+      )}
+    </figure>
+  );
+}

package/registry/examples.tsx

@@ -0,0 +1,96 @@
+"use client";
+
+import { CodeView } from "./code-view";
+import { Boundary } from "./lib/boundary";
+import { cx } from "./lib/cx";
+import { examplesFor, Missing, renderExample } from "./lib/lookup";
+import type { ComponentEntry, ExampleRef } from "./lib/manifest-types";
+import { inline } from "./lib/text";
+
+/**
+ * The canonical example first, the one to copy, then each do beside its don't.
+ * Every example is the real component; the code under it is the code that drew it.
+ */
+export function Examples({ entry, previewHref }: { entry: ComponentEntry; previewHref?: string }) {
+  const ex = entry.examples;
+  if (!ex) {
+    return (
+      <p data-slot="examples-empty" className="text-sm text-muted-foreground">
+        No examples yet. Add <code className="font-mono text-xs">{entry.source.replace(/\.tsx$/, ".examples.tsx")}</code> with a{" "}
+        <code className="font-mono text-xs">canonical</code> export and do and don&apos;t pairs.
+      </p>
+    );
+  }
+  const module = examplesFor(entry);
+  if (!module) return <Missing name={entry.name} what="examples" />;
+
+  const pairs = Array.from({ length: Math.max(ex.do.length, ex.dont.length) }, (_, i) => [ex.do[i], ex.dont[i]] as const);
+  const card = (ref: ExampleRef, kind: "canonical" | "do" | "dont" | "other") => (
+    <Example key={ref.name} example={ref} kind={kind} value={module[ref.name]} href={previewHref && `${previewHref}/${encodeURIComponent(ref.name)}`} />
+  );
+
+  return (
+    <div data-slot="examples" className="flex flex-col gap-6">
+      {ex.canonical && card(ex.canonical, "canonical")}
+      {pairs.map(([d, n], i) => (
+        <div key={i} data-slot="examples-pair" className="grid grid-cols-1 gap-4 md:grid-cols-2">
+          {d ? card(d, "do") : <span />}
+          {n ? card(n, "dont") : <span />}
+        </div>
+      ))}
+      {ex.other.length > 0 && <div className="grid grid-cols-1 gap-4 md:grid-cols-2">{ex.other.map((o) => card(o, "other"))}</div>}
+    </div>
+  );
+}
+
+const LABEL = { canonical: "Copy this one", do: "Do", dont: "Don't", other: "" } as const;
+
+function Example({ example, kind, value, href }: { example: ExampleRef; kind: keyof typeof LABEL; value: unknown; href?: string }) {
+  return (
+    <figure
+      data-slot="example"
+      data-kind={kind}
+      className={cx(
+        "flex min-w-0 flex-col overflow-hidden rounded-lg border",
+        kind === "do" ? "border-success" : kind === "dont" ? "border-destructive" : "border-border",
+      )}
+    >
+      <div data-slot="example-frame" className="flex min-h-32 items-center justify-center overflow-auto bg-surface p-6 text-surface-foreground">
+        <Boundary label={example.name}>{renderExample(value, example.name)}</Boundary>
+      </div>
+      <figcaption className="flex flex-col gap-2 border-t border-border px-4 py-3 text-sm">
+        <span className="flex items-baseline justify-between gap-3">
+          <span className="flex items-baseline gap-2">
+            {LABEL[kind] && (
+              <span
+                className={cx(
+                  "font-medium",
+                  kind === "do" && "text-success",
+                  kind === "dont" && "text-destructive",
+                )}
+              >
+                {kind === "do" ? "✓ " : kind === "dont" ? "✕ " : ""}
+                {LABEL[kind]}
+              </span>
+            )}
+            <code className="font-mono text-xs text-muted-foreground">{example.name}</code>
+          </span>
+          {href && (
+            <a href={href} className="text-xs underline underline-offset-2">
+              Open alone
+            </a>
+          )}
+        </span>
+        {example.description && <span className="text-muted-foreground">{inline(example.description)}</span>}
+        {example.code && (
+          <details>
+            <summary className="cursor-pointer text-xs text-muted-foreground">Code</summary>
+            <div className="mt-2">
+              <CodeView code={example.code} label={example.name} />
+            </div>
+          </details>
+        )}
+      </figcaption>
+    </figure>
+  );
+}

package/registry/glossary.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import { useId, useState } from "react";
+import type { TermEntry } from "./lib/manifest-types";
+import { inline } from "./lib/text";
+
+/** Every name in the system, searchable by its wrong forms too, so a wrong name finds the right one. */
+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 corrected = q ? terms.find((t) => t.wrong?.some((w) => w.toLowerCase() === q)) : undefined;
+
+  return (
+    <div data-slot="glossary" className="flex flex-col gap-4">
+      <div className="flex flex-col gap-1.5">
+        <label htmlFor={id} className="text-sm font-medium">
+          Find a term
+        </label>
+        <input
+          id={id}
+          type="search"
+          value={query}
+          onChange={(e) => setQuery(e.target.value)}
+          placeholder="Try a name you half remember"
+          className="h-(--size-xl) max-w-sm rounded-md border border-input bg-canvas px-3 text-sm focus-visible:outline-2 focus-visible:outline-ring"
+        />
+      </div>
+      <p aria-live="polite" className="text-sm text-muted-foreground">
+        {corrected ? (
+          <>
+            The system calls “{query.trim()}” <strong className="text-canvas-foreground">{corrected.name}</strong>.
+          </>
+        ) : q ? (
+          `${matches.length} ${matches.length === 1 ? "term" : "terms"}`
+        ) : (
+          `${terms.length} terms`
+        )}
+      </p>
+      <dl data-slot="glossary-list" className="flex flex-col divide-y divide-border border-y border-border">
+        {matches.map((t) => (
+          <div key={`${t.kind}:${t.name}`} className="grid gap-1 py-3 sm:grid-cols-[12rem_1fr]">
+            <dt className="flex items-baseline gap-2">
+              <span className="font-medium">{t.name}</span>
+              <span className="text-xs text-muted-foreground">{t.kind}</span>
+            </dt>
+            <dd className="flex flex-col gap-0.5 text-sm text-muted-foreground">
+              {t.wrong?.length ? <span>Not {t.wrong.map((w) => `“${w}”`).join(", ")}</span> : null}
+              {t.note && <span>{inline(t.note)}</span>}
+              {t.ref && <code className="font-mono text-xs">{t.ref}</code>}
+            </dd>
+          </div>
+        ))}
+      </dl>
+    </div>
+  );
+}