@designtools/blocks 0.0.0-stage → 0.2.0

package/reference/app/(design)/design/system/(docs)/brand/imagery/page.tsx

@@ -0,0 +1,15 @@
+import { CopyPage } from "../../../_components/copy-page";
+import { Imagery } from "../../../_blocks/imagery";
+import { DocsHeader } from "../../../_blocks/shell";
+import { assets, provenance } from "../../../_data";
+
+export default function ImageryPage() {
+  return (
+    <>
+      <DocsHeader title="Imagery and icons" lead="The approved icons and imagery, and how to use each." provenance={provenance}>
+        <CopyPage />
+      </DocsHeader>
+      <Imagery assets={assets.assets} />
+    </>
+  );
+}

package/reference/app/(design)/design/system/(docs)/brand/logo/page.tsx

@@ -0,0 +1,15 @@
+import { CopyPage } from "../../../_components/copy-page";
+import { LogoUsage } from "../../../_blocks/logo-usage";
+import { DocsHeader } from "../../../_blocks/shell";
+import { assets, BASE, provenance, rules } from "../../../_data";
+
+export default function Logo() {
+  return (
+    <>
+      <DocsHeader title="Logo" lead="Each logo on the surfaces it may sit on, at its smallest, with its clear space." provenance={provenance}>
+        <CopyPage />
+      </DocsHeader>
+      <LogoUsage assets={assets.assets} rules={rules.rules} rulesHref={`${BASE}/rules`} />
+    </>
+  );
+}

package/reference/app/(design)/design/system/(docs)/brand/page.tsx

@@ -0,0 +1,16 @@
+import { CopyPage } from "../../_components/copy-page";
+import { Markdown } from "../../_components/prose";
+import { DocsHeader } from "../../_blocks/shell";
+import { editorial } from "../../_data";
+
+export default function Brand() {
+  const page = editorial.brand;
+  return (
+    <>
+      <DocsHeader title={page.title} lead={page.lead} editorial={page.by}>
+        <CopyPage />
+      </DocsHeader>
+      <Markdown text={page.body} />
+    </>
+  );
+}

package/reference/app/(design)/design/system/(docs)/brand/voice/page.tsx

@@ -0,0 +1,15 @@
+import { CopyPage } from "../../../_components/copy-page";
+import { DocsHeader } from "../../../_blocks/shell";
+import { VoiceTerms } from "../../../_blocks/voice-terms";
+import { provenance, taxonomy } from "../../../_data";
+
+export default function Voice() {
+  return (
+    <>
+      <DocsHeader title="Voice and terms" lead="The words we use, beside the ones we do not." provenance={provenance}>
+        <CopyPage />
+      </DocsHeader>
+      <VoiceTerms terms={taxonomy.terms} />
+    </>
+  );
+}

package/reference/app/(design)/design/system/(docs)/colour/page.tsx

@@ -0,0 +1,26 @@
+import { CopyPage } from "../../_components/copy-page";
+import { DocsHeader, DocsSection } from "../../_blocks/shell";
+import { PageContrast, RampSwatches, SemanticSwatches } from "../../_blocks/swatches";
+import { provenance, tokens } from "../../_data";
+
+export default function Colour() {
+  return (
+    <>
+      <DocsHeader title="Colour" lead="Generated from one brand colour by @designtools/tokens. Write the semantic names in components; the ramps are what they point at." provenance={provenance}>
+        <CopyPage />
+      </DocsHeader>
+      <DocsSection title="Semantic colours" lead="Each pair is measured on the colours the browser paints, in each mode.">
+        <SemanticSwatches tokens={tokens} />
+      </DocsSection>
+      <DocsSection
+        title="On the page"
+        lead="Each colour on each background. A label is measured on its own fill above; this is the rest: a colour used as text on the page needs 4.5:1, as a shape (a meter fill, an icon without words) 3:1."
+      >
+        <PageContrast tokens={tokens} />
+      </DocsSection>
+            <DocsSection title="Ramps">
+        <RampSwatches tokens={tokens} />
+      </DocsSection>
+    </>
+  );
+}

package/reference/app/(design)/design/system/(docs)/components/[slug]/page.tsx

