@designtools/docs 0.2.3 → 0.3.0

package/src/anatomy.tsx

@@ -1,8 +1,9 @@
 "use client";
 
 import { Live } from "./lib/live";
+import { wrapIn } from "./lib/wrap";
 import { Layers } from "lucide-react";
-import { useEffect, useId, useRef, useState, type ReactNode } from "react";
+import { type ReactElement, type ReactNode, useEffect, useId, useRef, useState } from "react";
 import { cx, target } from "./lib/cx";
 import { renderExample, useLookup } from "./lib/lookup";
 import type { ComponentEntry } from "./lib/manifest-types";
@@ -16,8 +17,11 @@ import { Frame, Stage, Toolbar } from "./lib/ui";
 export function Anatomy({
   entry,
   children,
+  wrap,
 }: {
   entry: ComponentEntry;
+  /** What the bare component must sit in to work, when there is no example to show. */
+  wrap?: ReactElement<{ children?: ReactNode }>;
   /** The example to point into. Defaults to the canonical example, else the bare component. */
   children?: ReactNode;
 }) {
@@ -47,9 +51,7 @@ export function Anatomy({
   const first = entry.examples?.canonical?.name ?? entry.examples?.do[0]?.name ?? entry.examples?.other[0]?.name;
   const example =
     children ?? (module && first ? renderExample(module[first], first) : Component ? (
-        <Live>
-          <Component>{entry.name}</Component>
-        </Live>
+        <Live>{wrapIn(wrap, <Component>{entry.name}</Component>)}</Live>
       ) : null);
 
   const shown = entry.slots.filter((slot) => counts[slot]).length;

package/src/glossary.tsx

@@ -3,9 +3,9 @@
 import { ArrowRight, Search } from "lucide-react";
 import { useId, useState } from "react";
 import type { TermEntry } from "./lib/manifest-types";
-import { TermRow } from "./lib/terms";
+import { TermHead, TermRow } from "./lib/terms";
 
-/** Every name in the system, searchable by its wrong forms too, so a wrong name finds the right one. A to Z. */
+/** Every name in the system, A to Z, searchable by its wrong forms too, so a wrong name finds the right one. */
 export function Glossary({ terms }: { terms: TermEntry[] }) {
   const id = useId();
   const [query, setQuery] = useState("");
@@ -14,12 +14,6 @@ export function Glossary({ terms }: { terms: TermEntry[] }) {
     .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<string, TermEntry[]>();
-  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 (
     <div data-slot="glossary" className="flex flex-col gap-10">
       <div className="flex max-w-3xl flex-col gap-4">
@@ -46,24 +40,18 @@ export function Glossary({ terms }: { terms: TermEntry[] }) {
             </p>
           ) : (
             <p className="text-sm text-muted-foreground">
-              {q ? `${matches.length} ${matches.length === 1 ? "term" : "terms"}` : `${terms.length} terms, A to Z. Search by the right name or a wrong one.`}
+              {q ? `${matches.length} ${matches.length === 1 ? "term" : "terms"}` : `${terms.length} terms. Search by the right name or a wrong one.`}
             </p>
           )}
         </div>
       </div>
-      <div data-slot="glossary-list" className="flex flex-col gap-8">
-        {[...letters].map(([letter, list]) => (
-          <section key={letter} aria-label={letter} className="grid gap-x-8 lg:grid-cols-[3rem_minmax(0,1fr)]">
-            <h3 className="pt-5 text-2xl tracking-tight text-muted-foreground lg:sticky lg:top-24 lg:self-start">{letter}</h3>
-            <div>
-              <dl>
-                {list.map((t) => (
-                  <TermRow key={`${t.kind}:${t.name}`} term={t} kind />
-                ))}
-              </dl>
-            </div>
-          </section>
-        ))}
+      <div data-slot="glossary-list">
+        <TermHead />
+        <dl>
+          {matches.map((t) => (
+            <TermRow key={`${t.kind}:${t.name}`} term={t} kind />
+          ))}
+        </dl>
       </div>
     </div>
   );

package/src/lib/adherence-types.ts

@@ -35,6 +35,8 @@ export interface AdherenceReport {
   elements: ElementUsage[];
   /** Files a scanner could not parse, sorted by path. Their numbers are missing from the report. */
   skipped: SkippedFile[];
+  /** Checks that could not run, and why; present only when one couldn't. Their counts read zero for want of checking. */
+  unchecked?: string[];
 }
 
 /** The numbers every level of the report shares: the whole product, a route, a file. */

package/src/lib/colour.ts

@@ -0,0 +1,104 @@
+/**
+ * Colour values as hex, on the server, for files read outside a browser
+ * (design.md): a slide tool or a document template takes `#12171d`, not
+ * `oklch(19.78% 0.0144 253.17)` or `var(--color-neutral-950)`. Handles what the
+ * token generator writes: oklch, hex, rgb and a `var()` chain through the
+ * manifest. Anything else (color-mix, a keyword it doesn't know) has no hex.
+ */
+
+export type Rgb = [number, number, number];
+
+/** The sRGB a browser paints for a CSS colour, 0 to 255 per channel, or undefined when it can't be worked out here. */
+export function parseColour(css: string): Rgb | undefined {
+  const value = css.trim().toLowerCase();
+  if (value === "white") return [255, 255, 255];
+  if (value === "black") return [0, 0, 0];
+
+  const hex = /^#([0-9a-f]{3,8})$/.exec(value)?.[1];
+  if (hex) {
+    const full = hex.length <= 4 ? [...hex].map((c) => c + c).join("") : hex;
+    if (full.length !== 6 && full.length !== 8) return undefined;
+    return [0, 2, 4].map((i) => Number.parseInt(full.slice(i, i + 2), 16)) as Rgb;
+  }
+
+  const rgb = /^rgba?\(([^)]+)\)$/.exec(value)?.[1];
+  if (rgb) {
+    const parts = rgb.split(/[\s,/]+/).filter(Boolean).slice(0, 3);
+    if (parts.length < 3) return undefined;
+    return parts.map((p) => Math.round(p.endsWith("%") ? (Number.parseFloat(p) / 100) * 255 : Number.parseFloat(p))) as Rgb;
+  }
+
+  const oklch = /^oklch\(([^)]+)\)$/.exec(value)?.[1];
+  if (oklch) {
+    const [l, c, h] = oklch.split("/")[0].trim().split(/\s+/);
+    if (h === undefined) return undefined;
+    const L = l.endsWith("%") ? Number.parseFloat(l) / 100 : Number.parseFloat(l);
+    const C = c.endsWith("%") ? (Number.parseFloat(c) / 100) * 0.4 : Number.parseFloat(c);
+    const H = h === "none" ? 0 : Number.parseFloat(h);
+    if ([L, C, H].some(Number.isNaN)) return undefined;
+    return oklchToRgb(L, C, H);
+  }
+  return undefined;
+}
+
+/** `#rrggbb` for a CSS colour, or undefined. */
+export function toHex(css: string): string | undefined {
+  const rgb = parseColour(css);
+  return rgb && `#${rgb.map((v) => v.toString(16).padStart(2, "0")).join("")}`;
+}
+
+/** WCAG 2 relative luminance. */
+export function luminance([r, g, b]: Rgb): number {
+  const channel = (v: number) => {
+    const s = v / 255;
+    return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+
+/** WCAG 2 contrast ratio between two colours. */
+export function ratio(a: Rgb, b: Rgb): number {
+  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/**
+ * OKLCH to sRGB. Hex holds sRGB only, so a colour outside it keeps its
+ * lightness and hue and loses chroma until it fits, rather than being clipped
+ * channel by channel, which shifts its hue.
+ */
+function oklchToRgb(L: number, C: number, H: number): Rgb {
+  let linear = oklabToLinear(L, C, H);
+  if (!inGamut(linear)) {
+    let lo = 0;
+    let hi = C;
+    for (let i = 0; i < 24; i++) {
+      const mid = (lo + hi) / 2;
+      if (inGamut(oklabToLinear(L, mid, H))) lo = mid;
+      else hi = mid;
+    }
+    linear = oklabToLinear(L, lo, H);
+  }
+  return linear.map((v) => Math.round(gamma(Math.min(1, Math.max(0, v))) * 255)) as Rgb;
+}
+
+function oklabToLinear(L: number, C: number, H: number): [number, number, number] {
+  const a = C * Math.cos((H * Math.PI) / 180);
+  const b = C * Math.sin((H * Math.PI) / 180);
+  const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+  const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+  const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+  return [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  ];
+}
+
+function inGamut(rgb: number[]): boolean {
+  return rgb.every((v) => v >= -0.0001 && v <= 1.0001);
+}
+
+function gamma(v: number): number {
+  return v <= 0.0031308 ? 12.92 * v : 1.055 * v ** (1 / 2.4) - 0.055;
+}

package/src/lib/contrast.ts

@@ -4,6 +4,8 @@
  * a var chain) into sRGB bytes. Browser only.
  */
 
+import { luminance } from "./colour";
+
 let context: CanvasRenderingContext2D | null = null;
 
 function rgb(css: string): [number, number, number] | null {
@@ -22,14 +24,6 @@ function rgb(css: string): [number, number, number] | null {
   return [r, g, b];
 }
 
-function luminance([r, g, b]: [number, number, number]): number {
-  const channel = (v: number) => {
-    const s = v / 255;
-    return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
-  };
-  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
-}
-
 /** WCAG 2 contrast ratio between two CSS colours, or null where it cannot be measured. */
 export function contrastRatio(foreground: string, background: string): number | null {
   const a = rgb(foreground);

package/src/lib/design-md.ts

@@ -0,0 +1,193 @@
+/**
+ * design.md: the brand in one file, for making anything that should look and
+ * sound like it outside the repo's components: a page built elsewhere, a slide,
+ * a document. Two halves. The first is written by people, in the client's voice:
+ * what comes first when guidance conflicts, how to work, the reflexes to avoid,
+ * what to check. The second is generated from the manifest, so its values are
+ * never stale: colour roles as hex in each mode with their contrast, type,
+ * shape, the brand assets, the rules and what each component is for.
+ *
+ * `context.md` is for building in the repo, from the components; this is for
+ * everything else, from the values.
+ */
+
+import type { TokenEntry, TokensManifest, AssetEntry, ComponentsManifest, RuleEntry, TermEntry } from "./manifest-types";
+import { groupByCategory, ramps, semanticColours, shortName, tokensOfTier, typeScale, valueIn, type Mode } from "./manifest";
+import { assetsMarkdown, manifestLinks } from "./markdown";
+import { parseColour, ratio, toHex } from "./colour";
+
+export interface DesignMdInput {
+  title: string;
+  /** Where the docs are served, without a trailing slash ("" at the root). */
+  base: string;
+  provenance?: string;
+  components: ComponentsManifest;
+  tokens?: TokensManifest;
+  rules?: RuleEntry[];
+  assets?: AssetEntry[];
+  terms?: TermEntry[];
+  /** The hand-written half, in markdown: `##` sections. */
+  body?: string;
+}
+
+export function designMarkdown({ title, base, provenance, components, tokens, rules = [], assets = [], terms = [], body }: DesignMdInput): string {
+  const out = [`# ${title}: design.md`, ""];
+  if (provenance) out.push(`> ${provenance}. The first half is written by people; the second is generated from the code.`, "");
+  out.push(
+    `How to make anything in this brand: a page, a slide, a document. The first half is how to think. The second is the exact values, generated from the code, so they are always current. Building in the repo itself? Use the components instead: [the whole system](${base}/context.md).`,
+    "",
+  );
+
+  out.push(body?.trim() || "## How to work\n\nNobody has written this half yet. Until they do, go by the brand pages and the values below.", "");
+
+  if (tokens) out.push(colourSection(tokens), typeSection(tokens), shapeSection(tokens));
+  if (assets.length) out.push(assetsMarkdown(assets));
+  if (rules.length) out.push(rulesSection(rules));
+  const used = componentsSection(components);
+  if (used) out.push(used);
+  const words = wordsSection(terms);
+  if (words) out.push(words);
+  out.push(manifestLinks(`${base}/manifest`));
+  return out.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+}
+
+// ------------------------------------------------------------ sections
+
+function colourSection(tokens: TokensManifest): string {
+  const resolve = resolver(tokens);
+  const out = [
+    "## Colour",
+    "",
+    "Each role with the text that goes on it, as hex in light and dark, and the contrast between them. Choose a colour by its role, never by how it looks.",
+    "",
+    "| Role | Light | Dark | Text on it | Contrast |",
+    "| --- | --- | --- | --- | --- |",
+  ];
+  const all = semanticColours(tokens);
+  const states = all.filter((c) => /-(hover|active)$/.test(c.name));
+  for (const c of all.filter((c) => !states.includes(c))) {
+    const bg = (["light", "dark"] as Mode[]).map((m) => resolve(c.background, m));
+    const fg = c.foreground ? (["light", "dark"] as Mode[]).map((m) => resolve(c.foreground!, m)) : undefined;
+    const contrast = fg
+      ? (["light", "dark"] as Mode[])
+          .map((_, i) => {
+            const a = bg[i] && parseColour(bg[i]!);
+            const b = fg[i] && parseColour(fg[i]!);
+            return a && b ? `${ratio(a, b).toFixed(1)}:1` : "";
+          })
+          .filter(Boolean)
+      : [];
+    out.push(
+      `| \`${shortName(c.background)}\` | ${hexCell(bg[0])} | ${hexCell(bg[1])} | ${fg ? `${hexCell(fg[0])} / ${hexCell(fg[1])}` : ""} | ${[...new Set(contrast)].join(" / ")} |`,
+    );
+  }
+  if (states.length) {
+    const byBase = new Map<string, string[]>();
+    for (const c of states) {
+      const base = c.name.replace(/-(hover|active)$/, "");
+      byBase.set(base, [...(byBase.get(base) ?? []), hexCell(resolve(c.background, "light"))]);
+    }
+    out.push("", `Hover, then pressed: ${[...byBase].map(([base, hexes]) => `\`${shortName({ name: base })}\` ${hexes.join(", ")}`).join("; ")}.`);
+  }
+  const families = ramps(tokens);
+  if (families.length) {
+    out.push("", "The ramps behind the roles, for charts and illustration; never for a job a role above already has:", "");
+    const seen = new Map<string, string>();
+    for (const ramp of families) {
+      const steps = ramp.steps.map((s) => `${s.step} ${hexCell(resolve(s.token, "light"))}`).join(", ");
+      const same = seen.get(steps);
+      out.push(same ? `- ${ramp.family}: the ${same} ramp` : `- ${ramp.family}: ${steps}`);
+      if (!same) seen.set(steps, ramp.family);
+    }
+  }
+  return out.join("\n") + "\n";
+}
+
+function typeSection(tokens: TokensManifest): string {
+  const out = ["## Type", ""];
+  const families = tokensOfTier(tokens, "font");
+  for (const f of families) out.push(`- \`${shortName(f, "font")}\`: ${family(f.values.default ?? "")}`);
+  const weights = tokensOfTier(tokens, "font-weight");
+  if (weights.length) out.push(`- Weights: ${weights.map((t) => `${shortName(t, "font-weight")} ${t.values.default}`).join(", ")}`);
+  const steps = typeScale(tokens);
+  if (steps.length) {
+    const lh = steps.some((s) => s.lineHeight);
+    out.push("", `| Size | rem | px |${lh ? " Line height |" : ""}`, `| --- | --- | --- |${lh ? " --- |" : ""}`);
+    for (const s of steps) out.push(`| \`text-${shortName(s.size, "text")}\` | ${s.size.values.default ?? ""} | ${px(s.size.values.default)} |${lh ? ` ${s.lineHeight?.values.default ?? ""} |` : ""}`);
+  }
+  const leading = tokensOfTier(tokens, "leading");
+  const tracking = tokensOfTier(tokens, "tracking");
+  if (leading.length || tracking.length) out.push("");
+  if (leading.length) out.push(`- Leading: ${leading.map((t) => `${shortName(t, "leading")} ${t.values.default}`).join(", ")}`);
+  if (tracking.length) out.push(`- Tracking: ${tracking.map((t) => `${shortName(t, "tracking")} ${t.values.default}`).join(", ")}`);
+  return out.join("\n") + "\n";
+}
+
+function shapeSection(tokens: TokensManifest): string {
+  const radii = tokensOfTier(tokens, "radius");
+  if (!radii.length) return "";
+  return ["## Corners", "", radii.map((t) => `\`${shortName(t)}\` ${px(t.values.default) || t.values.default}`).join(", "), ""].join("\n");
+}
+
+/** The words that matter outside the components: product names and what not to call things. */
+function wordsSection(terms: TermEntry[]): string {
+  const words = terms.filter((t) => t.kind === "product" || t.wrong?.length);
+  if (!words.length) return "";
+  const out = ["## Words", "", "| Say | Not | Note |", "| --- | --- | --- |"];
+  for (const t of words) out.push(`| ${t.name} | ${t.wrong?.join(", ") ?? ""} | ${(t.note ?? "").replace(/\|/g, "\\|")} |`);
+  return out.join("\n") + "\n";
+}
+
+function rulesSection(rules: RuleEntry[]): string {
+  const out = ["## Rules", "", "What holds everywhere, and how each is checked. An assumption is a rule nobody has confirmed yet: say so when you rely on it.", ""];
+  for (const r of rules) {
+    const how = r.check ? `checked ${r.check.kind === "manual" ? "by review" : `by ${r.check.kind}`}` : "not checked";
+    out.push(`- **${r.title}.** ${r.statement}${r.threshold ? ` (${r.threshold})` : ""} _${r.status}, ${how}._`);
+  }
+  return out.join("\n") + "\n";
+}
+
+function componentsSection(components: ComponentsManifest): string {
+  const out: string[] = [];
+  for (const group of groupByCategory(components)) {
+    for (const c of group.components) {
+      const u = c.usage;
+      if (!u?.use && !u?.avoid) continue;
+      const bits = [u.use && `${u.use.replace(/\.$/, "")}.`, u.avoid && `Not for: ${u.avoid.replace(/\.$/, "")}.`, u.instead?.length && `Instead: ${u.instead.join(", ")}.`];
+      out.push(`- **${c.name}**: ${bits.filter(Boolean).join(" ")}`);
+    }
+  }
+  return out.length ? ["## Components", "", "What each is for, so a page or a slide made elsewhere uses the same thing for the same job.", "", ...out, ""].join("\n") : "";
+}
+
+// ------------------------------------------------------------ helpers
+
+/** A token's value in a mode, following `var(--x)` through the manifest to something with a hex. */
+function resolver(tokens: TokensManifest) {
+  const byName = new Map(tokens.tokens.map((t) => [t.name, t]));
+  return function resolve(token: TokenEntry, mode: Mode, depth = 0): string | undefined {
+    const value = valueIn(token, mode);
+    const ref = value && /^var\((--[\w-]+)(?:\s*,[^)]*)?\)$/.exec(value.trim())?.[1];
+    if (!ref) return value;
+    const next = byName.get(ref);
+    return next && depth < 8 ? resolve(next, mode, depth + 1) : value;
+  };
+}
+
+/** A family stack, with a font the app loads (`var(--font-x)`) named as the brand's own. */
+function family(stack: string): string {
+  const own = /^var\((--[\w-]+)\)\s*,?\s*/.exec(stack);
+  return own ? `the brand's typeface (\`${own[1]}\`, loaded by the app), then ${stack.slice(own[0].length)}` : stack;
+}
+
+/** `1.25rem` as `20px`; anything not in rem as nothing. */
+function px(value: string | undefined): string {
+  const rem = value && /^([\d.]+)rem$/.exec(value.trim());
+  return rem ? `${Math.round(Number.parseFloat(rem[1]) * 16 * 100) / 100}px` : value && /px$/.test(value) ? value : "";
+}
+
+function hexCell(value: string | undefined): string {
+  if (!value) return "";
+  const hex = toHex(value);
+  return hex ? `\`${hex}\`` : `\`${value.replace(/\|/g, "\\|")}\``;
+}

package/src/lib/markdown.ts

@@ -230,6 +230,7 @@ export function adherenceMarkdown(report: AdherenceReport): string {
     "",
     "A report, never a gate.",
     "",
+    ...(report.unchecked ?? []).flatMap((note) => [`> ${note}`, ""]),
     `- 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}`,

package/src/lib/terms.tsx

@@ -4,7 +4,7 @@ import { inline } from "./text";
 
 /** The wrong forms of a term: quiet chips, each with a cross, so "not this" reads without shouting. */
 export function WrongForms({ wrong }: { wrong?: string[] }) {
-  if (!wrong?.length) return <span className="text-sm text-muted-foreground">None</span>;
+  if (!wrong?.length) return null;
   return (
     <span className="flex flex-wrap gap-1.5">
       <span className="sr-only">Not </span>

package/src/lib/wrap.tsx

@@ -0,0 +1,6 @@
+import { cloneElement, isValidElement, type ReactElement, type ReactNode } from "react";
+
+/** A component inside what it must sit in to work (a provider, its root), as the config's `wrap` gives it. */
+export function wrapIn(wrap: ReactElement<{ children?: ReactNode }> | undefined, node: ReactNode): ReactNode {
+  return wrap && isValidElement(wrap) ? cloneElement(wrap, undefined, node) : node;
+}

package/src/logo-usage.tsx

@@ -24,8 +24,7 @@ export function LogoUsage({ assets, rules = [], rulesHref }: { assets: AssetEntr
   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-16">
-      {general.length > 0 && <RuleList rules={general} rulesHref={rulesHref} />}
+    <div data-slot="logo-usage" className="flex flex-col gap-16 lg:gap-24">
       {logos.map((logo) => {
         const src = lookup.assetUrl(logo);
         const names = new Set([logo.name.toLowerCase(), logo.file.toLowerCase()]);
@@ -111,27 +110,36 @@ export function LogoUsage({ assets, rules = [], rulesHref }: { assets: AssetEntr
           </section>
         );
       })}
+      {general.length > 0 && (
+        <section data-slot="logo-rules" aria-labelledby="logo-rules" className="flex flex-col gap-5">
+          <header className="flex flex-col gap-1.5">
+            <h3 id="logo-rules" className="text-3xl tracking-tight">
+              Rules for the logo
+            </h3>
+            <p className="max-w-2xl text-base text-muted-foreground">What holds for every logo above, each with how it is checked.</p>
+          </header>
+          <RuleList rules={general} rulesHref={rulesHref} />
+        </section>
+      )}
     </div>
   );
 }
 
 function RuleList({ rules, rulesHref }: { rules: RuleEntry[]; rulesHref?: string }) {
   return (
-    <ul data-slot="logo-rules" className="grid gap-x-12 sm:grid-cols-2">
+    <ul data-slot="logo-rules" className="flex flex-col divide-y divide-border border-y border-border">
       {rules.map((r) => (
-        <li key={r.id} className="border-t border-border">
+        <li key={r.id}>
           <a
             href={rulesHref ? `${rulesHref}#${r.id}` : `#${r.id}`}
-            className="group flex h-full flex-col gap-1.5 py-4 text-sm focus-visible:outline-2 focus-visible:outline-ring"
+            className="group grid items-baseline gap-x-8 gap-y-1.5 py-5 focus-visible:outline-2 focus-visible:outline-ring md:grid-cols-[14rem_minmax(0,1fr)_auto]"
           >
-            <span className="flex items-center justify-between gap-2">
-              <span className="flex items-center gap-2 text-base font-medium group-hover:underline group-hover:underline-offset-4">
-                <Scale aria-hidden className="size-(--dt-size-xs) text-muted-foreground" />
-                {r.title}
-              </span>
-              <StatusBadge status={r.status} />
+            <span className="flex items-center gap-2 text-base font-medium underline-offset-4 group-hover:underline">
+              <Scale aria-hidden className="size-(--dt-size-xs) shrink-0 text-muted-foreground" />
+              {r.title}
             </span>
-            <span className="text-muted-foreground">{inline(r.statement)}</span>
+            <span className="text-sm leading-relaxed text-muted-foreground">{inline(r.statement)}</span>
+            <StatusBadge status={r.status} />
           </a>
         </li>
       ))}

package/src/next/config.ts

@@ -85,6 +85,13 @@ export interface DocsConfig {
   provenance?: string;
   /** `designtools-adherence --json`, for the standards page. */
   adherence?: AdherenceReport;
+  /**
+   * design.md, served at `<base>/design.md`: the brand in one file for anything made outside the repo's
+   * components (a page built elsewhere, a slide, a document). `body` is its hand-written half, in markdown
+   * `##` sections: what comes first when guidance conflicts, how to work, the reflexes to avoid, a review
+   * list. The values after it are generated. Without a body the file still serves, with the values alone.
+   */
+  designMd?: { body: string };
   /** Pages people write, in the order they appear. */
   editorial?: EditorialPage[];
   /** Built-in pages to leave out. */

package/src/next/markdown.ts

@@ -15,12 +15,13 @@ import {
   systemMarkdown,
   typeMarkdown,
 } from "../lib/markdown";
+import { designMarkdown } from "../lib/design-md";
 import { navOf, resolve, type Site } from "./site";
 
 /**
  * The markdown form of a docs page, generated from the manifest rather than
  * converted from HTML, or nothing when there is no such page. `context` is the
- * whole system in one file.
+ * whole system in one file; `design` is design.md, the brand for work outside the repo.
  */
 export function markdownFor(site: Site, path: string): string | undefined {
   const { base, title, components, tokens, rules, patterns, taxonomy, assets, config } = site;
@@ -28,6 +29,19 @@ export function markdownFor(site: Site, path: string): string | undefined {
   if (path === "context")
     return systemMarkdown({ components, tokens, rules: rules.rules, patterns: patterns.patterns, terms: taxonomy.terms }, title, config.provenance ?? "");
 
+  if (path === "design")
+    return designMarkdown({
+      title,
+      base,
+      provenance: config.provenance,
+      components,
+      tokens,
+      rules: rules.rules,
+      assets: assets.assets,
+      terms: taxonomy.terms,
+      body: config.designMd?.body,
+    });
+
   const page = resolve(site, path ? path.split("/") : []);
   if (!page) return undefined;
   switch (page.kind) {
@@ -51,6 +65,7 @@ export function markdownFor(site: Site, path: string): string | undefined {
           ),
           ...(nav.standards.length ? [`- Standards: ${links(nav.standards)}`] : []),
           `- Everything in [one file](${base}/context.md)`,
+          `- The brand for work outside the repo, a page, a slide or a document: [design.md](${base}/design.md)`,
           "",
           manifestLinks(`${base}/manifest`),
         ].join("\n"),

package/src/next/pages.tsx

@@ -270,7 +270,7 @@ function ComponentPage({ site, blocks: B, entry }: { site: Site; blocks: Blocks;
       </B.Workbench>
 
       <DocsSection title="Anatomy">
-        <B.Anatomy entry={entry} />
+        <B.Anatomy entry={entry} wrap={setup.wrap} />
       </DocsSection>
 
       <DocsSection title="Examples" lead="The usual use first, then each do beside its don't. Every one is the real component.">
@@ -282,7 +282,7 @@ function ComponentPage({ site, blocks: B, entry }: { site: Site; blocks: Blocks;
           title="Variants"
           lead={`Every combination, from the ${entry.variants.from === "props" ? "props' types" : `${entry.variants.from}() config`}, then each state.`}
         >
-          <B.VariantMatrix entry={entry} props={setup.props}>
+          <B.VariantMatrix entry={entry} props={setup.props} wrap={setup.wrap}>
             {setup.children === "" ? undefined : (setup.content ?? entry.name)}
           </B.VariantMatrix>
         </DocsSection>
@@ -409,9 +409,13 @@ function Overview({ site }: { site: Site }) {
           </ol>
           <p className="flex flex-wrap items-center gap-x-2 gap-y-1 text-sm text-muted-foreground">
             See it the way an agent does:
-            <a href={`${base}.md`} className="inline-flex items-center gap-1 font-medium text-canvas-foreground underline underline-offset-4 hover:decoration-2">
+            <a href={base ? `${base}.md` : "/.md"} className="inline-flex items-center gap-1 font-medium text-canvas-foreground underline underline-offset-4 hover:decoration-2">
               this page as markdown <ArrowUpRight aria-hidden className="size-3.5" />
             </a>
+            or, for a page, slide or document made outside the repo,
+            <a href={`${base}/design.md`} className="inline-flex items-center gap-1 font-medium text-canvas-foreground underline underline-offset-4 hover:decoration-2">
+              design.md <ArrowUpRight aria-hidden className="size-3.5" />
+            </a>
           </p>
         </DocsSection>
       )}

package/src/next/proxy.ts

@@ -27,7 +27,7 @@ export function docsProxy({ basePath = "/design/system", production }: { basePat
     // the markdown responses keep theirs.
     const res = NextResponse.next();
     res.headers.set("vary", "Accept");
-    res.headers.set("link", `<${page}.md>; rel="alternate"; type="text/markdown"`);
+    res.headers.set("link", `<${page ? `${page}.md` : "/.md"}>; rel="alternate"; type="text/markdown"`);
     res.headers.set("x-robots-tag", "noindex");
     return res;
   };
@@ -36,7 +36,8 @@ export function docsProxy({ basePath = "/design/system", production }: { basePat
 /** The proxy's matcher for a base path. Next reads `config.matcher` statically, so write the result out where it must be a literal. */
 export function docsMatcher(basePath = "/design/system"): string[] {
   const base = basePath.replace(/\/$/, "");
-  return [base, `${base}.md`, `${base}/:path*`];
+  // served at the site root, every path is a docs path
+  return base ? [base, `${base}.md`, `${base}/:path*`] : ["/", "/:path*"];
 }
 
 /** text/markdown ranked above text/html in the Accept header. */

package/src/page-actions.tsx

@@ -1,14 +1,15 @@
 "use client";
 
 import { Menu } from "@base-ui/react/menu";
-import { Braces, Check, ChevronDown, Copy, FileText, Files } from "lucide-react";
+import { Braces, Check, ChevronDown, Copy, FileText, Files, Palette } from "lucide-react";
 import { usePathname } from "next/navigation";
 import { useState } from "react";
 
 /**
  * What a reader can take from a page, as one split button: copy the page as
  * markdown, the same markdown any agent gets at `.md`, with a menu beside it to
- * view that markdown, copy the whole system as one file, or open the manifest.
+ * view that markdown, copy the whole system as one file, copy design.md (the
+ * brand for work outside the repo), or open the manifest.
  * Put it in a `DocsHeader`.
  */
 export function PageActions({ basePath = "/design/system" }: { basePath?: string }) {
@@ -73,6 +74,13 @@ export function PageActions({ basePath = "/design/system" }: { basePath?: string
                   <span className="text-xs text-muted-foreground">Every page in one markdown file</span>
                 </span>
               </Menu.Item>
+              <Menu.Item className={item} onClick={() => copyFrom(`${basePath}/design.md`, "design.md copied")}>
+                <Palette aria-hidden className={icon} />
+                <span className="flex flex-col">
+                  Copy design.md
+                  <span className="text-xs text-muted-foreground">The brand for a page, slide or document made elsewhere</span>
+                </span>
+              </Menu.Item>
               <Menu.LinkItem className={item} href={`${basePath}/manifest/components.json`} target="_blank" rel="noreferrer">
                 <Braces aria-hidden className={icon} />
                 <span className="flex flex-col">