@designtools/docs 0.0.0-stage → 0.2.0

package/dist/cli.js

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+
+// cli/cli.ts
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "fs";
+import { basename, dirname as dirname2, join as join2, relative, resolve, sep } from "path";
+import { parseArgs } from "util";
+
+// cli/blocks.ts
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+var SOURCE_DIR = join(dirname(fileURLToPath(import.meta.url)), "../src");
+var BLOCKS = [
+  { name: "shell", file: "shell.tsx", exports: [], description: "The frame: navigation, search, the mode switch, page header, sections and footer. Restyle it with the theme variables." },
+  { name: "workbench", file: "workbench.tsx", exports: ["Workbench"], description: "A component's main area: the stage, its properties, code, props, actions, agent view and accessibility" },
+  { name: "usage", file: "usage.tsx", exports: ["Usage"], description: "When to use a component, when not, what instead, and its facts" },
+  { name: "examples", file: "examples.tsx", exports: ["Examples"], description: "The canonical example, then each do beside its don't" },
+  { name: "variant-matrix", file: "variant-matrix.tsx", exports: ["VariantMatrix"], description: "Every variant combination, then each state" },
+  { name: "anatomy", file: "anatomy.tsx", exports: ["Anatomy"], description: "The component's parts, found on hover" },
+  { name: "props-table", file: "props-table.tsx", exports: ["PropsTable"], description: "Props as an API reference" },
+  { name: "preview-frame", file: "preview-frame.tsx", exports: ["PreviewFrame"], description: "An example at device widths, in a browser window" },
+  { name: "pattern", file: "pattern.tsx", exports: ["Pattern"], description: "A screen composition, live, with what it is made of" },
+  { name: "rule", file: "rule.tsx", exports: ["Rule", "RuleIndex"], description: "A rule for people and as an agent reads it, with its check, and the index of every rule" },
+  { name: "swatches", file: "swatches.tsx", exports: ["SemanticSwatches", "PageContrast", "RampSwatches"], description: "Colour: each pair measured, each colour on each background, the ramps" },
+  { name: "type-ramp", file: "type-ramp.tsx", exports: ["TypeRamp"], description: "Type: families, the scale, weights, leading and tracking" },
+  { name: "scale", file: "scale.tsx", exports: ["Scale"], description: "Space, size, radius, elevation and motion" },
+  { name: "logo-usage", file: "logo-usage.tsx", exports: ["LogoUsage"], description: "Each logo on its surfaces, with its clear space and rules" },
+  { name: "imagery", file: "imagery.tsx", exports: ["Imagery"], description: "The approved icons and imagery" },
+  { name: "voice-terms", file: "voice-terms.tsx", exports: ["VoiceTerms"], description: "The words to use beside the ones not to" },
+  { name: "glossary", file: "glossary.tsx", exports: ["Glossary"], description: "Every name in the system, found by its wrong forms too" },
+  { name: "standards", file: "standards.tsx", exports: ["Standards"], description: "Budgets and targets from .mxa/stack.json" },
+  { name: "adherence-summary", file: "adherence-summary.tsx", exports: ["AdherenceSummary"], description: "How closely the product follows the system" }
+];
+function ejected(source, file) {
+  const dir = dirname(file);
+  return source.replace(/(from\s+|import\s*\(\s*)(["'])(\.{1,2}\/[^"']+)\2/g, (_, lead, quote, spec) => {
+    const target = join(dir, spec).replace(/^\.\//, "").replace(/\\/g, "/");
+    return `${lead}${quote}@designtools/docs/${target}${quote}`;
+  });
+}
+
+// cli/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-docs map from ${manifestPath2}. Do not edit: run designtools-docs map again.`,
+    `import { type Registry as Entries, RegistryProvider } from "@designtools/docs/registry";`,
+    `import type { ReactNode } 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 group = (name, rows) => [`  ${name}: {`, ...rows, "  },"];
+  return [
+    ...lines,
+    "",
+    "const entries: Entries = {",
+    ...group("components", components),
+    ...group("examples", examples),
+    ...group("patterns", patterns),
+    ...group("assets", assets),
+    "};",
+    "",
+    "/** The project's components, examples, patterns and assets, for the docs: `registry` in the docs config. */",
+    "export default function Registry({ children }: { children: ReactNode }) {",
+    "  return <RegistryProvider value={entries}>{children}</RegistryProvider>;",
+    "}",
+    ""
+  ].join("\n");
+}
+
+// cli/cli.ts
+var VERSION = JSON.parse(readFileSync(join2(SOURCE_DIR, "../package.json"), "utf8")).version;
+var CONFIG_FILE = "designtools.json";
+var HEADER = /^\/\/ @designtools\/docs (\S+) · ejected (\S+)\r?\n/;
+var HELP = `designtools-docs ${VERSION}
+
+Design system docs as a package: pages, navigation, search, a workbench per
+component and markdown for agents, themed by the project's tokens. This CLI
+writes the registry that reaches the project's components, and copies a block
+into the project when it needs to change more than the theme allows.
+
+Usage
+  designtools-docs map                   Write the registry from the manifest
+  designtools-docs map --check           Exit 1 if the registry is out of date
+  designtools-docs eject <block\u2026>        Copy blocks' source into the project, to own and change
+  designtools-docs status                Compare ejected blocks with this version
+  designtools-docs list                  List the blocks
+  designtools-docs show <block>          Print this version of a block
+
+Options
+  --registry <file>    Where the registry goes (default: docs.registry in designtools.json,
+                       else app/(design)/design/system/_registry.tsx, or src/app/\u2026 when src/app exists)
+  --dir <dir>          Where ejected blocks go (default: docs.blocks in designtools.json,
+                       else beside the registry, in _blocks)
+  --manifest <file>    components.json (default: from manifest.system in designtools.json)
+  --root <dir>         Project root (default: the current directory)
+  --force              eject: overwrite a block already ejected
+  -h, --help           Show this help
+  -v, --version        Show the version
+`;
+function fail(message, code = 2) {
+  process.stderr.write(`designtools-docs: ${message}
+`);
+  process.exit(code);
+}
+var parsed;
+function parse() {
+  return parseArgs({
+    allowPositionals: true,
+    options: {
+      registry: { type: "string" },
+      dir: { type: "string" },
+      manifest: { type: "string" },
+      root: { type: "string" },
+      force: { 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);
+}
+function real(path) {
+  if (existsSync(path)) return realpathSync(path);
+  const parent = dirname2(path);
+  return parent === path ? path : join2(real(parent), basename(path));
+}
+var root = real(resolve(values.root ?? "."));
+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");
+function readConfig() {
+  const path = join2(root, CONFIG_FILE);
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (e) {
+    fail(`${CONFIG_FILE} is not valid JSON: ${e.message}`);
+  }
+}
+function registryPath(config) {
+  if (values.registry) return values.registry;
+  if (config.docs?.registry) return config.docs.registry;
+  const app = existsSync(join2(root, "src/app")) ? "src/app" : "app";
+  return `${app}/(design)/design/system/_registry.tsx`;
+}
+function blocksDir(config) {
+  if (values.dir) return values.dir;
+  if (config.docs?.blocks) return config.docs.blocks;
+  return `${posix(dirname2(registryPath(config)))}/_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 [command, ...rest] = positionals;
+switch (command) {
+  case "map":
+    map();
+    break;
+  case "eject":
+    eject();
+    break;
+  case "status":
+    status();
+    break;
+  case "list":
+    list();
+    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 blockOf(name) {
+  const block = BLOCKS.find((b) => b.name === name || b.file === name);
+  if (!block) fail(`no block called "${name}". Run designtools-docs list to see them.`);
+  return block;
+}
+function map() {
+  const config = readConfig();
+  const target = registryPath(config);
+  const manifest = manifestPath(config);
+  if (!existsSync(abs(manifest))) fail(`${manifest} not found. Run designtools-manifest build first.`);
+  const expected = generate(target, manifest);
+  if (values.check) {
+    const ok = existsSync(abs(target)) && lf(readFileSync(abs(target), "utf8")) === expected;
+    process.stderr.write(ok ? `map: ${shown(target)} up to date
+` : `map: ${shown(target)} is out of date. Run designtools-docs map.
+`);
+    process.exit(ok ? 0 : 1);
+  }
+  mkdirSync(dirname2(abs(target)), { recursive: true });
+  writeFileSync(abs(target), expected);
+  process.stderr.write(`wrote ${shown(target)} from ${shown(manifest)}
+`);
+}
+function generate(target, manifest) {
+  const json = JSON.parse(readFileSync(abs(manifest), "utf8"));
+  const sibling = (name) => {
+    const path = join2(dirname2(abs(manifest)), name);
+    return existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : void 0;
+  };
+  return generateMap(
+    { components: json, patterns: sibling("patterns.json"), assets: sibling("assets.json") },
+    posix(relative(dirname2(abs(target)), 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 eject() {
+  if (rest.length === 0) fail("name the blocks to eject. Run designtools-docs list to see them.");
+  const config = readConfig();
+  const dir = blocksDir(config);
+  const lines = [];
+  for (const name of rest) {
+    const block = blockOf(name);
+    const target = join2(abs(dir), block.file);
+    if (existsSync(target) && !values.force) {
+      process.stderr.write(`kept ${shown(target)} (already ejected; --force to replace, designtools-docs status to compare)
+`);
+      continue;
+    }
+    mkdirSync(dirname2(target), { recursive: true });
+    const source = readFileSync(join2(SOURCE_DIR, block.file), "utf8");
+    writeFileSync(target, `// @designtools/docs ${VERSION} \xB7 ejected ${block.name}
+${ejected(source, block.file)}`);
+    process.stderr.write(`ejected ${shown(target)}
+`);
+    for (const e of block.exports) lines.push(`    ${e}: ${e},   // from "./${posix(relative(dirname2(abs(registryPath(config))), target)).replace(/\.tsx$/, "")}"`);
+  }
+  if (lines.length)
+    process.stderr.write(`
+Use it in the docs config:
+  blocks: {
+${lines.join("\n")}
+  },
+Everything else keeps upgrading with the package.
+`);
+}
+function status() {
+  const dir = blocksDir(readConfig());
+  let found = 0;
+  for (const block of BLOCKS) {
+    const target = join2(abs(dir), block.file);
+    if (!existsSync(target)) continue;
+    found++;
+    const copy = readFileSync(target, "utf8");
+    const header = HEADER.exec(copy);
+    const body = lf(header ? copy.slice(header[0].length) : copy);
+    const current = ejected(readFileSync(join2(SOURCE_DIR, block.file), "utf8"), block.file);
+    const from = header?.[1] ?? "unknown";
+    const state = body === current ? "same as the package" : from === VERSION ? "edited here" : `differs: ejected from ${from}, the package is ${VERSION} (designtools-docs show ${block.name} for the new one)`;
+    process.stdout.write(`${block.file.padEnd(22)} ${state}
+`);
+  }
+  if (!found) process.stdout.write(`no ejected blocks in ${shown(dir)}: everything comes from the package
+`);
+}
+function show() {
+  const [name] = rest;
+  if (!name) fail("name a block. Run designtools-docs list to see them.");
+  const block = blockOf(name);
+  process.stdout.write(ejected(readFileSync(join2(SOURCE_DIR, block.file), "utf8"), block.file));
+}

package/dist/code-view.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Code, highlighted once Shiki has loaded (it loads on first use, so pages
+ * without code never pay for it) and readable as plain text before then. A file
+ * header with a copy button, numbered lines, and long code folded behind "Show
+ * all". `bare` drops the frame, for code inside another frame.
+ */
+export declare function CodeView({ code, lang, label, wrap, bare, numbered, }: {
+    code: string;
+    lang?: string;
+    label?: string;
+    /** Wrap long lines, for prose such as markdown, instead of scrolling them. */
+    wrap?: boolean;
+    /** No border or header of its own: for code inside an example or playground frame. */
+    bare?: boolean;
+    /** Line numbers. On by default for more than one line of code, off for prose. */
+    numbered?: boolean;
+}): import("react").JSX.Element;

package/dist/code-view.js

@@ -0,0 +1,42 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronDown, FileCode } from "lucide-react";
+import { useEffect, useState } from "react";
+import { cx } from "./lib/cx.js";
+import { CopyButton } from "./lib/ui.js";
+/* Shiki writes both themes as CSS variables; these pick the one for the page's mode, and number the lines. */
+const THEME_CSS = `
+[data-slot="code-view"] .shiki { background: transparent !important; counter-reset: line; }
+[data-slot="code-view"][data-numbered] .shiki .line::before { counter-increment: line; content: counter(line); display: inline-block; width: 2ch; margin-right: 1.25rem; text-align: right; color: var(--muted-foreground); opacity: .6; }
+[data-theme="dark"] [data-slot="code-view"] .shiki, [data-theme="dark"] [data-slot="code-view"] .shiki span { color: var(--shiki-dark) !important; }
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) [data-slot="code-view"] .shiki, :root:not([data-theme="light"]) [data-slot="code-view"] .shiki span { color: var(--shiki-dark) !important; }
+}`;
+/** Lines past which the code folds, with a fade and a "Show all". */
+const FOLD = 14;
+/**
+ * Code, highlighted once Shiki has loaded (it loads on first use, so pages
+ * without code never pay for it) and readable as plain text before then. A file
+ * header with a copy button, numbered lines, and long code folded behind "Show
+ * all". `bare` drops the frame, for code inside another frame.
+ */
+export function CodeView({ code, lang = "tsx", label = "Code", wrap = false, bare = false, numbered, }) {
+    const [html, setHtml] = useState(null);
+    const lines = code.split("\n").length;
+    const [open, setOpen] = useState(lines <= FOLD);
+    const numbers = numbered ?? (!wrap && lines > 1);
+    useEffect(() => {
+        let live = true;
+        import("shiki")
+            .then(({ codeToHtml }) => codeToHtml(code, { lang, themes: { light: "github-light", dark: "github-dark" } }))
+            .then((out) => live && setHtml(out))
+            .catch(() => live && setHtml(null));
+        return () => {
+            live = false;
+        };
+    }, [code, lang]);
+    const body = cx("overflow-x-auto px-4 py-3.5 font-mono text-sm leading-relaxed", wrap && "[&_pre]:break-words [&_pre]:whitespace-pre-wrap", 
+    // room for the copy button floating at the top right
+    bare && "pr-12", !open && "max-h-96 overflow-y-hidden");
+    return (_jsxs("figure", { "data-slot": "code-view", "data-numbered": numbers || undefined, className: cx("relative min-w-0", !bare && "overflow-hidden rounded-xl border border-border bg-surface text-surface-foreground"), children: [_jsx("style", { children: THEME_CSS }), !bare && (_jsxs("figcaption", { className: "flex min-h-11 items-center justify-between gap-3 border-b border-border bg-muted/40 py-1 pr-1.5 pl-4 text-xs text-muted-foreground", children: [_jsxs("span", { className: "flex min-w-0 items-center gap-2", children: [_jsx(FileCode, { "aria-hidden": true, className: "size-(--dt-size-xs) shrink-0" }), _jsx("span", { className: "truncate font-medium text-canvas-foreground", children: label })] }), _jsx(CopyButton, { text: code, label: "Copy code" })] })), _jsxs("div", { className: "relative", children: [bare && (_jsx("span", { className: "absolute top-1.5 right-1.5 z-10", children: _jsx(CopyButton, { text: code, label: "Copy code" }) })), html ? (_jsx("div", { className: body, tabIndex: 0, role: "region", "aria-label": label, dangerouslySetInnerHTML: { __html: html } })) : (_jsx("pre", { tabIndex: 0, "aria-label": label, className: cx(body, wrap && "break-words whitespace-pre-wrap"), children: _jsx("code", { children: code }) })), !open && (_jsx("div", { className: "absolute inset-x-0 bottom-0 flex h-24 items-end justify-center bg-linear-to-t from-surface via-surface/80 to-transparent pb-3", children: _jsxs("button", { type: "button", onClick: () => setOpen(true), className: "inline-flex min-h-(--docs-target,2.75rem) cursor-pointer items-center gap-1.5 rounded-full border border-border bg-surface px-4 text-xs font-medium text-surface-foreground shadow-sm hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring", children: ["Show all ", lines, " lines ", _jsx(ChevronDown, { "aria-hidden": true, className: "size-(--dt-size-xs)" })] }) }))] })] }));
+}

package/dist/examples.d.ts

@@ -0,0 +1,25 @@
+import { type ReactNode } from "react";
+import type { ComponentEntry } from "./lib/manifest-types.js";
+/**
+ * The canonical example first, the one to copy, then each do beside its don't.
+ * Every example is the real component; the code behind it is the code that drew it.
+ */
+export declare function Examples({ entry, previewHref }: {
+    entry: ComponentEntry;
+    previewHref?: string;
+}): import("react").JSX.Element;
+type Kind = "canonical" | "do" | "dont" | "other";
+/**
+ * One example in its frame: Preview and Code on a switch, the stage in either mode
+ * or at a phone's width, a copy button, and a link to it alone. The caption says
+ * what kind of example it is and why. Patterns use it for their compositions too.
+ */
+export declare function ExampleFrame({ name, kind, description, code, href, children, }: {
+    name: string;
+    kind?: Kind;
+    description?: string;
+    code?: string;
+    href?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export {};

package/dist/examples.js

@@ -0,0 +1,48 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CircleCheck, CircleX, Code, Eye, Maximize2, Moon, Smartphone, Sun } from "lucide-react";
+import { useState } from "react";
+import { CodeView } from "./code-view.js";
+import { Boundary } from "./lib/boundary.js";
+import { cx } from "./lib/cx.js";
+import { Missing, renderExample, useLookup } from "./lib/lookup.js";
+import { inline } from "./lib/text.js";
+import { CopyButton, IconButton, IconLink, Segmented, SegmentedList, SegmentedPanel, Stage, Toolbar } from "./lib/ui.js";
+/**
+ * The canonical example first, the one to copy, then each do beside its don't.
+ * Every example is the real component; the code behind it is the code that drew it.
+ */
+export function Examples({ entry, previewHref }) {
+    const lookup = useLookup();
+    const ex = entry.examples;
+    if (!ex) {
+        return (_jsxs("p", { "data-slot": "examples-empty", className: "rounded-xl border border-dashed border-border p-6 text-sm text-muted-foreground", children: ["No examples yet. Add ", _jsx("code", { className: "font-mono text-xs", children: entry.source.replace(/\.tsx$/, ".examples.tsx") }), " with a", " ", _jsx("code", { className: "font-mono text-xs", children: "canonical" }), " export and do and don't pairs."] }));
+    }
+    const module = lookup.examplesFor(entry);
+    if (!module)
+        return _jsx(Missing, { name: entry.name, what: "examples" });
+    const pairs = Array.from({ length: Math.max(ex.do.length, ex.dont.length) }, (_, i) => [ex.do[i], ex.dont[i]]);
+    const frame = (ref, kind) => (_jsx(ExampleFrame, { name: ref.name, kind: kind, description: ref.description, code: ref.code, href: previewHref && `${previewHref}/${encodeURIComponent(ref.name)}`, children: renderExample(module[ref.name], ref.name) }, ref.name));
+    return (_jsxs("div", { "data-slot": "examples", className: "flex flex-col gap-10", children: [ex.canonical && frame(ex.canonical, "canonical"), pairs.length > 0 && (_jsx("div", { className: "flex flex-col gap-6", children: pairs.map(([d, n], i) => (_jsxs("div", { "data-slot": "examples-pair", className: "grid grid-cols-1 gap-4 lg:grid-cols-2", children: [d ? frame(d, "do") : _jsx("span", {}), n ? frame(n, "dont") : _jsx("span", {})] }, d?.name ?? n?.name ?? i))) })), ex.other.length > 0 && _jsx("div", { className: "grid grid-cols-1 gap-4 lg:grid-cols-2", children: ex.other.map((o) => frame(o, "other")) })] }));
+}
+const MARK = {
+    // the canonical example is simply first, the usual use; it needs no badge to say so
+    canonical: { label: "", tone: "" },
+    // a measured pairing, never a fill colour used as text (text-success read 3.9:1 on the canvas)
+    do: { label: "Do", icon: CircleCheck, tone: "bg-success-subdued text-success-subdued-foreground" },
+    dont: { label: "Don't", icon: CircleX, tone: "bg-destructive-subdued text-destructive-subdued-foreground" },
+    other: { label: "", tone: "" },
+};
+/**
+ * One example in its frame: Preview and Code on a switch, the stage in either mode
+ * or at a phone's width, a copy button, and a link to it alone. The caption says
+ * what kind of example it is and why. Patterns use it for their compositions too.
+ */
+export function ExampleFrame({ name, kind = "other", description, code, href, children, }) {
+    const [theme, setTheme] = useState();
+    const [narrow, setNarrow] = useState(false);
+    const mark = MARK[kind];
+    const Icon = mark.icon;
+    const views = [{ value: "preview", label: "Preview", icon: Eye }, ...(code ? [{ value: "code", label: "Code", icon: Code }] : [])];
+    return (_jsxs("figure", { "data-slot": "example", "data-kind": kind, className: "flex min-w-0 flex-col gap-3", children: [_jsxs(Segmented, { defaultValue: "preview", className: "overflow-hidden rounded-xl border border-border bg-surface text-surface-foreground shadow-xs", children: [_jsxs(Toolbar, { children: [_jsx(SegmentedList, { items: views, label: `${name}: preview or code` }), _jsxs("span", { className: "flex items-center gap-0.5", children: [_jsx(IconButton, { icon: Smartphone, label: "Phone width", pressed: narrow, onClick: () => setNarrow(!narrow) }), _jsx(IconButton, { icon: theme === "dark" ? Sun : Moon, label: theme === "dark" ? "Show in light mode" : "Show in dark mode", pressed: theme !== undefined, onClick: () => setTheme(theme === "dark" ? "light" : "dark") }), code && _jsx(CopyButton, { text: code, label: "Copy code" }), href && _jsx(IconLink, { icon: Maximize2, label: "Open on its own", href: href })] })] }), _jsx(SegmentedPanel, { value: "preview", children: _jsx(Stage, { theme: theme, width: narrow ? 375 : undefined, className: kind === "canonical" ? "min-h-64" : "min-h-48", children: _jsx(Boundary, { label: name, children: children }) }) }), code && (_jsx(SegmentedPanel, { value: "code", children: _jsx(CodeView, { code: code, label: name, bare: true }) }))] }), (mark.label || description) && (_jsxs("figcaption", { className: "flex items-start gap-2 px-1", children: [mark.label && (_jsxs("span", { className: cx("inline-flex h-6 shrink-0 items-center gap-1.5 rounded-full pr-2.5 pl-2 text-xs font-medium", mark.tone), children: [Icon && _jsx(Icon, { "aria-hidden": true, className: "size-3.5" }), mark.label] })), description && _jsx("span", { className: "pt-0.5 text-sm", children: inline(description) })] }))] }));
+}

package/dist/glossary.d.ts

@@ -0,0 +1,5 @@
+import type { TermEntry } from "./lib/manifest-types.js";
+/** Every name in the system, searchable by its wrong forms too, so a wrong name finds the right one. A to Z. */
+export declare function Glossary({ terms }: {
+    terms: TermEntry[];
+}): import("react").JSX.Element;

package/dist/glossary.js

@@ -0,0 +1,21 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ArrowRight, Search } from "lucide-react";
+import { useId, useState } from "react";
+import { TermRow } from "./lib/terms.js";
+/** Every name in the system, searchable by its wrong forms too, so a wrong name finds the right one. A to Z. */
+export function Glossary({ terms }) {
+    const id = useId();
+    const [query, setQuery] = useState("");
+    const q = query.trim().toLowerCase();
+    const matches = (q ? terms.filter((t) => t.name.toLowerCase().includes(q) || t.wrong?.some((w) => w.toLowerCase().includes(q))) : terms)
+        .slice()
+        .sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: "base" }));
+    const corrected = q ? terms.find((t) => t.wrong?.some((w) => w.toLowerCase() === q)) : undefined;
+    const letters = new Map();
+    for (const t of matches) {
+        const l = /[a-z]/i.test(t.name[0]) ? t.name[0].toUpperCase() : "#";
+        letters.set(l, [...(letters.get(l) ?? []), t]);
+    }
+    return (_jsxs("div", { "data-slot": "glossary", className: "flex flex-col gap-10", children: [_jsxs("div", { className: "flex max-w-3xl flex-col gap-4", children: [_jsx("label", { htmlFor: id, className: "sr-only", children: "Find a term" }), _jsxs("div", { className: "relative", children: [_jsx(Search, { "aria-hidden": true, className: "pointer-events-none absolute top-1/2 left-0 size-(--dt-size-md) -translate-y-1/2 text-muted-foreground" }), _jsx("input", { id: id, type: "search", value: query, onChange: (e) => setQuery(e.target.value), placeholder: "Find a term, or a name you half remember", className: "h-16 w-full border-0 border-b border-border bg-transparent pr-2 pl-10 text-2xl tracking-tight placeholder:text-muted-foreground/70 hover:border-input focus-visible:border-b-2 focus-visible:border-canvas-foreground focus-visible:outline-none" })] }), _jsx("div", { "aria-live": "polite", children: corrected ? (_jsxs("p", { "data-slot": "glossary-correction", className: "flex flex-wrap items-center gap-2 rounded-xl bg-muted/60 px-5 py-4 text-lg", children: ["Say ", _jsx("strong", { className: "font-semibold", children: corrected.name }), _jsx(ArrowRight, { "aria-hidden": true, className: "size-4 text-muted-foreground" }), _jsxs("span", { className: "text-muted-foreground", children: ["not \u201C", query.trim(), "\u201D"] })] })) : (_jsx("p", { className: "text-sm text-muted-foreground", children: q ? `${matches.length} ${matches.length === 1 ? "term" : "terms"}` : `${terms.length} terms, A to Z. Search by the right name or a wrong one.` })) })] }), _jsx("div", { "data-slot": "glossary-list", className: "flex flex-col gap-8", children: [...letters].map(([letter, list]) => (_jsxs("section", { "aria-label": letter, className: "grid gap-x-8 lg:grid-cols-[3rem_minmax(0,1fr)]", children: [_jsx("h3", { className: "pt-5 text-2xl tracking-tight text-muted-foreground lg:sticky lg:top-24 lg:self-start", children: letter }), _jsx("div", { children: _jsx("dl", { children: list.map((t) => (_jsx(TermRow, { term: t, kind: true }, `${t.kind}:${t.name}`))) }) })] }, letter))) })] }));
+}

package/dist/imagery.d.ts

@@ -0,0 +1,6 @@
+import type { AssetEntry } from "./lib/manifest-types.js";
+/** The approved icons and imagery, each on a stage with how to use it; an icon is shown at its three sizes too. */
+export declare function Imagery({ assets, kinds }: {
+    assets: AssetEntry[];
+    kinds?: AssetEntry["kind"][];
+}): import("react").JSX.Element;

package/dist/imagery.js

@@ -0,0 +1,17 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useLookup } from "./lib/lookup.js";
+import { inline } from "./lib/text.js";
+import { Stage } from "./lib/ui.js";
+/** The approved icons and imagery, each on a stage with how to use it; an icon is shown at its three sizes too. */
+export function Imagery({ assets, kinds = ["icon", "image", "other"] }) {
+    const lookup = useLookup();
+    const shown = assets.filter((a) => kinds.includes(a.kind));
+    if (shown.length === 0)
+        return _jsx("p", { className: "text-sm text-muted-foreground", children: "No icons or imagery in the brand folder yet." });
+    return (_jsx("ul", { "data-slot": "imagery", className: "grid grid-cols-1 gap-4 sm:grid-cols-2 xl:grid-cols-3", children: shown.map((a) => {
+            const src = lookup.assetUrl(a);
+            const icon = a.kind === "icon";
+            return (_jsx("li", { className: "min-w-0", children: _jsxs("figure", { "data-slot": "asset", className: "flex h-full flex-col overflow-hidden rounded-2xl border border-border bg-surface text-surface-foreground shadow-xs", children: [_jsx(Stage, { className: "h-44 p-6", children: src ? (icon ? (_jsx("span", { "aria-hidden": !a.alt, role: a.alt ? "img" : undefined, "aria-label": a.alt || undefined, className: "block size-14 bg-current", style: { mask: `url(${src}) center / contain no-repeat`, WebkitMask: `url(${src}) center / contain no-repeat` } })) : (_jsx("img", { src: src, alt: a.alt ?? "", className: "max-h-full max-w-full rounded-md object-contain" }))) : (_jsx("span", { className: "font-mono text-xs text-muted-foreground", children: a.file })) }), _jsxs("figcaption", { className: "flex flex-1 flex-col gap-2 border-t border-border p-4 text-sm", children: [_jsxs("span", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: "text-lg", children: a.name }), icon && src ? (_jsx("span", { "aria-hidden": true, className: "flex items-end gap-2 text-muted-foreground", children: [16, 20, 24].map((size) => (_jsx("span", { className: "block bg-current", style: { width: size, height: size, mask: `url(${src}) center / contain no-repeat`, WebkitMask: `url(${src}) center / contain no-repeat` } }, size))) })) : (_jsx("span", { className: "rounded-full bg-muted px-2 py-0.5 font-mono text-xs text-muted-foreground", children: a.kind }))] }), _jsx("span", { className: "text-muted-foreground", children: a.usage ? inline(a.usage) : "No usage notes yet." }), _jsxs("span", { className: "mt-auto pt-1 font-mono text-xs text-muted-foreground", children: [a.file, a.width && a.height ? ` · ${a.width} × ${a.height}` : ""] })] })] }) }, a.file));
+        }) }));
+}

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @designtools/docs: every block, for a project composing its own pages. Most
+ * projects use `@designtools/docs/next` instead, which composes them.
+ */
+export { A11yPanel, AxeReport, useAxe } from "./a11y-panel.js";
+export { AdherenceSummary } from "./adherence-summary.js";
+export { AgentInstructions, AgentView } from "./agent-view.js";
+export { Anatomy } from "./anatomy.js";
+export { AskClaude } from "./ask-claude.js";
+export { CodeView } from "./code-view.js";
+export { ExampleFrame, Examples } from "./examples.js";
+export { Glossary } from "./glossary.js";
+export { Imagery } from "./imagery.js";
+export { LogoUsage } from "./logo-usage.js";
+export { PageActions } from "./page-actions.js";
+export { Pattern } from "./pattern.js";
+export { Playground } from "./playground.js";
+export { PreviewComposition, PreviewExample, PreviewFrame, PreviewSurface } from "./preview-frame.js";
+export { PropsTable } from "./props-table.js";
+export { Rule, RuleIndex } from "./rule.js";
+export { Scale } from "./scale.js";
+export { DocsSearch } from "./search.js";
+export { type DocsLink, DocsFooter, DocsHeader, DocsSection, DocsShell } from "./shell.js";
+export { Standards } from "./standards.js";
+export { PageContrast, RampSwatches, SemanticSwatches } from "./swatches.js";
+export { ThemeSwitch, themeScript, useThemeScript } from "./theme-switch.js";
+export { TypeRamp } from "./type-ramp.js";
+export { Usage } from "./usage.js";
+export { VariantMatrix } from "./variant-matrix.js";
+export { VoiceTerms } from "./voice-terms.js";
+export { Workbench } from "./workbench.js";
+export { Live } from "./lib/live.js";
+export { type Registry, RegistryProvider, useRegistry } from "./lib/registry.js";
+export * from "./lib/manifest-types.js";
+export type { AdherenceReport } from "./lib/adherence-types.js";