@@ -0,0 +1,86 @@
+import { notFound } from "next/navigation";
+import { CopyPage } from "../../../_components/copy-page";
+import { A11yPanel } from "../../../_blocks/a11y-panel";
+import { AgentView } from "../../../_blocks/agent-view";
+import { Anatomy } from "../../../_blocks/anatomy";
+import { AskClaude } from "../../../_blocks/ask-claude";
+import { Examples } from "../../../_blocks/examples";
+import { Playground } from "../../../_blocks/playground";
+import { PreviewFrame } from "../../../_blocks/preview-frame";
+import { PropsTable } from "../../../_blocks/props-table";
+import { DocsHeader, DocsSection } from "../../../_blocks/shell";
+import { Usage } from "../../../_blocks/usage";
+import { VariantMatrix } from "../../../_blocks/variant-matrix";
+import { findBySlug, slugOf } from "../../../_blocks/lib/manifest";
+import { BASE, components, provenance } from "../../../_data";
+
+/** What a component needs to render at all. The rest comes from the controls. */
+const needs: Record<string, { props?: Record<string, unknown>; children?: string }> = {
+  Select: {
+    props: { label: "Project", value: "beacon", options: [{ value: "atlas", label: "Atlas" }, { value: "beacon", label: "Beacon" }] },
+    children: "",
+  },
+  Switch: { props: { "aria-label": "Notifications" }, children: "" },
+  Alert: { props: { title: "Timesheets close on Friday" } },
+};
+
+export function generateStaticParams() {
+  return components.components.map((c) => ({ slug: slugOf(c) }));
+}
+
+export default async function ComponentPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const entry = findBySlug(components, slug);
+  if (!entry) notFound();
+  const need = needs[entry.name] ?? {};
+  const preview = `${BASE}/preview/${slug}`;
+  const first = entry.examples?.canonical?.name;
+
+  return (
+    <>
+      <DocsHeader title={entry.name} lead={entry.description} source={entry.source} provenance={provenance}>
+        <CopyPage />
+      </DocsHeader>
+
+      <DocsSection title="Usage">
+        <Usage entry={entry} manifest={components} basePath={BASE} />
+      </DocsSection>
+
+      <DocsSection title="Examples" lead="Each is the real component. Copy the first one.">
+        <A11yPanel entry={entry}>
+          <Examples entry={entry} previewHref={preview} />
+        </A11yPanel>
+      </DocsSection>
+
+      <DocsSection title="Playground">
+        <AgentView entry={entry}>
+          <Playground entry={entry} props={need.props} children={need.children} />
+        </AgentView>
+      </DocsSection>
+
+      {!!entry.variants?.axes.length && (
+        <DocsSection title="Variants" lead={`From the ${entry.variants.from === "props" ? "props' types" : `${entry.variants.from}() config`}.`}>
+          <VariantMatrix entry={entry} props={need.props}>
+            {need.children === "" ? undefined : entry.name}
+          </VariantMatrix>
+        </DocsSection>
+      )}
+
+      {first && (
+        <DocsSection title="At each width">
+          <PreviewFrame src={`${preview}/${first}`} title={`${entry.name}: ${first}`} />
+        </DocsSection>
+      )}
+
+      <DocsSection title="Anatomy">
+        <Anatomy entry={entry} />
+      </DocsSection>
+
+      <DocsSection title="Props">
+        <PropsTable entry={entry} />
+      </DocsSection>
+
+      <AskClaude entry={entry} />
+    </>
+  );
+}

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

