@designtools/docs 0.0.0-stage → 0.1.0

package/src/next/pages.tsx

@@ -0,0 +1,370 @@
+import { ArrowRight, ArrowUpRight } from "lucide-react";
+import Link from "next/link";
+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 } 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,
+  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)}
+          <Markdown text={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)}
+          {(["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 (
+        <>
+          {header(page.pattern.name, page.pattern.description)}
+          <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} />
+    </>
+  );
+}
+
+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 }: { site: 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 is { title: string; href: string; line: string } => !!s);
+
+  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>
+      )}
+      <ol className="flex max-w-3xl flex-col">
+        {starts.map(({ title, href, line }, n) => (
+          <li key={title} className="border-t border-border first:border-t-0">
+            <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]"
+            >
+              <span className="text-lg text-muted-foreground tabular-nums">{String(n + 1).padStart(2, "0")}</span>
+              <span className="flex flex-col gap-2">
+                <span className="text-2xl leading-snug tracking-tight underline-offset-[6px] group-hover:underline md:text-3xl">{title}</span>
+                <span className="text-lg leading-relaxed text-muted-foreground">{line}</span>
+              </span>
+              <ArrowUpRight
+                aria-hidden
+                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"
+              />
+            </Link>
+          </li>
+        ))}
+      </ol>
+
+      {site.shows("components") && (
+        <DocsSection title="Components" lead={`${count} components, grouped as the navigation groups them. Each page has its usage, a workbench, anatomy, examples and variants.`}>
+          <div className="flex flex-col gap-12">
+            {/* a component's parts (CardHeader, CardTitle) are named on its entry, not given entries of their own */}
+            {families.map((group) => (
+              <div key={group.category} className="flex flex-col gap-1">
+                <h3 className="text-xs font-medium tracking-wide text-muted-foreground uppercase">{group.category}</h3>
+                <ul className="grid gap-x-10 sm:grid-cols-2 xl:grid-cols-3">
+                  {group.families.map(({ head: c, parts }) => (
+                    <li key={c.source + c.export}>
+                      <Link href={`${base}/components/${slugOf(c)}`} className={row}>
+                        <span className="flex items-center justify-between gap-2">
+                          <span className="text-xl tracking-tight underline-offset-4 group-hover:underline">{c.name}</span>
+                          <StatusBadge status={c.status} />
+                        </span>
+                        {c.description && <span className="line-clamp-2 text-sm text-muted-foreground">{c.description}</span>}
+                        {parts.length > 0 && <span className="mt-auto font-mono text-xs text-muted-foreground">with {parts.map((p) => p.name).join(", ")}</span>}
+                      </Link>
+                    </li>
+                  ))}
+                </ul>
+              </div>
+            ))}
+          </div>
+        </DocsSection>
+      )}
+      <DocsFooter provenance={config.provenance} />
+    </>
+  );
+}
+

package/src/next/prose.tsx

@@ -0,0 +1,87 @@
+import { DocsSection } from "../shell";
+
+/**
+ * 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 }: { 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) => {
+        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)] gap-x-4 gap-y-3 sm:grid-cols-[4rem_minmax(0,1fr)]">
+                      <span className="pt-1 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(/(\*\*[^*]+\*\*|`[^`]+`)/).map((part, i) =>
+    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");
+}