@designtools/docs 0.0.0-stage → 0.1.0

package/src/lib/vision.tsx

@@ -0,0 +1,44 @@
+/**
+ * How the preview looks to people who see colour differently, or less sharply.
+ * SVG colour matrices for the three common colour-vision deficiencies and for no
+ * colour at all, from Machado, Oliveira and Fernandes (2009) at full severity, and
+ * a blur for low acuity. A simulation is a prompt to look again, not a test.
+ */
+
+export type Vision = "typical" | "protanopia" | "deuteranopia" | "tritanopia" | "achromatopsia" | "blurred";
+
+export const VISIONS: { value: Vision; label: string; note: string }[] = [
+  { value: "typical", label: "Typical", note: "No simulation" },
+  { value: "protanopia", label: "Protanopia", note: "No red cones, about 1% of men" },
+  { value: "deuteranopia", label: "Deuteranopia", note: "No green cones, about 1% of men" },
+  { value: "tritanopia", label: "Tritanopia", note: "No blue cones, rare" },
+  { value: "achromatopsia", label: "Achromatopsia", note: "No colour at all" },
+  { value: "blurred", label: "Blurred", note: "Low acuity, or a screen far away" },
+];
+
+const MATRICES: Record<Exclude<Vision, "typical" | "blurred">, string> = {
+  protanopia: "0.152 1.053 -0.205 0 0  0.115 0.786 0.099 0 0  -0.004 -0.048 1.052 0 0  0 0 0 1 0",
+  deuteranopia: "0.367 0.861 -0.228 0 0  0.280 0.673 0.047 0 0  -0.012 0.043 0.969 0 0  0 0 0 1 0",
+  tritanopia: "1.256 -0.077 -0.179 0 0  -0.078 0.931 0.148 0 0  0.005 0.691 0.304 0 0  0 0 0 1 0",
+  achromatopsia: "0.299 0.587 0.114 0 0  0.299 0.587 0.114 0 0  0.299 0.587 0.114 0 0  0 0 0 1 0",
+};
+
+/** The filters, once per page; `filterFor` points an element at one. */
+export function VisionFilters({ id }: { id: string }) {
+  return (
+    <svg aria-hidden width="0" height="0" className="absolute">
+      {Object.entries(MATRICES).map(([name, values]) => (
+        <filter key={name} id={`${id}-${name}`} colorInterpolationFilters="linearRGB">
+          <feColorMatrix type="matrix" values={values} />
+        </filter>
+      ))}
+    </svg>
+  );
+}
+
+/** The CSS `filter` for a vision, given the id the filters were rendered with. */
+export function filterFor(vision: Vision, id: string): string | undefined {
+  if (vision === "typical") return undefined;
+  if (vision === "blurred") return "blur(1.5px)";
+  return `url(#${id}-${vision})`;
+}

package/src/logo-usage.tsx

