@designtools/blocks 0.0.0-stage → 0.2.0

package/registry/lib/markdown.ts

@@ -0,0 +1,288 @@
+/**
+ * The markdown form of every block, generated from the manifest rather than
+ * converted from HTML, so the same manifest always gives the same markdown.
+ * A docs page answers `Accept: text/markdown` (or `.md`) with these; the agent
+ * tabs show them; copy-page copies them.
+ *
+ * Structure survives as typed fences (```rule, ```example, ```do, ```dont) so
+ * an agent can tell what each part is. Status travels with everything.
+ */
+
+import { groupByCategory, importOf, ramps, semanticColours, shortName, slugOf, tokensOfTier, typeScale, valueIn } from "./manifest";
+import type { AdherenceReport } from "./adherence-types";
+import { standardsSections } from "./standards";
+import type {
+  AssetEntry,
+  ComponentEntry,
+  ComponentsManifest,
+  ExampleRef,
+  PatternEntry,
+  PropEntry,
+  RuleEntry,
+  TermEntry,
+  TokenTier,
+  TokensManifest,
+} from "./manifest-types";
+
+// ------------------------------------------------------------ headers
+
+/** A generated page: the system version and commit it came from. Never a review date, which would be invented. */
+export function generatedHeader(provenance: string): string {
+  return `> ${provenance}. Generated from the code; do not edit this page by hand.\n\n`;
+}
+
+/** An editorial page: who wrote it, when it was last reviewed, and whether it is settled. */
+export function editorialHeader({ author, reviewer, reviewed, status }: { author: string; reviewer?: string; reviewed: string; status: "draft" | "published" }): string {
+  return `> Written by ${author}. ${reviewer ? `Reviewed by ${reviewer}, ${reviewed}` : `Last reviewed ${reviewed}`}. Status: ${status}.\n\n`;
+}
+
+// ------------------------------------------------------------ components
+
+/**
+ * A component as an agent reads it. `level` is its heading's: 1 when it is the
+ * whole page (`/components/button.md`), 2 inside a longer document (`context.md`),
+ * so a page never opens with the same heading twice.
+ */
+export function componentMarkdown(entry: ComponentEntry, level: 1 | 2 = 2): string {
+  const out: string[] = [`${"#".repeat(level)} ${entry.name}`, ""];
+  out.push(`Status: ${entry.status ?? "not set"}${entry.statusNote ? `. ${entry.statusNote}` : ""}`, "");
+  out.push(`\`import { ${entry.export} } from "${importOf(entry)}"\``, "");
+  if (entry.description) out.push(entry.description, "");
+
+  if (entry.usage) {
+    if (entry.usage.use) out.push(`Use it for: ${entry.usage.use}`);
+    if (entry.usage.avoid) out.push(`Not for: ${entry.usage.avoid}`);
+    if (entry.usage.instead?.length) out.push(`Instead: ${entry.usage.instead.join(", ")}`);
+    out.push("");
+  }
+
+  if (entry.examples) out.push(...examplesMarkdown(entry.examples.canonical, entry.examples.do, entry.examples.dont, entry.examples.other));
+
+  const own = Object.entries(entry.props).filter(([, p]) => !p.from);
+  const inherited = Object.entries(entry.props).filter(([, p]) => p.from);
+  if (own.length) {
+    out.push("Props:");
+    for (const [name, p] of own) out.push(`- ${propLine(name, p)}`);
+    out.push("");
+  }
+  const also = [
+    ...(entry.inherits ?? []).map((x) => (/^[a-z][\w-]*$/.test(x) ? `every <${x}> prop` : `every prop of ${x}`)),
+    ...[...new Set(inherited.map(([, p]) => p.from!))].map((pkg) => `${inherited.filter(([, p]) => p.from === pkg).length} props from ${pkg}`),
+  ];
+  if (also.length) out.push(`Also accepts ${also.join(", ")}.`, "");
+
+  const variants = entry.variants;
+  if (variants?.axes.length) {
+    const from = variants.from === "props" ? "its props" : `the ${variants.from}() config \`${variants.config}\``;
+    out.push(`Variants, from ${from}. Use these, not classes, to change how it looks:`);
+    for (const axis of variants.axes) {
+      out.push(`- \`${axis.name}\`: ${axis.options.map((o) => (o.name === axis.default ? `${o.name} (default)` : o.name)).join(" | ")}`);
+      for (const o of axis.options) if (o.description) out.push(`  - \`${o.name}\`: ${o.description}`);
+    }
+    out.push("");
+  }
+
+  if (entry.slots.length) out.push(`Parts (\`data-slot\`): ${entry.slots.map((s) => `\`${s}\``).join(", ")}. Keep these on the elements they mark.`, "");
+  if (entry.a11y?.role || entry.a11y?.keyboard) {
+    out.push(`Accessibility: ${[entry.a11y.role && `role \`${entry.a11y.role}\``, entry.a11y.keyboard && `keys ${entry.a11y.keyboard.join(", ")}`].filter(Boolean).join("; ")}.`, "");
+  }
+  if (entry.replaces?.length) out.push(`Use it instead of a raw ${entry.replaces.map((r) => `\`<${r}>\``).join(" or ")}.`, "");
+  for (const snippet of entry.snippets ?? []) out.push("```tsx", snippet, "```", "");
+  if (entry.primitive) out.push(`Wraps: ${entry.primitive}`, "");
+  if (entry.aria) out.push(`ARIA pattern: ${entry.aria}`, "");
+  if (entry.see?.length) out.push(`See also: ${entry.see.join(", ")}`, "");
+  return end(out);
+}
+
+function examplesMarkdown(canonical: ExampleRef | undefined, dos: ExampleRef[], donts: ExampleRef[], other: ExampleRef[]): string[] {
+  const out: string[] = [];
+  const fence = (kind: string, ex: ExampleRef) => {
+    if (ex.description) out.push(ex.description);
+    out.push(`\`\`\`${kind} ${ex.name}`, ex.code ?? `// ${ex.name}`, "```", "");
+  };
+  if (canonical) {
+    out.push("Copy this one:");
+    fence("example", canonical);
+  }
+  // in pairs, as the page shows them: the first do beside the first don't
+  for (let i = 0; i < Math.max(dos.length, donts.length); i++) {
+    if (dos[i]) fence("do", dos[i]);
+    if (donts[i]) fence("dont", donts[i]);
+  }
+  for (const o of other) fence("example", o);
+  return out;
+}
+
+function propLine(name: string, p: PropEntry): string {
+  const type = p.values ? p.values.map((v) => `"${v}"`).join(" | ") : p.type;
+  const bits = [`\`${name}${p.required ? "" : "?"}\`: \`${type}\``];
+  if (p.default !== undefined) bits.push(`default \`${p.default}\``);
+  if (p.deprecated !== undefined) bits.push(`deprecated${p.deprecated ? `: ${p.deprecated}` : ""}`);
+  let line = bits.join(", ");
+  if (p.description) line += `. ${p.description.replace(/\s*\n\s*/g, " ")}`;
+  return line;
+}
+
+// ------------------------------------------------------------ tokens
+
+const TIER_TITLES: [TokenTier, string][] = [
+  ["spacing", "Spacing"],
+  ["size", "Size"],
+  ["radius", "Radius"],
+  ["shadow", "Shadow"],
+  ["duration", "Duration"],
+  ["ease", "Easing"],
+  ["motion", "Motion"],
+];
+
+export function coloursMarkdown(tokens: TokensManifest): string {
+  const out = ["## Colour", "", "Write the semantic names in components (`bg-primary text-primary-foreground`). The ramps are what they point at.", ""];
+  out.push("| Token | Light | Dark |", "| --- | --- | --- |");
+  for (const c of semanticColours(tokens)) {
+    out.push(`| \`${c.name}\`${c.foreground ? ` with \`${c.foreground.name}\`` : ""} | ${cell(valueIn(c.background, "light"))} | ${cell(valueIn(c.background, "dark"))} |`);
+  }
+  out.push("");
+  for (const ramp of ramps(tokens)) out.push(`- ${ramp.family}: ${ramp.steps.map((s) => s.step).join(", ")}`);
+  return end(out);
+}
+
+export function typeMarkdown(tokens: TokensManifest): string {
+  const out = ["## Type", "", "| Size | Value | Line height |", "| --- | --- | --- |"];
+  for (const s of typeScale(tokens)) out.push(`| \`text-${shortName(s.size, "text")}\` | ${cell(s.size.values.default)} | ${cell(s.lineHeight?.values.default)} |`);
+  for (const [tier, title] of [["font", "Families"], ["font-weight", "Weights"], ["leading", "Leading"], ["tracking", "Tracking"]] as const) {
+    const rows = tokensOfTier(tokens, tier);
+    if (rows.length) out.push("", `${title}: ${rows.map((t) => `\`${shortName(t, tier)}\` ${t.values.default}`).join(", ")}`);
+  }
+  return end(out);
+}
+
+export function scaleMarkdown(tokens: TokensManifest): string {
+  const out = ["## Scale", ""];
+  for (const [tier, title] of TIER_TITLES) {
+    const rows = tokensOfTier(tokens, tier);
+    if (!rows.length) continue;
+    out.push(`### ${title}`, "", "| Token | Value | Notes |", "| --- | --- | --- |");
+    for (const t of rows) out.push(`| \`${t.name}\` | ${cell(t.values.default)} | ${cell(t.description)} |`);
+    out.push("");
+  }
+  return end(out);
+}
+
+// ------------------------------------------------------------ rules, patterns, taxonomy, brand
+
+export function ruleMarkdown(rule: RuleEntry): string {
+  const out = [`### ${rule.title}`, "", `\`\`\`rule id=${rule.id} kind=${rule.kind} status=${rule.status}`, rule.statement, "```", ""];
+  if (rule.threshold) out.push(`- Threshold: ${rule.threshold}`);
+  if (rule.appliesTo?.length) out.push(`- Applies to: ${rule.appliesTo.join(", ")}`);
+  if (rule.exceptions?.length) out.push(`- Exceptions: ${rule.exceptions.join("; ")}`);
+  if (rule.tokens?.length) out.push(`- Tokens: ${rule.tokens.map((t) => `\`${t}\``).join(", ")}`);
+  if (rule.check) out.push(`- Checked by: ${rule.check.kind}${rule.check.ref ? ` (\`${rule.check.ref}\`)` : ""}${rule.check.description ? `. ${rule.check.description}` : ""}`);
+  if (rule.status === "assumption") out.push("- Still an assumption: say so when you rely on it.");
+  if (out[out.length - 1] !== "") out.push("");
+  if (rule.rationale) out.push(rule.rationale, "");
+  return end(out);
+}
+
+/** A pattern; `level` as for `componentMarkdown`. */
+export function patternMarkdown(pattern: PatternEntry, level: 1 | 2 = 2): string {
+  const out = [`${"#".repeat(level)} ${pattern.name}`, "", `Status: ${pattern.status ?? "not set"}`, ""];
+  if (pattern.description) out.push(pattern.description, "");
+  if (pattern.components.length) out.push(`Composes: ${pattern.components.join(", ")}`, "");
+  for (const ex of pattern.examples) {
+    if (ex.description) out.push(ex.description);
+    out.push(`\`\`\`example ${ex.name}`, ex.code ?? `// ${ex.name}`, "```", "");
+  }
+  return end(out);
+}
+
+export function glossaryMarkdown(terms: TermEntry[]): string {
+  const out = ["## Vocabulary", "", "| Say | Not | Kind | Note |", "| --- | --- | --- | --- |"];
+  for (const t of terms) out.push(`| ${t.name} | ${cell(t.wrong?.join(", "))} | ${t.kind} | ${cell(t.note)} |`);
+  return end(out);
+}
+
+export function assetsMarkdown(assets: AssetEntry[]): string {
+  const out = ["## Brand assets", "", "| Asset | Kind | Minimum size | Clear space | Surfaces | Usage |", "| --- | --- | --- | --- | --- | --- |"];
+  for (const a of assets) {
+    out.push(`| ${a.name} (\`${a.file}\`) | ${a.kind} | ${cell(a.minSize)} | ${cell(a.clearSpace)} | ${cell(a.surfaces?.join(", "))} | ${cell(a.usage)} |`);
+  }
+  return end(out);
+}
+
+/** `.mxa/stack.json` baselines, or anything shaped like them: a table of name and target. */
+export function standardsMarkdown(baselines: Record<string, unknown>): string {
+  const out = ["## Standards", ""];
+  for (const section of standardsSections(baselines)) {
+    out.push(`### ${section.title}`, "");
+    for (const row of section.rows) out.push(row.label ? `- ${row.label}: ${row.value}` : row.value);
+    if (section.rows.length) out.push("");
+    for (const note of section.notes) out.push(note, "");
+  }
+  return end(out);
+}
+
+/** The adherence report, as a page: totals, then routes. It informs; it never blocks. */
+export function adherenceMarkdown(report: AdherenceReport): string {
+  const pct = (v: number | null) => (v === null ? "n/a" : `${Math.round(v * 1000) / 10}%`);
+  const s = report.summary;
+  const out = [
+    "## Adherence",
+    "",
+    "A report, never a gate.",
+    "",
+    `- From the system: ${pct(s.share)} (${s.systemUses} system uses, ${s.rawElements} raw elements a component replaces)`,
+    `- Off-system values: ${s.offSystemValues} (${s.offSystem.palette} palette steps, ${s.offSystem.arbitrary} arbitrary values, ${s.offSystem["status-text"] ?? 0} status colours as text)`,
+    `- Overrides: ${s.overrides}`,
+    `- Components never used: ${s.componentsUnused.length ? s.componentsUnused.join(", ") : "none"}`,
+    "",
+  ];
+  if (report.routes.length) {
+    out.push("| Route | From the system | Raw | Off-system | Overrides |", "| --- | --- | --- | --- | --- |");
+    for (const r of report.routes) out.push(`| \`${r.route}\` | ${pct(r.counts.share)} | ${r.counts.rawElements} | ${r.counts.offSystemValues} | ${r.counts.overrides} |`);
+  }
+  return end(out);
+}
+
+// ------------------------------------------------------------ the whole system
+
+/** Everything an agent needs, in one file: tokens first, then rules, patterns and components by category. */
+export function systemMarkdown(
+  input: { components: ComponentsManifest; tokens?: TokensManifest; rules?: RuleEntry[]; patterns?: PatternEntry[]; terms?: TermEntry[] },
+  title = "Design system",
+  provenance?: string,
+): string {
+  const out = [`# ${title}`, ""];
+  if (provenance) out.push(generatedHeader(provenance).trimEnd(), "");
+  out.push(
+    `Generated from \`${input.components.system}/manifest\`. Build screens from these components and tokens; do not restyle them with raw values. Carry each thing's status when you quote it.`,
+    "",
+  );
+  if (input.tokens) out.push(coloursMarkdown(input.tokens), typeMarkdown(input.tokens), scaleMarkdown(input.tokens));
+  if (input.rules?.length) out.push("# Rules", "", ...input.rules.map(ruleMarkdown));
+  if (input.patterns?.length) out.push("# Patterns", "", ...input.patterns.map((p) => patternMarkdown(p)));
+  for (const group of groupByCategory(input.components)) out.push(`# ${group.category}`, "", ...group.components.map((c) => componentMarkdown(c)));
+  if (input.terms?.length) out.push(glossaryMarkdown(input.terms));
+  return end(out);
+}
+
+/** Links an agent outside the repo can follow to the exact data. */
+export function manifestLinks(base: string): string {
+  return end([
+    "## The manifest, as data",
+    "",
+    ...["components", "tokens", "rules", "patterns", "taxonomy", "assets"].map((f) => `- [${f}.json](${base}/${f}.json)`),
+  ]);
+}
+
+export { slugOf };
+
+// ------------------------------------------------------------ helpers
+
+function cell(value: unknown): string {
+  if (value === undefined || value === null || value === "") return "";
+  return String(value).replace(/\|/g, "\\|").replace(/\s*\n\s*/g, " ");
+}
+
+function end(lines: string[]): string {
+  return lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+}

