@designtools/docs 0.0.0-stage → 0.1.0

package/dist/next/index.js

@@ -0,0 +1,63 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import "../styles.css";
+import { notFound } from "next/navigation";
+import { findBySlug, slugOf } from "../lib/manifest.js";
+import { PreviewExample, PreviewSurface } from "../preview-frame.js";
+import { DocsShell } from "../shell.js";
+import { manifestFiles, manifestRoute, markdownRoute } from "./markdown.js";
+import { DocsPageView } from "./pages.js";
+import { allSlugs, metaOf, navOf, resolve, siteOf } from "./site.js";
+export { markdownFor } from "./markdown.js";
+export { docsMatcher, docsProxy, prefersMarkdown } from "./proxy.js";
+/**
+ * A whole docs site from one config, for the Next App Router. Each export is
+ * what one route file re-exports, so a project's docs are a handful of
+ * one-line files:
+ *
+ * - `(docs)/layout.tsx`: `export default docs.Layout`
+ * - `(docs)/[[...slug]]/page.tsx`: `export default docs.Page`, with `generateStaticParams` and `generateMetadata`
+ * - `md/[[...path]]/route.ts`: `export const GET = docs.markdown`
+ * - `manifest/[file]/route.ts`: `export const GET = docs.manifest`, with `generateStaticParams = docs.manifestParams`
+ * - `preview/[slug]/[example]/page.tsx`: `export default docs.Preview`
+ *
+ * The same files serve the docs inside a product's app or as a standalone app.
+ */
+export function createDocs(config) {
+    const site = siteOf(config);
+    const nav = navOf(site);
+    const Registry = config.registry;
+    function Layout({ children }) {
+        return (_jsx(Registry, { children: _jsx(DocsShell, { manifest: site.components, rules: site.rules, patterns: site.patterns, terms: site.taxonomy, title: site.title, logo: config.logo, basePath: site.base, brand: nav.brand, foundations: nav.foundations, standards: nav.standards, hero: config.hero, children: children }) }));
+    }
+    async function Page({ params }) {
+        const page = resolve(site, (await params).slug);
+        if (!page)
+            notFound();
+        return _jsx(DocsPageView, { site: site, page: page });
+    }
+    async function generateMetadata({ params }) {
+        const page = resolve(site, (await params).slug);
+        return page ? metaOf(site, page) : {};
+    }
+    /** One example on its own, outside the shell: what the preview frame shows, and the target for visual regression. */
+    async function Preview({ params, searchParams }) {
+        const { slug, example } = await params;
+        const { theme } = await searchParams;
+        const entry = findBySlug(site.components, slug);
+        if (!entry?.examples)
+            notFound();
+        return (_jsx(Registry, { children: _jsx(PreviewSurface, { theme: theme, children: _jsx(PreviewExample, { entry: entry, example: decodeURIComponent(example) }) }) }));
+    }
+    return {
+        site,
+        Layout,
+        Page,
+        generateMetadata,
+        generateStaticParams: () => allSlugs(site).map((slug) => ({ slug })),
+        Preview,
+        previewParams: () => site.components.components.flatMap((c) => c.examples ? [c.examples.canonical, ...c.examples.do, ...c.examples.dont, ...c.examples.other].filter(Boolean).map((e) => ({ slug: slugOf(c), example: e.name })) : []),
+        markdown: markdownRoute(site),
+        manifest: manifestRoute(site),
+        manifestParams: () => Object.keys(manifestFiles(site)).map((name) => ({ file: `${name}.json` })),
+    };
+}

package/dist/next/markdown.d.ts

@@ -0,0 +1,20 @@
+import { type Site } from "./site.js";
+/**
+ * The markdown form of a docs page, generated from the manifest rather than
+ * converted from HTML, or nothing when there is no such page. `context` is the
+ * whole system in one file.
+ */
+export declare function markdownFor(site: Site, path: string): string | undefined;
+/** The route handler for `md/[[...path]]`: the page's markdown with `Vary: Accept` and its canonical link, or a markdown 404. */
+export declare function markdownRoute(site: Site): (_: Request, { params }: {
+    params: Promise<{
+        path?: string[];
+    }>;
+}) => Promise<Response>;
+/** The route handler for `manifest/[file]`: each manifest file as JSON, so an agent outside the repo gets the exact data. */
+export declare function manifestRoute(site: Site): (_: Request, { params }: {
+    params: Promise<{
+        file: string;
+    }>;
+}) => Promise<Response>;
+export declare function manifestFiles(site: Site): Record<string, unknown>;