@@ -0,0 +1,140 @@
+"use client";
+
+import { Scale } from "lucide-react";
+import type { ReactNode } from "react";
+import { useLookup } from "./lib/lookup";
+import type { AssetEntry, RuleEntry } from "./lib/manifest-types";
+import { StatusBadge } from "./lib/status";
+import { inline } from "./lib/text";
+
+const LENGTH = /^\s*(\d+(?:\.\d+)?)(px|rem|em)\b/;
+
+/**
+ * Each logo on the surfaces it may sit on, at its minimum size, with its clear
+ * space drawn, and the brand rules that govern it: rules for every logo once,
+ * above them, and a rule naming one logo under that logo. Surfaces are semantic
+ * colour names painted from the light-mode tokens whatever the docs' mode, because a
+ * brand book's surfaces are fixed colours (white, the brand colour, an off-white),
+ * and dark mode would otherwise show the logo on a surface the brand forbids.
+ */
+export function LogoUsage({ assets, rules = [], rulesHref }: { assets: AssetEntry[]; rules?: RuleEntry[]; rulesHref?: string }) {
+  const lookup = useLookup();
+  const logos = assets.filter((a) => a.kind === "logo");
+  if (logos.length === 0) return <p className="text-sm text-muted-foreground">No logos in the brand folder yet.</p>;
+  const brand = rules.filter((r) => r.kind === "brand");
+  const general = brand.filter((r) => (r.appliesTo ?? []).some((x) => ["logo", "logos"].includes(x.toLowerCase())));
+  return (
+    <div data-slot="logo-usage" className="flex flex-col gap-16">
+      {general.length > 0 && <RuleList rules={general} rulesHref={rulesHref} />}
+      {logos.map((logo) => {
+        const src = lookup.assetUrl(logo);
+        const names = new Set([logo.name.toLowerCase(), logo.file.toLowerCase()]);
+        const own = brand.filter((r) => !general.includes(r) && (r.appliesTo ?? []).some((x) => names.has(x.toLowerCase())));
+        const clear = LENGTH.exec(logo.clearSpace ?? "");
+        const min = LENGTH.exec(logo.minSize ?? "");
+        const surfaces = logo.surfaces?.length ? logo.surfaces : ["canvas"];
+        const paint = (surface: string) => ({ background: `var(--${surface})`, color: `var(--${surface}-foreground, var(--canvas-foreground))` });
+        const facts: [string, ReactNode][] = [
+          [
+            "Minimum size",
+            <span key="m" className="flex flex-wrap items-center gap-3">
+              {logo.minSize ?? "not set"}
+              {src && min && (
+                // on the logo's own first surface, so a reversed (white) logo is visible at the size it is shown at
+                <span data-slot="logo-min-size" data-theme="light" className="inline-flex rounded-md border border-border p-2" style={paint(surfaces[0])}>
+                  <img src={src} alt="" aria-hidden className="block w-auto" style={{ height: `${min[1]}${min[2]}` }} />
+                </span>
+              )}
+            </span>,
+          ],
+          ["Clear space", logo.clearSpace ?? "not set"],
+        ];
+        if (logo.width && logo.height) facts.push(["Proportions", <span key="p" className="font-mono text-xs">{logo.width} × {logo.height}</span>]);
+        return (
+          <section key={logo.file} data-slot="logo" className="flex flex-col gap-5">
+            <header className="flex flex-col gap-1.5">
+              <h3 className="text-3xl tracking-tight">{logo.name}</h3>
+              {logo.usage && <p className="max-w-2xl text-base text-muted-foreground">{inline(logo.usage)}</p>}
+            </header>
+            <div className="grid gap-3 lg:grid-cols-[minmax(0,2fr)_minmax(0,1fr)]">
+              {/* the logo large, on its first surface, with its clear space drawn and named */}
+              <div
+                data-slot="logo-surface"
+                data-theme="light"
+                className="relative flex min-h-72 items-center justify-center overflow-hidden rounded-2xl border border-border p-10"
+                style={paint(surfaces[0])}
+              >
+                <span className="absolute top-4 left-4 font-mono text-xs opacity-70">{surfaces[0]}</span>
+                <span className="relative inline-flex">
+                  <span
+                    data-slot="logo-clear-space"
+                    className="inline-flex border border-dashed"
+                    style={{ padding: clear ? `calc(${clear[1]}${clear[2]} * 2)` : "1.5rem", borderColor: "color-mix(in oklch, currentColor 45%, transparent)" }}
+                    title={`Clear space: ${logo.clearSpace ?? "not set"}`}
+                  >
+                    {src ? <img src={src} alt={logo.alt ?? logo.name} className="block h-16 w-auto sm:h-20" /> : <span className="text-xs">{logo.file}</span>}
+                  </span>
+                  {clear && (
+                    <span className="absolute -bottom-6 left-1/2 -translate-x-1/2 font-mono text-xs whitespace-nowrap opacity-70">clear space, shown at 2×</span>
+                  )}
+                </span>
+              </div>
+              <ul className="grid grid-cols-2 gap-3 lg:grid-cols-1 lg:grid-rows-3">
+                {surfaces.slice(1).map((surface) => (
+                  <li
+                    key={surface}
+                    data-slot="logo-surface"
+                    data-theme="light"
+                    className="relative flex min-h-28 items-center justify-center rounded-2xl border border-border p-6"
+                    style={paint(surface)}
+                  >
+                    <span className="absolute top-3 left-3 font-mono text-xs opacity-70">{surface}</span>
+                    {src && <img src={src} alt="" aria-hidden className="block h-9 w-auto" />}
+                  </li>
+                ))}
+                {surfaces.length === 1 && (
+                  <li className="col-span-2 flex items-center rounded-2xl border border-dashed border-border p-6 text-sm text-muted-foreground lg:col-span-1 lg:row-span-3">
+                    Only on {surfaces[0]}.
+                  </li>
+                )}
+              </ul>
+            </div>
+            <dl className="grid gap-x-10 gap-y-5 sm:grid-cols-3">
+              {facts.map(([term, detail]) => (
+                <div key={term} className="flex flex-col gap-1.5">
+                  <dt className="text-xs font-medium text-muted-foreground">{term}</dt>
+                  <dd className="text-sm">{detail}</dd>
+                </div>
+              ))}
+            </dl>
+            {own.length > 0 && <RuleList rules={own} rulesHref={rulesHref} />}
+          </section>
+        );
+      })}
+    </div>
+  );
+}
+
+function RuleList({ rules, rulesHref }: { rules: RuleEntry[]; rulesHref?: string }) {
+  return (
+    <ul data-slot="logo-rules" className="grid gap-x-12 sm:grid-cols-2">
+      {rules.map((r) => (
+        <li key={r.id} className="border-t border-border">
+          <a
+            href={rulesHref ? `${rulesHref}#${r.id}` : `#${r.id}`}
+            className="group flex h-full flex-col gap-1.5 py-4 text-sm focus-visible:outline-2 focus-visible:outline-ring"
+          >
+            <span className="flex items-center justify-between gap-2">
+              <span className="flex items-center gap-2 text-base font-medium group-hover:underline group-hover:underline-offset-4">
+                <Scale aria-hidden className="size-(--dt-size-xs) text-muted-foreground" />
+                {r.title}
+              </span>
+              <StatusBadge status={r.status} />
+            </span>
+            <span className="text-muted-foreground">{inline(r.statement)}</span>
+          </a>
+        </li>
+      ))}
+    </ul>
+  );
+}