package/dist/index.js

@@ -0,0 +1,34 @@
+/**
+ * @designtools/docs: every block, for a project composing its own pages. Most
+ * projects use `@designtools/docs/next` instead, which composes them.
+ */
+export { A11yPanel, AxeReport, useAxe } from "./a11y-panel.js";
+export { AdherenceSummary } from "./adherence-summary.js";
+export { AgentInstructions, AgentView } from "./agent-view.js";
+export { Anatomy } from "./anatomy.js";
+export { AskClaude } from "./ask-claude.js";
+export { CodeView } from "./code-view.js";
+export { ExampleFrame, Examples } from "./examples.js";
+export { Glossary } from "./glossary.js";
+export { Imagery } from "./imagery.js";
+export { LogoUsage } from "./logo-usage.js";
+export { PageActions } from "./page-actions.js";
+export { Pattern } from "./pattern.js";
+export { Playground } from "./playground.js";
+export { PreviewComposition, PreviewExample, PreviewFrame, PreviewSurface } from "./preview-frame.js";
+export { PropsTable } from "./props-table.js";
+export { Rule, RuleIndex } from "./rule.js";
+export { Scale } from "./scale.js";
+export { DocsSearch } from "./search.js";
+export { DocsFooter, DocsHeader, DocsSection, DocsShell } from "./shell.js";
+export { Standards } from "./standards.js";
+export { PageContrast, RampSwatches, SemanticSwatches } from "./swatches.js";
+export { ThemeSwitch, themeScript, useThemeScript } from "./theme-switch.js";
+export { TypeRamp } from "./type-ramp.js";
+export { Usage } from "./usage.js";
+export { VariantMatrix } from "./variant-matrix.js";
+export { VoiceTerms } from "./voice-terms.js";
+export { Workbench } from "./workbench.js";
+export { Live } from "./lib/live.js";
+export { RegistryProvider, useRegistry } from "./lib/registry.js";
+export * from "./lib/manifest-types.js";