package/dist/next/markdown.js

@@ -0,0 +1,95 @@
+import { groupByCategory, slugOf } from "../lib/manifest.js";
+import { adherenceMarkdown, assetsMarkdown, coloursMarkdown, componentMarkdown, editorialHeader, generatedHeader, glossaryMarkdown, manifestLinks, patternMarkdown, ruleMarkdown, scaleMarkdown, standardsMarkdown, systemMarkdown, typeMarkdown, } from "../lib/markdown.js";
+import { navOf, resolve } from "./site.js";
+/**
+ * The markdown form of a docs page, generated from the manifest rather than
+ * converted from HTML, or nothing when there is no such page. `context` is the
+ * whole system in one file.
+ */
+export function markdownFor(site, path) {
+    const { base, title, components, tokens, rules, patterns, taxonomy, assets, config } = site;
+    const generated = (md) => generatedHeader(config.provenance ?? "") + md;
+    if (path === "context")
+        return systemMarkdown({ components, tokens, rules: rules.rules, patterns: patterns.patterns, terms: taxonomy.terms }, title, config.provenance ?? "");
+    const page = resolve(site, path ? path.split("/") : []);
+    if (!page)
+        return undefined;
+    switch (page.kind) {
+        case "overview": {
+            const nav = navOf(site);
+            const links = (list) => list.map((l) => `[${l.label}](${l.href}.md)`).join(", ");
+            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",
+                "",
+                ...(nav.brand.length ? [`- Brand: ${links(nav.brand)}`] : []),
+                `- Foundations: ${links(nav.foundations)}`,
+                ...(rules.rules.length ? [`- [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"}`)),
+                ...(nav.standards.length ? [`- Standards: ${links(nav.standards)}`] : []),
+                `- Everything in [one file](${base}/context.md)`,
+                "",
+                manifestLinks(`${base}/manifest`),
+            ].join("\n"));
+        }
+        case "editorial":
+            return `${editorialHeader(page.page.by)}# ${page.page.title}\n\n${page.page.lead ? `${page.page.lead}\n\n` : ""}${page.page.body}\n`;
+        case "logo":
+            return generated(assetsMarkdown(assets.assets.filter((a) => a.kind === "logo")) +
+                "\n" +
+                rules.rules
+                    .filter((r) => r.kind === "brand")
+                    .map(ruleMarkdown)
+                    .join("\n"));
+        case "imagery":
+            return generated(assetsMarkdown(assets.assets.filter((a) => a.kind !== "logo")));
+        case "voice":
+            return generated(glossaryMarkdown(taxonomy.terms.filter((t) => t.kind === "product" || t.wrong?.length)));
+        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 "pattern":
+            return generated(patternMarkdown(page.pattern, 1));
+        case "component":
+            return generated(componentMarkdown(page.entry, 1));
+        case "standards":
+            return generated(`${config.baselines ? standardsMarkdown(config.baselines) : ""}\n${config.adherence ? adherenceMarkdown(config.adherence) : ""}`);
+        case "vocabulary":
+            return generated(glossaryMarkdown(taxonomy.terms));
+    }
+}
+/** The route handler for `md/[[...path]]`: the page's markdown with `Vary: Accept` and its canonical link, or a markdown 404. */
+export function markdownRoute(site) {
+    return async function GET(_, { params }) {
+        const path = ((await params).path ?? []).join("/").replace(/\.md$/, "");
+        const page = markdownFor(site, path);
+        const canonical = `${site.base}${path ? `/${path}` : ""}`;
+        return new Response(page ?? `# Not found\n\nThere is no page at \`${canonical}\`. The index is at [${site.base}.md](${site.base}.md).\n`, {
+            status: page ? 200 : 404,
+            headers: { "content-type": "text/markdown; charset=utf-8", vary: "Accept", link: `<${canonical}>; rel="canonical"` },
+        });
+    };
+}
+/** The route handler for `manifest/[file]`: each manifest file as JSON, so an agent outside the repo gets the exact data. */
+export function manifestRoute(site) {
+    const files = manifestFiles(site);
+    return async function GET(_, { params }) {
+        const { file } = await params;
+        const data = files[file.replace(/\.json$/, "")];
+        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);
+    };
+}
+export function manifestFiles(site) {
+    return Object.fromEntries(Object.entries(site.config.manifest).filter(([, v]) => v !== undefined));
+}