package/registry/lib/search.ts

@@ -0,0 +1,99 @@
+/**
+ * The docs search: components, their parts, rules, patterns and pages, matched
+ * fuzzily on their names, with the taxonomy's wrong forms as aliases, so
+ * "dropdown" finds Select and "buton" finds Button. It aids navigation and does
+ * nothing else: no full text, no index to build, because the manifest is small
+ * enough to search in the browser. The same query always gives the same order.
+ */
+
+import fuzzysort from "fuzzysort";
+import { groupFamilies, slugOf } from "./manifest";
+import type { ComponentsManifest, PatternEntry, RuleEntry, TermEntry } from "./manifest-types";
+
+export type SearchKind = "Component" | "Rule" | "Pattern" | "Page";
+
+export interface SearchItem {
+  kind: SearchKind;
+  label: string;
+  href: string;
+  /** The taxonomy's wrong forms for it: typing one finds it, and the result says so. */
+  wrong: string[];
+  /** Anything else it answers to quietly, such as a rule's id. */
+  also?: string[];
+  /** One short line under the label: a category, "part of Card", a rule's kind. */
+  detail?: string;
+}
+
+export interface SearchGroup {
+  kind: SearchKind;
+  /** `matched` is the wrong form a result was found by ("Dropdown" for Select). */
+  items: (SearchItem & { matched?: string })[];
+}
+
+const ORDER: SearchKind[] = ["Component", "Rule", "Pattern", "Page"];
+
+export function searchIndex({
+  manifest,
+  rules = [],
+  patterns = [],
+  terms = [],
+  pages = [],
+  basePath = "/design/system",
+}: {
+  manifest: ComponentsManifest;
+  rules?: RuleEntry[];
+  patterns?: PatternEntry[];
+  terms?: TermEntry[];
+  pages?: { label: string; href: string }[];
+  basePath?: string;
+}): SearchItem[] {
+  const wrong = new Map<string, string[]>();
+  for (const t of terms) if (t.wrong?.length) wrong.set(t.name.toLowerCase(), t.wrong);
+  const wrongOf = (name: string) => wrong.get(name.toLowerCase()) ?? [];
+
+  const items: SearchItem[] = [];
+  for (const { category, families } of groupFamilies(manifest)) {
+    for (const { head, parts } of families) {
+      items.push({ kind: "Component", label: head.name, href: `${basePath}/components/${slugOf(head)}`, wrong: wrongOf(head.name), detail: category });
+      for (const p of parts) {
+        items.push({ kind: "Component", label: p.name, href: `${basePath}/components/${slugOf(p)}`, wrong: wrongOf(p.name), detail: `part of ${head.name}` });
+      }
+    }
+  }
+  for (const r of rules) {
+    items.push({ kind: "Rule", label: r.title, href: `${basePath}/rules#${r.id}`, wrong: wrongOf(r.title), also: [r.id.replace(/-/g, " ")], detail: r.kind === "brand" ? "Brand rule" : "Interface rule" });
+  }
+  for (const p of patterns) items.push({ kind: "Pattern", label: p.name, href: `${basePath}/patterns/${p.id}`, wrong: wrongOf(p.name) });
+  for (const p of pages) items.push({ kind: "Page", label: p.label, href: p.href, wrong: [] });
+  return items;
+}
+
+/**
+ * The matches for a query, grouped by kind (components, rules, patterns, pages),
+ * best first within each, at most `perGroup` of each. A match found only through
+ * an alias says which: `matched` is the wrong form typed ("Dropdown").
+ */
+export function search(items: SearchItem[], query: string, perGroup = 6): SearchGroup[] {
+  const q = query.trim();
+  if (!q) return [];
+  const results = fuzzysort.go(q, items, { keys: ["label", (item: SearchItem) => item.wrong.join(" / "), (item: SearchItem) => (item.also ?? []).join(" / ")], limit: 0, threshold: 0.3 });
+  const ranked = [...results].sort(
+    (a, b) => b.score - a.score || ORDER.indexOf(a.obj.kind) - ORDER.indexOf(b.obj.kind) || (a.obj.label < b.obj.label ? -1 : a.obj.label > b.obj.label ? 1 : 0),
+  );
+  return ORDER.map((kind) => ({
+    kind,
+    items: ranked
+      .filter((r) => r.obj.kind === kind)
+      .slice(0, perGroup)
+      .map((r) => {
+        const viaWrong = (r[1]?.score ?? 0) > Math.max(r[0]?.score ?? 0, r[2]?.score ?? 0);
+        // the wrong form that matched best, to say why a result is here ("Dropdown" for Select)
+        const alias = viaWrong
+          ? r.obj.wrong
+              .map((a) => ({ a, score: fuzzysort.single(q, a)?.score ?? 0 }))
+              .sort((x, y) => y.score - x.score)[0]?.a
+          : undefined;
+        return alias ? { ...r.obj, matched: alias } : r.obj;
+      }),
+  })).filter((g) => g.items.length > 0);
+}

