@designtools/blocks 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @designtools/blocks
 
+## 0.2.0
+
+### Minor Changes
+
+- 3da728f: From the first end-to-end run:
+  
+  - Component markdown imports through the alias the manifest found (`@ds/button/button`), so the line an agent copies resolves; `importOf` gives the same specifier to the blocks.
+  - `componentMarkdown` and `patternMarkdown` take a heading level: `1` for a page of its own, so it no longer opens with the same heading twice. Do and don't examples come out in pairs, as the page shows them.
+  - Every pressable thing in the blocks is at least 44 × 44 CSS px, and a project sets `--docs-target` for its own rule (`3rem` for 48px).
+  - A component's parts fold under it in the navigation (`groupFamilies`), instead of each taking a line.
+  - The standards block titles its sections and rows, shows notes as sentences, leaves out values nobody has set, and titles thresholds beyond the schema from their keys; its markdown matches.
+  - The logo's minimum-size sample is painted on the logo's own surface, so a reversed logo is visible.
+  - The demo's docs app ships in `reference/`: `proxy.ts`, the data module, the markdown, manifest and preview routes, and every page.
+  - `add` defaults to `app/(design)/design/system/_blocks`, beside the docs in the `(design)` route group, unless the docs are already in `app/design/system`.
+  - `search` (and the shell, by default): find a component, part, rule, pattern or page by name, fuzzily, or by a wrong name from the taxonomy, on ⌘K, Ctrl+K or `/`. Base UI's Autocomplete in a Dialog, ranked by `fuzzysort`; the manifest is the index. Pass `terms` to the shell for the wrong names.
+  - The shell takes the client's `logo`. Editorial headers take a `reviewer` as well as an author.
+  - Accessibility, from the second run: scrolling tables and code are keyboard-reachable regions; no text below `text-xs` (the props table's "required" and the ramp labels were 10px); do and don't labels and a failing contrast grade use measured subdued pairs, not fill colours as text; rule anchors and "instead" links meet the target size.
+  - The logo page paints surfaces in their light-mode colours whatever the docs' mode, lists rules for every logo once above them, and drops the faded surface label.
+  - `reference/` gates the docs in production in every format (the `(design)` layout and `proxy.ts`), shows parts on their component's overview tile, puts the logo in the shell, and pins its packages exactly.
+  - `PageContrast` in the swatches block: each colour on each background (canvas, surface, overlay and every named `--surface-*`), per mode, measured on what the browser paints and marked as fine for text, as a shape, or neither.
+  - The status badge shows `measured` (a rule generated from the tokens) apart from confirmed and assumed ones.
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -17,14 +17,14 @@ The blocks expect a Next app on the suite stack: React, Tailwind v4 over tokens
 ```json
 {
   "manifest": { "system": "src/ds", "tokens": ["app/styles/tokens.css", "app/styles/scale.css"] },
-  "blocks": { "dir": "app/design/system/_blocks" }
+  "blocks": { "dir": "app/(design)/design/system/_blocks" }
 }
 ```
 
-`add` records `blocks.dir` the first time if you have not, defaulting to `app/design/system/_blocks` (or under `src/app` when the project has one). The leading underscore keeps the folder out of Next's routing.
+`add` records `blocks.dir` the first time if you have not, defaulting to `app/(design)/design/system/_blocks`, beside the docs in the `(design)` route group (or under `src/app` when the project has one; `app/design/system/_blocks` when the docs already live outside the group). The leading underscore keeps the folder out of Next's routing.
 
 1. `designtools-manifest build` writes `components.json` and `tokens.json`.
-2. `designtools-blocks add <block…>` copies the blocks, the shared files they import, and nothing else. It says which packages they need that the project lacks: `@base-ui/react` for the shell and playground, `shiki` for the code view, `axe-core` for the accessibility panel.
+2. `designtools-blocks add <block…>` copies the blocks, the shared files they import, and nothing else. It says which packages they need that the project lacks: `@base-ui/react` for the shell, search and playground, `fuzzysort` (MIT) for search, `shiki` (MIT) for the code view, `axe-core` for the accessibility panel. Pin them exactly. `axe-core` is MPL-2.0: check it against the project's licence list before adding `a11y-panel`, and leave the panel out if the list will not take it; nothing else needs it.
 3. `designtools-blocks map` writes `registry.generated.tsx`: every component, examples module, pattern and brand asset in the manifest, imported by path. Run it after each manifest build; `map --check` exits 1 when it is stale, for a pre-commit hook.
 
 Blocks that render components are client components, and a server page cannot pass a component to one. So a page passes the manifest entry, which is plain data, and the block finds the component in the generated map.
@@ -60,17 +60,18 @@ export default async function Page({ params }: { params: Promise<{ slug: string
 }
 ```
 
-`readComponents` and `readTokens` type a JSON import and check its schema version. [`examples/demo`](../../examples/demo) has the full site: brand, logo, imagery, voice, colour, type, scale, rules, a pattern, a component page using every component block, standards and vocabulary, the preview route, and the markdown route.
+`readComponents` and `readTokens` type a JSON import and check its schema version. The full site ships with the package, in `reference/` (`node_modules/@designtools/blocks/reference/`): brand, logo, imagery, voice, colour, type, scale, rules, a pattern, a component page using every component block, standards and vocabulary, the preview route, the markdown and manifest routes, and `proxy.ts`. It is a copy of the designtools repo's `examples/demo`, taken at build, so it matches this version of the blocks. Read it; do not import from it.
 
 ## Blocks
 
 | Block | Shows | Reads |
 | --- | --- | --- |
-| `shell` | `DocsShell`: navigation in the site's order (brand, foundations, rules, patterns, components by `@category`, standards). `DocsHeader` with the provenance of a generated page or the author and review date of an editorial one. `DocsSection` | `components.json`, `rules.json`, `patterns.json` |
-| `logo-usage` | Each logo on its surfaces, at minimum size, with clear space drawn and its brand rules | `assets.json`, `rules.json`, the map |
+| `shell` | `DocsShell`: the client's `logo` and title, search, and navigation in the site's order (brand, foundations, rules, patterns, components by `@category` with their parts folded under them, standards). `DocsHeader` with the provenance of a generated page, or the author, reviewer and review date of an editorial one. `DocsSection` | `components.json`, `rules.json`, `patterns.json`, `taxonomy.json` |
+| `search` | `DocsSearch`: find a component, part, rule, pattern or page by name, fuzzily (`buton` finds Button), or by a wrong name from the taxonomy (`dropdown` finds Select, and says so). ⌘K, Ctrl+K or `/` opens it; arrows and Enter go. Navigation only, not page text: the manifest is the index, so there is nothing to build. The shell includes it; `search={false}` leaves it out | the same, through `searchIndex` in `lib/search` |
+| `logo-usage` | Each logo on its surfaces, at minimum size, with clear space drawn. Surfaces are painted in their light-mode colours whatever the docs' mode, because a brand book's surfaces are fixed. Rules for every logo once, above them; a rule naming one logo, under it | `assets.json`, `rules.json`, the map |
 | `imagery` | The approved icons and imagery with their usage notes | `assets.json`, the map |
 | `voice-terms` | Preferred terms beside their wrong forms | `taxonomy.json` |
-| `swatches` | Each semantic colour in light and dark side by side, contrast measured on the painted colours; the ramps | `tokens.json` |
+| `swatches` | Each semantic colour in light and dark side by side, contrast measured on the painted colours; every colour on every background (`PageContrast`); the ramps | `tokens.json` |
 | `type-ramp` | Each `--text-*` size with its leading and tracking, then families, weights, leading, tracking | `tokens.json` |
 | `scale` | Spacing, size, radius, shadow, duration and easing, drawn the way each is used | `tokens.json` |
 | `rule` | A rule for people, and as an agent reads it, with its check and a slot for a demonstration | `rules.json` |
@@ -89,11 +90,14 @@ export default async function Page({ params }: { params: Promise<{ slug: string
 | `ask-claude` | Copies a prompt naming the component, its file, the variant and the example | an entry |
 | `agent-view` | Any block's markdown form, copyable, in a tab beside the rendered one | an entry, or markdown |
 
+
+Every pressable thing in the blocks (navigation, tabs, buttons, summaries, the playground's controls) is at least 44 by 44 CSS pixels, WCAG 2.5.5's size. A client whose own rule is larger sets `--docs-target` on the docs layout (`style={{ "--docs-target": "3rem" }}` for 48px), so the site that states the rule meets it. A component's parts (`CardHeader`, `CardTitle`) are folded under it in the navigation and open when you are on one of them.
+
 ## Markdown
 
-`lib/markdown.ts` holds the markdown form of every block, generated from the manifest rather than converted from HTML: `componentMarkdown`, `coloursMarkdown`, `typeMarkdown`, `scaleMarkdown`, `ruleMarkdown`, `patternMarkdown`, `glossaryMarkdown`, `assetsMarkdown`, `standardsMarkdown`, and `systemMarkdown` for everything in one file. Structure survives as typed fences (```` ```rule ````, ```` ```example ````, ```` ```do ````, ```` ```dont ````), and status travels with everything. `generatedHeader` opens a generated page with its version and commit; `editorialHeader` opens a written one with its author and review date.
+`lib/markdown.ts` holds the markdown form of every block, generated from the manifest rather than converted from HTML: `componentMarkdown`, `coloursMarkdown`, `typeMarkdown`, `scaleMarkdown`, `ruleMarkdown`, `patternMarkdown`, `glossaryMarkdown`, `assetsMarkdown`, `standardsMarkdown`, and `systemMarkdown` for everything in one file. Structure survives as typed fences (```` ```rule ````, ```` ```example ````, ```` ```do ````, ```` ```dont ````), and status travels with everything. `generatedHeader` opens a generated page with its version and commit; `editorialHeader` opens a written one with its author and review date. Pass `1` as the second argument to `componentMarkdown` or `patternMarkdown` when it is the whole page, so the page has one heading; inside `systemMarkdown` they sit at level 2. Do and don't examples come out in pairs, as the page shows them, and the import line uses the alias the manifest found (`@ds/button/button`).
 
-Serving it is per-app wiring, so it is not packaged: the demo's `proxy.ts` answers `Accept: text/markdown` and `.md` with these, sets `Vary: Accept` and the canonical `Link`, and returns a markdown 404 for a page that does not exist.
+Serving it is per-app wiring, so it is copied rather than imported: `reference/proxy.ts` answers `Accept: text/markdown` and `.md` with these, sets `Vary: Accept` and the canonical `Link`, and returns a markdown 404 for a page that does not exist.
 
 ## Styling
 

package/dist/cli.js

@@ -13,6 +13,7 @@ var REGISTRY_DIR = join(dirname(fileURLToPath(import.meta.url)), "../registry");
 var GENERATED = "registry.generated.tsx";
 var BLOCKS = [
   { name: "shell", file: "shell.tsx", description: "Docs frame: brand, foundations, rules, patterns, components, standards; page header and sections" },
+  { name: "search", file: "search.tsx", description: "Fuzzy search over components, parts, rules, patterns and pages, wrong names included; \u2318K, Ctrl+K or /" },
   { name: "logo-usage", file: "logo-usage.tsx", description: "Each logo on its surfaces, at minimum size, with clear space and its brand rules" },
   { name: "imagery", file: "imagery.tsx", description: "The approved icons and imagery with their usage notes" },
   { name: "voice-terms", file: "voice-terms.tsx", description: "Preferred terms beside their wrong forms" },
@@ -142,7 +143,8 @@ Usage
 
 Options
   --dir <dir>          Where blocks live (default: blocks.dir in designtools.json,
-                       else app/design/system/_blocks, or src/app/\u2026 when src/app exists)
+                       else app/(design)/design/system/_blocks, or src/app/\u2026 when
+                       src/app exists; app/design/system/_blocks if the docs are there)
   --manifest <file>    components.json (default: from manifest.system in designtools.json)
   --root <dir>         Project root (default: the current directory)
   --force              add: overwrite files that already exist
@@ -206,7 +208,9 @@ function readConfig() {
 function blocksDir(config) {
   if (values.dir) return values.dir;
   if (config.blocks?.dir) return config.blocks.dir;
-  return existsSync2(join2(root, "src/app")) ? "src/app/design/system/_blocks" : "app/design/system/_blocks";
+  const app = existsSync2(join2(root, "src/app")) ? "src/app" : "app";
+  if (existsSync2(join2(root, app, "design/system")) && !existsSync2(join2(root, app, "(design)"))) return `${app}/design/system/_blocks`;
+  return `${app}/(design)/design/system/_blocks`;
 }
 function manifestPath(config) {
   if (values.manifest) return values.manifest;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@designtools/blocks",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Unstyled, accessible React blocks for design system docs, copied into your repo: swatches, type ramp, scale, variant matrix, state grid, props table, anatomy, playground, code view, accessibility panel, preview frame. Each reads the @designtools/manifest JSON and renders your real components.",
   "type": "module",
   "license": "MIT",
@@ -20,6 +20,7 @@
   "files": [
     "dist",
     "registry",
+    "reference",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -44,6 +45,7 @@
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "axe-core": "^4.14.0",
+    "fuzzysort": "4.0.2",
     "next": "16.3.0",
     "react": "19.2.7",
     "react-dom": "19.2.7",
@@ -54,7 +56,7 @@
     "vitest": "^4.1.11"
   },
   "scripts": {
-    "build": "tsup src/cli.ts --format esm --clean",
+    "build": "node scripts/reference.mjs && tsup src/cli.ts --format esm --clean",
     "typecheck": "tsc --noEmit && tsc --noEmit -p registry",
     "test": "vitest run",
     "cli": "tsx src/cli.ts"

package/reference/README.md

@@ -0,0 +1,20 @@
+# Reference: a docs site wired end to end
+
+A copy of `examples/demo` in the designtools repo, taken when this version of
+`@designtools/blocks` was built: everything a project writes per app, around the
+blocks it copies. Read it; do not import from it.
+
+| File | What it shows |
+| --- | --- |
+| `proxy.ts` | Markdown on `Accept: text/markdown` or `.md`, `Vary: Accept`, the alternate `Link`, and a 404 for every docs URL on production, route handlers included |
+| `app/(design)/layout.tsx` | The 404 and `noindex` for every design page on production |
+| `app/(design)/design/system/_data.ts` | One data module that the pages and the markdown route both read |
+| `app/(design)/design/system/md/[[...path]]/route.ts` | Every page as markdown, with the canonical `Link` and a markdown 404 |
+| `app/(design)/design/system/manifest/[file]/route.ts` | The manifest served as JSON |
+| `app/(design)/design/system/preview/[slug]/[example]/page.tsx` | One example alone, for the preview frame and visual regression |
+| `app/(design)/design/system/(docs)/` | The pages, composing the blocks: brand, foundations, rules, patterns, components, standards, vocabulary |
+| `package.json`, `designtools.json`, `app/globals.css` | The setup scripts, the config, and the `@source` line Tailwind needs for the blocks |
+
+Paths match a project that keeps its system in `src/ds` and its docs in the
+`(design)` route group. Blocks are imported relatively from `_blocks`, where
+`designtools-blocks add` puts them.

package/reference/app/(design)/design/system/(docs)/brand/imagery/page.tsx

@@ -0,0 +1,15 @@
+import { CopyPage } from "../../../_components/copy-page";
+import { Imagery } from "../../../_blocks/imagery";
+import { DocsHeader } from "../../../_blocks/shell";
+import { assets, provenance } from "../../../_data";
+
+export default function ImageryPage() {
+  return (
+    <>
+      <DocsHeader title="Imagery and icons" lead="The approved icons and imagery, and how to use each." provenance={provenance}>
+        <CopyPage />
+      </DocsHeader>
+      <Imagery assets={assets.assets} />
+    </>
+  );
+}

package/reference/app/(design)/design/system/(docs)/brand/logo/page.tsx

@@ -0,0 +1,15 @@
+import { CopyPage } from "../../../_components/copy-page";
+import { LogoUsage } from "../../../_blocks/logo-usage";
+import { DocsHeader } from "../../../_blocks/shell";
+import { assets, BASE, provenance, rules } from "../../../_data";
+
+export default function Logo() {
+  return (
+    <>
+      <DocsHeader title="Logo" lead="Each logo on the surfaces it may sit on, at its smallest, with its clear space." provenance={provenance}>
+        <CopyPage />
+      </DocsHeader>
+      <LogoUsage assets={assets.assets} rules={rules.rules} rulesHref={`${BASE}/rules`} />
+    </>
+  );
+}

package/reference/app/(design)/design/system/(docs)/brand/page.tsx

@@ -0,0 +1,16 @@
+import { CopyPage } from "../../_components/copy-page";
+import { Markdown } from "../../_components/prose";
+import { DocsHeader } from "../../_blocks/shell";
+import { editorial } from "../../_data";
+
+export default function Brand() {
+  const page = editorial.brand;
+  return (
+    <>
+      <DocsHeader title={page.title} lead={page.lead} editorial={page.by}>
+        <CopyPage />
+      </DocsHeader>
+      <Markdown text={page.body} />
+    </>
+  );
+}

package/reference/app/(design)/design/system/(docs)/brand/voice/page.tsx

@@ -0,0 +1,15 @@
+import { CopyPage } from "../../../_components/copy-page";
+import { DocsHeader } from "../../../_blocks/shell";
+import { VoiceTerms } from "../../../_blocks/voice-terms";
+import { provenance, taxonomy } from "../../../_data";
+
+export default function Voice() {
+  return (
+    <>
+      <DocsHeader title="Voice and terms" lead="The words we use, beside the ones we do not." provenance={provenance}>
+        <CopyPage />
+      </DocsHeader>
+      <VoiceTerms terms={taxonomy.terms} />
+    </>
+  );
+}

package/reference/app/(design)/design/system/(docs)/colour/page.tsx

@@ -0,0 +1,26 @@
+import { CopyPage } from "../../_components/copy-page";
+import { DocsHeader, DocsSection } from "../../_blocks/shell";
+import { PageContrast, RampSwatches, SemanticSwatches } from "../../_blocks/swatches";
+import { provenance, tokens } from "../../_data";
+
+export default function Colour() {
+  return (
+    <>
+      <DocsHeader title="Colour" lead="Generated from one brand colour by @designtools/tokens. Write the semantic names in components; the ramps are what they point at." provenance={provenance}>
+        <CopyPage />
+      </DocsHeader>
+      <DocsSection title="Semantic colours" lead="Each pair is measured on the colours the browser paints, in each mode.">
+        <SemanticSwatches tokens={tokens} />
+      </DocsSection>
+      <DocsSection
+        title="On the page"
+        lead="Each colour on each background. A label is measured on its own fill above; this is the rest: a colour used as text on the page needs 4.5:1, as a shape (a meter fill, an icon without words) 3:1."
+      >
+        <PageContrast tokens={tokens} />
+      </DocsSection>
+            <DocsSection title="Ramps">
+        <RampSwatches tokens={tokens} />
+      </DocsSection>
+    </>
+  );
+}

package/reference/app/(design)/design/system/(docs)/components/[slug]/page.tsx

@@ -0,0 +1,86 @@
+import { notFound } from "next/navigation";
+import { CopyPage } from "../../../_components/copy-page";
+import { A11yPanel } from "../../../_blocks/a11y-panel";
+import { AgentView } from "../../../_blocks/agent-view";
+import { Anatomy } from "../../../_blocks/anatomy";
+import { AskClaude } from "../../../_blocks/ask-claude";
+import { Examples } from "../../../_blocks/examples";
+import { Playground } from "../../../_blocks/playground";
+import { PreviewFrame } from "../../../_blocks/preview-frame";
+import { PropsTable } from "../../../_blocks/props-table";
+import { DocsHeader, DocsSection } from "../../../_blocks/shell";
+import { Usage } from "../../../_blocks/usage";
+import { VariantMatrix } from "../../../_blocks/variant-matrix";
+import { findBySlug, slugOf } from "../../../_blocks/lib/manifest";
+import { BASE, components, provenance } from "../../../_data";
+
+/** What a component needs to render at all. The rest comes from the controls. */
+const needs: Record<string, { props?: Record<string, unknown>; children?: string }> = {
+  Select: {
+    props: { label: "Project", value: "beacon", options: [{ value: "atlas", label: "Atlas" }, { value: "beacon", label: "Beacon" }] },
+    children: "",
+  },
+  Switch: { props: { "aria-label": "Notifications" }, children: "" },
+  Alert: { props: { title: "Timesheets close on Friday" } },
+};
+
+export function generateStaticParams() {
+  return components.components.map((c) => ({ slug: slugOf(c) }));
+}
+
+export default async function ComponentPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const entry = findBySlug(components, slug);
+  if (!entry) notFound();
+  const need = needs[entry.name] ?? {};
+  const preview = `${BASE}/preview/${slug}`;
+  const first = entry.examples?.canonical?.name;
+
+  return (
+    <>
+      <DocsHeader title={entry.name} lead={entry.description} source={entry.source} provenance={provenance}>
+        <CopyPage />
+      </DocsHeader>
+
+      <DocsSection title="Usage">
+        <Usage entry={entry} manifest={components} basePath={BASE} />
+      </DocsSection>
+
+      <DocsSection title="Examples" lead="Each is the real component. Copy the first one.">
+        <A11yPanel entry={entry}>
+          <Examples entry={entry} previewHref={preview} />
+        </A11yPanel>
+      </DocsSection>
+
+      <DocsSection title="Playground">
+        <AgentView entry={entry}>
+          <Playground entry={entry} props={need.props} children={need.children} />
+        </AgentView>
+      </DocsSection>
+
+      {!!entry.variants?.axes.length && (
+        <DocsSection title="Variants" lead={`From the ${entry.variants.from === "props" ? "props' types" : `${entry.variants.from}() config`}.`}>
+          <VariantMatrix entry={entry} props={need.props}>
+            {need.children === "" ? undefined : entry.name}
+          </VariantMatrix>
+        </DocsSection>
+      )}
+
+      {first && (
+        <DocsSection title="At each width">
+          <PreviewFrame src={`${preview}/${first}`} title={`${entry.name}: ${first}`} />
+        </DocsSection>
+      )}
+
+      <DocsSection title="Anatomy">
+        <Anatomy entry={entry} />
+      </DocsSection>
+
+      <DocsSection title="Props">
+        <PropsTable entry={entry} />
+      </DocsSection>
+
+      <AskClaude entry={entry} />
+    </>
+  );
+}

package/reference/app/(design)/design/system/(docs)/layout.tsx

@@ -0,0 +1,35 @@
+import type { ReactNode } from "react";
+import wordmark from "@ds/brand/logos/wordmark.svg";
+import { DocsShell } from "../_blocks/shell";
+import { BASE, components, patterns, rules, taxonomy, TITLE } from "../_data";
+
+export default function DocsLayout({ children }: { children: ReactNode }) {
+  return (
+    <DocsShell
+      manifest={components}
+      rules={rules}
+      patterns={patterns}
+      terms={taxonomy}
+      title={TITLE}
+      logo={<img src={wordmark.src} alt="" className="h-6 w-auto" />}
+      basePath={BASE}
+      brand={[
+        { label: "Principles and language", href: `${BASE}/brand` },
+        { label: "Logo", href: `${BASE}/brand/logo` },
+        { label: "Imagery and icons", href: `${BASE}/brand/imagery` },
+        { label: "Voice and terms", href: `${BASE}/brand/voice` },
+      ]}
+      foundations={[
+        { label: "Colour", href: `${BASE}/colour` },
+        { label: "Type", href: `${BASE}/type` },
+        { label: "Scale", href: `${BASE}/scale` },
+      ]}
+      standards={[
+        { label: "Standards", href: `${BASE}/standards` },
+        { label: "Vocabulary", href: `${BASE}/vocabulary` },
+      ]}
+    >
+      {children}
+    </DocsShell>
+  );
+}

package/reference/app/(design)/design/system/(docs)/page.tsx

@@ -0,0 +1,48 @@
+import Link from "next/link";
+import { CopyPage } from "../_components/copy-page";
+import { DocsHeader, DocsSection } from "../_blocks/shell";
+import { groupFamilies, slugOf } from "../_blocks/lib/manifest";
+import { StatusBadge } from "../_blocks/lib/status";
+import { BASE, components, provenance, TITLE } from "../_data";
+
+export default function Overview() {
+  return (
+    <>
+      <DocsHeader
+        title={TITLE}
+        lead="The brand and the design system in one place, for the people who make the product and the agents that build it with them. Every page is built from the code."
+        provenance={provenance}
+      >
+        <p className="text-sm">
+          For agents: <a href={`${BASE}.md`} className="underline underline-offset-2">this site as markdown</a>, the whole
+          system in <a href={`${BASE}/md/context`} className="underline underline-offset-2">one file</a>, or the{" "}
+          <a href={`${BASE}/manifest/components.json`} className="underline underline-offset-2">manifest as data</a>. Add{" "}
+          <code className="font-mono text-xs">.md</code> to any page.
+        </p>
+        <CopyPage />
+      </DocsHeader>
+      {/* a component's parts (CardHeader, CardTitle) are named on its tile, not given tiles of their own */}
+      {groupFamilies(components).map((group) => (
+        <DocsSection key={group.category} title={group.category}>
+          <ul className="grid gap-3 sm:grid-cols-2">
+            {group.families.map(({ head: c, parts }) => (
+              <li key={c.source + c.export}>
+                <Link
+                  href={`${BASE}/components/${slugOf(c)}`}
+                  className="flex h-full flex-col gap-2 rounded-lg border border-border p-4 hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring"
+                >
+                  <span className="flex items-center justify-between gap-2">
+                    <span className="font-medium">{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="font-mono text-xs text-muted-foreground">with {parts.map((p) => p.name).join(", ")}</span>}
+                </Link>
+              </li>
+            ))}
+          </ul>
+        </DocsSection>
+      ))}
+    </>
+  );
+}

package/reference/app/(design)/design/system/(docs)/patterns/[id]/page.tsx

@@ -0,0 +1,23 @@
+import { notFound } from "next/navigation";
+import { CopyPage } from "../../../_components/copy-page";
+import { Pattern } from "../../../_blocks/pattern";
+import { DocsHeader } from "../../../_blocks/shell";
+import { BASE, components, patterns, provenance } from "../../../_data";
+
+export function generateStaticParams() {
+  return patterns.patterns.map((p) => ({ id: p.id }));
+}
+
+export default async function PatternPage({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+  const pattern = patterns.patterns.find((p) => p.id === id);
+  if (!pattern) notFound();
+  return (
+    <>
+      <DocsHeader title={pattern.name} lead={pattern.description} source={pattern.source} provenance={provenance}>
+        <CopyPage />
+      </DocsHeader>
+      <Pattern pattern={pattern} manifest={components} basePath={BASE} />
+    </>
+  );
+}

package/reference/app/(design)/design/system/(docs)/rules/page.tsx

@@ -0,0 +1,42 @@
+import { CopyPage } from "../../_components/copy-page";
+import { Rule } from "../../_blocks/rule";
+import { DocsHeader, DocsSection } from "../../_blocks/shell";
+import { provenance, rules } from "../../_data";
+
+/** A demonstration for the rule that needs persuading: the same control, too small and big enough. */
+function TouchTargets() {
+  return (
+    <div className="flex flex-wrap items-end gap-8 rounded-lg bg-muted p-6">
+      {[32, 48].map((size) => (
+        <figure key={size} className="flex flex-col items-center gap-2">
+          <span className="flex items-center justify-center border border-dashed border-destructive" style={{ width: size, height: size }}>
+            <span className="size-4 rounded-full bg-primary" />
+          </span>
+          <figcaption className="text-xs text-muted-foreground">
+            {size} px {size < 48 ? "is missed" : "is hit"}
+          </figcaption>
+        </figure>
+      ))}
+    </div>
+  );
+}
+
+export default function Rules() {
+  const groups = (["brand", "interface"] as const).map((kind) => ({ kind, rules: rules.rules.filter((r) => r.kind === kind) }));
+  return (
+    <>
+      <DocsHeader title="Rules" lead="Brand and interface rules in one format, each with the check that proves it. Written for people; agents read the same rule." provenance={provenance}>
+        <CopyPage />
+      </DocsHeader>
+      {groups.map((g) => (
+        <DocsSection key={g.kind} title={g.kind === "brand" ? "Brand" : "Interface"}>
+          {g.rules.map((r) => (
+            <Rule key={r.id} rule={r}>
+              {r.id === "touch-target" ? <TouchTargets /> : null}
+            </Rule>
+          ))}
+        </DocsSection>
+      ))}
+    </>
+  );
+}

package/reference/app/(design)/design/system/(docs)/scale/page.tsx

@@ -0,0 +1,15 @@
+import { CopyPage } from "../../_components/copy-page";
+import { Scale } from "../../_blocks/scale";
+import { DocsHeader } from "../../_blocks/shell";
+import { provenance, tokens } from "../../_data";
+
+export default function ScalePage() {
+  return (
+    <>
+      <DocsHeader title="Scale" lead="Space, size, radius, elevation and motion. Hover a motion row to play it." provenance={provenance}>
+        <CopyPage />
+      </DocsHeader>
+      <Scale tokens={tokens} />
+    </>
+  );
+}

package/reference/app/(design)/design/system/(docs)/standards/page.tsx

@@ -0,0 +1,21 @@
+import { CopyPage } from "../../_components/copy-page";
+import { DocsHeader, DocsSection } from "../../_blocks/shell";
+import { AdherenceSummary } from "../../_blocks/adherence-summary";
+import { Standards } from "../../_blocks/standards";
+import { adherence, baselines, provenance } from "../../_data";
+
+export default function StandardsPage() {
+  return (
+    <>
+      <DocsHeader title="Standards" lead="The budgets and targets the project holds itself to, read from .mxa/stack.json, where the checks read them too." provenance={provenance}>
+        <CopyPage />
+      </DocsHeader>
+      <DocsSection title="Targets">
+        <Standards baselines={baselines} />
+      </DocsSection>
+      <DocsSection title="Adherence" lead="How closely the product follows the system, from @designtools/adherence. It informs; it never blocks.">
+        <AdherenceSummary report={adherence} />
+      </DocsSection>
+    </>
+  );
+}

package/reference/app/(design)/design/system/(docs)/type/page.tsx

@@ -0,0 +1,15 @@
+import { CopyPage } from "../../_components/copy-page";
+import { DocsHeader } from "../../_blocks/shell";
+import { TypeRamp } from "../../_blocks/type-ramp";
+import { provenance, tokens } from "../../_data";
+
+export default function Type() {
+  return (
+    <>
+      <DocsHeader title="Type" lead="A size is never set without its leading." provenance={provenance}>
+        <CopyPage />
+      </DocsHeader>
+      <TypeRamp tokens={tokens} />
+    </>
+  );
+}

package/reference/app/(design)/design/system/(docs)/vocabulary/page.tsx

@@ -0,0 +1,15 @@
+import { CopyPage } from "../../_components/copy-page";
+import { Glossary } from "../../_blocks/glossary";
+import { DocsHeader } from "../../_blocks/shell";
+import { provenance, taxonomy } from "../../_data";
+
+export default function Vocabulary() {
+  return (
+    <>
+      <DocsHeader title="Vocabulary" lead="Every name in the system. Search by a wrong name and it finds the right one." provenance={provenance}>
+        <CopyPage />
+      </DocsHeader>
+      <Glossary terms={taxonomy.terms} />
+    </>
+  );
+}

package/reference/app/(design)/design/system/_components/copy-page.tsx

@@ -0,0 +1,32 @@
+"use client";
+
+import { usePathname } from "next/navigation";
+import { useState } from "react";
+
+/** Copies this page's markdown, for people handing it to an assistant. The same markdown any agent gets at `.md`. */
+export function CopyPage() {
+  const path = usePathname();
+  const [state, setState] = useState<"idle" | "copied" | "failed">("idle");
+  const copy = async () => {
+    try {
+      const res = await fetch(`${path.replace(/\/$/, "")}.md`);
+      await navigator.clipboard.writeText(await res.text());
+      setState("copied");
+    } catch {
+      setState("failed");
+    }
+    setTimeout(() => setState("idle"), 1500);
+  };
+  return (
+    <button
+      type="button"
+      onClick={copy}
+      className="min-h-[var(--docs-target,2.75rem)] self-start rounded-md border border-border px-2.5 py-1 text-xs hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring"
+    >
+      {state === "copied" ? "Copied" : state === "failed" ? "Could not copy" : "Copy page as markdown"}
+      <span className="sr-only" aria-live="polite">
+        {state === "copied" ? "Page copied" : ""}
+      </span>
+    </button>
+  );
+}