package/dist/next/pages.d.ts

@@ -0,0 +1,6 @@
+import { type PageRef, type Site } from "./site.js";
+/** The page for a reference, composed of blocks. */
+export declare function DocsPageView({ site, page }: {
+    site: Site;
+    page: PageRef;
+}): import("react").JSX.Element;

package/dist/next/pages.js

@@ -0,0 +1,122 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { ArrowRight, ArrowUpRight } from "lucide-react";
+import Link from "next/link";
+import { AdherenceSummary } from "../adherence-summary.js";
+import { Anatomy } from "../anatomy.js";
+import { Examples } from "../examples.js";
+import { Glossary } from "../glossary.js";
+import { Imagery } from "../imagery.js";
+import { groupFamilies, slugOf } from "../lib/manifest.js";
+import { StatusBadge } from "../lib/status.js";
+import { LogoUsage } from "../logo-usage.js";
+import { PageActions } from "../page-actions.js";
+import { Pattern } from "../pattern.js";
+import { PreviewFrame } from "../preview-frame.js";
+import { PropsTable } from "../props-table.js";
+import { Rule } from "../rule.js";
+import { Scale } from "../scale.js";
+import { DocsFooter, DocsHeader, DocsSection } from "../shell.js";
+import { Standards } from "../standards.js";
+import { PageContrast, RampSwatches, SemanticSwatches } from "../swatches.js";
+import { TypeRamp } from "../type-ramp.js";
+import { Usage } from "../usage.js";
+import { VariantMatrix } from "../variant-matrix.js";
+import { VoiceTerms } from "../voice-terms.js";
+import { Workbench } from "../workbench.js";
+import { Markdown } from "./prose.js";
+import { COPY } from "./site.js";
+/** 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,
+    Scale,
+    SemanticSwatches,
+    Standards,
+    TypeRamp,
+    Usage,
+    VariantMatrix,
+    VoiceTerms,
+    Workbench,
+};
+function blocksOf(site) {
+    return { ...DEFAULT_BLOCKS, ...site.config.blocks };
+}
+/** The page for a reference, composed of blocks. */
+export function DocsPageView({ site, page }) {
+    const B = blocksOf(site);
+    const { base, config } = site;
+    const footer = _jsx(DocsFooter, { provenance: config.provenance });
+    const header = (title, lead) => (_jsx(DocsHeader, { title: title, lead: lead, children: _jsx(PageActions, { basePath: base }) }));
+    switch (page.kind) {
+        case "overview":
+            return _jsx(Overview, { site: site });
+        case "editorial":
+            return (_jsxs(_Fragment, { children: [header(page.page.title, page.page.lead), _jsx(Markdown, { text: page.page.body }), _jsx(DocsFooter, { editorial: page.page.by })] }));
+        case "logo":
+            return (_jsxs(_Fragment, { children: [header(COPY.logo.title, COPY.logo.lead), _jsx(B.LogoUsage, { assets: site.assets.assets, rules: site.rules.rules, rulesHref: `${base}/rules` }), footer] }));
+        case "imagery":
+            return (_jsxs(_Fragment, { children: [header(COPY.imagery.title, COPY.imagery.lead), _jsx(B.Imagery, { assets: site.assets.assets }), footer] }));
+        case "voice":
+            return (_jsxs(_Fragment, { children: [header(COPY.voice.title, COPY.voice.lead), _jsx(B.VoiceTerms, { terms: site.taxonomy.terms }), footer] }));
+        case "colour":
+            return (_jsxs(_Fragment, { children: [header(COPY.colour.title, COPY.colour.lead), _jsx(DocsSection, { title: "Semantic colours", lead: "Each pair is measured on the colours the browser paints, in each mode.", children: _jsx(B.SemanticSwatches, { tokens: site.tokens }) }), _jsx(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.", children: _jsx(B.PageContrast, { tokens: site.tokens }) }), _jsx(DocsSection, { title: "Ramps", children: _jsx(B.RampSwatches, { tokens: site.tokens }) }), footer] }));
+        case "type":
+            return (_jsxs(_Fragment, { children: [header(COPY.type.title, COPY.type.lead), _jsx(B.TypeRamp, { tokens: site.tokens }), footer] }));
+        case "scale":
+            return (_jsxs(_Fragment, { children: [header(COPY.scale.title, COPY.scale.lead), _jsx(B.Scale, { tokens: site.tokens }), footer] }));
+        case "rules":
+            return (_jsxs(_Fragment, { children: [header(COPY.rules.title, COPY.rules.lead), ["brand", "interface"].map((kind) => {
+                        const rules = site.rules.rules.filter((r) => r.kind === kind);
+                        return rules.length ? (_jsx(DocsSection, { title: kind === "brand" ? "Brand" : "Interface", children: rules.map((r) => (_jsx(B.Rule, { rule: r, children: config.demonstrations?.[r.id] }, r.id))) }, kind)) : null;
+                    }), footer] }));
+        case "standards":
+            return (_jsxs(_Fragment, { children: [header(COPY.standards.title, COPY.standards.lead), config.baselines && (_jsx(DocsSection, { title: "Targets", children: _jsx(B.Standards, { baselines: config.baselines }) })), config.adherence && (_jsx(DocsSection, { title: "Adherence", lead: "How closely the product follows the system, from @designtools/adherence. It informs; it never blocks.", children: _jsx(B.AdherenceSummary, { report: config.adherence }) })), footer] }));
+        case "vocabulary":
+            return (_jsxs(_Fragment, { children: [header(COPY.vocabulary.title, COPY.vocabulary.lead), _jsx(B.Glossary, { terms: site.taxonomy.terms }), footer] }));
+        case "pattern":
+            return (_jsxs(_Fragment, { children: [header(page.pattern.name, page.pattern.description), _jsx(B.Pattern, { pattern: page.pattern, manifest: site.components, basePath: base }), _jsx(DocsFooter, { source: page.pattern.source, provenance: config.provenance })] }));
+        case "component":
+            return _jsx(ComponentPage, { site: site, blocks: B, entry: page.entry });
+    }
+}
+function ComponentPage({ site, blocks: B, 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 (_jsxs(_Fragment, { children: [_jsx(DocsHeader, { title: entry.name, lead: entry.description ?? `A part of ${head.name}, used inside it.`, children: _jsx(PageActions, { basePath: base }) }), _jsx(DocsSection, { title: "Part of", lead: `Its examples, variants and anatomy are on ${head.name}'s page, where it renders inside the whole.`, children: _jsxs(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", children: [_jsxs("span", { className: "flex flex-col gap-1", children: [_jsx("span", { className: "text-xl tracking-tight underline-offset-4 group-hover:underline", children: head.name }), head.description && _jsx("span", { className: "line-clamp-2 text-sm text-muted-foreground", children: head.description })] }), _jsx(ArrowRight, { "aria-hidden": true, className: "size-5 shrink-0 text-muted-foreground" })] }) }), _jsx(DocsSection, { title: "Props", children: _jsx(B.PropsTable, { entry: entry }) }), _jsx(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 (_jsxs(_Fragment, { children: [_jsx(DocsHeader, { title: entry.name, lead: entry.description, children: _jsx(PageActions, { basePath: base }) }), _jsx(DocsSection, { title: "Usage", children: _jsx(B.Usage, { entry: entry, manifest: site.components, basePath: base }) }), _jsx(B.Workbench, { entry: entry, props: setup.props, content: setup.content, wrap: setup.wrap, backgrounds: backgrounds, previewHref: first && `${preview}/${first}`, children: setup.children }), _jsx(DocsSection, { title: "Anatomy", children: _jsx(B.Anatomy, { entry: entry }) }), _jsx(DocsSection, { title: "Examples", lead: "The usual use first, then each do beside its don't. Every one is the real component.", children: _jsx(B.Examples, { entry: entry, previewHref: preview }) }), !!entry.variants?.axes.length && (_jsx(DocsSection, { title: "Variants", lead: `Every combination, from the ${entry.variants.from === "props" ? "props' types" : `${entry.variants.from}() config`}, then each state.`, children: _jsx(B.VariantMatrix, { entry: entry, props: setup.props, children: setup.children === "" ? undefined : (setup.content ?? entry.name) }) })), first && (_jsx(DocsSection, { title: "At each width", children: _jsx(B.PreviewFrame, { src: `${preview}/${first}`, title: `${entry.name}: ${first}` }) })), _jsx(DocsFooter, { source: entry.source, provenance: config.provenance })] }));
+}
+const row = "group flex h-full flex-col gap-2 border-t border-border py-5 focus-visible:outline-2 focus-visible:outline-ring";
+/** The overview: where to start, then every component by category. Below the hero when there is one. */
+function Overview({ site }) {
+    const { base, config } = site;
+    const families = groupFamilies(site.components);
+    const count = families.reduce((n, g) => n + g.families.length, 0);
+    const brandFirst = site.editorial.find((p) => (p.section ?? "brand") === "brand");
+    const starts = [
+        brandFirst || site.shows("logo") ? { title: "Brand", href: `${base}/${brandFirst?.slug ?? "brand/logo"}`, line: "Principles, the logo, imagery and the words we use." } : null,
+        { title: "Foundations", href: `${base}/colour`, line: "Colour, type and the scale, rendered from the tokens." },
+        site.rules.rules.length ? { title: "Rules", href: `${base}/rules`, line: `${site.rules.rules.length} rules, brand and interface, each with its check.` } : null,
+        site.patterns.patterns.length
+            ? { title: "Patterns", href: `${base}/patterns/${site.patterns.patterns[0].id}`, line: `${site.patterns.patterns.length} recurring screens, made of the real components.` }
+            : null,
+    ].filter((s) => !!s);
+    return (_jsxs(_Fragment, { children: [!config.hero && (_jsx(DocsHeader, { title: site.title, lead: config.lead ?? "The brand and the design system in one place, for the people who make the product and the agents that build it with them.", children: _jsx(PageActions, { basePath: base }) })), _jsx("ol", { className: "flex max-w-3xl flex-col", children: starts.map(({ title, href, line }, n) => (_jsx("li", { className: "border-t border-border first:border-t-0", children: _jsxs(Link, { href: href, className: "group grid grid-cols-[3rem_minmax(0,1fr)_auto] items-baseline gap-x-4 py-6 focus-visible:outline-2 focus-visible:outline-ring sm:grid-cols-[4rem_minmax(0,1fr)_auto]", children: [_jsx("span", { className: "text-lg text-muted-foreground tabular-nums", children: String(n + 1).padStart(2, "0") }), _jsxs("span", { className: "flex flex-col gap-2", children: [_jsx("span", { className: "text-2xl leading-snug tracking-tight underline-offset-[6px] group-hover:underline md:text-3xl", children: title }), _jsx("span", { className: "text-lg leading-relaxed text-muted-foreground", children: line })] }), _jsx(ArrowUpRight, { "aria-hidden": true, className: "size-5 self-center text-muted-foreground transition-transform duration-(--dt-duration-fast) group-hover:translate-x-0.5 group-hover:-translate-y-0.5" })] }) }, title))) }), site.shows("components") && (_jsx(DocsSection, { title: "Components", lead: `${count} components, grouped as the navigation groups them. Each page has its usage, a workbench, anatomy, examples and variants.`, children: _jsx("div", { className: "flex flex-col gap-12", children: families.map((group) => (_jsxs("div", { className: "flex flex-col gap-1", children: [_jsx("h3", { className: "text-xs font-medium tracking-wide text-muted-foreground uppercase", children: group.category }), _jsx("ul", { className: "grid gap-x-10 sm:grid-cols-2 xl:grid-cols-3", children: group.families.map(({ head: c, parts }) => (_jsx("li", { children: _jsxs(Link, { href: `${base}/components/${slugOf(c)}`, className: row, children: [_jsxs("span", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: "text-xl tracking-tight underline-offset-4 group-hover:underline", children: c.name }), _jsx(StatusBadge, { status: c.status })] }), c.description && _jsx("span", { className: "line-clamp-2 text-sm text-muted-foreground", children: c.description }), parts.length > 0 && _jsxs("span", { className: "mt-auto font-mono text-xs text-muted-foreground", children: ["with ", parts.map((p) => p.name).join(", ")] })] }) }, c.source + c.export))) })] }, group.category))) }) })), _jsx(DocsFooter, { provenance: config.provenance })] }));
+}

package/dist/next/prose.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The few markdown shapes editorial pages use: `##` sections, paragraphs and bullet lists, with bold
+ * and code. Each `##` is a docs section, so it reads at the same size as a generated page and is
+ * 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 declare function Markdown({ text }: {
+    text: string;
+}): import("react").JSX.Element;

package/dist/next/prose.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { DocsSection } from "../shell.js";
+/**
+ * The few markdown shapes editorial pages use: `##` sections, paragraphs and bullet lists, with bold
+ * and code. Each `##` is a docs section, so it reads at the same size as a generated page and is
+ * 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 }) {
+    const sections = [{ 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 (_jsx(_Fragment, { children: sections.map((s, i) => s.title ? (_jsx(DocsSection, { title: s.title, children: _jsx(Blocks, { blocks: s.blocks }) }, s.title)) : (s.blocks.length > 0 && _jsx(Blocks, { blocks: s.blocks }, i))) }));
+}
+function Blocks({ blocks }) {
+    return (_jsx("div", { className: "flex flex-col gap-5", children: blocks.map((b, i) => {
+            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 (_jsx("ol", { className: "flex max-w-3xl flex-col gap-12", children: items.map((l, n) => {
+                            const [, head, rest] = /^\*\*([^*]+)\*\*\s*(.*)$/.exec(l) ?? [];
+                            return (_jsxs("li", { className: "grid grid-cols-[3rem_minmax(0,1fr)] gap-x-4 gap-y-3 sm:grid-cols-[4rem_minmax(0,1fr)]", children: [_jsx("span", { className: "pt-1 text-lg text-muted-foreground tabular-nums", children: String(n + 1).padStart(2, "0") }), _jsxs("span", { className: "flex flex-col gap-3", children: [_jsx("span", { className: "text-2xl leading-snug tracking-tight md:text-3xl", children: head.replace(/\.$/, "") }), _jsx("span", { className: "text-lg leading-relaxed text-canvas-foreground/75", children: inline(rest) })] })] }, l));
+                        }) }, i));
+                return (_jsx("ul", { className: "flex max-w-3xl list-disc flex-col gap-2 pl-5 text-lg leading-relaxed", children: items.map((l) => (_jsx("li", { children: inline(l) }, l))) }, i));
+            }
+            return (_jsx("p", { className: "max-w-3xl text-lg leading-relaxed text-canvas-foreground/80", children: inline(b) }, i));
+        }) }));
+}
+function inline(text) {
+    return text.split(/(\*\*[^*]+\*\*|`[^`]+`)/).map((part, i) => part.startsWith("**") ? (_jsx("strong", { className: "font-semibold", children: part.slice(2, -2) }, i)) : part.startsWith("`") ? (_jsx("code", { className: "font-mono text-[0.9em]", children: part.slice(1, -1) }, i)) : (part));
+}

package/dist/next/proxy.d.ts

@@ -0,0 +1,19 @@
+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 declare function docsProxy({ basePath, production }?: {
+    basePath?: string;
+    production?: () => boolean;
+}): (request: NextRequest) => NextResponse<unknown>;
+/** 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 declare function docsMatcher(basePath?: string): string[];
+/** text/markdown ranked above text/html in the Accept header. */
+export declare function prefersMarkdown(accept: string | null): boolean;

package/dist/next/proxy.js

@@ -0,0 +1,56 @@
+import { 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 } = {}) {
+    const base = basePath.replace(/\/$/, "");
+    const isProduction = production ?? (() => process.env.VERCEL_ENV === "production");
+    return function proxy(request) {
+        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") {
+    const base = basePath.replace(/\/$/, "");
+    return [base, `${base}.md`, `${base}/:path*`];
+}
+/** text/markdown ranked above text/html in the Accept header. */
+export function prefersMarkdown(accept) {
+    if (!accept)
+        return false;
+    const q = (type) => {
+        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");
+}

package/dist/next/site.d.ts

@@ -0,0 +1,53 @@
+import type { DocsLink } from "../shell.js";
+import type { AssetsManifest, ComponentEntry, ComponentsManifest, PatternEntry, PatternsManifest, RulesManifest, TaxonomyManifest, TokensManifest } from "../lib/manifest-types.js";
+import type { BuiltInPage, DocsConfig, EditorialPage } from "./config.js";
+/** The config, read once: the manifest typed and checked, and what is shown. */
+export interface Site {
+    config: DocsConfig;
+    base: string;
+    title: string;
+    components: ComponentsManifest;
+    tokens: TokensManifest;
+    rules: RulesManifest;
+    patterns: PatternsManifest;
+    taxonomy: TaxonomyManifest;
+    assets: AssetsManifest;
+    editorial: EditorialPage[];
+    shows: (page: BuiltInPage) => boolean;
+}
+export declare function siteOf(config: DocsConfig): Site;
+/** One page of the docs, by what it shows. */
+export type PageRef = {
+    kind: "overview";
+} | {
+    kind: "editorial";
+    page: EditorialPage;
+} | {
+    kind: "logo" | "imagery" | "voice" | "colour" | "type" | "scale" | "rules" | "standards" | "vocabulary";
+} | {
+    kind: "component";
+    entry: ComponentEntry;
+} | {
+    kind: "pattern";
+    pattern: PatternEntry;
+};
+/** The page at a path under the docs, or nothing. */
+export declare function resolve(site: Site, slug?: string[]): PageRef | undefined;
+/** Every page's path, for static generation. */
+export declare function allSlugs(site: Site): string[][];
+/** The navigation's editorial and generated groups: brand, foundations, standards. Rules, patterns and components the shell adds from the manifest. */
+export declare function navOf(site: Site): {
+    brand: DocsLink[];
+    foundations: DocsLink[];
+    standards: DocsLink[];
+};
+/** Each built-in page's title and lead: what the page says it is, which is also its description. */
+export declare const COPY: Record<Exclude<PageRef["kind"], "overview" | "editorial" | "component" | "pattern">, {
+    title: string;
+    lead: string;
+}>;
+/** A page's title and description, for its metadata. */
+export declare function metaOf(site: Site, ref: PageRef): {
+    title: string;
+    description?: string;
+};

package/dist/next/site.js

@@ -0,0 +1,136 @@
+import { findBySlug, readComponents, readTokens, slugOf } from "../lib/manifest.js";
+export function siteOf(config) {
+    const hidden = new Set(config.hide ?? []);
+    return {
+        config,
+        base: (config.basePath ?? "/design/system").replace(/\/$/, ""),
+        title: config.title,
+        components: readComponents(config.manifest.components),
+        tokens: readTokens(config.manifest.tokens),
+        rules: config.manifest.rules ?? { rules: [] },
+        patterns: config.manifest.patterns ?? { patterns: [] },
+        taxonomy: config.manifest.taxonomy ?? { terms: [] },
+        assets: config.manifest.assets ?? { assets: [] },
+        editorial: config.editorial ?? [],
+        shows: (page) => !hidden.has(page),
+    };
+}
+const BUILT_IN = {
+    "brand/logo": "logo",
+    "brand/imagery": "imagery",
+    "brand/voice": "voice",
+    colour: "colour",
+    type: "type",
+    scale: "scale",
+    rules: "rules",
+    standards: "standards",
+    vocabulary: "vocabulary",
+};
+/** Whether a built-in page has anything to show, as well as not being hidden. */
+function has(site, kind) {
+    return site.shows(kind) && KIND_NEEDS[kind](site);
+}
+const KIND_NEEDS = {
+    logo: (s) => s.assets.assets.some((a) => a.kind === "logo"),
+    imagery: (s) => s.assets.assets.some((a) => a.kind !== "logo"),
+    voice: (s) => s.taxonomy.terms.some((t) => t.kind === "product" || t.wrong?.length),
+    colour: () => true,
+    type: () => true,
+    scale: () => true,
+    rules: (s) => s.rules.rules.length > 0,
+    standards: (s) => !!s.config.baselines || !!s.config.adherence,
+    vocabulary: (s) => s.taxonomy.terms.length > 0,
+};
+/** The page at a path under the docs, or nothing. */
+export function resolve(site, slug = []) {
+    const path = slug.join("/");
+    if (!path)
+        return { kind: "overview" };
+    const editorial = site.editorial.find((p) => p.slug === path);
+    if (editorial)
+        return { kind: "editorial", page: editorial };
+    const builtIn = BUILT_IN[path];
+    if (builtIn)
+        return has(site, builtIn) ? { kind: builtIn } : undefined;
+    const [section, id] = slug;
+    if (section === "components" && id && site.shows("components")) {
+        const entry = findBySlug(site.components, id);
+        return entry ? { kind: "component", entry } : undefined;
+    }
+    if (section === "patterns" && id && site.shows("patterns")) {
+        const pattern = site.patterns.patterns.find((p) => p.id === id);
+        return pattern ? { kind: "pattern", pattern } : undefined;
+    }
+    return undefined;
+}
+/** Every page's path, for static generation. */
+export function allSlugs(site) {
+    const out = [[]];
+    for (const p of site.editorial)
+        out.push(p.slug.split("/"));
+    for (const [path, kind] of Object.entries(BUILT_IN))
+        if (has(site, kind))
+            out.push(path.split("/"));
+    if (site.shows("components"))
+        for (const c of site.components.components)
+            out.push(["components", slugOf(c)]);
+    if (site.shows("patterns"))
+        for (const p of site.patterns.patterns)
+            out.push(["patterns", p.id]);
+    return out;
+}
+/** The navigation's editorial and generated groups: brand, foundations, standards. Rules, patterns and components the shell adds from the manifest. */
+export function navOf(site) {
+    const link = (label, path) => ({ label, href: `${site.base}/${path}` });
+    const written = (section) => site.editorial.filter((p) => (p.section ?? "brand") === section).map((p) => link(p.nav ?? p.title, p.slug));
+    return {
+        brand: [
+            ...written("brand"),
+            ...(has(site, "logo") ? [link("Logo", "brand/logo")] : []),
+            ...(has(site, "imagery") ? [link("Imagery and icons", "brand/imagery")] : []),
+            ...(has(site, "voice") ? [link("Voice and terms", "brand/voice")] : []),
+        ],
+        foundations: [...written("foundations"), link("Colour", "colour"), link("Type", "type"), link("Scale", "scale")].filter((l) => !["colour", "type", "scale"].some((k) => l.href.endsWith(`/${k}`) && !site.shows(k))),
+        standards: [
+            ...written("standards"),
+            ...(has(site, "standards") ? [link("Standards", "standards")] : []),
+            ...(has(site, "vocabulary") ? [link("Vocabulary", "vocabulary")] : []),
+        ],
+    };
+}
+/** Each built-in page's title and lead: what the page says it is, which is also its description. */
+export const COPY = {
+    logo: { title: "Logo", lead: "Each logo on the surfaces it may sit on, at its smallest, with its clear space." },
+    imagery: { title: "Imagery and icons", lead: "The approved icons and imagery, and how to use each." },
+    voice: { title: "Voice and terms", lead: "The words we use, beside the ones we do not." },
+    colour: {
+        title: "Colour",
+        lead: "Generated from the brand colour by @designtools/tokens. Write the semantic names in components; the ramps are what they point at.",
+    },
+    type: { title: "Type", lead: "Each family, then the scale: a size is never set without its leading." },
+    scale: { title: "Scale", lead: "Space, size, radius, elevation and motion, each drawn the way it is used." },
+    rules: {
+        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.",
+    },
+    standards: {
+        title: "Standards",
+        lead: "The budgets and targets the project holds itself to, read from .mxa/stack.json, where the checks read them too.",
+    },
+    vocabulary: { title: "Vocabulary", lead: "Every name in the system. Search by a wrong name and it finds the right one." },
+};
+/** A page's title and description, for its metadata. */
+export function metaOf(site, ref) {
+    switch (ref.kind) {
+        case "overview":
+            return { title: site.title, description: site.config.lead ?? `${site.title}: the brand and the design system in one place.` };
+        case "editorial":
+            return { title: ref.page.title, description: ref.page.lead };
+        case "component":
+            return { title: `${ref.entry.name} · Components`, description: ref.entry.description };
+        case "pattern":
+            return { title: `${ref.pattern.name} · Patterns`, description: ref.pattern.description };
+        default:
+            return { title: COPY[ref.kind].title, description: COPY[ref.kind].lead };
+    }
+}

package/dist/page-actions.d.ts

@@ -0,0 +1,9 @@
+/**
+ * What a reader can take from a page, as one split button: copy the page as
+ * markdown, the same markdown any agent gets at `.md`, with a menu beside it to
+ * view that markdown, copy the whole system as one file, or open the manifest.
+ * Put it in a `DocsHeader`.
+ */
+export declare function PageActions({ basePath }: {
+    basePath?: string;
+}): import("react").JSX.Element;