@designtools/blocks 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# @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
+
+- First release. Twenty-three accessible blocks for one branded site holding a brand and its design system, copied into the project with `designtools-blocks add`: shell, logo usage, imagery, voice and terms, swatches, type ramp, scale, rule, pattern, usage, examples, variant matrix, props table, anatomy, playground, code view, accessibility panel, preview frame, standards, glossary, adherence summary, Ask Claude and agent view. Each reads the `@designtools/manifest` JSON, renders the project's real components and assets, and is styled only with the semantic tokens `@designtools/tokens` generates. Every block has a markdown form, with typed fences for rules, examples, do and don't.
+
+  `designtools-blocks map` writes the registry of components, examples, patterns and assets the client blocks render from, and `status` and `show` compare a project's copies with the current version.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Made by Many Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# @designtools/blocks
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Accessible React blocks for one branded site that holds a client's brand and design system together, for the people who make the product and the agents that build it with them: logo usage, imagery, voice and terms, swatches, type, scale, rules, patterns, usage, examples, a variant matrix, props, anatomy, a playground, code, accessibility, a preview frame, standards, a glossary and more. They are copied into your repo, not installed, so they are yours to edit, and they carry no look of their own: they are styled with your tokens, so the site looks like the brand.
+
+Each block reads the JSON [`@designtools/manifest`](../manifest) writes and renders your real components and assets. Nothing is restated or drawn by hand, so the site cannot drift from the code. Every block also has a markdown form, so an agent gets the same page as text.
+
+```bash
+npx @designtools/blocks add swatches type-ramp scale shell   # the token pages
+npx @designtools/blocks add --all                            # everything
+npx @designtools/blocks map                                  # after each manifest build
+```
+
+## Setup
+
+The blocks expect a Next app on the suite stack: React, Tailwind v4 over tokens from `@designtools/tokens`, and Base UI. In `designtools.json`:
+
+```json
+{
+  "manifest": { "system": "src/ds", "tokens": ["app/styles/tokens.css", "app/styles/scale.css"] },
+  "blocks": { "dir": "app/(design)/design/system/_blocks" }
+}
+```
+
+`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, 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.
+
+## Pages
+
+A component page is a server component that reads the manifest and composes blocks:
+
+```tsx
+import components from "@ds/manifest/components.json";
+import { findBySlug, readComponents } from "../../_blocks/lib/manifest";
+import { DocsHeader, DocsSection } from "../../_blocks/shell";
+import { Playground } from "../../_blocks/playground";
+import { PropsTable } from "../../_blocks/props-table";
+import { Examples } from "../../_blocks/examples";
+import { Usage } from "../../_blocks/usage";
+import { VariantMatrix } from "../../_blocks/variant-matrix";
+
+const manifest = readComponents(components);
+
+export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
+  const entry = findBySlug(manifest, (await params).slug)!;
+  return (
+    <>
+      <DocsHeader title={entry.name} lead={entry.description} source={entry.source} />
+      <DocsSection title="Playground"><Playground entry={entry} /></DocsSection>
+      <DocsSection title="Variants"><VariantMatrix entry={entry} /></DocsSection>
+      <DocsSection title="Usage"><Usage entry={entry} manifest={manifest} /></DocsSection>
+      <DocsSection title="Examples"><Examples entry={entry} previewHref={`/design/system/preview/${entry.name.toLowerCase()}`} /></DocsSection>
+      <DocsSection title="Props"><PropsTable entry={entry} /></DocsSection>
+    </>
+  );
+}
+```
+
+`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`: 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; 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` |
+| `pattern` | Each composition live, with its code and the components it uses | `patterns.json`, the map |
+| `usage` | Status, when to use it, when not, and what instead | an entry |
+| `examples` | The canonical example, then each do beside its don't, with code | an entry, the map |
+| `variant-matrix` | The first two axes as a grid, each further axis as a row | an entry, the map |
+| `props-table` | Own props first, a wrapped primitive's folded away, deprecations struck through | an entry |
+| `anatomy` | The `data-slot` parts; pointing at one outlines it in the canonical example | an entry, the map |
+| `playground` | The component live, controls from its axes and boolean props, and the JSX for what is showing | an entry, the map |
+| `code-view` | Highlighted code with copy; Shiki loads on first use | code |
+| `a11y-panel` | axe-core over what it wraps, on demand | the DOM |
+| `preview-frame` | `PreviewFrame`: a preview route at 375, 768 and 1280 wide, light or dark. `PreviewSurface`, `PreviewExample` and `PreviewComposition` for the route itself | the map |
+| `standards` | Performance budgets, accessibility target and support baseline | `.mxa/stack.json` baselines |
+| `glossary` | Every term, searchable by its wrong forms, so a wrong name finds the right one | `taxonomy.json` |
+| `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. 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 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
+
+Blocks use only the semantic utilities every `@designtools/tokens` palette defines (`bg-surface`, `text-muted-foreground`, `border-border`, `bg-primary`, …) and the scale's sizes. To restyle a block, edit your copy. There is no theming API and no plugin system.
+
+A mode panel switches mode with `data-theme` on the element that paints, because the generated stylesheet redefines the `--color-*` bridge per mode: a whole cell in `data-theme="dark"` would put dark-mode text on a light page.
+
+If the blocks folder is gitignored, Tailwind skips it when scanning for classes. Commit the blocks (they are your code), or add `@source "./design/system/_blocks";` to the stylesheet.
+
+## Upgrading
+
+Copies never update themselves. Each starts with a header naming the version it came from:
+
+```
+// @designtools/blocks 0.1.0 · swatches · yours to edit; designtools-blocks status compares it with the registry
+```
+
+`designtools-blocks status` reports each copy as the same as this version, edited here, or from an older version. `designtools-blocks show <file>` prints this version, to compare with your copy and carry your edits across. `add --force` replaces a copy outright.
+
+## Licence
+
+[MIT](LICENSE), © Made by Many Ltd.

package/dist/cli.js

@@ -0,0 +1,385 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { existsSync as existsSync2, mkdirSync, readdirSync, readFileSync as readFileSync2, realpathSync, writeFileSync } from "fs";
+import { basename, dirname as dirname2, join as join2, relative, resolve, sep } from "path";
+import { parseArgs } from "util";
+
+// src/registry.ts
+import { existsSync, readFileSync } from "fs";
+import { dirname, join, normalize } from "path";
+import { fileURLToPath } from "url";
+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" },
+  { name: "swatches", file: "swatches.tsx", description: "Semantic colour pairs per mode with measured contrast, and the primitive ramps" },
+  { name: "type-ramp", file: "type-ramp.tsx", description: "Type scale with leading and tracking pairs, families, weights" },
+  { name: "scale", file: "scale.tsx", description: "Space, size, radius, elevation and motion tiers" },
+  { name: "rule", file: "rule.tsx", description: "A rule for people, and as an agent reads it, with its check and room for a demonstration" },
+  { name: "pattern", file: "pattern.tsx", description: "A screen composition, live, with the components it uses" },
+  { name: "usage", file: "usage.tsx", description: "When to use a component, when not, what instead, and its status" },
+  { name: "examples", file: "examples.tsx", description: "The canonical example, then do and don't pairs side by side" },
+  { name: "variant-matrix", file: "variant-matrix.tsx", description: "Every variant combination, rendered live" },
+  { name: "props-table", file: "props-table.tsx", description: "Props, types, defaults, required; a wrapped primitive's folded away" },
+  { name: "anatomy", file: "anatomy.tsx", description: "The component's data-slot parts, outlined on hover" },
+  { name: "playground", file: "playground.tsx", description: "The component live, with controls from its variants and flags, and its JSX" },
+  { name: "code-view", file: "code-view.tsx", description: "Highlighted code with copy; Shiki loads on first use" },
+  { name: "a11y-panel", file: "a11y-panel.tsx", description: "axe-core over a preview, on demand" },
+  { name: "preview-frame", file: "preview-frame.tsx", description: "A preview route in an iframe at set widths and either mode" },
+  { name: "standards", file: "standards.tsx", description: "Performance budgets, accessibility target and support baseline" },
+  { name: "glossary", file: "glossary.tsx", description: "The taxonomy, searchable, so a wrong name finds the right one" },
+  { name: "adherence-summary", file: "adherence-summary.tsx", description: "The latest @designtools/adherence report: share, off-system values, overrides, by route" },
+  { name: "ask-claude", file: "ask-claude.tsx", description: "Copies a prompt naming the component, file, variant and example" },
+  { name: "agent-view", file: "agent-view.tsx", description: "Any block's markdown form, copyable, in a tab beside the rendered one" }
+];
+var ASSUMED = /* @__PURE__ */ new Set(["react", "react-dom"]);
+var IMPORT = /^[ \t]*(?:import|export)\s[^"'`;]*?from\s+["']([^"']+)["']|\bimport\(\s*["']([^"']+)["']\s*\)/gm;
+function importsOf(source) {
+  return [...source.matchAll(IMPORT)].map((m) => m[1] ?? m[2]);
+}
+function resolveBlocks(names) {
+  const files = /* @__PURE__ */ new Set();
+  const packages = /* @__PURE__ */ new Set();
+  let needsMap = false;
+  const queue = names.map((n) => {
+    const block = BLOCKS.find((b) => b.name === n);
+    if (!block) throw new Error(`unknown block "${n}". Run designtools-blocks list to see them.`);
+    return block.file;
+  });
+  while (queue.length) {
+    const file = queue.shift();
+    if (files.has(file)) continue;
+    files.add(file);
+    for (const spec of importsOf(readFileSync(join(REGISTRY_DIR, file), "utf8"))) {
+      if (!spec.startsWith(".")) {
+        const pkg = spec.startsWith("@") ? spec.split("/").slice(0, 2).join("/") : spec.split("/")[0];
+        if (!ASSUMED.has(pkg)) packages.add(pkg);
+        continue;
+      }
+      const target = registryFile(normalize(join(dirname(file), spec)));
+      if (target === GENERATED) needsMap = true;
+      else queue.push(target);
+    }
+  }
+  return { files: [...files].sort(), packages: [...packages].sort(), needsMap };
+}
+function registryFile(path) {
+  const clean = path.split("\\").join("/");
+  for (const ext of ["", ".tsx", ".ts"]) {
+    if (existsSync(join(REGISTRY_DIR, clean + ext)) && /\.(tsx?)$/.test(clean + ext)) return clean + ext;
+  }
+  throw new Error(`registry import not found: ${clean}`);
+}
+
+// src/map.ts
+function generateMap(manifest, toRoot, manifestPath2) {
+  const spec = (source, keepExtension = false) => {
+    const path = `${toRoot || "."}/${keepExtension ? source : source.replace(/\.tsx?$/, "")}`;
+    return path.startsWith(".") ? path : `./${path}`;
+  };
+  const lines = [
+    `"use client";`,
+    `// Generated by designtools-blocks map from ${manifestPath2}. Do not edit: run designtools-blocks map again.`,
+    `import type { ComponentType } from "react";`
+  ];
+  const components = [];
+  const examples = [];
+  const patterns = [];
+  const assets = [];
+  const seen = /* @__PURE__ */ new Set();
+  manifest.components.components.forEach((c, i) => {
+    lines.push(`import { ${c.export} as C${i} } from ${JSON.stringify(spec(c.source))};`);
+    components.push(`  ${JSON.stringify(`${c.source}#${c.export}`)}: C${i},`);
+    if (c.examples && !seen.has(c.examples.source)) {
+      seen.add(c.examples.source);
+      const name = `E${examples.length}`;
+      lines.push(`import * as ${name} from ${JSON.stringify(spec(c.examples.source))};`);
+      examples.push(`  ${JSON.stringify(c.examples.source)}: ${name},`);
+    }
+  });
+  (manifest.patterns?.patterns ?? []).forEach((p, i) => {
+    lines.push(`import * as P${i} from ${JSON.stringify(spec(p.source))};`);
+    patterns.push(`  ${JSON.stringify(p.source)}: P${i},`);
+  });
+  (manifest.assets?.assets ?? []).forEach((a, i) => {
+    lines.push(`import A${i} from ${JSON.stringify(spec(a.file, true))};`);
+    assets.push(`  ${JSON.stringify(a.file)}: A${i},`);
+  });
+  const block = (head, rows) => [head, ...rows, "};", ""];
+  return [
+    ...lines,
+    "",
+    "// eslint-disable-next-line @typescript-eslint/no-explicit-any",
+    ...block("export const components: Record<string, ComponentType<any>> = {", components),
+    ...block("export const examples: Record<string, Record<string, unknown>> = {", examples),
+    ...block("export const patterns: Record<string, Record<string, unknown>> = {", patterns),
+    ...block("export const assets: Record<string, string | { src: string }> = {", assets)
+  ].join("\n");
+}
+
+// src/cli.ts
+var VERSION = JSON.parse(readFileSync2(join2(REGISTRY_DIR, "../package.json"), "utf8")).version;
+var CONFIG_FILE = "designtools.json";
+var HEADER = /^\/\/ @designtools\/blocks (\S+) · .*\r?\n/;
+var HELP = `designtools-blocks ${VERSION}
+
+Unstyled, accessible docs blocks for a React design system, copied into your
+repo to own and edit. Each reads the @designtools/manifest JSON and renders
+your real components.
+
+Usage
+  designtools-blocks list                List the blocks
+  designtools-blocks add <block\u2026>        Copy blocks, and the files they need, into the project
+  designtools-blocks add --all           Copy every block
+  designtools-blocks map                 Write registry.generated.tsx from the manifest
+  designtools-blocks map --check         Exit 1 if registry.generated.tsx is out of date
+  designtools-blocks status              Compare the project's copies with this version
+  designtools-blocks show <file>         Print this version of a block file, e.g. swatches.tsx
+
+Options
+  --dir <dir>          Where blocks live (default: blocks.dir in designtools.json,
+                       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
+  -h, --help           Show this help
+  -v, --version        Show the version
+`;
+function fail(message, code = 2) {
+  process.stderr.write(`designtools-blocks: ${message}
+`);
+  process.exit(code);
+}
+var parsed;
+function parse() {
+  return parseArgs({
+    allowPositionals: true,
+    options: {
+      dir: { type: "string" },
+      manifest: { type: "string" },
+      root: { type: "string" },
+      force: { type: "boolean" },
+      all: { type: "boolean" },
+      check: { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" }
+    }
+  });
+}
+try {
+  parsed = parse();
+} catch (e) {
+  fail(`${e.message}
+
+${HELP}`);
+}
+var { values, positionals } = parsed;
+if (values.help) {
+  process.stdout.write(HELP);
+  process.exit(0);
+}
+if (values.version) {
+  process.stdout.write(`${VERSION}
+`);
+  process.exit(0);
+}
+var [command, ...rest] = positionals;
+function real(path) {
+  if (existsSync2(path)) return realpathSync(path);
+  const parent = dirname2(path);
+  return parent === path ? path : join2(real(parent), basename(path));
+}
+var root = real(resolve(values.root ?? "."));
+function readConfig() {
+  const path = join2(root, CONFIG_FILE);
+  if (!existsSync2(path)) return {};
+  try {
+    return JSON.parse(readFileSync2(path, "utf8"));
+  } catch (e) {
+    fail(`${CONFIG_FILE} is not valid JSON: ${e.message}`);
+  }
+}
+function blocksDir(config) {
+  if (values.dir) return values.dir;
+  if (config.blocks?.dir) return config.blocks.dir;
+  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;
+  const m = config.manifest;
+  if (!m?.system && !m?.out) {
+    fail(`no manifest. Pass --manifest <components.json>, or set manifest.system in ${CONFIG_FILE}.`);
+  }
+  return `${(m.out ?? `${m.system.replace(/\/+$/, "")}/manifest`).replace(/\/+$/, "")}/components.json`;
+}
+var posix = (p) => p.split(sep).join("/");
+var abs = (p) => real(resolve(root, p));
+var shown = (p) => posix(relative(root, abs(p))) || ".";
+var lf = (text) => text.replace(/\r\n/g, "\n");
+switch (command) {
+  case "list":
+    list();
+    break;
+  case "add":
+    add();
+    break;
+  case "map":
+    map();
+    break;
+  case "status":
+    status();
+    break;
+  case "show":
+    show();
+    break;
+  default:
+    fail(command ? `unknown command "${command}"
+
+${HELP}` : `a command is required
+
+${HELP}`);
+}
+function list() {
+  const width = Math.max(...BLOCKS.map((b) => b.name.length));
+  for (const b of BLOCKS) process.stdout.write(`${b.name.padEnd(width)}  ${b.description}
+`);
+}
+function add() {
+  const names = values.all ? BLOCKS.map((b) => b.name) : rest;
+  if (names.length === 0) fail("name the blocks to add, or pass --all. Run designtools-blocks list to see them.");
+  let resolved;
+  try {
+    resolved = resolveBlocks(names);
+  } catch (e) {
+    fail(e.message);
+  }
+  const config = readConfig();
+  const dir = blocksDir(config);
+  const written = [];
+  const kept = [];
+  for (const file of resolved.files) {
+    const target = join2(abs(dir), file);
+    if (existsSync2(target) && !values.force) {
+      kept.push(file);
+      continue;
+    }
+    mkdirSync(dirname2(target), { recursive: true });
+    writeFileSync(target, withHeader(file, readFileSync2(join2(REGISTRY_DIR, file), "utf8")));
+    written.push(file);
+  }
+  if (!config.blocks?.dir) {
+    const next = { ...config, blocks: { ...config.blocks, dir: shown(dir) } };
+    writeFileSync(join2(root, CONFIG_FILE), JSON.stringify(next, null, 2) + "\n");
+    process.stderr.write(`recorded blocks.dir = ${shown(dir)} in ${CONFIG_FILE}
+`);
+  }
+  for (const f of written) process.stderr.write(`added ${dir}/${f}
+`);
+  for (const f of kept) process.stderr.write(`kept ${dir}/${f} (exists; --force to replace, or designtools-blocks status to compare)
+`);
+  const pkg = existsSync2(join2(root, "package.json")) ? JSON.parse(readFileSync2(join2(root, "package.json"), "utf8")) : {};
+  const installed = { ...pkg.dependencies, ...pkg.devDependencies };
+  const missing = resolved.packages.filter((p) => !(p in installed));
+  if (missing.length) process.stderr.write(`
+these blocks need: ${missing.join(" ")}
+  pnpm add ${missing.join(" ")}
+`);
+  if (resolved.needsMap) {
+    const path = config.manifest?.system || config.manifest?.out || values.manifest ? manifestPath(config) : void 0;
+    if (path && existsSync2(abs(path))) writeMap(dir, path);
+    else process.stderr.write(`
+then build the manifest and run designtools-blocks map, which writes ${dir}/${GENERATED}
+`);
+  }
+}
+function withHeader(file, source) {
+  const block = BLOCKS.find((b) => b.file === file)?.name ?? file;
+  return `// @designtools/blocks ${VERSION} \xB7 ${block} \xB7 yours to edit; designtools-blocks status compares it with the registry
+${source}`;
+}
+function map() {
+  const config = readConfig();
+  const dir = blocksDir(config);
+  const path = manifestPath(config);
+  if (!existsSync2(abs(path))) fail(`${path} not found. Run designtools-manifest build first.`);
+  if (values.check) {
+    const target = join2(abs(dir), GENERATED);
+    const expected = generate(dir, path);
+    const ok = existsSync2(target) && lf(readFileSync2(target, "utf8")) === expected;
+    process.stderr.write(ok ? `map: ${dir}/${GENERATED} up to date
+` : `map: ${dir}/${GENERATED} is out of date. Run designtools-blocks map.
+`);
+    process.exit(ok ? 0 : 1);
+  }
+  writeMap(dir, path);
+}
+function generate(dir, manifest) {
+  const json = JSON.parse(readFileSync2(abs(manifest), "utf8"));
+  const sibling = (name) => {
+    const path = join2(dirname2(abs(manifest)), name);
+    return existsSync2(path) ? JSON.parse(readFileSync2(path, "utf8")) : void 0;
+  };
+  return generateMap(
+    { components: json, patterns: sibling("patterns.json"), assets: sibling("assets.json") },
+    posix(relative(abs(dir), sourceRoot(abs(manifest), json.system))),
+    shown(manifest)
+  );
+}
+function sourceRoot(manifest, system) {
+  const path = posix(manifest);
+  const tail = system ? `/${system.replace(/^\.?\/+|\/+$/g, "")}/manifest/components.json` : void 0;
+  return tail && path.endsWith(tail) ? path.slice(0, -tail.length) || "/" : root;
+}
+function writeMap(dir, manifest) {
+  const target = join2(abs(dir), GENERATED);
+  mkdirSync(dirname2(target), { recursive: true });
+  writeFileSync(target, generate(dir, manifest));
+  process.stderr.write(`wrote ${shown(dir)}/${GENERATED} from ${shown(manifest)}
+`);
+}
+function status() {
+  const dir = blocksDir(readConfig());
+  let found = 0;
+  const all = resolveBlocks(BLOCKS.map((b) => b.name)).files;
+  for (const file of all) {
+    const target = join2(abs(dir), file);
+    if (!existsSync2(target)) continue;
+    found++;
+    const copy = readFileSync2(target, "utf8");
+    const header = HEADER.exec(copy);
+    const body = lf(header ? copy.slice(header[0].length) : copy);
+    const current = readFileSync2(join2(REGISTRY_DIR, file), "utf8");
+    const from = header?.[1] ?? "unknown";
+    const state = body === current ? "same as the registry" : from === VERSION ? "edited here" : `differs: copied from ${from}, registry is ${VERSION} (may include your edits; designtools-blocks show ${file})`;
+    process.stdout.write(`${file.padEnd(24)} ${state}
+`);
+  }
+  const known = /* @__PURE__ */ new Set([...all, GENERATED]);
+  const walk = (folder, prefix) => existsSync2(folder) ? readdirSync(folder, { withFileTypes: true }).flatMap(
+    (d) => d.isDirectory() ? walk(join2(folder, d.name), `${prefix}${d.name}/`) : [`${prefix}${d.name}`]
+  ) : [];
+  for (const file of walk(abs(dir), "").sort()) {
+    if (known.has(file) || !/\.tsx?$/.test(file)) continue;
+    if (!HEADER.test(readFileSync2(join2(abs(dir), file), "utf8"))) continue;
+    found++;
+    process.stdout.write(`${file.padEnd(24)} not in ${VERSION}: removed or renamed in the registry; delete it once nothing imports it
+`);
+  }
+  if (!found) process.stdout.write(`no blocks in ${dir}
+`);
+}
+function show() {
+  const [file] = rest;
+  if (!file) fail("name a registry file, e.g. designtools-blocks show swatches.tsx");
+  const path = join2(REGISTRY_DIR, file);
+  if (!path.startsWith(REGISTRY_DIR) || !existsSync2(path) || file === GENERATED) fail(`no registry file ${file}`);
+  process.stdout.write(readFileSync2(path, "utf8"));
+}

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@designtools/blocks",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "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",
+  "author": "Made by Many",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/madebymany/designtools.git",
+    "directory": "packages/blocks"
+  },
+  "homepage": "https://github.com/madebymany/designtools/tree/main/packages/blocks#readme",
+  "bugs": {
+    "url": "https://github.com/madebymany/designtools/issues"
+  },
+  "bin": {
+    "designtools-blocks": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "registry",
+    "reference",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "design-system",
+    "documentation",
+    "react",
+    "base-ui",
+    "tailwind",
+    "docs",
+    "swatches",
+    "props-table",
+    "playground"
+  ],
+  "devDependencies": {
+    "@base-ui/react": "1.6.0",
+    "@types/node": "^24.19.1",
+    "@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",
+    "shiki": "^4.5.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.15",
+    "typescript": "~6.0.3",
+    "vitest": "^4.1.11"
+  },
+  "scripts": {
+    "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.