@designtools/docs 0.1.0 → 0.2.0

package/src/next/pages.tsx

@@ -1,5 +1,7 @@
 import { ArrowRight, ArrowUpRight } from "lucide-react";
 import Link from "next/link";
+import type { ReactNode } from "react";
+import { cx, display } from "../lib/cx";
 import { AdherenceSummary } from "../adherence-summary";
 import { Anatomy } from "../anatomy";
 import { Examples } from "../examples";
@@ -12,7 +14,7 @@ import { PageActions } from "../page-actions";
 import { Pattern } from "../pattern";
 import { PreviewFrame } from "../preview-frame";
 import { PropsTable } from "../props-table";
-import { Rule } from "../rule";
+import { Rule, RuleIndex } from "../rule";
 import { Scale } from "../scale";
 import { DocsFooter, DocsHeader, DocsSection } from "../shell";
 import { Standards } from "../standards";
@@ -39,6 +41,7 @@ const DEFAULT_BLOCKS = {
   PropsTable,
   RampSwatches,
   Rule,
+  RuleIndex,
   Scale,
   SemanticSwatches,
   Standards,
@@ -73,7 +76,7 @@ export function DocsPageView({ site, page }: { site: Site; page: PageRef }) {
       return (
         <>
           {header(page.page.title, page.page.lead)}
-          <Markdown text={page.page.body} />
+          {typeof page.page.body === "string" ? <Markdown text={page.page.body} /> : page.page.body}
           <DocsFooter editorial={page.page.by} />
         </>
       );
@@ -147,6 +150,9 @@ export function DocsPageView({ site, page }: { site: Site; page: PageRef }) {
       return (
         <>
           {header(COPY.rules.title, COPY.rules.lead)}
+          <DocsSection title="Every rule" lead="A line each: what it covers, how settled it is, and how it is checked.">
+            <B.RuleIndex rules={[...site.rules.rules].sort((a, b) => a.kind.localeCompare(b.kind))} />
+          </DocsSection>
           {(["brand", "interface"] as const).map((kind) => {
             const rules = site.rules.rules.filter((r) => r.kind === kind);
             return rules.length ? (
@@ -193,7 +199,9 @@ export function DocsPageView({ site, page }: { site: Site; page: PageRef }) {
     case "pattern":
       return (
         <>
-          {header(page.pattern.name, page.pattern.description)}
+          <DocsHeader title={page.pattern.name} lead={page.pattern.description} status={page.pattern.status}>
+            <PageActions basePath={base} />
+          </DocsHeader>
           <B.Pattern pattern={page.pattern} manifest={site.components} basePath={base} />
           <DocsFooter source={page.pattern.source} provenance={config.provenance} />
         </>
@@ -292,22 +300,128 @@ function ComponentPage({ site, blocks: B, entry }: { site: Site; blocks: Blocks;
   );
 }
 
-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. */
+/** The overview, below the hero when there is one: each part of the system and why it exists, then why it is agentic. */
 function Overview({ site }: { 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);
+  const brandPages = site.editorial.filter((p) => (p.section ?? "brand") === "brand");
+  const brandFirst = brandPages[0];
+  const products = site.taxonomy.terms.filter((t) => t.kind === "product" && t.wrong?.length);
+  const example = products[0] ?? site.taxonomy.terms.find((t) => t.wrong?.length);
+  const fills = ["--primary", "--neutral", "--success", "--warning", "--destructive"].filter((n) =>
+    site.tokens.tokens.some((t) => t.name === n),
+  );
+  const share = config.adherence?.summary.share;
+
+  // each section of the system, why it exists, how much is in it, and a glimpse of it, live from the manifest
+  const sections: { title: string; href: string; why: string; count: string; preview: ReactNode }[] = [];
+  if (brandFirst || site.shows("logo"))
+    sections.push({
+      title: "Brand",
+      href: `${base}/${brandFirst?.slug ?? "brand/logo"}`,
+      why: "What the brand believes, how it sounds and how it looks, so every screen and sentence comes from the same place.",
+      count: `${brandPages.length + (site.assets.assets.some((a) => a.kind === "logo") ? 1 : 0)} pages`,
+      preview: config.logo ? <span className="flex h-10 items-center [&_img]:h-8 [&_svg]:h-8">{config.logo}</span> : null,
+    });
+  sections.push({
+    title: "Foundations",
+    href: `${base}/colour`,
+    why: "Colour, type and the scale, generated from the tokens and measured in both modes, so nothing is a guess.",
+    count: `${site.tokens.tokens.length} tokens`,
+    preview: (
+      <span className="flex items-center gap-4">
+        <span className="flex -space-x-1.5">
+          {fills.map((n) => (
+            <span key={n} aria-hidden className="size-8 rounded-full ring-2 ring-canvas" style={{ background: `var(${n})` }} />
+          ))}
+        </span>
+        <span aria-hidden className={cx(display, "text-3xl leading-none tracking-tight")}>
+          Aa
+        </span>
+      </span>
+    ),
+  });
+  if (site.rules.rules.length)
+    sections.push({
+      title: "Rules",
+      href: `${base}/rules`,
+      why: "The lines the brand and the interface hold, each written for people, with the check that proves it.",
+      count: `${site.rules.rules.length} rules, ${site.rules.rules.filter((r) => r.status === "confirmed").length} confirmed`,
+      preview: (
+        <span className="flex flex-col gap-1.5 text-sm">
+          {site.rules.rules
+            .filter((r) => r.kind === "brand")
+            .slice(0, 2)
+            .map((r) => (
+              <span key={r.id} className="flex items-center gap-2">
+                <StatusBadge status={r.status} />
+                <span className="truncate">{r.title}</span>
+              </span>
+            ))}
+        </span>
+      ),
+    });
+  if (site.shows("components") && count)
+    sections.push({
+      title: "Components",
+      href: `${base}/components/${slugOf(families[0].families[0].head)}`,
+      why: "The real components the product is built from, each with when to use it, a live workbench and an accessibility report.",
+      count: `${count} components`,
+      preview: (
+        <span className="flex flex-wrap gap-1.5">
+          {families.slice(0, 6).map((g) => (
+            <span key={g.category} className="inline-flex min-h-7 items-center rounded-md bg-muted px-2 text-xs">
+              {g.category} <span className="ml-1.5 text-muted-foreground tabular-nums">{g.families.length}</span>
+            </span>
+          ))}
+        </span>
+      ),
+    });
+  if (site.patterns.patterns.length)
+    sections.push({
+      title: "Patterns",
+      href: `${base}/patterns/${site.patterns.patterns[0].id}`,
+      why: "The screens the product keeps making, composed of the components, so a recurring problem is solved once.",
+      count: `${site.patterns.patterns.length} patterns`,
+      preview: <span className="text-sm text-muted-foreground">{site.patterns.patterns.slice(0, 3).map((p) => p.name).join(" · ")}</span>,
+    });
+  if (site.shows("standards") && (config.baselines || config.adherence))
+    sections.push({
+      title: "Standards",
+      href: `${base}/standards`,
+      why: "The bar the product is held to, and how closely it follows the system today, reported on every change.",
+      count: share == null ? "Baselines agreed" : `${Math.round(share * 100)}% of the product on the system`,
+      preview:
+        share == null ? null : (
+          <span className="flex w-full max-w-56 items-center gap-3">
+            <span className="h-1.5 flex-1 overflow-hidden rounded-full bg-muted">
+              <span className="block h-full rounded-full bg-canvas-foreground" style={{ width: `${Math.round(share * 100)}%` }} />
+            </span>
+            <span className="text-sm tabular-nums">{Math.round(share * 100)}%</span>
+          </span>
+        ),
+    });
+  if (site.shows("vocabulary") && site.taxonomy.terms.length)
+    sections.push({
+      title: "Vocabulary",
+      href: `${base}/vocabulary`,
+      why: "One name for each thing, and the names people reach for instead, so people and agents mean the same thing.",
+      count: `${site.taxonomy.terms.length} terms`,
+      preview: example ? (
+        <span className="text-sm">
+          Say <strong className="font-semibold">{example.name}</strong>, <span className="text-muted-foreground line-through decoration-current/40">{example.wrong?.[0]}</span>
+        </span>
+      ) : null,
+    });
+
+  const loop = [
+    ["Written once", "The components, tokens and rules live in the product's own code. Nobody keeps a second copy in a slide deck or a wiki."],
+    ["Generated, never drifting", "This site is built from that code on every change, so it cannot fall out of date."],
+    ["Read by people and agents", "Every page is also plain markdown, and coding agents are pointed at the same source, so they build with the real components and rules."],
+    ["Checked", "Each rule names the check that proves it. Stale docs stop a commit; everything else is reported."],
+    ["Measured", "A report on every change shows how closely the product follows the system. It informs the conversation; it never blocks the work."],
+  ];
 
   return (
     <>
@@ -316,51 +430,50 @@ function Overview({ site }: { site: Site }) {
           <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>
+
+      <DocsSection title="What's here, and why" lead="Each part of the system has one job. Together they mean the product, its people and its agents work from the same source.">
+        <ul data-slot="overview-sections" className="grid gap-x-12 md:grid-cols-2">
+          {sections.map((sec) => (
+            <li key={sec.title} className="border-t border-border">
+              <Link href={sec.href} className="group flex h-full flex-col gap-4 py-7 focus-visible:outline-2 focus-visible:outline-ring">
+                <span className="flex items-baseline justify-between gap-4">
+                  <span className="text-2xl leading-tight tracking-tight underline-offset-[6px] group-hover:underline">{sec.title}</span>
+                  <span className="shrink-0 text-xs text-muted-foreground tabular-nums">{sec.count}</span>
+                </span>
+                <span className="max-w-md text-base leading-relaxed text-muted-foreground">{sec.why}</span>
+                {sec.preview && <span className="mt-auto flex min-h-10 items-center pt-2">{sec.preview}</span>}
+              </Link>
+            </li>
+          ))}
+        </ul>
+      </DocsSection>
+
+      {config.overview?.agentic !== false && (
+        <DocsSection
+          title="Why this is agentic"
+          lead={
+            config.overview?.agenticLead ??
+            "A design system used to be a document people were asked to follow. This one is the source the product, its people and its AI agents all work from, and it checks itself."
+          }
+        >
+          <ol data-slot="overview-loop" className="grid gap-x-6 gap-y-8 sm:grid-cols-2 xl:grid-cols-5">
+            {loop.map(([title, body], i) => (
+              <li key={title} className="relative flex flex-col gap-3 xl:pr-2">
+                <span className="flex items-center gap-3">
+                  <span className="grid size-8 shrink-0 place-items-center rounded-full bg-canvas-foreground text-sm font-medium text-canvas tabular-nums">{i + 1}</span>
+                  {i < loop.length - 1 && <span aria-hidden className="hidden h-px flex-1 bg-border xl:block" />}
+                </span>
+                <span className="text-lg leading-snug tracking-tight">{title}</span>
+                <span className="text-sm leading-relaxed text-muted-foreground">{body}</span>
+              </li>
             ))}
-          </div>
+          </ol>
+          <p className="flex flex-wrap items-center gap-x-2 gap-y-1 text-sm text-muted-foreground">
+            See it the way an agent does:
+            <a href={`${base}.md`} className="inline-flex items-center gap-1 font-medium text-canvas-foreground underline underline-offset-4 hover:decoration-2">
+              this page as markdown <ArrowUpRight aria-hidden className="size-3.5" />
+            </a>
+          </p>
         </DocsSection>
       )}
       <DocsFooter provenance={config.provenance} />

package/src/next/prose.tsx

@@ -1,8 +1,8 @@
 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
+ * The few markdown shapes editorial pages use: `##` sections, `###` headings, paragraphs and bullet
+ * lists, with bold, code and links. Each `##` is a docs section, so it reads at the same size as a generated page and is
  * listed in "On this page". A list whose every item opens in bold ("**Say it plainly.** …") is a set
  * of principles, numbered, each a heading over its sentence.
  */
@@ -31,6 +31,12 @@ function Blocks({ blocks }: { blocks: string[] }) {
   return (
     <div className="flex flex-col gap-5">
       {blocks.map((b, i) => {
+        if (b.startsWith("### "))
+          return (
+            <h3 key={i} className="mt-4 max-w-3xl text-2xl leading-snug tracking-tight first:mt-0">
+              {inline(b.slice(4))}
+            </h3>
+          );
         const lines = b.split("\n");
         if (lines.every((l) => l.startsWith("- "))) {
           const items = lines.map((l) => l.slice(2));
@@ -41,8 +47,8 @@ function Blocks({ blocks }: { blocks: string[] }) {
                 {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>
+                    <li key={l} className="grid grid-cols-[3rem_minmax(0,1fr)] items-baseline gap-x-4 gap-y-3 sm:grid-cols-[4rem_minmax(0,1fr)]">
+                      <span className="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>
@@ -71,8 +77,12 @@ function Blocks({ blocks }: { blocks: string[] }) {
 }
 
 function inline(text: string) {
-  return text.split(/(\*\*[^*]+\*\*|`[^`]+`)/).map((part, i) =>
-    part.startsWith("**") ? (
+  return text.split(/(\*\*[^*]+\*\*|`[^`]+`|\[[^\]]+\]\([^)\s]+\))/).map((part, i) =>
+    part.startsWith("[") ? (
+      <a key={i} href={/\(([^)]+)\)$/.exec(part)?.[1]} className="underline decoration-from-font underline-offset-4 hover:decoration-2">
+        {/^\[([^\]]+)\]/.exec(part)?.[1]}
+      </a>
+    ) : part.startsWith("**") ? (
       <strong key={i} className="font-semibold">
         {part.slice(2, -2)}
       </strong>

package/src/pattern.tsx

@@ -1,14 +1,17 @@
 "use client";
 
-import { ArrowUpRight } from "lucide-react";
 import Link from "next/link";
 import { ExampleFrame } from "./examples";
 import { Missing, renderExample, useLookup } from "./lib/lookup";
 import { slugOf } from "./lib/manifest";
 import type { ComponentsManifest, PatternEntry } from "./lib/manifest-types";
 import { StatusBadge } from "./lib/status";
+import { DocsSection } from "./shell";
 
-/** A recurring screen composition: what it is made of, then each composition live in its frame, with its code. */
+/**
+ * A recurring screen composition: each composition live in its frame, with its code, then the
+ * components it is made of, each linking to its page. Its status sits in the page header.
+ */
 export function Pattern({
   pattern,
   manifest,
@@ -23,45 +26,47 @@ export function Pattern({
   const module = lookup.compositionsFor(pattern);
   const known = new Map((manifest?.components ?? []).map((c) => [c.name, c]));
   return (
-    <div data-slot="pattern" className="flex flex-col gap-10">
-      <div className="flex flex-col gap-3 rounded-xl border border-border bg-surface p-4 text-surface-foreground sm:flex-row sm:items-center sm:gap-6">
-        <span className="flex items-center gap-2">
-          <span className="text-xs font-medium text-muted-foreground">Status</span>
-          <StatusBadge status={pattern.status} />
-        </span>
-        {pattern.components.length > 0 && (
-          <span className="flex flex-wrap items-center gap-2">
-            <span className="text-xs font-medium text-muted-foreground">Made of</span>
+    <>
+      <div data-slot="pattern" className="flex flex-col gap-10">
+        {!module ? (
+          <Missing name={pattern.name} what="compositions" />
+        ) : (
+          pattern.examples.map((ex, i) => (
+            <ExampleFrame key={ex.name} name={ex.name} kind={i === 0 ? "canonical" : "other"} description={ex.description} code={ex.code}>
+              {renderExample(module[ex.name], ex.name)}
+            </ExampleFrame>
+          ))
+        )}
+      </div>
+      {pattern.components.length > 0 && (
+        <DocsSection title="Made of" lead="The system's own components, so the pattern changes when they do.">
+          <ul data-slot="pattern-parts" className="grid gap-x-10 sm:grid-cols-2">
             {pattern.components.map((name) => {
               const c = known.get(name);
-              const chip = "inline-flex min-h-8 items-center gap-1 rounded-full border border-border px-3 text-xs font-medium";
-              return c ? (
-                <Link
-                  key={name}
-                  href={`${basePath}/components/${slugOf(c)}`}
-                  className={`${chip} relative hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring after:absolute after:-inset-y-1.5 after:inset-x-0 after:content-['']`}
-                >
-                  {name}
-                  <ArrowUpRight aria-hidden className="size-3.5 text-muted-foreground" />
-                </Link>
-              ) : (
-                <span key={name} className={chip}>
-                  {name}
-                </span>
+              const body = (
+                <>
+                  <span className="flex items-center justify-between gap-3">
+                    <span className="text-lg tracking-tight underline-offset-4 group-hover:underline">{name}</span>
+                    {c && <StatusBadge status={c.status} />}
+                  </span>
+                  {c?.description && <span className="line-clamp-2 text-sm text-muted-foreground">{c.description}</span>}
+                </>
+              );
+              return (
+                <li key={name} className="border-t border-border">
+                  {c ? (
+                    <Link href={`${basePath}/components/${slugOf(c)}`} className="group flex flex-col gap-1.5 py-4 focus-visible:outline-2 focus-visible:outline-ring">
+                      {body}
+                    </Link>
+                  ) : (
+                    <span className="flex flex-col gap-1.5 py-4">{body}</span>
+                  )}
+                </li>
               );
             })}
-          </span>
-        )}
-      </div>
-      {!module ? (
-        <Missing name={pattern.name} what="compositions" />
-      ) : (
-        pattern.examples.map((ex, i) => (
-          <ExampleFrame key={ex.name} name={ex.name} kind={i === 0 ? "canonical" : "other"} description={ex.description} code={ex.code}>
-            {renderExample(module[ex.name], ex.name)}
-          </ExampleFrame>
-        ))
+          </ul>
+        </DocsSection>
       )}
-    </div>
+    </>
   );
 }

package/src/playground.tsx

@@ -137,6 +137,8 @@ export function Label({ id, name, info, htmlFor }: { id?: string; name: string;
       )}
       <Tooltip.Root>
         <Tooltip.Trigger
+          delay={0}
+          closeDelay={0}
           aria-label={`About ${title(name)}`}
           className="relative inline-flex size-6 cursor-pointer items-center justify-center rounded-full text-muted-foreground hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring after:absolute after:-inset-2.5 after:content-['']"
         >
@@ -144,8 +146,11 @@ export function Label({ id, name, info, htmlFor }: { id?: string; name: string;
         </Tooltip.Trigger>
         <Tooltip.Portal>
           <Tooltip.Positioner data-designtools="" side="left" sideOffset={8} className="z-50">
-            <Tooltip.Popup className="flex max-w-64 flex-col gap-1.5 rounded-lg border border-border bg-overlay px-3 py-2.5 text-xs text-overlay-foreground shadow-md transition-opacity data-ending-style:opacity-0 data-starting-style:opacity-0">
-              <code className="font-mono font-medium">{name}</code>
+            <Tooltip.Popup
+              data-slot="docs-tooltip"
+              className="flex max-w-64 flex-col gap-1 rounded-md bg-canvas-foreground px-2.5 py-2 text-xs leading-snug text-canvas shadow-md transition-opacity duration-(--dt-duration-fast) data-ending-style:opacity-0 data-starting-style:opacity-0 [&_*]:text-canvas/80"
+            >
+              <code className="font-mono font-medium text-canvas!">{name}</code>
               {info}
             </Tooltip.Popup>
           </Tooltip.Positioner>