@designtools/docs 0.0.0-stage → 0.2.0

package/src/lib/ui.tsx

@@ -0,0 +1,291 @@
+"use client";
+
+import { Menu } from "@base-ui/react/menu";
+import { Tabs } from "@base-ui/react/tabs";
+import { Check, ChevronDown, Copy, type LucideIcon } from "lucide-react";
+import { type ComponentProps, type ReactNode, useState } from "react";
+import { cx } from "./cx";
+
+/**
+ * The pieces every block is built from, so the docs read as one thing: the stage a
+ * component is shown on, the frame around a stage, small icon buttons, a segmented
+ * control and a copy button. All drawn from the semantic tokens.
+ */
+
+/**
+ * Where a component is shown: the page's canvas with a faint dot grid, so the
+ * component reads as an object on a surface rather than more page. `theme` renders
+ * it in one mode whatever the page is in; `width` narrows it to a phone.
+ */
+export function Stage({
+  theme,
+  width,
+  className,
+  children,
+  ...props
+}: { theme?: "light" | "dark"; width?: number; className?: string; children: ReactNode } & Omit<ComponentProps<"div">, "className">) {
+  return (
+    <div
+      data-slot="stage"
+      data-docs-stage=""
+      data-theme={theme}
+      className={cx(
+        "relative flex min-w-0 items-center justify-center overflow-auto bg-canvas p-8 text-canvas-foreground sm:p-10",
+        "bg-[radial-gradient(color-mix(in_oklch,var(--border)_85%,transparent)_1px,transparent_1px)] [background-size:14px_14px]",
+        className,
+      )}
+      {...props}
+    >
+      {width ? (
+        <div className="w-full rounded-lg border border-dashed border-border p-4" style={{ maxWidth: width }}>
+          {children}
+        </div>
+      ) : (
+        children
+      )}
+    </div>
+  );
+}
+
+/** A rounded card that frames a stage and its toolbar: every example, playground and preview sits in one. */
+export function Frame({ className, children, ...props }: ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="frame"
+      className={cx("flex min-w-0 flex-col overflow-hidden rounded-xl border border-border bg-surface text-surface-foreground shadow-xs", className)}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
+
+/** The bar along the top of a frame. */
+export function Toolbar({ className, children }: { className?: string; children: ReactNode }) {
+  return (
+    <div data-slot="frame-toolbar" className={cx("flex min-h-12 flex-wrap items-center justify-between gap-2 border-b border-border px-2 py-1.5", className)}>
+      {children}
+    </div>
+  );
+}
+
+/**
+ * A small icon button: drawn at 32px, pressed at the docs' target size (44px by
+ * default) through a transparent ring, so a toolbar stays tight and every button
+ * is still easy to hit.
+ */
+export function IconButton({
+  icon: Icon,
+  label,
+  pressed,
+  className,
+  ...props
+}: { icon: LucideIcon; label: string; pressed?: boolean } & Omit<ComponentProps<"button">, "children">) {
+  return (
+    <button
+      type="button"
+      aria-label={label}
+      title={label}
+      aria-pressed={pressed}
+      className={cx(
+        "relative inline-flex size-8 shrink-0 cursor-pointer items-center justify-center rounded-md text-muted-foreground transition-colors duration-(--dt-duration-fast)",
+        "after:absolute after:-inset-[calc((var(--docs-target,2.75rem)-2rem)/2)] after:content-['']",
+        "hover:bg-muted hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring aria-pressed:bg-muted aria-pressed:text-canvas-foreground",
+        className,
+      )}
+      {...props}
+    >
+      <Icon aria-hidden className="size-(--dt-size-xs)" />
+    </button>
+  );
+}
+
+/** An `IconButton` that goes somewhere: opening an example on its own, a source file. */
+export function IconLink({ icon: Icon, label, className, ...props }: { icon: LucideIcon; label: string } & Omit<ComponentProps<"a">, "children">) {
+  return (
+    <a
+      aria-label={label}
+      title={label}
+      className={cx(
+        "relative inline-flex size-8 shrink-0 cursor-pointer items-center justify-center rounded-md text-muted-foreground transition-colors duration-(--dt-duration-fast)",
+        "after:absolute after:-inset-[calc((var(--docs-target,2.75rem)-2rem)/2)] after:content-['']",
+        "hover:bg-muted hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring",
+        className,
+      )}
+      {...props}
+    >
+      <Icon aria-hidden className="size-(--dt-size-xs)" />
+    </a>
+  );
+}
+
+/** Copies text, and says so: an icon button, or a labelled one with `withLabel`. */
+export function CopyButton({ text, label = "Copy", withLabel, className }: { text: string; label?: string; withLabel?: boolean; className?: string }) {
+  const [copied, setCopied] = useState(false);
+  const copy = async () => {
+    try {
+      await navigator.clipboard.writeText(text);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1500);
+    } catch {
+      // clipboard refused (an insecure origin, a denied permission): nothing changes
+    }
+  };
+  return (
+    <>
+      {withLabel ? (
+        <button
+          type="button"
+          onClick={copy}
+          className={cx(
+            "inline-flex min-h-(--docs-target,2.75rem) cursor-pointer items-center gap-2 rounded-md border border-border bg-surface px-3 text-sm font-medium text-surface-foreground shadow-xs hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring",
+            className,
+          )}
+        >
+          {copied ? <Check aria-hidden className="size-(--dt-size-xs)" /> : <Copy aria-hidden className="size-(--dt-size-xs) text-muted-foreground" />}
+          {copied ? "Copied" : label}
+        </button>
+      ) : (
+        <IconButton icon={copied ? Check : Copy} label={copied ? "Copied" : label} onClick={copy} className={className} />
+      )}
+      <span className="sr-only" aria-live="polite">
+        {copied ? "Copied" : ""}
+      </span>
+    </>
+  );
+}
+
+/**
+ * Two to four views of one thing, as a pill track with the chosen one raised.
+ * Tabs underneath, so arrow keys move between them and each panel is labelled by
+ * its tab. Put a `SegmentedList` where the switch belongs and a `SegmentedPanel`
+ * for each view.
+ */
+export function Segmented({ defaultValue, className, children }: { defaultValue: string; className?: string; children: ReactNode }) {
+  return (
+    <Tabs.Root data-slot="segmented" defaultValue={defaultValue} className={cx("flex min-w-0 flex-col", className)}>
+      {children}
+    </Tabs.Root>
+  );
+}
+
+/** The track of a `Segmented`: put it where the switch belongs, usually a toolbar. */
+export function SegmentedList({ items, label }: { items: { value: string; label: string; icon?: LucideIcon }[]; label: string }) {
+  return (
+    <Tabs.List aria-label={label} data-slot="segmented-list" className="relative flex items-center gap-0.5 rounded-lg border border-border p-0.5">
+      {items.map(({ value, label: text, icon: Icon }) => (
+        <Tabs.Tab
+          key={value}
+          value={value}
+          className={cx(
+            "relative inline-flex h-7 cursor-pointer items-center gap-1.5 rounded-md px-2.5 text-xs font-medium text-muted-foreground transition-colors duration-(--dt-duration-fast)",
+            "after:absolute after:inset-x-0 after:-inset-y-[calc((var(--docs-target,2.75rem)-1.75rem)/2)] after:content-['']",
+            "hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring data-active:bg-muted data-active:text-canvas-foreground",
+          )}
+        >
+          {Icon && <Icon aria-hidden className="size-(--dt-size-xs)" />}
+          {text}
+        </Tabs.Tab>
+      ))}
+    </Tabs.List>
+  );
+}
+
+export function SegmentedPanel({ value, className, children }: { value: string; className?: string; children: ReactNode }) {
+  return (
+    <Tabs.Panel value={value} className={cx("min-w-0 outline-none focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-ring", className)}>
+      {children}
+    </Tabs.Panel>
+  );
+}
+
+/** A small label above a group of controls or a column. */
+export function Eyebrow({ className, children }: { className?: string; children: ReactNode }) {
+  return <p className={cx("text-xs font-medium tracking-wide text-muted-foreground uppercase", className)}>{children}</p>;
+}
+
+/**
+ * A toolbar menu for one setting: the trigger shows an icon and, when the setting
+ * is not at its default, its current value; the menu lists every option with the
+ * chosen one checked. For viewport, background, colour vision and the like.
+ */
+export function ToolbarMenu<T extends string>({
+  icon: Icon,
+  label,
+  value,
+  fallback,
+  options,
+  onChange,
+  swatch,
+}: {
+  icon: LucideIcon;
+  /** What the setting is, for the trigger's name and the menu's heading. */
+  label: string;
+  value: T;
+  /** The default: while chosen, the trigger shows only its icon. */
+  fallback: T;
+  options: { value: T; label: string; note?: string }[];
+  onChange: (value: T) => void;
+  /** A colour to paint beside each option: for backgrounds. */
+  swatch?: (value: T) => string | undefined;
+}) {
+  const current = options.find((o) => o.value === value);
+  const changed = value !== fallback;
+  return (
+    <Menu.Root>
+      <Menu.Trigger
+        aria-label={`${label}: ${current?.label ?? value}`}
+        title={label}
+        className={cx(
+          "relative inline-flex h-8 shrink-0 cursor-pointer items-center gap-1.5 rounded-md px-2 text-xs font-medium text-muted-foreground transition-colors duration-(--dt-duration-fast)",
+          "after:absolute after:inset-x-0 after:-inset-y-[calc((var(--docs-target,2.75rem)-2rem)/2)] after:content-['']",
+          "hover:bg-muted hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring data-popup-open:bg-muted data-popup-open:text-canvas-foreground",
+          changed && "bg-muted text-canvas-foreground",
+        )}
+      >
+        {swatch && swatch(value) ? (
+          <span aria-hidden className="size-3.5 rounded-full ring-1 ring-border" style={{ background: swatch(value) }} />
+        ) : (
+          <Icon aria-hidden className="size-(--dt-size-xs)" />
+        )}
+        {changed && <span className="max-w-28 truncate">{current?.label ?? value}</span>}
+        <ChevronDown aria-hidden className="size-3 opacity-60" />
+      </Menu.Trigger>
+      <Menu.Portal>
+        <Menu.Positioner data-designtools="" sideOffset={6} align="start" className="z-50">
+          <Menu.Popup className="min-w-56 rounded-xl border border-border bg-overlay p-1.5 text-overlay-foreground shadow-lg transition-[opacity,scale] duration-(--dt-duration-fast) data-ending-style:scale-95 data-ending-style:opacity-0 data-starting-style:scale-95 data-starting-style:opacity-0">
+            <Menu.Group>
+              <Menu.GroupLabel className="px-3 pt-1.5 pb-1 text-xs text-muted-foreground">{label}</Menu.GroupLabel>
+              <Menu.RadioGroup value={value} onValueChange={(v) => onChange(v as T)}>
+                {options.map((o) => (
+                  <Menu.RadioItem
+                    key={o.value}
+                    value={o.value}
+                    closeOnClick
+                    className="grid min-h-(--docs-target,2.75rem) cursor-pointer grid-cols-[1rem_1fr] items-center gap-3 rounded-md px-3 text-sm outline-none select-none data-highlighted:bg-muted"
+                  >
+                    <Menu.RadioItemIndicator keepMounted className="flex items-center justify-center data-unchecked:invisible">
+                      <Check aria-hidden className="size-4" />
+                    </Menu.RadioItemIndicator>
+                    <span className="flex items-center gap-2.5">
+                      {swatch?.(o.value) && <span aria-hidden className="size-4 shrink-0 rounded-full ring-1 ring-border" style={{ background: swatch(o.value) }} />}
+                      <span className="flex flex-col">
+                        {o.label}
+                        {o.note && <span className="text-xs text-muted-foreground">{o.note}</span>}
+                      </span>
+                    </span>
+                  </Menu.RadioItem>
+                ))}
+              </Menu.RadioGroup>
+            </Menu.Group>
+          </Menu.Popup>
+        </Menu.Positioner>
+      </Menu.Portal>
+    </Menu.Root>
+  );
+}
+
+/** A thin upright rule between groups of toolbar controls. */
+export function ToolbarDivider() {
+  return <span aria-hidden className="mx-1 h-5 w-px shrink-0 bg-border" />;
+}

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,101 @@
+import type { ComponentType, ReactElement, ReactNode } from "react";
+import type { AdherenceReport } from "../lib/adherence-types";
+
+/** A page people write: brand, principles, a design language, with its author and how settled it is. */
+export type EditorialPage = EditorialBase &
+  (
+    | {
+        /** Markdown: `##` and `###` sections, paragraphs, bullet lists, bold, code and links; a list whose items open in bold is a set of principles. */
+        body: string;
+        markdown?: undefined;
+      }
+    | {
+        /**
+         * The page as React: real components from the project's system beside the docs' own `DocsSection`
+         * and `Prose`, for a page that has to show rather than tell. Rendered as is, under the page header.
+         */
+        body: ReactNode;
+        /** What agents read instead, at the page's `.md`: the same page, in words. */
+        markdown: string;
+      }
+  );
+
+interface EditorialBase {
+  /** Its path under the docs, e.g. `brand` or `brand/accessibility`. */
+  slug: string;
+  title: string;
+  lead?: 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 overview after its hero or header: `agentic: false` drops "Why this is agentic", and `agenticLead`
+   * replaces the line that opens it.
+   */
+  overview?: { agentic?: boolean; agenticLead?: 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>>>;
+}