@@ -0,0 +1,35 @@
+import type { ReactNode } from "react";
+import wordmark from "@ds/brand/logos/wordmark.svg";
+import { DocsShell } from "../_blocks/shell";
+import { BASE, components, patterns, rules, taxonomy, TITLE } from "../_data";
+
+export default function DocsLayout({ children }: { children: ReactNode }) {
+  return (
+    <DocsShell
+      manifest={components}
+      rules={rules}
+      patterns={patterns}
+      terms={taxonomy}
+      title={TITLE}
+      logo={<img src={wordmark.src} alt="" className="h-6 w-auto" />}
+      basePath={BASE}
+      brand={[
+        { label: "Principles and language", href: `${BASE}/brand` },
+        { label: "Logo", href: `${BASE}/brand/logo` },
+        { label: "Imagery and icons", href: `${BASE}/brand/imagery` },
+        { label: "Voice and terms", href: `${BASE}/brand/voice` },
+      ]}
+      foundations={[
+        { label: "Colour", href: `${BASE}/colour` },
+        { label: "Type", href: `${BASE}/type` },
+        { label: "Scale", href: `${BASE}/scale` },
+      ]}
+      standards={[
+        { label: "Standards", href: `${BASE}/standards` },
+        { label: "Vocabulary", href: `${BASE}/vocabulary` },
+      ]}
+    >
+      {children}
+    </DocsShell>
+  );
+}

package/reference/app/(design)/design/system/(docs)/page.tsx

@@ -0,0 +1,48 @@
+import Link from "next/link";
+import { CopyPage } from "../_components/copy-page";
+import { DocsHeader, DocsSection } from "../_blocks/shell";
+import { groupFamilies, slugOf } from "../_blocks/lib/manifest";
+import { StatusBadge } from "../_blocks/lib/status";
+import { BASE, components, provenance, TITLE } from "../_data";
+
+export default function Overview() {
+  return (
+    <>
+      <DocsHeader
+        title={TITLE}
+        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. Every page is built from the code."
+        provenance={provenance}
+      >
+        <p className="text-sm">
+          For agents: <a href={`${BASE}.md`} className="underline underline-offset-2">this site as markdown</a>, the whole
+          system in <a href={`${BASE}/md/context`} className="underline underline-offset-2">one file</a>, or the{" "}
+          <a href={`${BASE}/manifest/components.json`} className="underline underline-offset-2">manifest as data</a>. Add{" "}
+          <code className="font-mono text-xs">.md</code> to any page.
+        </p>
+        <CopyPage />
+      </DocsHeader>
+      {/* a component's parts (CardHeader, CardTitle) are named on its tile, not given tiles of their own */}
+      {groupFamilies(components).map((group) => (
+        <DocsSection key={group.category} title={group.category}>
+          <ul className="grid gap-3 sm:grid-cols-2">
+            {group.families.map(({ head: c, parts }) => (
+              <li key={c.source + c.export}>
+                <Link
+                  href={`${BASE}/components/${slugOf(c)}`}
+                  className="flex h-full flex-col gap-2 rounded-lg border border-border p-4 hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring"
+                >
+                  <span className="flex items-center justify-between gap-2">
+                    <span className="font-medium">{c.name}</span>
+                    <StatusBadge status={c.status} />
+                  </span>
+                  {c.description && <span className="line-clamp-2 text-sm text-muted-foreground">{c.description}</span>}
+                  {parts.length > 0 && <span className="font-mono text-xs text-muted-foreground">with {parts.map((p) => p.name).join(", ")}</span>}
+                </Link>
+              </li>
+            ))}
+          </ul>
+        </DocsSection>
+      ))}
+    </>
+  );
+}

package/reference/app/(design)/design/system/(docs)/patterns/[id]/page.tsx