package/registry/lib/standards.ts

@@ -0,0 +1,82 @@
+/**
+ * The baselines a project records (`.mxa/stack.json` `baselines`), as a person
+ * reads them: titled sections, labelled rows, notes as sentences, and nothing
+ * shown for a value nobody has set. One shape, so the page and its markdown agree.
+ */
+
+export interface StandardsSection {
+  key: string;
+  title: string;
+  rows: { label: string; value: string }[];
+  notes: string[];
+}
+
+const TITLES: Record<string, string> = {
+  a11y: "Accessibility",
+  performance: "Performance budgets",
+  support: "Support",
+  seo: "Search and discovery",
+  licences: "Licences allowed",
+  textSize: "Text size",
+  touchTargets: "Touch targets",
+};
+
+const LABELS: Record<string, string> = {
+  browsers: "Browsers",
+  devices: "Devices",
+  viewports: "Viewports",
+  LCP: "Largest contentful paint",
+  CLS: "Cumulative layout shift",
+  TBT: "Total blocking time",
+  INP: "Interaction to next paint",
+  lighthouse: "Lighthouse score",
+  aiCrawlable: "Readable by AI crawlers",
+};
+
+const UNITS: Record<string, string> = { viewports: "px" };
+
+/** `textSize` to "Text size", `aiCrawlable` to "Ai crawlable": a fallback, never as good as a title. */
+export function humanise(key: string): string {
+  const words = key.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[-_]+/g, " ").toLowerCase();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+function shown(key: string, value: unknown): string | undefined {
+  if (value === null || value === undefined || value === "") return undefined;
+  if (typeof value === "boolean") return value ? "yes" : "no";
+  if (Array.isArray(value)) return value.length ? value.join(", ") + (UNITS[key] ? ` ${UNITS[key]}` : "") : "not agreed yet";
+  if (typeof value === "object") return undefined;
+  return String(value);
+}
+
+export function standardsSections(baselines: Record<string, unknown>): StandardsSection[] {
+  const keys = Object.keys(baselines).filter((k) => !k.startsWith("$"));
+  // `a11yNotes` is the note on `a11y`, not a section of its own
+  const noteOf = (k: string) => (/Notes?$/.test(k) && keys.includes(k.replace(/Notes?$/, "")) ? k.replace(/Notes?$/, "") : undefined);
+  const out: StandardsSection[] = [];
+  for (const key of keys) {
+    if (noteOf(key)) continue;
+    const value = baselines[key];
+    const section: StandardsSection = { key, title: TITLES[key] ?? humanise(key), rows: [], notes: [] };
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+        if (k.startsWith("$")) continue;
+        if (/^notes?$/i.test(k)) {
+          if (typeof v === "string" && v) section.notes.push(v);
+          continue;
+        }
+        const text = shown(k, v);
+        if (text !== undefined) section.rows.push({ label: LABELS[k] ?? humanise(k), value: text });
+      }
+    } else {
+      const text = shown(key, value);
+      if (text !== undefined) section.rows.push({ label: "", value: text });
+    }
+    for (const k of keys) {
+      const v = baselines[k];
+      if (noteOf(k) === key && typeof v === "string" && v) section.notes.push(v);
+    }
+    if (section.rows.length || section.notes.length) out.push(section);
+  }
+  return out;
+}

