@designtools/docs 0.0.0-stage → 0.2.0

package/dist/next/index.d.ts

@@ -0,0 +1,65 @@
+import "../styles.css";
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+import type { DocsConfig } from "./config.js";
+export { Live } from "../lib/live.js";
+export { DocsSection } from "../shell.js";
+export type { BuiltInPage, DocsConfig, EditorialPage, WorkbenchSetup } from "./config.js";
+export { Markdown as Prose } from "./prose.js";
+export { markdownFor } from "./markdown.js";
+export { docsMatcher, docsProxy, prefersMarkdown } from "./proxy.js";
+type SlugParams = {
+    params: Promise<{
+        slug?: string[];
+    }>;
+};
+/**
+ * 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 declare function createDocs(config: DocsConfig): {
+    site: import("./site.js").Site;
+    Layout: ({ children }: {
+        children: ReactNode;
+    }) => import("react").JSX.Element;
+    Page: ({ params }: SlugParams) => Promise<import("react").JSX.Element>;
+    generateMetadata: ({ params }: SlugParams) => Promise<Metadata>;
+    generateStaticParams: () => {
+        slug: string[];
+    }[];
+    Preview: ({ params, searchParams }: {
+        params: Promise<{
+            slug: string;
+            example: string;
+        }>;
+        searchParams: Promise<{
+            theme?: string;
+        }>;
+    }) => Promise<import("react").JSX.Element>;
+    previewParams: () => {
+        slug: string;
+        example: string;
+    }[];
+    markdown: (_: Request, { params }: {
+        params: Promise<{
+            path?: string[];
+        }>;
+    }) => Promise<Response>;
+    manifest: (_: Request, { params }: {
+        params: Promise<{
+            file: string;
+        }>;
+    }) => Promise<Response>;
+    manifestParams: () => {
+        file: string;
+    }[];
+};

package/dist/next/index.js

@@ -0,0 +1,66 @@
+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 { Live } from "../lib/live.js";
+export { DocsSection } from "../shell.js";
+export { Markdown as Prose } from "./prose.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` : ""}${typeof page.page.body === "string" ? page.page.body : page.page.markdown}\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,188 @@
+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 { cx, display } from "../lib/cx.js";
+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, RuleIndex } 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,
+    RuleIndex,
+    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), typeof page.page.body === "string" ? _jsx(Markdown, { text: page.page.body }) : 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), _jsx(DocsSection, { title: "Every rule", lead: "A line each: what it covers, how settled it is, and how it is checked.", children: _jsx(B.RuleIndex, { rules: [...site.rules.rules].sort((a, b) => a.kind.localeCompare(b.kind)) }) }), ["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: [_jsx(DocsHeader, { title: page.pattern.name, lead: page.pattern.description, status: page.pattern.status, children: _jsx(PageActions, { basePath: base }) }), _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 })] }));
+}
+/** 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 }) {
+    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 = [];
+    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 ? _jsx("span", { className: "flex h-10 items-center [&_img]:h-8 [&_svg]:h-8", children: config.logo }) : 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: (_jsxs("span", { className: "flex items-center gap-4", children: [_jsx("span", { className: "flex -space-x-1.5", children: fills.map((n) => (_jsx("span", { "aria-hidden": true, className: "size-8 rounded-full ring-2 ring-canvas", style: { background: `var(${n})` } }, n))) }), _jsx("span", { "aria-hidden": true, className: cx(display, "text-3xl leading-none tracking-tight"), children: "Aa" })] })),
+    });
+    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: (_jsx("span", { className: "flex flex-col gap-1.5 text-sm", children: site.rules.rules
+                    .filter((r) => r.kind === "brand")
+                    .slice(0, 2)
+                    .map((r) => (_jsxs("span", { className: "flex items-center gap-2", children: [_jsx(StatusBadge, { status: r.status }), _jsx("span", { className: "truncate", children: r.title })] }, r.id))) })),
+        });
+    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: (_jsx("span", { className: "flex flex-wrap gap-1.5", children: families.slice(0, 6).map((g) => (_jsxs("span", { className: "inline-flex min-h-7 items-center rounded-md bg-muted px-2 text-xs", children: [g.category, " ", _jsx("span", { className: "ml-1.5 text-muted-foreground tabular-nums", children: g.families.length })] }, g.category))) })),
+        });
+    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: _jsx("span", { className: "text-sm text-muted-foreground", children: site.patterns.patterns.slice(0, 3).map((p) => p.name).join(" · ") }),
+        });
+    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 : (_jsxs("span", { className: "flex w-full max-w-56 items-center gap-3", children: [_jsx("span", { className: "h-1.5 flex-1 overflow-hidden rounded-full bg-muted", children: _jsx("span", { className: "block h-full rounded-full bg-canvas-foreground", style: { width: `${Math.round(share * 100)}%` } }) }), _jsxs("span", { className: "text-sm tabular-nums", children: [Math.round(share * 100), "%"] })] })),
+        });
+    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 ? (_jsxs("span", { className: "text-sm", children: ["Say ", _jsx("strong", { className: "font-semibold", children: example.name }), ", ", _jsx("span", { className: "text-muted-foreground line-through decoration-current/40", children: example.wrong?.[0] })] })) : 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 (_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(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.", children: _jsx("ul", { "data-slot": "overview-sections", className: "grid gap-x-12 md:grid-cols-2", children: sections.map((sec) => (_jsx("li", { className: "border-t border-border", children: _jsxs(Link, { href: sec.href, className: "group flex h-full flex-col gap-4 py-7 focus-visible:outline-2 focus-visible:outline-ring", children: [_jsxs("span", { className: "flex items-baseline justify-between gap-4", children: [_jsx("span", { className: "text-2xl leading-tight tracking-tight underline-offset-[6px] group-hover:underline", children: sec.title }), _jsx("span", { className: "shrink-0 text-xs text-muted-foreground tabular-nums", children: sec.count })] }), _jsx("span", { className: "max-w-md text-base leading-relaxed text-muted-foreground", children: sec.why }), sec.preview && _jsx("span", { className: "mt-auto flex min-h-10 items-center pt-2", children: sec.preview })] }) }, sec.title))) }) }), config.overview?.agentic !== false && (_jsxs(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.", children: [_jsx("ol", { "data-slot": "overview-loop", className: "grid gap-x-6 gap-y-8 sm:grid-cols-2 xl:grid-cols-5", children: loop.map(([title, body], i) => (_jsxs("li", { className: "relative flex flex-col gap-3 xl:pr-2", children: [_jsxs("span", { className: "flex items-center gap-3", children: [_jsx("span", { className: "grid size-8 shrink-0 place-items-center rounded-full bg-canvas-foreground text-sm font-medium text-canvas tabular-nums", children: i + 1 }), i < loop.length - 1 && _jsx("span", { "aria-hidden": true, className: "hidden h-px flex-1 bg-border xl:block" })] }), _jsx("span", { className: "text-lg leading-snug tracking-tight", children: title }), _jsx("span", { className: "text-sm leading-relaxed text-muted-foreground", children: body })] }, title))) }), _jsxs("p", { className: "flex flex-wrap items-center gap-x-2 gap-y-1 text-sm text-muted-foreground", children: ["See it the way an agent does:", _jsxs("a", { href: `${base}.md`, className: "inline-flex items-center gap-1 font-medium text-canvas-foreground underline underline-offset-4 hover:decoration-2", children: ["this page as markdown ", _jsx(ArrowUpRight, { "aria-hidden": true, className: "size-3.5" })] })] })] })), _jsx(DocsFooter, { provenance: config.provenance })] }));
+}

package/dist/next/prose.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 declare function Markdown({ text }: {
+    text: string;
+}): import("react").JSX.Element;

package/dist/next/prose.js

@@ -0,0 +1,39 @@
+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, `###` 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 }) {
+    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) => {
+            if (b.startsWith("### "))
+                return (_jsx("h3", { className: "mt-4 max-w-3xl text-2xl leading-snug tracking-tight first:mt-0", children: inline(b.slice(4)) }, 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)] items-baseline gap-x-4 gap-y-3 sm:grid-cols-[4rem_minmax(0,1fr)]", 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-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(/(\*\*[^*]+\*\*|`[^`]+`|\[[^\]]+\]\([^)\s]+\))/).map((part, i) => part.startsWith("[") ? (_jsx("a", { href: /\(([^)]+)\)$/.exec(part)?.[1], className: "underline decoration-from-font underline-offset-4 hover:decoration-2", children: /^\[([^\]]+)\]/.exec(part)?.[1] }, 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;
+};