@@ -0,0 +1,23 @@
+import { notFound } from "next/navigation";
+import { CopyPage } from "../../../_components/copy-page";
+import { Pattern } from "../../../_blocks/pattern";
+import { DocsHeader } from "../../../_blocks/shell";
+import { BASE, components, patterns, provenance } from "../../../_data";
+
+export function generateStaticParams() {
+  return patterns.patterns.map((p) => ({ id: p.id }));
+}
+
+export default async function PatternPage({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+  const pattern = patterns.patterns.find((p) => p.id === id);
+  if (!pattern) notFound();
+  return (
+    <>
+      <DocsHeader title={pattern.name} lead={pattern.description} source={pattern.source} provenance={provenance}>
+        <CopyPage />
+      </DocsHeader>
+      <Pattern pattern={pattern} manifest={components} basePath={BASE} />
+    </>
+  );
+}

package/reference/app/(design)/design/system/(docs)/rules/page.tsx

@@ -0,0 +1,42 @@
+import { CopyPage } from "../../_components/copy-page";
+import { Rule } from "../../_blocks/rule";
+import { DocsHeader, DocsSection } from "../../_blocks/shell";
+import { provenance, rules } from "../../_data";
+
+/** A demonstration for the rule that needs persuading: the same control, too small and big enough. */
+function TouchTargets() {
+  return (
+    <div className="flex flex-wrap items-end gap-8 rounded-lg bg-muted p-6">
+      {[32, 48].map((size) => (
+        <figure key={size} className="flex flex-col items-center gap-2">
+          <span className="flex items-center justify-center border border-dashed border-destructive" style={{ width: size, height: size }}>
+            <span className="size-4 rounded-full bg-primary" />
+          </span>
+          <figcaption className="text-xs text-muted-foreground">
+            {size} px {size < 48 ? "is missed" : "is hit"}
+          </figcaption>
+        </figure>
+      ))}
+    </div>
+  );
+}
+
+export default function Rules() {
+  const groups = (["brand", "interface"] as const).map((kind) => ({ kind, rules: rules.rules.filter((r) => r.kind === kind) }));
+  return (
+    <>
+      <DocsHeader title="Rules" lead="Brand and interface rules in one format, each with the check that proves it. Written for people; agents read the same rule." provenance={provenance}>
+        <CopyPage />
+      </DocsHeader>
+      {groups.map((g) => (
+        <DocsSection key={g.kind} title={g.kind === "brand" ? "Brand" : "Interface"}>
+          {g.rules.map((r) => (
+            <Rule key={r.id} rule={r}>
+              {r.id === "touch-target" ? <TouchTargets /> : null}
+            </Rule>
+          ))}
+        </DocsSection>
+      ))}
+    </>
+  );
+}

package/reference/app/(design)/design/system/(docs)/scale/page.tsx

@@ -0,0 +1,15 @@
+import { CopyPage } from "../../_components/copy-page";
+import { Scale } from "../../_blocks/scale";
+import { DocsHeader } from "../../_blocks/shell";
+import { provenance, tokens } from "../../_data";
+
+export default function ScalePage() {
+  return (
+    <>
+      <DocsHeader title="Scale" lead="Space, size, radius, elevation and motion. Hover a motion row to play it." provenance={provenance}>
+        <CopyPage />
+      </DocsHeader>
+      <Scale tokens={tokens} />
+    </>
+  );
+}

package/reference/app/(design)/design/system/(docs)/standards/page.tsx

@@ -0,0 +1,21 @@
+import { CopyPage } from "../../_components/copy-page";
+import { DocsHeader, DocsSection } from "../../_blocks/shell";
+import { AdherenceSummary } from "../../_blocks/adherence-summary";
+import { Standards } from "../../_blocks/standards";
+import { adherence, baselines, provenance } from "../../_data";
+
+export default function StandardsPage() {
+  return (
+    <>
+      <DocsHeader title="Standards" lead="The budgets and targets the project holds itself to, read from .mxa/stack.json, where the checks read them too." provenance={provenance}>
+        <CopyPage />
+      </DocsHeader>
+      <DocsSection title="Targets">
+        <Standards baselines={baselines} />
+      </DocsSection>
+      <DocsSection title="Adherence" lead="How closely the product follows the system, from @designtools/adherence. It informs; it never blocks.">
+        <AdherenceSummary report={adherence} />
+      </DocsSection>
+    </>
+  );
+}

package/reference/app/(design)/design/system/(docs)/type/page.tsx

@@ -0,0 +1,15 @@
+import { CopyPage } from "../../_components/copy-page";
+import { DocsHeader } from "../../_blocks/shell";
+import { TypeRamp } from "../../_blocks/type-ramp";
+import { provenance, tokens } from "../../_data";
+
+export default function Type() {
+  return (
+    <>
+      <DocsHeader title="Type" lead="A size is never set without its leading." provenance={provenance}>
+        <CopyPage />
+      </DocsHeader>
+      <TypeRamp tokens={tokens} />
+    </>
+  );
+}

package/reference/app/(design)/design/system/(docs)/vocabulary/page.tsx

@@ -0,0 +1,15 @@
+import { CopyPage } from "../../_components/copy-page";
+import { Glossary } from "../../_blocks/glossary";
+import { DocsHeader } from "../../_blocks/shell";
+import { provenance, taxonomy } from "../../_data";
+
+export default function Vocabulary() {
+  return (
+    <>
+      <DocsHeader title="Vocabulary" lead="Every name in the system. Search by a wrong name and it finds the right one." provenance={provenance}>
+        <CopyPage />
+      </DocsHeader>
+      <Glossary terms={taxonomy.terms} />
+    </>
+  );
+}

package/reference/app/(design)/design/system/_components/copy-page.tsx

@@ -0,0 +1,32 @@
+"use client";
+
+import { usePathname } from "next/navigation";
+import { useState } from "react";
+
+/** Copies this page's markdown, for people handing it to an assistant. The same markdown any agent gets at `.md`. */
+export function CopyPage() {
+  const path = usePathname();
+  const [state, setState] = useState<"idle" | "copied" | "failed">("idle");
+  const copy = async () => {
+    try {
+      const res = await fetch(`${path.replace(/\/$/, "")}.md`);
+      await navigator.clipboard.writeText(await res.text());
+      setState("copied");
+    } catch {
+      setState("failed");
+    }
+    setTimeout(() => setState("idle"), 1500);
+  };
+  return (
+    <button
+      type="button"
+      onClick={copy}
+      className="min-h-[var(--docs-target,2.75rem)] self-start rounded-md border border-border px-2.5 py-1 text-xs hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring"
+    >
+      {state === "copied" ? "Copied" : state === "failed" ? "Could not copy" : "Copy page as markdown"}
+      <span className="sr-only" aria-live="polite">
+        {state === "copied" ? "Page copied" : ""}
+      </span>
+    </button>
+  );
+}

package/reference/app/(design)/design/system/_components/prose.tsx

@@ -0,0 +1,26 @@
+/** The few markdown shapes editorial pages use: headings, paragraphs and bullet lists, with bold and code. */
+export function Markdown({ text }: { text: string }) {
+  const blocks = text.split(/\n{2,}/);
+  return (
+    <div className="flex max-w-prose flex-col gap-4">
+      {blocks.map((b, i) => {
+        if (b.startsWith("## ")) return <h2 key={i} className="pt-4 text-xl font-semibold">{b.slice(3)}</h2>;
+        if (b.split("\n").every((l) => l.startsWith("- ")))
+          return (
+            <ul key={i} className="flex list-disc flex-col gap-2 pl-5">
+              {b.split("\n").map((l) => (
+                <li key={l}>{inline(l.slice(2))}</li>
+              ))}
+            </ul>
+          );
+        return <p key={i}>{inline(b)}</p>;
+      })}
+    </div>
+  );
+}
+
+function inline(text: string) {
+  return text.split(/(\*\*[^*]+\*\*|`[^`]+`)/).map((part, i) =>
+    part.startsWith("**") ? <strong key={i}>{part.slice(2, -2)}</strong> : part.startsWith("`") ? <code key={i} className="font-mono text-[0.9em]">{part.slice(1, -1)}</code> : part,
+  );
+}

package/reference/app/(design)/design/system/_data.ts

@@ -0,0 +1,53 @@
+/**
+ * Everything the docs read, in one place, for the HTML pages and the markdown
+ * route alike: the manifest, the project's standards, the provenance of this
+ * build, and the editorial pages people write.
+ */
+
+import assetsJson from "@ds/manifest/assets.json";
+import componentsJson from "@ds/manifest/components.json";
+import patternsJson from "@ds/manifest/patterns.json";
+import rulesJson from "@ds/manifest/rules.json";
+import taxonomyJson from "@ds/manifest/taxonomy.json";
+import tokensJson from "@ds/manifest/tokens.json";
+import stack from "../../../../.mxa/stack.json";
+import adherenceJson from "./_adherence.json";
+import provenanceJson from "./_provenance.json";
+import type { AdherenceReport } from "./_blocks/lib/adherence-types";
+import type { AssetsManifest, PatternsManifest, RulesManifest, TaxonomyManifest } from "./_blocks/lib/manifest-types";
+import { readComponents, readTokens } from "./_blocks/lib/manifest";
+
+export const BASE = "/design/system";
+export const TITLE = "Demo design system";
+
+export const components = readComponents(componentsJson);
+export const tokens = readTokens(tokensJson);
+export const rules = rulesJson as RulesManifest;
+export const patterns = patternsJson as PatternsManifest;
+export const taxonomy = taxonomyJson as TaxonomyManifest;
+export const assets = assetsJson as AssetsManifest;
+export const baselines = stack.baselines as Record<string, unknown>;
+export const provenance = (provenanceJson as { line: string }).line;
+export const adherence = adherenceJson as unknown as AdherenceReport;
+
+export const manifestFiles = { components: componentsJson, tokens: tokensJson, rules: rulesJson, patterns: patternsJson, taxonomy: taxonomyJson, assets: assetsJson };
+
+/** Editorial pages: written by people, so they carry an author and a review date, never a commit. */
+export const editorial = {
+  brand: {
+    title: "Brand",
+    by: { author: "Demo studio", reviewed: "10 October 2026", status: "draft" as const },
+    lead: "Plain, calm and exact. We sound like the person in the room who has read the contract.",
+    body: [
+      "## Principles",
+      "",
+      "- **Say the thing.** A label names what happens; a message says what to do next.",
+      "- **Quiet by default.** One primary action a screen. Colour is for meaning, not decoration.",
+      "- **Nothing invented.** Every value comes from a token, every example from the real component.",
+      "",
+      "## Design language",
+      "",
+      "Generous space, a single teal for action, and greys that lean cool. Corners are soft but small: this is a ledger, not a toy. Motion is short and settles; nothing bounces.",
+    ].join("\n"),
+  },
+};

package/reference/app/(design)/design/system/manifest/[file]/route.ts

@@ -0,0 +1,15 @@
+import { manifestFiles } from "../../_data";
+
+export const dynamic = "force-static";
+
+export function generateStaticParams() {
+  return Object.keys(manifestFiles).map((name) => ({ file: `${name}.json` }));
+}
+
+/** The manifest served beside the docs, so an agent outside the repo gets the exact data, not prose about it. */
+export async function GET(_: Request, { params }: { params: Promise<{ file: string }> }) {
+  const { file } = await params;
+  const data = manifestFiles[file.replace(/\.json$/, "") as keyof typeof manifestFiles];
+  if (!data) return new Response(`# Not found\n\nNo manifest file called ${file}.\n`, { status: 404, headers: { "content-type": "text/markdown; charset=utf-8" } });
+  return Response.json(data);
+}

package/reference/app/(design)/design/system/md/[[...path]]/route.ts

@@ -0,0 +1,94 @@
+import {
+  adherenceMarkdown,
+  assetsMarkdown,
+  coloursMarkdown,
+  componentMarkdown,
+  generatedHeader,
+  editorialHeader,
+  glossaryMarkdown,
+  manifestLinks,
+  patternMarkdown,
+  ruleMarkdown,
+  scaleMarkdown,
+  standardsMarkdown,
+  systemMarkdown,
+  typeMarkdown,
+} from "../../_blocks/lib/markdown";
+import { findBySlug, groupByCategory, slugOf } from "../../_blocks/lib/manifest";
+import { adherence, assets, BASE, baselines, components, editorial, patterns, provenance, rules, taxonomy, TITLE, tokens } from "../../_data";
+
+/**
+ * The markdown form of every docs page, generated from the manifest rather
+ * than converted from HTML. proxy.ts sends `Accept: text/markdown` and `.md`
+ * requests here; a page that does not exist gets a markdown 404.
+ */
+export async function GET(_: Request, { params }: { params: Promise<{ path?: string[] }> }) {
+  const path = ((await params).path ?? []).join("/").replace(/\.md$/, "");
+  const page = render(path);
+  const canonical = `${BASE}${path ? `/${path}` : ""}`;
+  return new Response(page ?? `# Not found\n\nThere is no page at \`${canonical}\`. The index is at [${BASE}.md](${BASE}.md).\n`, {
+    status: page ? 200 : 404,
+    headers: {
+      "content-type": "text/markdown; charset=utf-8",
+      vary: "Accept",
+      link: `<${canonical}>; rel="canonical"`,
+    },
+  });
+}
+
+function render(path: string): string | undefined {
+  const generated = (md: string) => generatedHeader(provenance) + md;
+  const [section, id] = path.split("/");
+  switch (section) {
+    case "":
+      return generated(
+        [
+          `# ${TITLE}`,
+          "",
+          "The brand and the design system in one place. Every page here has a markdown form: add `.md` to its URL.",
+          "",
+          "## Pages",
+          "",
+          `- [Brand](${BASE}/brand.md), [logo](${BASE}/brand/logo.md), [imagery](${BASE}/brand/imagery.md), [voice and terms](${BASE}/brand/voice.md)`,
+          `- [Colour](${BASE}/colour.md), [type](${BASE}/type.md), [scale](${BASE}/scale.md)`,
+          `- [Rules](${BASE}/rules.md)`,
+          ...patterns.patterns.map((p) => `- Pattern: [${p.name}](${BASE}/patterns/${p.id}.md)`),
+          ...groupByCategory(components).flatMap((g) => g.components.map((c) => `- ${g.category}: [${c.name}](${BASE}/components/${slugOf(c)}.md), ${c.status ?? "status not set"}`)),
+          `- [Standards](${BASE}/standards.md), [vocabulary](${BASE}/vocabulary.md)`,
+          `- Everything in [one file](${BASE}/context.md)`,
+          "",
+          manifestLinks(`${BASE}/manifest`),
+        ].join("\n"),
+      );
+    case "context":
+      return systemMarkdown({ components, tokens, rules: rules.rules, patterns: patterns.patterns, terms: taxonomy.terms }, TITLE, provenance);
+    case "brand":
+      if (id === "logo") return generated(assetsMarkdown(assets.assets.filter((a) => a.kind === "logo")) + "\n" + rules.rules.filter((r) => r.kind === "brand").map(ruleMarkdown).join("\n"));
+      if (id === "imagery") return generated(assetsMarkdown(assets.assets.filter((a) => a.kind !== "logo")));
+      if (id === "voice") return generated(glossaryMarkdown(taxonomy.terms.filter((t) => t.kind === "product" || t.wrong?.length)));
+      if (!id) return editorialHeader(editorial.brand.by) + `# ${editorial.brand.title}\n\n${editorial.brand.lead}\n\n${editorial.brand.body}\n`;
+      return undefined;
+    case "colour":
+      return generated(coloursMarkdown(tokens));
+    case "type":
+      return generated(typeMarkdown(tokens));
+    case "scale":
+      return generated(scaleMarkdown(tokens));
+    case "rules":
+      return generated(["# Rules", "", ...rules.rules.map(ruleMarkdown)].join("\n"));
+    case "patterns": {
+      const p = patterns.patterns.find((x) => x.id === id);
+      return p && generated(patternMarkdown(p, 1));
+    }
+    case "components": {
+      const c = id ? findBySlug(components, id) : undefined;
+      return c && generated(componentMarkdown(c, 1));
+    }
+    case "standards":
+      return generated(standardsMarkdown(baselines) + "\n" + adherenceMarkdown(adherence));
+    case "vocabulary":
+      return generated(glossaryMarkdown(taxonomy.terms));
+    default:
+      return undefined;
+  }
+}

package/reference/app/(design)/design/system/preview/[slug]/[example]/page.tsx

@@ -0,0 +1,23 @@
+import { notFound } from "next/navigation";
+import { PreviewExample, PreviewSurface } from "../../../_blocks/preview-frame";
+import { findBySlug } from "../../../_blocks/lib/manifest";
+import { components } from "../../../_data";
+
+/** One example on its own: the target for the preview frame and for visual regression snapshots. */
+export default async function Preview({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ slug: string; example: string }>;
+  searchParams: Promise<{ theme?: string }>;
+}) {
+  const { slug, example } = await params;
+  const { theme } = await searchParams;
+  const entry = findBySlug(components, slug);
+  if (!entry?.examples) notFound();
+  return (
+    <PreviewSurface theme={theme}>
+      <PreviewExample entry={entry} example={decodeURIComponent(example)} />
+    </PreviewSurface>
+  );
+}