@designtools/docs 0.0.0-stage → 0.2.0

package/src/next/pages.tsx

@@ -0,0 +1,483 @@
+import { ArrowRight, ArrowUpRight } from "lucide-react";
+import Link from "next/link";
+import type { ReactNode } from "react";
+import { cx, display } from "../lib/cx";
+import { AdherenceSummary } from "../adherence-summary";
+import { Anatomy } from "../anatomy";
+import { Examples } from "../examples";
+import { Glossary } from "../glossary";
+import { Imagery } from "../imagery";
+import { groupFamilies, slugOf } from "../lib/manifest";
+import { StatusBadge } from "../lib/status";
+import { LogoUsage } from "../logo-usage";
+import { PageActions } from "../page-actions";
+import { Pattern } from "../pattern";
+import { PreviewFrame } from "../preview-frame";
+import { PropsTable } from "../props-table";
+import { Rule, RuleIndex } from "../rule";
+import { Scale } from "../scale";
+import { DocsFooter, DocsHeader, DocsSection } from "../shell";
+import { Standards } from "../standards";
+import { PageContrast, RampSwatches, SemanticSwatches } from "../swatches";
+import { TypeRamp } from "../type-ramp";
+import { Usage } from "../usage";
+import { VariantMatrix } from "../variant-matrix";
+import { VoiceTerms } from "../voice-terms";
+import { Workbench } from "../workbench";
+import { Markdown } from "./prose";
+import { COPY, type PageRef, type Site } from "./site";
+
+/** Every block a page renders, by the name `config.blocks` replaces it under. */
+const DEFAULT_BLOCKS = {
+  AdherenceSummary,
+  Anatomy,
+  Examples,
+  Glossary,
+  Imagery,
+  LogoUsage,
+  PageContrast,
+  Pattern,
+  PreviewFrame,
+  PropsTable,
+  RampSwatches,
+  Rule,
+  RuleIndex,
+  Scale,
+  SemanticSwatches,
+  Standards,
+  TypeRamp,
+  Usage,
+  VariantMatrix,
+  VoiceTerms,
+  Workbench,
+};
+type Blocks = typeof DEFAULT_BLOCKS;
+
+function blocksOf(site: Site): Blocks {
+  return { ...DEFAULT_BLOCKS, ...(site.config.blocks as Partial<Blocks> | undefined) };
+}
+
+/** The page for a reference, composed of blocks. */
+export function DocsPageView({ site, page }: { site: Site; page: PageRef }) {
+  const B = blocksOf(site);
+  const { base, config } = site;
+  const footer = <DocsFooter provenance={config.provenance} />;
+  const header = (title: string, lead?: string) => (
+    <DocsHeader title={title} lead={lead}>
+      <PageActions basePath={base} />
+    </DocsHeader>
+  );
+
+  switch (page.kind) {
+    case "overview":
+      return <Overview site={site} />;
+
+    case "editorial":
+      return (
+        <>
+          {header(page.page.title, page.page.lead)}
+          {typeof page.page.body === "string" ? <Markdown text={page.page.body} /> : page.page.body}
+          <DocsFooter editorial={page.page.by} />
+        </>
+      );
+
+    case "logo":
+      return (
+        <>
+          {header(COPY.logo.title, COPY.logo.lead)}
+          <B.LogoUsage assets={site.assets.assets} rules={site.rules.rules} rulesHref={`${base}/rules`} />
+          {footer}
+        </>
+      );
+
+    case "imagery":
+      return (
+        <>
+          {header(COPY.imagery.title, COPY.imagery.lead)}
+          <B.Imagery assets={site.assets.assets} />
+          {footer}
+        </>
+      );
+
+    case "voice":
+      return (
+        <>
+          {header(COPY.voice.title, COPY.voice.lead)}
+          <B.VoiceTerms terms={site.taxonomy.terms} />
+          {footer}
+        </>
+      );
+
+    case "colour":
+      return (
+        <>
+          {header(COPY.colour.title, COPY.colour.lead)}
+          <DocsSection title="Semantic colours" lead="Each pair is measured on the colours the browser paints, in each mode.">
+            <B.SemanticSwatches tokens={site.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."
+          >
+            <B.PageContrast tokens={site.tokens} />
+          </DocsSection>
+          <DocsSection title="Ramps">
+            <B.RampSwatches tokens={site.tokens} />
+          </DocsSection>
+          {footer}
+        </>
+      );
+
+    case "type":
+      return (
+        <>
+          {header(COPY.type.title, COPY.type.lead)}
+          <B.TypeRamp tokens={site.tokens} />
+          {footer}
+        </>
+      );
+
+    case "scale":
+      return (
+        <>
+          {header(COPY.scale.title, COPY.scale.lead)}
+          <B.Scale tokens={site.tokens} />
+          {footer}
+        </>
+      );
+
+    case "rules":
+      return (
+        <>
+          {header(COPY.rules.title, COPY.rules.lead)}
+          <DocsSection title="Every rule" lead="A line each: what it covers, how settled it is, and how it is checked.">
+            <B.RuleIndex rules={[...site.rules.rules].sort((a, b) => a.kind.localeCompare(b.kind))} />
+          </DocsSection>
+          {(["brand", "interface"] as const).map((kind) => {
+            const rules = site.rules.rules.filter((r) => r.kind === kind);
+            return rules.length ? (
+              <DocsSection key={kind} title={kind === "brand" ? "Brand" : "Interface"}>
+                {rules.map((r) => (
+                  <B.Rule key={r.id} rule={r}>
+                    {config.demonstrations?.[r.id]}
+                  </B.Rule>
+                ))}
+              </DocsSection>
+            ) : null;
+          })}
+          {footer}
+        </>
+      );
+
+    case "standards":
+      return (
+        <>
+          {header(COPY.standards.title, COPY.standards.lead)}
+          {config.baselines && (
+            <DocsSection title="Targets">
+              <B.Standards baselines={config.baselines} />
+            </DocsSection>
+          )}
+          {config.adherence && (
+            <DocsSection title="Adherence" lead="How closely the product follows the system, from @designtools/adherence. It informs; it never blocks.">
+              <B.AdherenceSummary report={config.adherence} />
+            </DocsSection>
+          )}
+          {footer}
+        </>
+      );
+
+    case "vocabulary":
+      return (
+        <>
+          {header(COPY.vocabulary.title, COPY.vocabulary.lead)}
+          <B.Glossary terms={site.taxonomy.terms} />
+          {footer}
+        </>
+      );
+
+    case "pattern":
+      return (
+        <>
+          <DocsHeader title={page.pattern.name} lead={page.pattern.description} status={page.pattern.status}>
+            <PageActions basePath={base} />
+          </DocsHeader>
+          <B.Pattern pattern={page.pattern} manifest={site.components} basePath={base} />
+          <DocsFooter source={page.pattern.source} provenance={config.provenance} />
+        </>
+      );
+
+    case "component":
+      return <ComponentPage site={site} blocks={B} entry={page.entry} />;
+  }
+}
+
+function ComponentPage({ site, blocks: B, entry }: { site: Site; blocks: Blocks; entry: Extract<PageRef, { kind: "component" }>["entry"] }) {
+  const { base, config } = site;
+  // A part (TabsPanel, CardHeader) renders inside its family's root, so it is shown there, never alone:
+  // a part rendered on its own can throw for want of the root's context.
+  const head = entry.category ? undefined : site.components.components.find((c) => c.source === entry.source && c.category);
+  if (head)
+    return (
+      <>
+        <DocsHeader title={entry.name} lead={entry.description ?? `A part of ${head.name}, used inside it.`}>
+          <PageActions basePath={base} />
+        </DocsHeader>
+        <DocsSection title="Part of" lead={`Its examples, variants and anatomy are on ${head.name}'s page, where it renders inside the whole.`}>
+          <Link
+            href={`${base}/components/${slugOf(head)}`}
+            className="group flex max-w-md items-center justify-between gap-3 border-t border-border py-5 focus-visible:outline-2 focus-visible:outline-ring"
+          >
+            <span className="flex flex-col gap-1">
+              <span className="text-xl tracking-tight underline-offset-4 group-hover:underline">{head.name}</span>
+              {head.description && <span className="line-clamp-2 text-sm text-muted-foreground">{head.description}</span>}
+            </span>
+            <ArrowRight aria-hidden className="size-5 shrink-0 text-muted-foreground" />
+          </Link>
+        </DocsSection>
+        <DocsSection title="Props">
+          <B.PropsTable entry={entry} />
+        </DocsSection>
+        <DocsFooter source={entry.source} provenance={config.provenance} />
+      </>
+    );
+
+  const setup = config.workbench?.[entry.name] ?? {};
+  const preview = `${base}/preview/${slugOf(entry)}`;
+  const first = entry.examples?.canonical?.name;
+  // the brand's named backgrounds (--surface-<name>), offered on the workbench's stage
+  const backgrounds = site.tokens.tokens.map((t) => t.name.slice(2)).filter((n) => /^surface-[a-z]/.test(n) && !n.endsWith("-foreground"));
+
+  return (
+    <>
+      <DocsHeader title={entry.name} lead={entry.description}>
+        <PageActions basePath={base} />
+      </DocsHeader>
+
+      <DocsSection title="Usage">
+        <B.Usage entry={entry} manifest={site.components} basePath={base} />
+      </DocsSection>
+
+      {/* the component's one main area: live, with its properties, code, props, actions, agent view and accessibility */}
+      <B.Workbench
+        entry={entry}
+        props={setup.props}
+        content={setup.content}
+        wrap={setup.wrap}
+        backgrounds={backgrounds}
+        previewHref={first && `${preview}/${first}`}
+      >
+        {setup.children}
+      </B.Workbench>
+
+      <DocsSection title="Anatomy">
+        <B.Anatomy entry={entry} />
+      </DocsSection>
+
+      <DocsSection title="Examples" lead="The usual use first, then each do beside its don't. Every one is the real component.">
+        <B.Examples entry={entry} previewHref={preview} />
+      </DocsSection>
+
+      {!!entry.variants?.axes.length && (
+        <DocsSection
+          title="Variants"
+          lead={`Every combination, from the ${entry.variants.from === "props" ? "props' types" : `${entry.variants.from}() config`}, then each state.`}
+        >
+          <B.VariantMatrix entry={entry} props={setup.props}>
+            {setup.children === "" ? undefined : (setup.content ?? entry.name)}
+          </B.VariantMatrix>
+        </DocsSection>
+      )}
+
+      {first && (
+        <DocsSection title="At each width">
+          <B.PreviewFrame src={`${preview}/${first}`} title={`${entry.name}: ${first}`} />
+        </DocsSection>
+      )}
+
+      <DocsFooter source={entry.source} provenance={config.provenance} />
+    </>
+  );
+}
+
+/** 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 }: { site: Site }) {
+  const { base, config } = site;
+  const families = groupFamilies(site.components);
+  const count = families.reduce((n, g) => n + g.families.length, 0);
+  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: { title: string; href: string; why: string; count: string; preview: ReactNode }[] = [];
+  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 ? <span className="flex h-10 items-center [&_img]:h-8 [&_svg]:h-8">{config.logo}</span> : 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: (
+      <span className="flex items-center gap-4">
+        <span className="flex -space-x-1.5">
+          {fills.map((n) => (
+            <span key={n} aria-hidden className="size-8 rounded-full ring-2 ring-canvas" style={{ background: `var(${n})` }} />
+          ))}
+        </span>
+        <span aria-hidden className={cx(display, "text-3xl leading-none tracking-tight")}>
+          Aa
+        </span>
+      </span>
+    ),
+  });
+  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: (
+        <span className="flex flex-col gap-1.5 text-sm">
+          {site.rules.rules
+            .filter((r) => r.kind === "brand")
+            .slice(0, 2)
+            .map((r) => (
+              <span key={r.id} className="flex items-center gap-2">
+                <StatusBadge status={r.status} />
+                <span className="truncate">{r.title}</span>
+              </span>
+            ))}
+        </span>
+      ),
+    });
+  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: (
+        <span className="flex flex-wrap gap-1.5">
+          {families.slice(0, 6).map((g) => (
+            <span key={g.category} className="inline-flex min-h-7 items-center rounded-md bg-muted px-2 text-xs">
+              {g.category} <span className="ml-1.5 text-muted-foreground tabular-nums">{g.families.length}</span>
+            </span>
+          ))}
+        </span>
+      ),
+    });
+  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: <span className="text-sm text-muted-foreground">{site.patterns.patterns.slice(0, 3).map((p) => p.name).join(" · ")}</span>,
+    });
+  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 : (
+          <span className="flex w-full max-w-56 items-center gap-3">
+            <span className="h-1.5 flex-1 overflow-hidden rounded-full bg-muted">
+              <span className="block h-full rounded-full bg-canvas-foreground" style={{ width: `${Math.round(share * 100)}%` }} />
+            </span>
+            <span className="text-sm tabular-nums">{Math.round(share * 100)}%</span>
+          </span>
+        ),
+    });
+  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 ? (
+        <span className="text-sm">
+          Say <strong className="font-semibold">{example.name}</strong>, <span className="text-muted-foreground line-through decoration-current/40">{example.wrong?.[0]}</span>
+        </span>
+      ) : 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 (
+    <>
+      {!config.hero && (
+        <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."}>
+          <PageActions basePath={base} />
+        </DocsHeader>
+      )}
+
+      <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.">
+        <ul data-slot="overview-sections" className="grid gap-x-12 md:grid-cols-2">
+          {sections.map((sec) => (
+            <li key={sec.title} className="border-t border-border">
+              <Link href={sec.href} className="group flex h-full flex-col gap-4 py-7 focus-visible:outline-2 focus-visible:outline-ring">
+                <span className="flex items-baseline justify-between gap-4">
+                  <span className="text-2xl leading-tight tracking-tight underline-offset-[6px] group-hover:underline">{sec.title}</span>
+                  <span className="shrink-0 text-xs text-muted-foreground tabular-nums">{sec.count}</span>
+                </span>
+                <span className="max-w-md text-base leading-relaxed text-muted-foreground">{sec.why}</span>
+                {sec.preview && <span className="mt-auto flex min-h-10 items-center pt-2">{sec.preview}</span>}
+              </Link>
+            </li>
+          ))}
+        </ul>
+      </DocsSection>
+
+      {config.overview?.agentic !== false && (
+        <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."
+          }
+        >
+          <ol data-slot="overview-loop" className="grid gap-x-6 gap-y-8 sm:grid-cols-2 xl:grid-cols-5">
+            {loop.map(([title, body], i) => (
+              <li key={title} className="relative flex flex-col gap-3 xl:pr-2">
+                <span className="flex items-center gap-3">
+                  <span className="grid size-8 shrink-0 place-items-center rounded-full bg-canvas-foreground text-sm font-medium text-canvas tabular-nums">{i + 1}</span>
+                  {i < loop.length - 1 && <span aria-hidden className="hidden h-px flex-1 bg-border xl:block" />}
+                </span>
+                <span className="text-lg leading-snug tracking-tight">{title}</span>
+                <span className="text-sm leading-relaxed text-muted-foreground">{body}</span>
+              </li>
+            ))}
+          </ol>
+          <p className="flex flex-wrap items-center gap-x-2 gap-y-1 text-sm text-muted-foreground">
+            See it the way an agent does:
+            <a href={`${base}.md`} className="inline-flex items-center gap-1 font-medium text-canvas-foreground underline underline-offset-4 hover:decoration-2">
+              this page as markdown <ArrowUpRight aria-hidden className="size-3.5" />
+            </a>
+          </p>
+        </DocsSection>
+      )}
+      <DocsFooter provenance={config.provenance} />
+    </>
+  );
+}
+

package/src/next/prose.tsx

@@ -0,0 +1,97 @@
+import { DocsSection } from "../shell";
+
+/**
+ * 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.
+ */
+export function Markdown({ text }: { text: string }) {
+  const sections: { title?: string; blocks: string[] }[] = [{ blocks: [] }];
+  for (const b of text.split(/\n{2,}/)) {
+    if (b.startsWith("## ")) sections.push({ title: b.slice(3), blocks: [] });
+    else sections[sections.length - 1].blocks.push(b);
+  }
+  return (
+    <>
+      {sections.map((s, i) =>
+        s.title ? (
+          <DocsSection key={s.title} title={s.title}>
+            <Blocks blocks={s.blocks} />
+          </DocsSection>
+        ) : (
+          s.blocks.length > 0 && <Blocks key={i} blocks={s.blocks} />
+        ),
+      )}
+    </>
+  );
+}
+
+function Blocks({ blocks }: { blocks: string[] }) {
+  return (
+    <div className="flex flex-col gap-5">
+      {blocks.map((b, i) => {
+        if (b.startsWith("### "))
+          return (
+            <h3 key={i} className="mt-4 max-w-3xl text-2xl leading-snug tracking-tight first:mt-0">
+              {inline(b.slice(4))}
+            </h3>
+          );
+        const lines = b.split("\n");
+        if (lines.every((l) => l.startsWith("- "))) {
+          const items = lines.map((l) => l.slice(2));
+          const principles = items.every((l) => /^\*\*[^*]+\*\*/.test(l));
+          if (principles)
+            return (
+              <ol key={i} className="flex max-w-3xl flex-col gap-12">
+                {items.map((l, n) => {
+                  const [, head, rest] = /^\*\*([^*]+)\*\*\s*(.*)$/.exec(l) ?? [];
+                  return (
+                    <li key={l} className="grid grid-cols-[3rem_minmax(0,1fr)] items-baseline gap-x-4 gap-y-3 sm:grid-cols-[4rem_minmax(0,1fr)]">
+                      <span className="text-lg text-muted-foreground tabular-nums">{String(n + 1).padStart(2, "0")}</span>
+                      <span className="flex flex-col gap-3">
+                        <span className="text-2xl leading-snug tracking-tight md:text-3xl">{head.replace(/\.$/, "")}</span>
+                        <span className="text-lg leading-relaxed text-canvas-foreground/75">{inline(rest)}</span>
+                      </span>
+                    </li>
+                  );
+                })}
+              </ol>
+            );
+          return (
+            <ul key={i} className="flex max-w-3xl list-disc flex-col gap-2 pl-5 text-lg leading-relaxed">
+              {items.map((l) => (
+                <li key={l}>{inline(l)}</li>
+              ))}
+            </ul>
+          );
+        }
+        return (
+          <p key={i} className="max-w-3xl text-lg leading-relaxed text-canvas-foreground/80">
+            {inline(b)}
+          </p>
+        );
+      })}
+    </div>
+  );
+}
+
+function inline(text: string) {
+  return text.split(/(\*\*[^*]+\*\*|`[^`]+`|\[[^\]]+\]\([^)\s]+\))/).map((part, i) =>
+    part.startsWith("[") ? (
+      <a key={i} href={/\(([^)]+)\)$/.exec(part)?.[1]} className="underline decoration-from-font underline-offset-4 hover:decoration-2">
+        {/^\[([^\]]+)\]/.exec(part)?.[1]}
+      </a>
+    ) : part.startsWith("**") ? (
+      <strong key={i} className="font-semibold">
+        {part.slice(2, -2)}
+      </strong>
+    ) : part.startsWith("`") ? (
+      <code key={i} className="font-mono text-[0.9em]">
+        {part.slice(1, -1)}
+      </code>
+    ) : (
+      part
+    ),
+  );
+}