package/registry/lib/status.tsx

@@ -0,0 +1,32 @@
+import { cx } from "./cx";
+
+type Any = "stable" | "emerging" | "deprecated" | "confirmed" | "assumption" | "measured" | "draft" | "published";
+
+const LOOK: Record<Any, string> = {
+  stable: "bg-success-subdued text-success-subdued-foreground",
+  confirmed: "bg-success-subdued text-success-subdued-foreground",
+  published: "bg-success-subdued text-success-subdued-foreground",
+  emerging: "bg-warning-subdued text-warning-subdued-foreground",
+  assumption: "bg-warning-subdued text-warning-subdued-foreground",
+  // generated from the tokens: a fact, not a decision, so neither settled nor pending
+  measured: "bg-muted text-muted-foreground",
+  draft: "bg-warning-subdued text-warning-subdued-foreground",
+  deprecated: "bg-destructive-subdued text-destructive-subdued-foreground",
+};
+
+/** A status, everywhere one is shown: components, patterns, rules and editorial pages. Unset says so. */
+export function StatusBadge({ status, className }: { status?: Any; className?: string }) {
+  return (
+    <span
+      data-slot="status-badge"
+      data-status={status ?? "unset"}
+      className={cx(
+        "inline-flex h-6 items-center rounded-full px-2.5 text-xs font-medium",
+        status ? LOOK[status] : "border border-dashed border-border text-muted-foreground",
+        className,
+      )}
+    >
+      {status ?? "status not set"}
+    </span>
+  );
+}