package/src/next/config.ts

@@ -0,0 +1,80 @@
+import type { ComponentType, ReactElement, ReactNode } from "react";
+import type { AdherenceReport } from "../lib/adherence-types";
+
+/** A page people write: brand, principles, a design language. Markdown, with its author and how settled it is. */
+export interface EditorialPage {
+  /** Its path under the docs, e.g. `brand` or `brand/accessibility`. */
+  slug: string;
+  title: string;
+  lead?: string;
+  /** Markdown: `##` sections, paragraphs, bullet lists; a list whose items open in bold is a set of principles. */
+  body: string;
+  by: { author: string; reviewer?: string; reviewed: string; status: "draft" | "published" };
+  /** The navigation group it sits in. Default: brand. */
+  section?: "brand" | "foundations" | "standards";
+  /** Its label in the navigation, when shorter than its title. */
+  nav?: string;
+}
+
+/** What a component needs to render on its workbench. */
+export interface WorkbenchSetup {
+  /** Starting props: what it needs to render at all (a Select's options). */
+  props?: Record<string, unknown>;
+  /** Text inside it. "" for a component that takes none. */
+  children?: string;
+  /** Children richer than text: a Card's parts, a Tabs' list and panels. */
+  content?: ReactNode;
+  /** What it must sit inside to work: a provider, the root a part belongs to. */
+  wrap?: ReactElement<{ children?: ReactNode }>;
+}
+
+/** The built-in generated pages, each of which can be turned off. */
+export type BuiltInPage = "logo" | "imagery" | "voice" | "colour" | "type" | "scale" | "rules" | "patterns" | "components" | "standards" | "vocabulary";
+
+/**
+ * Everything one site of docs needs: the manifest it renders, the registry that
+ * reaches the project's components, the brand around it, and what each part
+ * says. The pages, their order, the navigation, search and the markdown for
+ * agents all come from this.
+ */
+export interface DocsConfig {
+  title: string;
+  /** Where the docs are served. Default: `/design/system`. */
+  basePath?: string;
+  /** The client's logo, beside the title in the navigation. */
+  logo?: ReactNode;
+  /** A full-bleed introduction across the top of the overview. Without one the overview has a plain header. */
+  hero?: ReactNode;
+  /** The overview's lead, when there is no hero. */
+  lead?: string;
+  /** The generated registry (`designtools-docs map`): a provider for the project's components, examples and assets. */
+  registry: ComponentType<{ children: ReactNode }>;
+  /** The manifest, as `designtools-manifest build` writes it. */
+  manifest: {
+    components: unknown;
+    tokens: unknown;
+    rules?: unknown;
+    patterns?: unknown;
+    taxonomy?: unknown;
+    assets?: unknown;
+  };
+  /** `.mxa/stack.json`'s baselines, for the standards page. */
+  baselines?: Record<string, unknown>;
+  /** `designtools-manifest provenance`'s line: the version and commit the docs were built from. */
+  provenance?: string;
+  /** `designtools-adherence --json`, for the standards page. */
+  adherence?: AdherenceReport;
+  /** Pages people write, in the order they appear. */
+  editorial?: EditorialPage[];
+  /** Built-in pages to leave out. */
+  hide?: BuiltInPage[];
+  /** Per component, by name: what it needs on its workbench. */
+  workbench?: Record<string, WorkbenchSetup>;
+  /** Per rule, by id: a demonstration shown on its card, for a rule that needs persuading. */
+  demonstrations?: Record<string, ReactNode>;
+  /**
+   * Blocks replaced by the project's own, by name: `{ Usage: LocalUsage }`.
+   * `designtools-docs eject <block>` copies one into the project to start from.
+   */
+  blocks?: Partial<Record<string, ComponentType<any>>>;
+}