package/src/next/proxy.ts

@@ -0,0 +1,55 @@
+import { type NextRequest, NextResponse } from "next/server";
+
+/**
+ * One URL, two formats, and never public. 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 responses say
+ * `Vary: Accept` and the HTML links to its markdown. On a production deployment
+ * (`VERCEL_ENV`, or `production` you pass) every docs URL, in every format, is a
+ * 404, the route handlers included, which no layout wraps.
+ *
+ * In `proxy.ts`: `export const proxy = docsProxy(); export const config = { matcher: docsMatcher() };`
+ */
+export function docsProxy({ basePath = "/design/system", production }: { basePath?: string; production?: () => boolean } = {}) {
+  const base = basePath.replace(/\/$/, "");
+  const isProduction = production ?? (() => process.env.VERCEL_ENV === "production");
+  return function proxy(request: NextRequest) {
+    const { pathname } = request.nextUrl;
+    if (isProduction()) 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 page = pathname.replace(/\.md$/, "").replace(/\/$/, "");
+    if (pathname.endsWith(".md") || prefersMarkdown(request.headers.get("accept"))) {
+      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.
+    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;
+  };
+}
+
+/** The proxy's matcher for a base path. Next reads `config.matcher` statically, so write the result out where it must be a literal. */
+export function docsMatcher(basePath = "/design/system"): string[] {
+  const base = basePath.replace(/\/$/, "");
+  return [base, `${base}.md`, `${base}/:path*`];
+}
+
+/** text/markdown ranked above text/html in the Accept header. */
+export 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");
+}