@designtools/docs 0.0.0-stage → 0.2.0

package/src/shell.tsx

@@ -0,0 +1,569 @@
+"use client";
+
+import { Collapsible } from "@base-ui/react/collapsible";
+import { Dialog } from "@base-ui/react/dialog";
+import { ArrowLeft, ArrowRight, BookOpen, ChevronRight, Component, Gauge, House, LayoutTemplate, type LucideIcon, Menu, Palette, Scale, X } from "lucide-react";
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { createContext, type ReactNode, useContext, useEffect, useMemo, useState } from "react";
+import { Live } from "./lib/live";
+import { accent, cx, display, target } from "./lib/cx";
+import { type Status, StatusBadge } from "./lib/status";
+import { groupFamilies, slugOf } from "./lib/manifest";
+import type { ComponentsManifest, PatternsManifest, RulesManifest, TaxonomyManifest } from "./lib/manifest-types";
+import { searchIndex } from "./lib/search";
+import { Prose } from "./lib/text";
+import { DocsSearch } from "./search";
+import { ThemeSwitch, useThemeScript } from "./theme-switch";
+
+export interface DocsLink {
+  label: string;
+  href: string;
+  /** Shown beneath it while you are on it or one of them: a component's parts. */
+  children?: DocsLink[];
+}
+
+/** A top-level section of the navigation: one page, or groups of pages that fold away. */
+interface Section {
+  id: string;
+  label: string;
+  icon: LucideIcon;
+  /** A section of one page is a link, not a fold. */
+  href?: string;
+  groups: { heading?: string; links: DocsLink[] }[];
+}
+
+/** What the page knows from the navigation: the section it sits in, and its neighbours. */
+const DocsPage = createContext<{ section?: string; prev?: DocsLink; next?: DocsLink }>({});
+
+/**
+ * The docs frame, in the site's order: overview, brand, foundations, rules,
+ * patterns, components by `@category`, standards. Editorial pages are the links
+ * you pass; rules, patterns and components come from the manifest.
+ *
+ * On a laptop the navigation is an inset panel down the left, each section
+ * folding open where the current page is, with search at the top and the colour
+ * mode at the foot; wide screens add an "On this page" rail. On a phone it is a
+ * bar with search and a drawer. Every page ends with the previous and next page,
+ * and `DocsHeader` names the section it sits in. Put it in the docs layout.
+ */
+export function DocsShell({
+  manifest,
+  rules,
+  patterns,
+  terms,
+  search = true,
+  themeSwitch = true,
+  title = "Design system",
+  logo,
+  basePath = "/design/system",
+  brand = [],
+  foundations = [],
+  standards = [],
+  hero,
+  children,
+}: {
+  manifest: ComponentsManifest;
+  /** Listed under Rules, each linking to its anchor on `${basePath}/rules`. */
+  rules?: RulesManifest;
+  /** Listed under Patterns, each at `${basePath}/patterns/${id}`. */
+  patterns?: PatternsManifest;
+  /** The taxonomy, so search finds a component by a wrong name ("Dropdown" finds Select). */
+  terms?: TaxonomyManifest;
+  /** Search over components, parts, rules, patterns and pages, on ⌘K, Ctrl+K or /. On by default. */
+  search?: boolean;
+  /** System, light and dark, at the foot of the navigation. Off for a project with its own switch. */
+  themeSwitch?: boolean;
+  title?: string;
+  /** The client's logo, shown beside the title: the site is theirs. */
+  logo?: ReactNode;
+  /** Component pages live at `${basePath}/components/${slug}`. */
+  basePath?: string;
+  /** Brand pages: principles, design language, voice, logo, imagery. */
+  brand?: DocsLink[];
+  /** Foundations pages: colour, type, scale. */
+  foundations?: DocsLink[];
+  /** Standards pages: budgets, accessibility, adherence. */
+  standards?: DocsLink[];
+  /**
+   * A full-bleed introduction across the top of the overview, edge to edge of the
+   * content area: the brand's splash. The overview's own header can then be left out.
+   */
+  hero?: ReactNode;
+  children: ReactNode;
+}) {
+  const current = usePathname();
+  const searchItems = useMemo(
+    () =>
+      searchIndex({
+        manifest,
+        rules: rules?.rules,
+        patterns: patterns?.patterns,
+        terms: terms?.terms,
+        pages: [...brand, ...foundations, ...(rules?.rules.length ? [{ label: "Rules", href: `${basePath}/rules` }] : []), ...standards],
+        basePath,
+      }),
+    [manifest, rules, patterns, terms, brand, foundations, standards, basePath],
+  );
+
+  const sections = useMemo<Section[]>(() => {
+    const families = groupFamilies(manifest);
+    const all: Section[] = [
+      { id: "overview", label: "Overview", icon: House, href: basePath, groups: [] },
+      { id: "brand", label: "Brand", icon: BookOpen, groups: [{ links: brand }] },
+      { id: "foundations", label: "Foundations", icon: Palette, groups: [{ links: foundations }] },
+      ...(rules?.rules.length ? [{ id: "rules", label: "Rules", icon: Scale, href: `${basePath}/rules`, groups: [] }] : []),
+      {
+        id: "patterns",
+        label: "Patterns",
+        icon: LayoutTemplate,
+        groups: [{ links: (patterns?.patterns ?? []).map((p) => ({ label: p.name, href: `${basePath}/patterns/${p.id}` })) }],
+      },
+      {
+        id: "components",
+        label: "Components",
+        icon: Component,
+        groups: families.map((g) => ({
+          heading: families.length > 1 ? g.category : undefined,
+          links: g.families.map(({ head, parts }) => ({
+            label: head.name,
+            href: `${basePath}/components/${slugOf(head)}`,
+            children: parts.map((p) => ({ label: p.name, href: `${basePath}/components/${slugOf(p)}` })),
+          })),
+        })),
+      },
+      { id: "standards", label: "Standards", icon: Gauge, groups: [{ links: standards }] },
+    ];
+    return all.filter((s) => s.href || s.groups.some((g) => g.links.length));
+  }, [manifest, rules, patterns, brand, foundations, standards, basePath]);
+
+  // every page in navigation order, for the section a page sits in and its neighbours
+  const page = useMemo(() => {
+    // a section of one page has no section above it: the page is the section
+    const order: { link: DocsLink; section?: string }[] = [];
+    for (const s of sections) {
+      if (s.href) order.push({ link: { label: s.label, href: s.href } });
+      for (const g of s.groups) for (const l of g.links) order.push({ link: l, section: s.label });
+    }
+    const at = order.findIndex(({ link }) => link.href === current || link.children?.some((c) => c.href === current));
+    if (at < 0) return {};
+    return { section: order[at].section, prev: order[at - 1]?.link, next: order[at + 1]?.link };
+  }, [sections, current]);
+
+  // a hook, so it runs whether or not the switch is shown; the script only reads a saved choice
+  useThemeScript();
+  const [menu, setMenu] = useState(false);
+  useEffect(() => setMenu(false), [current]);
+
+  const brandLink = (
+    <Link href={basePath} data-slot="docs-title" className={cx(target, "flex min-w-0 items-center gap-3 rounded-md focus-visible:outline-2 focus-visible:outline-ring")}>
+      {logo && (
+        <span data-slot="docs-logo" className="shrink-0">
+          <Live>{logo}</Live>
+        </span>
+      )}
+      <span className={cx(logo ? "sr-only" : "truncate text-base font-semibold tracking-tight")}>{title}</span>
+    </Link>
+  );
+
+  return (
+    <DocsPage.Provider value={page}>
+      <div data-designtools="" data-slot="docs-shell" className="min-h-dvh bg-canvas text-canvas-foreground lg:grid lg:grid-cols-[19rem_minmax(0,1fr)]">
+
+        <aside data-slot="docs-sidebar" className="sticky top-0 hidden h-dvh p-3 lg:block">
+          <div className="flex h-full flex-col overflow-hidden rounded-xl border border-border bg-surface text-surface-foreground shadow-xs">
+            <div className="flex flex-col gap-3 p-4 pb-3">
+              {brandLink}
+              {search && <DocsSearch items={searchItems} />}
+            </div>
+            <Nav sections={sections} current={current} title={title} />
+            {themeSwitch && (
+              <div data-slot="docs-sidebar-foot" className="flex items-center justify-between gap-3 border-t border-border px-4 py-3">
+                <span className="text-xs font-medium text-muted-foreground">Appearance</span>
+                <ThemeSwitch />
+              </div>
+            )}
+          </div>
+        </aside>
+
+        <div className="min-w-0">
+          <header
+            data-slot="docs-topbar"
+            className="sticky top-0 z-20 flex h-16 items-center gap-2 border-b border-border bg-canvas/85 px-3 backdrop-blur-md lg:hidden"
+          >
+            <Dialog.Root open={menu} onOpenChange={setMenu}>
+              <Dialog.Trigger aria-label="Open the navigation" className={iconButton}>
+                <Menu aria-hidden className="size-(--dt-size-sm)" />
+              </Dialog.Trigger>
+              <Dialog.Portal>
+                <Dialog.Backdrop data-designtools="" className="fixed inset-0 z-40 bg-canvas-foreground/30 transition-opacity duration-(--dt-duration-base) data-ending-style:opacity-0 data-starting-style:opacity-0" />
+                <Dialog.Popup
+                  data-designtools=""
+                  data-slot="docs-drawer"
+                  aria-label={title}
+                  className="fixed inset-y-0 left-0 z-50 flex w-[min(21rem,88vw)] flex-col bg-surface text-surface-foreground shadow-xl transition-transform duration-(--dt-duration-slow) ease-(--dt-ease-out) data-ending-style:-translate-x-full data-starting-style:-translate-x-full"
+                >
+                  <div className="flex items-center justify-between gap-2 border-b border-border p-3 pl-4">
+                    {brandLink}
+                    <Dialog.Close aria-label="Close the navigation" className={iconButton}>
+                      <X aria-hidden className="size-(--dt-size-sm)" />
+                    </Dialog.Close>
+                  </div>
+                  <Nav sections={sections} current={current} title={title} className="pt-4" />
+                  {themeSwitch && (
+                    <div className="flex items-center justify-between gap-3 border-t border-border px-4 py-3">
+                      <span className="text-xs font-medium text-muted-foreground">Appearance</span>
+                      <ThemeSwitch />
+                    </div>
+                  )}
+                </Dialog.Popup>
+              </Dialog.Portal>
+            </Dialog.Root>
+            <div className="min-w-0 flex-1">{brandLink}</div>
+            {/* the sidebar's search owns the keyboard shortcut, so one key press opens one dialog */}
+            {search && <DocsSearch items={searchItems} shortcuts={false} variant="icon" />}
+          </header>
+
+          {hero && current === basePath && (
+            <div data-slot="docs-hero" className="w-full">
+              <Live>{hero}</Live>
+            </div>
+          )}
+          <div className="mx-auto flex w-full max-w-[90rem] gap-16 px-5 pt-12 pb-20 sm:px-8 lg:px-12 lg:pt-20 xl:px-20">
+            <main data-slot="docs-main" className="flex min-w-0 flex-1 flex-col gap-16 [counter-reset:docs-section] lg:gap-24">
+              {children}
+              <Pager prev={page.prev} next={page.next} />
+            </main>
+            <OnThisPage current={current} />
+          </div>
+        </div>
+      </div>
+    </DocsPage.Provider>
+  );
+}
+
+const iconButton =
+  "inline-flex size-(--docs-target,2.75rem) shrink-0 cursor-pointer items-center justify-center rounded-md text-muted-foreground hover:bg-muted hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring";
+
+/** The sections, each a link or a fold that opens where the current page is. */
+function Nav({ sections, current, title, className }: { sections: Section[]; current: string; title: string; className?: string }) {
+  const holds = (s: Section) => s.groups.some((g) => g.links.some((l) => l.href === current || l.children?.some((c) => c.href === current)));
+  const [open, setOpen] = useState<Record<string, boolean>>(() => Object.fromEntries(sections.map((s) => [s.id, holds(s)])));
+  // moving to a page opens its section; nothing closes on its own
+  useEffect(() => {
+    const here = sections.find(holds);
+    if (here) setOpen((o) => (o[here.id] ? o : { ...o, [here.id]: true }));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [current, sections]);
+
+  return (
+    <nav aria-label={title} data-slot="docs-nav" className={cx("min-h-0 flex-1 overflow-y-auto px-3 pb-4 text-sm", className)}>
+      <ul className="flex flex-col gap-0.5">
+        {sections.map((s) => {
+          const Icon = s.icon;
+          const row = cx(
+            target,
+            "group flex w-full items-center gap-3 rounded-md px-2.5 font-medium text-canvas-foreground hover:bg-muted focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-ring",
+          );
+          const icon = <Icon aria-hidden className="size-(--dt-size-xs) shrink-0 text-muted-foreground group-hover:text-canvas-foreground" />;
+          if (s.href) {
+            const active = current === s.href;
+            return (
+              <li key={s.id}>
+                <Link href={s.href} aria-current={active ? "page" : undefined} data-slot="docs-nav-section" className={cx(row, active && "bg-muted")}>
+                  {icon}
+                  {s.label}
+                </Link>
+              </li>
+            );
+          }
+          return (
+            <li key={s.id}>
+              <Collapsible.Root open={open[s.id] ?? false} onOpenChange={(next) => setOpen((o) => ({ ...o, [s.id]: next }))}>
+                <Collapsible.Trigger data-slot="docs-nav-section" className={row}>
+                  {icon}
+                  <span className="flex-1 text-left">{s.label}</span>
+                  <ChevronRight
+                    aria-hidden
+                    className="size-(--dt-size-xs) text-muted-foreground transition-transform duration-(--dt-duration-fast) group-data-panel-open:rotate-90"
+                  />
+                </Collapsible.Trigger>
+                <Collapsible.Panel
+                  data-slot="docs-nav-panel"
+                  className="h-(--collapsible-panel-height) overflow-hidden transition-[height] duration-(--dt-duration-base) ease-(--dt-ease-out) data-ending-style:h-0 data-starting-style:h-0"
+                >
+                  <div className="ml-[1.1875rem] flex flex-col gap-3 border-l border-border py-1 pl-3">
+                    {s.groups.map((g, i) => (
+                      <div key={g.heading ?? i} className="flex flex-col">
+                        {g.heading && (
+                          <p data-slot="docs-nav-heading" className="px-2.5 pt-3 pb-1.5 text-[0.6875rem] font-semibold tracking-[0.08em] text-muted-foreground uppercase first:pt-1">
+                            {g.heading}
+                          </p>
+                        )}
+                        <ul className="flex flex-col">
+                          {g.links.map((link) => {
+                            const here = current === link.href || link.children?.some((c) => c.href === current);
+                            return (
+                              <li key={link.href}>
+                                <NavLink link={link} current={current} />
+                                {here && link.children?.length ? (
+                                  <ul data-slot="docs-nav-parts" aria-label={`${link.label} parts`} className="ml-3 flex flex-col border-l border-border pl-2">
+                                    {link.children.map((child) => (
+                                      <li key={child.href}>
+                                        <NavLink link={child} current={current} />
+                                      </li>
+                                    ))}
+                                  </ul>
+                                ) : null}
+                              </li>
+                            );
+                          })}
+                        </ul>
+                      </div>
+                    ))}
+                  </div>
+                </Collapsible.Panel>
+              </Collapsible.Root>
+            </li>
+          );
+        })}
+      </ul>
+    </nav>
+  );
+}
+
+function NavLink({ link, current }: { link: DocsLink; current: string }) {
+  const active = current === link.href;
+  return (
+    <Link
+      href={link.href}
+      aria-current={active ? "page" : undefined}
+      data-slot="docs-nav-link"
+      className={cx(
+        target,
+        "relative flex items-center rounded-md px-2.5 text-canvas-foreground/80 hover:bg-muted hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-ring",
+        active && "bg-muted font-medium text-canvas-foreground",
+      )}
+    >
+      {active && <span aria-hidden data-slot="docs-nav-marker" className={cx(accent, "absolute inset-y-2.5 -left-[0.8125rem] w-0.5 rounded-full")} />}
+      {link.label}
+    </Link>
+  );
+}
+
+/** The page's sections, beside it on a wide screen, marking the one being read. */
+function OnThisPage({ current }: { current: string }) {
+  const [items, setItems] = useState<{ id: string; label: string }[]>([]);
+  const [active, setActive] = useState<string>();
+
+  useEffect(() => {
+    const headings = [...document.querySelectorAll<HTMLElement>('[data-slot="docs-main"] [data-slot="docs-section-title"][id]')];
+    setItems(headings.map((h) => ({ id: h.id, label: h.textContent ?? "" })));
+    setActive(headings[0]?.id);
+    if (!headings.length) return;
+    // the section being read is the last whose heading has passed the top quarter of the window
+    let frame = 0;
+    const update = () => {
+      frame = 0;
+      const line = window.innerHeight * 0.25;
+      let at = headings[0];
+      for (const h of headings) if (h.getBoundingClientRect().top <= line) at = h;
+      // at the foot of the page the last section is the one in view, however short
+      if (window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - 4) at = headings[headings.length - 1];
+      setActive(at.id);
+    };
+    const onScroll = () => {
+      if (!frame) frame = requestAnimationFrame(update);
+    };
+    update();
+    window.addEventListener("scroll", onScroll, { passive: true });
+    window.addEventListener("resize", onScroll);
+    return () => {
+      cancelAnimationFrame(frame);
+      window.removeEventListener("scroll", onScroll);
+      window.removeEventListener("resize", onScroll);
+    };
+  }, [current]);
+
+  if (items.length < 2) return null;
+  return (
+    <nav aria-label="On this page" data-slot="docs-toc" className="sticky top-16 hidden h-fit w-48 shrink-0 2xl:block">
+      <p className="mb-3 text-xs font-medium tracking-wide text-muted-foreground uppercase">On this page</p>
+      <ul className="flex flex-col border-l border-border text-sm">
+        {items.map((item) => (
+          <li key={item.id}>
+            <a
+              href={`#${item.id}`}
+              aria-current={active === item.id ? "location" : undefined}
+              className={cx(
+                "relative -ml-px block border-l border-transparent py-1.5 pl-4 text-muted-foreground hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring",
+                active === item.id && "font-medium text-canvas-foreground",
+              )}
+            >
+              {active === item.id && <span aria-hidden className={cx(accent, "absolute inset-y-1.5 -left-px w-0.5 rounded-full")} />}
+              {item.label}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  );
+}
+
+/** The previous and next page in the navigation's order. */
+function Pager({ prev, next }: { prev?: DocsLink; next?: DocsLink }) {
+  if (!prev && !next) return null;
+  const card = cx(
+    target,
+    "group flex flex-col gap-1 rounded-lg border border-border p-5 transition-colors duration-(--dt-duration-fast) hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring",
+  );
+  return (
+    <nav aria-label="Previous and next" data-slot="docs-pager" className="-mt-4 grid gap-3 sm:grid-cols-2 lg:-mt-8">
+      {prev ? (
+        <Link href={prev.href} className={card}>
+          <span className="flex items-center gap-1.5 text-xs text-muted-foreground">
+            <ArrowLeft aria-hidden className="size-(--dt-size-xs) transition-transform group-hover:-translate-x-0.5" /> Previous
+          </span>
+          <span className="text-base font-medium">{prev.label}</span>
+        </Link>
+      ) : (
+        <span />
+      )}
+      {next && (
+        <Link href={next.href} className={cx(card, "sm:items-end sm:text-right")}>
+          <span className="flex items-center gap-1.5 text-xs text-muted-foreground">
+            Next <ArrowRight aria-hidden className="size-(--dt-size-xs) transition-transform group-hover:translate-x-0.5" />
+          </span>
+          <span className="text-base font-medium">{next.label}</span>
+        </Link>
+      )}
+    </nav>
+  );
+}
+
+/**
+ * A page's heading: the section it sits in (from the navigation), the title, the
+ * lead, and the page's actions as children. Where the page comes from goes at the
+ * foot, in `DocsFooter`.
+ */
+export function DocsHeader({
+  title,
+  lead,
+  eyebrow,
+  status,
+  children,
+}: {
+  title: string;
+  lead?: string;
+  /** Above the title. Defaults to the section the page sits in. */
+  eyebrow?: string;
+  /** How settled the thing the page documents is, beside the eyebrow: a pattern's status. */
+  status?: Status;
+  /** The page's actions, beside the title: `PageActions`. */
+  children?: ReactNode;
+}) {
+  const { section } = useContext(DocsPage);
+  const over = eyebrow ?? (section && section !== title ? section : undefined);
+  return (
+    <header data-slot="docs-header" className="flex flex-col gap-6">
+      <div className="flex flex-wrap items-center justify-between gap-4">
+        {over || status ? (
+          <span className="flex flex-wrap items-center gap-3">
+            {over && (
+              <p data-slot="docs-eyebrow" className="text-xs font-medium tracking-[var(--tracking-widest,0.16em)] text-muted-foreground uppercase">
+                {over}
+              </p>
+            )}
+            {status && <StatusBadge status={status} />}
+          </span>
+        ) : (
+          <span />
+        )}
+        {children && (
+          <div data-slot="docs-header-actions" className="flex flex-wrap items-center gap-2">
+            {children}
+          </div>
+        )}
+      </div>
+      <h1 className={cx(display, "text-5xl leading-[1.05] tracking-tight md:text-7xl")}>{title}</h1>
+      {lead && (
+        // a lead is read, not studied: light, large, and code in it set in the text's own colour, without a chip
+        <div
+          data-slot="docs-lead"
+          className="flex max-w-3xl flex-col gap-3 text-xl leading-snug font-light text-muted-foreground md:text-2xl md:leading-snug [&_code]:bg-transparent [&_code]:p-0"
+        >
+          <Prose text={lead} />
+        </div>
+      )}
+    </header>
+  );
+}
+
+/**
+ * Where a page comes from, at its foot: a generated page names the version and
+ * commit it was built from; an editorial page names its author, who reviewed it,
+ * when, and whether it is settled. Never both, and never a review date on a
+ * generated page, which would be invented. `source` names the file it documents.
+ */
+export function DocsFooter({
+  provenance,
+  editorial,
+  source,
+}: {
+  /** For a generated page: `Generated from acme-web@1.4.0 at 3f2a9c1`, from `designtools-manifest provenance`. */
+  provenance?: string;
+  /** For an editorial page. `reviewer` when the person who signs it off is not the author. */
+  editorial?: { author: string; reviewer?: string; reviewed: string; status: "draft" | "published" };
+  source?: string;
+}) {
+  if (!provenance && !editorial && !source) return null;
+  return (
+    // order-last: the page renders its footer before the shell adds the pager, and where a page comes from is the last thing on it
+    <footer
+      data-slot="docs-footer"
+      className="order-last -mt-8 flex flex-wrap items-center gap-x-6 gap-y-2 border-t border-border pt-6 text-xs text-muted-foreground lg:-mt-14"
+    >
+      {(provenance || editorial) && (
+        <p data-slot="docs-provenance" className="flex items-center gap-2">
+          <span
+            aria-hidden
+            className={cx("size-1.5 shrink-0 rounded-full", editorial ? (editorial.status === "published" ? "bg-success" : "bg-warning") : "bg-primary")}
+          />
+          {editorial
+            ? `Written by ${editorial.author} · ${editorial.reviewer ? `reviewed by ${editorial.reviewer}, ` : "last reviewed "}${editorial.reviewed} · ${editorial.status}`
+            : `${provenance} · generated from the code`}
+        </p>
+      )}
+      {source && (
+        <p data-slot="docs-source" className="font-mono">
+          {source}
+        </p>
+      )}
+    </footer>
+  );
+}
+
+/**
+ * A titled section of a docs page, numbered in a gutter beside it (01, 02, …,
+ * counted by CSS in page order) and listed in "On this page".
+ */
+export function DocsSection({ title, lead, children }: { title: string; lead?: string; children: ReactNode }) {
+  const id = title.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+  return (
+    <section data-slot="docs-section" aria-labelledby={id} className="grid gap-x-10 gap-y-8 [counter-increment:docs-section] xl:grid-cols-[5rem_minmax(0,1fr)]">
+      <span
+        aria-hidden
+        className="font-mono text-xs tracking-[var(--tracking-widest,0.16em)] text-muted-foreground [text-box:trim-both_cap_alphabetic] before:content-[counter(docs-section,decimal-leading-zero)]"
+      />
+      <div className="flex min-w-0 flex-col gap-10">
+        <div className="flex flex-col gap-4">
+          <h2 id={id} data-slot="docs-section-title" className={cx(display, "scroll-mt-24 text-4xl leading-[1.1] tracking-tight [text-box:trim-both_cap_alphabetic] md:text-5xl")}>
+            {title}
+          </h2>
+          {lead && <p className="max-w-2xl text-lg leading-relaxed text-muted-foreground">{lead}</p>}
+        </div>
+        {children}
+      </div>
+    </section>
+  );
+}

package/src/standards.tsx

@@ -0,0 +1,58 @@
+import { Gauge, Info, Monitor, PersonStanding, Ruler } from "lucide-react";
+import type { ReactNode } from "react";
+import { standardsSections } from "./lib/standards";
+
+const ICON: Record<string, typeof Gauge> = { a11y: PersonStanding, performance: Gauge, support: Monitor };
+
+/**
+ * The project's performance budgets, accessibility target and support baseline,
+ * rendered from the thresholds it already records (`.mxa/stack.json`
+ * `baselines`), so the docs and the checks cannot disagree. A value nobody has
+ * set is left out rather than shown as `null`; a note is shown as a sentence.
+ * Thresholds a client agrees beyond the schema (`textSize`, `touchTargets`) are
+ * titled from their keys.
+ */
+export function Standards({ baselines, children }: { baselines: Record<string, unknown>; children?: ReactNode }) {
+  return (
+    <div data-slot="standards" className="flex flex-col gap-6">
+      <div className="grid gap-x-12 gap-y-10 md:grid-cols-2 xl:grid-cols-3">
+        {standardsSections(baselines).map((section) => {
+          const Icon = ICON[section.key] ?? Ruler;
+          const single = section.rows.length === 1 && !section.rows[0].label;
+          return (
+            <section key={section.key} data-slot="standard" className="flex flex-col gap-4 border-t border-border pt-5">
+              <h3 className="flex items-center gap-2 text-sm font-medium text-muted-foreground">
+                <Icon aria-hidden className="size-(--dt-size-xs)" />
+                {section.title}
+              </h3>
+              {single ? (
+                <p className="text-5xl font-light tracking-tight">{section.rows[0].value}</p>
+              ) : section.rows.length ? (
+                <dl className="flex flex-col gap-3">
+                  {section.rows.map((row) => (
+                    <div key={row.label} className="flex flex-col gap-0.5">
+                      <dt className="text-xs text-muted-foreground">{row.label}</dt>
+                      <dd className="text-2xl font-light tracking-tight tabular-nums">{row.value}</dd>
+                    </div>
+                  ))}
+                </dl>
+              ) : null}
+              {section.notes.map((note) => (
+                <p key={note} className="text-sm text-muted-foreground">
+                  {note}
+                </p>
+              ))}
+            </section>
+          );
+        })}
+      </div>
+      {typeof baselines.$note === "string" && (
+        <p className="flex items-start gap-2 text-sm text-muted-foreground">
+          <Info aria-hidden className="mt-0.5 size-(--dt-size-xs) shrink-0" />
+          {baselines.$note}
+        </p>
+      )}
+      {children}
+    </div>
+  );
+}