@designtools/blocks 0.0.0-stage → 0.2.0

package/reference/app/(design)/layout.tsx

@@ -0,0 +1,16 @@
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import type { ReactNode } from "react";
+
+/**
+ * Every design page, under /design: never public. A 404 on a production deployment
+ * (VERCEL_ENV, or the host's equivalent), never indexed, kept on previews so a
+ * colleague can open a link. proxy.ts does the same for every docs URL, including
+ * the markdown and manifest route handlers, which no layout wraps.
+ */
+export const metadata: Metadata = { robots: { index: false, follow: false } };
+
+export default function DesignLayout({ children }: { children: ReactNode }) {
+  if (process.env.VERCEL_ENV === "production") notFound();
+  return children;
+}

package/reference/app/globals.css

@@ -0,0 +1,14 @@
+@import "tailwindcss";
+@import "./styles/tokens.css";
+@import "./styles/scale.css";
+
+/* The demo gitignores its generated blocks, and Tailwind skips ignored files unless told. */
+@source "./(design)/design/system/_blocks";
+
+@layer base {
+  html {
+    background: var(--canvas);
+    color: var(--canvas-foreground);
+    font-family: var(--font-sans);
+  }
+}

package/reference/app/layout.tsx

@@ -0,0 +1,16 @@
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "designtools demo",
+  robots: { index: false },
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

package/reference/designtools.json

@@ -0,0 +1,14 @@
+{
+  "manifest": {
+    "system": "src/ds",
+    "tokens": [
+      "app/styles/tokens.css",
+      "app/styles/scale.css"
+    ],
+    "docs": "/design/system",
+    "usage": "app/styles/tokens.usage.json"
+  },
+  "blocks": {
+    "dir": "app/(design)/design/system/_blocks"
+  }
+}

package/reference/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@designtools/example-demo",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "setup": "pnpm tokens && pnpm manifest && pnpm blocks && pnpm adherence",
+    "tokens": "generate-tokens --primary \"#4e9caf\" --neutral \"#8a8f98\" --background \"sand=#efe9dc/#2b2721\" --format tailwind-v4 --out app/styles/tokens.css --usage app/styles/tokens.usage.json",
+    "manifest": "designtools-manifest build && designtools-manifest provenance --json > 'app/(design)/design/system/_provenance.json'",
+    "blocks": "rm -rf 'app/(design)/design/system/_blocks' && designtools-blocks add --all && designtools-blocks map",
+    "dev": "next dev --port 4310",
+    "build": "next build",
+    "typecheck": "tsc --noEmit",
+    "adherence": "designtools-adherence --json 'app/(design)/design/system/_adherence.json' > /dev/null"
+  },
+  "dependencies": {
+    "@base-ui/react": "1.6.0",
+    "axe-core": "4.14.0",
+    "fuzzysort": "4.0.2",
+    "next": "16.3.8",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "shiki": "4.5.0",
+    "tailwind-merge": "3.6.0",
+    "tailwind-variants": "3.3.1"
+  },
+  "devDependencies": {
+    "@designtools/adherence": "workspace:*",
+    "@designtools/blocks": "workspace:*",
+    "@designtools/manifest": "workspace:*",
+    "@designtools/tokens": "workspace:*",
+    "@tailwindcss/postcss": "4.3.3",
+    "@types/node": "^24",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "tailwindcss": "4.3.3",
+    "typescript": "~6.0.3"
+  }
+}

package/reference/proxy.ts

@@ -0,0 +1,55 @@
+import { NextResponse, type NextRequest } from "next/server";
+
+const BASE = "/design/system";
+
+/**
+ * One URL, two formats. A docs URL answers `Accept: text/markdown`, or the same
+ * path with `.md`, with markdown generated from the manifest. Negotiation is on
+ * Accept only, never the user agent, so every response says `Vary: Accept`,
+ * and the HTML links to its markdown.
+ *
+ * Never public: on a production deployment every docs URL, in every format, is a
+ * 404. The (design) layout does the same for the pages, the preview route among
+ * them; this also covers the markdown and manifest route handlers, which no
+ * layout wraps.
+ */
+export function proxy(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+  if (process.env.VERCEL_ENV === "production") {
+    return new NextResponse("Not found\n", { status: 404, headers: { "x-robots-tag": "noindex" } });
+  }
+  if (pathname.startsWith(`${BASE}/md`) || pathname.startsWith(`${BASE}/manifest/`) || pathname.startsWith(`${BASE}/preview/`)) {
+    return NextResponse.next();
+  }
+  const wantsMarkdown = pathname.endsWith(".md") || prefersMarkdown(request.headers.get("accept"));
+  const page = pathname.replace(/\.md$/, "").replace(/\/$/, "");
+  if (wantsMarkdown) {
+    const url = request.nextUrl.clone();
+    url.pathname = `${BASE}/md${page.slice(BASE.length)}`;
+    return NextResponse.rewrite(url, { headers: { vary: "Accept", "x-robots-tag": "noindex" } });
+  }
+  // Next 16 replaces Vary on page responses with its own, so this one does not survive on HTML;
+  // the markdown responses keep theirs. See the demo README.
+  const res = NextResponse.next();
+  res.headers.set("vary", "Accept");
+  res.headers.set("link", `<${page}.md>; rel="alternate"; type="text/markdown"`);
+  res.headers.set("x-robots-tag", "noindex");
+  return res;
+}
+
+/** text/markdown ranked above text/html in the Accept header. */
+function prefersMarkdown(accept: string | null): boolean {
+  if (!accept) return false;
+  const q = (type: string) => {
+    for (const part of accept.split(",")) {
+      const [name, ...params] = part.trim().split(";");
+      if (name.trim() !== type) continue;
+      const weight = params.map((p) => p.trim()).find((p) => p.startsWith("q="));
+      return weight ? Number(weight.slice(2)) : 1;
+    }
+    return 0;
+  };
+  return q("text/markdown") > 0 && q("text/markdown") >= q("text/html");
+}
+
+export const config = { matcher: ["/design/system", "/design/system.md", "/design/system/:path*"] };

package/registry/a11y-panel.tsx

@@ -0,0 +1,99 @@
+"use client";
+
+import { useRef, useState, type ReactNode } from "react";
+import { cx, target } 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={cx(target, "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={cx(target, "inline-flex items-center 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, target } 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" tabIndex={0} role="region" aria-label="Adherence by route">
+          <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={cx(target, "flex cursor-pointer items-center 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 === "status-text" ? "a status fill used as text; use its subdued foreground" : 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,58 @@
+"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";
+import { target } from "./lib/cx";
+
+/**
+ * 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 =
+  target + " -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,89 @@
+"use client";
+
+import { useEffect, useId, useRef, useState, type ReactNode } from "react";
+import { cx, target } 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(
+                target,
+                "flex w-full items-center 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,73 @@
+"use client";
+
+import { useId, useState } from "react";
+import { importOf } from "./lib/manifest";
+import type { ComponentEntry } from "./lib/manifest-types";
+import { target } from "./lib/cx";
+
+/**
+ * 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={`${target} 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} (imported from "${importOf(entry)}")`];
+  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,77 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { cx, target } 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={cx(target, "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")}
+          tabIndex={0}
+          role="region"
+          aria-label={label}
+          dangerouslySetInnerHTML={{ __html: html }}
+        />
+      ) : (
+        <pre tabIndex={0} aria-label={label} className={cx("overflow-x-auto p-4 font-mono text-xs leading-relaxed", wrap && "break-words whitespace-pre-wrap")}>
+          <code>{code}</code>
+        </pre>
+      )}
+    </figure>
+  );
+}