@designtools/blocks 0.0.0-stage → 0.1.0

package/registry/lib/manifest.ts

@@ -0,0 +1,182 @@
+/**
+ * Reading the manifest: grouping components for navigation, and sorting tokens
+ * into the shapes the token blocks draw (semantic pairs, ramps, a type scale).
+ * Pure functions over the JSON; nothing here touches the DOM.
+ */
+
+import {
+  MANIFEST_SCHEMA,
+  type ComponentEntry,
+  type ComponentsManifest,
+  type TokenEntry,
+  type TokenTier,
+  type TokensManifest,
+} from "./manifest-types";
+
+/**
+ * A `components.json` import, typed and checked. A JSON import is typed by its
+ * literal contents, which do not line up with the schema, so read it through here.
+ */
+export function readComponents(json: unknown): ComponentsManifest {
+  checkSchema(json, "components.json");
+  return json as ComponentsManifest;
+}
+
+/** A `tokens.json` import, typed and checked. */
+export function readTokens(json: unknown): TokensManifest {
+  checkSchema(json, "tokens.json");
+  return json as TokensManifest;
+}
+
+function checkSchema(json: unknown, file: string) {
+  const schema = (json as { schema?: unknown } | null)?.schema;
+  if (schema !== MANIFEST_SCHEMA) {
+    throw new Error(
+      `${file} has schema ${String(schema)}; these blocks read schema ${MANIFEST_SCHEMA}. Rebuild it with a matching @designtools/manifest.`,
+    );
+  }
+}
+
+/** Where components without `@category` are listed. */
+export const DEFAULT_CATEGORY = "Components";
+
+/** The key the generated registry files a component under: `src/ds/badge/badge.tsx#Badge`. */
+export function componentKey(entry: Pick<ComponentEntry, "source" | "export">): string {
+  return `${entry.source}#${entry.export}`;
+}
+
+/** `RadioGroup` → `radio-group`, for URLs. */
+export function slugOf(entry: Pick<ComponentEntry, "name">): string {
+  return entry.name
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/[^A-Za-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .toLowerCase();
+}
+
+export function findBySlug(manifest: ComponentsManifest, slug: string): ComponentEntry | undefined {
+  return manifest.components.find((c) => slugOf(c) === slug);
+}
+
+export interface CategoryGroup {
+  category: string;
+  components: ComponentEntry[];
+}
+
+/**
+ * Categories in name order, uncategorised last; components by name within each.
+ * A part without its own `@category` (CardHeader) joins the category of a
+ * component in the same file (Card), so a family stays together.
+ */
+export function groupByCategory(manifest: ComponentsManifest): CategoryGroup[] {
+  const fileCategory = new Map<string, string>();
+  for (const c of manifest.components) if (c.category && !fileCategory.has(c.source)) fileCategory.set(c.source, c.category);
+  const groups = new Map<string, ComponentEntry[]>();
+  for (const c of manifest.components) {
+    const key = c.category ?? fileCategory.get(c.source) ?? DEFAULT_CATEGORY;
+    groups.set(key, [...(groups.get(key) ?? []), c]);
+  }
+  return [...groups.entries()]
+    .sort(([a], [b]) => (a === DEFAULT_CATEGORY ? 1 : b === DEFAULT_CATEGORY ? -1 : a < b ? -1 : a > b ? 1 : 0))
+    .map(([category, components]) => ({ category, components }));
+}
+
+export function tokensOfTier(manifest: TokensManifest, tier: TokenTier): TokenEntry[] {
+  return manifest.tokens.filter((t) => t.tier === tier);
+}
+
+export type Mode = "light" | "dark";
+
+/** A token's value in a mode, falling back to its mode-invariant value. */
+export function valueIn(token: TokenEntry, mode: Mode): string | undefined {
+  return token.values[mode] ?? token.values.default;
+}
+
+export interface Ramp {
+  /** `primary` for `--color-primary-500`. */
+  family: string;
+  steps: { step: string; token: TokenEntry }[];
+}
+
+/** `--color-<family>-<step>` primitives, families in source order, steps as declared. */
+export function ramps(manifest: TokensManifest): Ramp[] {
+  const out = new Map<string, Ramp>();
+  for (const t of manifest.tokens) {
+    const m = /^--color-([a-z][\w-]*?)-(\d+)$/.exec(t.name);
+    if (!m) continue;
+    const ramp = out.get(m[1]) ?? { family: m[1], steps: [] };
+    ramp.steps.push({ step: m[2], token: t });
+    out.set(m[1], ramp);
+  }
+  return [...out.values()];
+}
+
+export interface SemanticColour {
+  /** `--primary` */
+  name: string;
+  background: TokenEntry;
+  /** `--primary-foreground`, when the generator paired one. */
+  foreground?: TokenEntry;
+}
+
+/**
+ * Semantic colours (unprefixed, mode-aware: `--primary`, `--canvas`), each with
+ * its foreground when it has one. The `--color-*` bridge that points Tailwind
+ * at them is left out: it is the same colour under a second name.
+ */
+export function semanticColours(manifest: TokensManifest): SemanticColour[] {
+  const colours = manifest.tokens.filter((t) => t.tier === "color" && !t.name.startsWith("--color-"));
+  const byName = new Map(colours.map((t) => [t.name, t]));
+  return colours
+    .filter((t) => !t.name.endsWith("-foreground"))
+    .map((background) => {
+      const foreground = byName.get(`${background.name}-foreground`);
+      return foreground ? { name: background.name, background, foreground } : { name: background.name, background };
+    });
+}
+
+export interface TypeStep {
+  /** `--text-sm` */
+  name: string;
+  size: TokenEntry;
+  lineHeight?: TokenEntry;
+  letterSpacing?: TokenEntry;
+  fontWeight?: TokenEntry;
+}
+
+/** `--text-*` sizes with the `--text-*--line-height` (and tracking, weight) Tailwind pairs with them. */
+export function typeScale(manifest: TokensManifest): TypeStep[] {
+  const text = tokensOfTier(manifest, "text");
+  const byName = new Map(text.map((t) => [t.name, t]));
+  return text
+    .filter((t) => !t.name.includes("--", 2) && !/shadow/.test(t.name))
+    .map((size) => {
+      const step: TypeStep = { name: size.name, size };
+      const lh = byName.get(`${size.name}--line-height`);
+      const ls = byName.get(`${size.name}--letter-spacing`);
+      const fw = byName.get(`${size.name}--font-weight`);
+      if (lh) step.lineHeight = lh;
+      if (ls) step.letterSpacing = ls;
+      if (fw) step.fontWeight = fw;
+      return step;
+    });
+}
+
+/** `--radius-md` → `md`; `--spacing` → `spacing`. */
+export function shortName(token: Pick<TokenEntry, "name">, prefix?: string): string {
+  const name = token.name.replace(/^--/, "");
+  return prefix && name.startsWith(`${prefix}-`) ? name.slice(prefix.length + 1) : name;
+}
+
+/**
+ * Descriptions run over several tokens (one comment above a group), so show a
+ * description only where it changes.
+ */
+export function withGroupDescriptions<T extends { description?: string }>(items: T[]): (T & { groupDescription?: string })[] {
+  let last: string | undefined;
+  return items.map((item) => {
+    const changed = item.description !== last;
+    last = item.description;
+    return changed && item.description ? { ...item, groupDescription: item.description } : item;
+  });
+}

package/registry/lib/markdown.ts

@@ -0,0 +1,283 @@
+/**
+ * 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, ramps, semanticColours, shortName, slugOf, tokensOfTier, typeScale, valueIn } from "./manifest";
+import type { AdherenceReport } from "./adherence-types";
+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, reviewed, status }: { author: string; reviewed: string; status: "draft" | "published" }): string {
+  return `> Written by ${author}. Last reviewed ${reviewed}. Status: ${status}.\n\n`;
+}
+
+// ------------------------------------------------------------ components
+
+export function componentMarkdown(entry: ComponentEntry): string {
+  const out: string[] = [`## ${entry.name}`, ""];
+  out.push(`Status: ${entry.status ?? "not set"}${entry.statusNote ? `. ${entry.statusNote}` : ""}`, "");
+  out.push(`\`import { ${entry.export} } from "${entry.source.replace(/\.(tsx?|jsx?)$/, "")}"\``, "");
+  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);
+  }
+  for (const d of dos) fence("do", d);
+  for (const d of donts) fence("dont", d);
+  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);
+}
+
+export function patternMarkdown(pattern: PatternEntry): string {
+  const out = [`## ${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", "", "| Standard | Target |", "| --- | --- |"];
+  for (const [name, value] of flatten(baselines)) out.push(`| ${name} | ${cell(value)} |`);
+  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)`,
+    `- 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(patternMarkdown));
+  for (const group of groupByCategory(input.components)) out.push(`# ${group.category}`, "", ...group.components.map(componentMarkdown));
+  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 flatten(value: unknown, prefix = ""): [string, string][] {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return Object.entries(value as Record<string, unknown>)
+      .filter(([k]) => !k.startsWith("$"))
+      .flatMap(([k, v]) => flatten(v, prefix ? `${prefix} ${k}` : k));
+  }
+  if (Array.isArray(value)) return value.length ? [[prefix, value.join(", ")]] : [];
+  return [[prefix, String(value)]];
+}
+
+function end(lines: string[]): string {
+  return lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+}

package/registry/lib/status.tsx

@@ -0,0 +1,30 @@
+import { cx } from "./cx";
+
+type Any = "stable" | "emerging" | "deprecated" | "confirmed" | "assumption" | "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",
+  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,87 @@
+"use client";
+
+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. Surfaces are semantic colour
+ * names, so the panels paint from the tokens.
+ */
+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>;
+  return (
+    <div data-slot="logo-usage" className="flex flex-col gap-10">
+      {logos.map((logo) => {
+        const src = assetUrl(logo);
+        const names = new Set(["logo", "logos", logo.name.toLowerCase(), logo.file.toLowerCase()]);
+        const governing = rules.filter((r) => r.kind === "brand" && (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"
+                  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 opacity-80">{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 && <img src={src} alt="" aria-hidden className="w-auto" style={{ height: `${min[1]}${min[2]}` }} />}
+              </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>
+            {governing.length > 0 && (
+              <ul data-slot="logo-rules" className="flex flex-col gap-2 text-sm">
+                {governing.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="font-medium underline underline-offset-2">
+                      {r.title}
+                    </a>
+                    <span className="text-muted-foreground">{inline(r.statement)}</span>
+                  </li>
+                ))}
+              </ul>
+            )}
+          </section>
+        );
+      })}
+    </div>
+  );
+}