package/src/next/index.tsx

@@ -0,0 +1,100 @@
+import "../styles.css";
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import type { ReactNode } from "react";
+import { findBySlug, slugOf } from "../lib/manifest";
+import { PreviewExample, PreviewSurface } from "../preview-frame";
+import { DocsShell } from "../shell";
+import type { DocsConfig } from "./config";
+import { manifestFiles, manifestRoute, markdownRoute } from "./markdown";
+import { DocsPageView } from "./pages";
+import { allSlugs, metaOf, navOf, resolve, siteOf } from "./site";
+
+export type { BuiltInPage, DocsConfig, EditorialPage, WorkbenchSetup } from "./config";
+export { markdownFor } from "./markdown";
+export { docsMatcher, docsProxy, prefersMarkdown } from "./proxy";
+
+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 function createDocs(config: DocsConfig) {
+  const site = siteOf(config);
+  const nav = navOf(site);
+  const Registry = config.registry;
+
+  function Layout({ children }: { children: ReactNode }) {
+    return (
+      <Registry>
+        <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}
+        </DocsShell>
+      </Registry>
+    );
+  }
+
+  async function Page({ params }: SlugParams) {
+    const page = resolve(site, (await params).slug);
+    if (!page) notFound();
+    return <DocsPageView site={site} page={page} />;
+  }
+
+  async function generateMetadata({ params }: SlugParams): Promise<Metadata> {
+    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 }: { params: Promise<{ slug: string; example: string }>; searchParams: Promise<{ theme?: string }> }) {
+    const { slug, example } = await params;
+    const { theme } = await searchParams;
+    const entry = findBySlug(site.components, slug);
+    if (!entry?.examples) notFound();
+    return (
+      <Registry>
+        <PreviewSurface theme={theme}>
+          <PreviewExample entry={entry} example={decodeURIComponent(example)} />
+        </PreviewSurface>
+      </Registry>
+    );
+  }
+
+  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/src/next/markdown.ts

@@ -0,0 +1,119 @@
+import { groupByCategory, slugOf } from "../lib/manifest";
+import {
+  adherenceMarkdown,
+  assetsMarkdown,
+  coloursMarkdown,
+  componentMarkdown,
+  editorialHeader,
+  generatedHeader,
+  glossaryMarkdown,
+  manifestLinks,
+  patternMarkdown,
+  ruleMarkdown,
+  scaleMarkdown,
+  standardsMarkdown,
+  systemMarkdown,
+  typeMarkdown,
+} from "../lib/markdown";
+import { navOf, resolve, type Site } from "./site";
+
+/**
+ * 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: Site, path: string): string | undefined {
+  const { base, title, components, tokens, rules, patterns, taxonomy, assets, config } = site;
+  const generated = (md: string) => 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: { label: string; href: string }[]) => 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: Site) {
+  return async function GET(_: Request, { params }: { params: Promise<{ path?: string[] }> }) {
+    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: Site) {
+  const files = manifestFiles(site);
+  return async function GET(_: Request, { params }: { params: Promise<{ file: string }> }) {
+    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: Site): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(site.config.manifest).filter(([, v]) => v !== undefined));
+}