package/registry/lib/text.tsx

@@ -0,0 +1,27 @@
+import type { ReactNode } from "react";
+
+/** JSDoc prose: paragraphs split on blank lines, `code` spans set as code. Nothing else is interpreted. */
+export function Prose({ text, className }: { text: string; className?: string }) {
+  return (
+    <>
+      {text.split(/\n{2,}/).map((p, i) => (
+        <p key={i} className={className}>
+          {inline(p)}
+        </p>
+      ))}
+    </>
+  );
+}
+
+/** One line of prose with its `code` spans. */
+export function inline(text: string): ReactNode[] {
+  return text.split(/(`[^`]+`)/).map((part, i) =>
+    /^`[^`]+`$/.test(part) ? (
+      <code key={i} className="rounded-sm bg-muted px-1 font-mono text-[0.9em]">
+        {part.slice(1, -1)}
+      </code>
+    ) : (
+      part
+    ),
+  );
+}

package/registry/logo-usage.tsx

@@ -0,0 +1,112 @@
+"use client";
+
+import { target } from "./lib/cx";
+import { assetUrl } from "./lib/lookup";
+import type { AssetEntry, RuleEntry } from "./lib/manifest-types";
+import { StatusBadge } from "./lib/status";
+import { inline } from "./lib/text";
+
+const LENGTH = /^\s*(\d+(?:\.\d+)?)(px|rem|em)\b/;
+
+/**
+ * Each logo on the surfaces it may sit on, at its minimum size, with its clear
+ * space drawn, and the brand rules that govern it: rules for every logo once,
+ * above them, and a rule naming one logo under that logo. Surfaces are semantic
+ * colour names painted from the light-mode tokens whatever the docs' mode, because a
+ * brand book's surfaces are fixed colours (white, the brand colour, an off-white),
+ * and dark mode would otherwise show the logo on a surface the brand forbids.
+ */
+export function LogoUsage({ assets, rules = [], rulesHref }: { assets: AssetEntry[]; rules?: RuleEntry[]; rulesHref?: string }) {
+  const logos = assets.filter((a) => a.kind === "logo");
+  if (logos.length === 0) return <p className="text-sm text-muted-foreground">No logos in the brand folder yet.</p>;
+  const brand = rules.filter((r) => r.kind === "brand");
+  const general = brand.filter((r) => (r.appliesTo ?? []).some((x) => ["logo", "logos"].includes(x.toLowerCase())));
+  return (
+    <div data-slot="logo-usage" className="flex flex-col gap-10">
+      {general.length > 0 && <RuleList rules={general} rulesHref={rulesHref} boxed />}
+      {logos.map((logo) => {
+        const src = assetUrl(logo);
+        const names = new Set([logo.name.toLowerCase(), logo.file.toLowerCase()]);
+        const own = brand.filter((r) => !general.includes(r) && (r.appliesTo ?? []).some((x) => names.has(x.toLowerCase())));
+        const clear = LENGTH.exec(logo.clearSpace ?? "");
+        const min = LENGTH.exec(logo.minSize ?? "");
+        return (
+          <section key={logo.file} data-slot="logo" className="flex flex-col gap-4">
+            <header className="flex flex-col gap-1">
+              <h3 className="font-semibold">{logo.name}</h3>
+              {logo.usage && <p className="max-w-prose text-sm text-muted-foreground">{inline(logo.usage)}</p>}
+            </header>
+            <ul className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
+              {(logo.surfaces?.length ? logo.surfaces : ["canvas"]).map((surface) => (
+                <li
+                  key={surface}
+                  data-slot="logo-surface"
+                  data-theme="light"
+                  className="flex min-h-40 flex-col items-center justify-center gap-3 rounded-lg border border-border p-6"
+                  style={{ background: `var(--${surface})`, color: `var(--${surface}-foreground, var(--canvas-foreground))` }}
+                >
+                  <span
+                    data-slot="logo-clear-space"
+                    className="inline-flex border border-dashed"
+                    style={{ padding: clear ? `${clear[1]}${clear[2]}` : "0.75rem", borderColor: "currentColor" }}
+                    title={`Clear space: ${logo.clearSpace ?? "not set"}`}
+                  >
+                    {src ? <img src={src} alt={logo.alt ?? logo.name} className="block h-12 w-auto" /> : <span className="text-xs">{logo.file}</span>}
+                  </span>
+                  <span className="font-mono text-xs">{surface}</span>
+                </li>
+              ))}
+            </ul>
+            <dl className="grid gap-x-6 gap-y-2 text-sm sm:grid-cols-[8rem_1fr]">
+              <dt className="font-medium">Minimum size</dt>
+              <dd className="flex items-center gap-3 text-muted-foreground">
+                {logo.minSize ?? "not set"}
+                {src && min && (
+                  // on the logo's own first surface, so a reversed (white) logo is visible at the size it is shown at
+                  <span
+                    data-slot="logo-min-size"
+                    data-theme="light"
+                    className="inline-flex rounded-md border border-border p-2"
+                    style={{ background: `var(--${logo.surfaces?.[0] ?? "canvas"})` }}
+                  >
+                    <img src={src} alt="" aria-hidden className="block w-auto" style={{ height: `${min[1]}${min[2]}` }} />
+                  </span>
+                )}
+              </dd>
+              <dt className="font-medium">Clear space</dt>
+              <dd className="text-muted-foreground">{logo.clearSpace ?? "not set"}</dd>
+              {logo.width && logo.height && (
+                <>
+                  <dt className="font-medium">Proportions</dt>
+                  <dd className="font-mono text-xs text-muted-foreground">
+                    {logo.width} × {logo.height}
+                  </dd>
+                </>
+              )}
+            </dl>
+            {own.length > 0 && <RuleList rules={own} rulesHref={rulesHref} />}
+          </section>
+        );
+      })}
+    </div>
+  );
+}
+
+function RuleList({ rules, rulesHref, boxed }: { rules: RuleEntry[]; rulesHref?: string; boxed?: boolean }) {
+  return (
+    <ul
+      data-slot="logo-rules"
+      className={boxed ? "flex flex-col gap-3 rounded-lg border border-border bg-surface p-4 text-sm text-surface-foreground" : "flex flex-col gap-2 text-sm"}
+    >
+      {rules.map((r) => (
+        <li key={r.id} className="flex flex-wrap items-baseline gap-2">
+          <StatusBadge status={r.status} />
+          <a href={rulesHref ? `${rulesHref}#${r.id}` : `#${r.id}`} className={`${target} inline-flex items-center font-medium underline underline-offset-2`}>
+            {r.title}
+          </a>
+          <span className="text-muted-foreground">{inline(r.statement)}</span>
+        </li>
+      ))}
+    </ul>
+  );
+}