@designtools/docs 0.2.2 → 0.3.0

package/dist/type-ramp.js

@@ -16,7 +16,7 @@ export function TypeRamp({ tokens, sample = "The quick brown fox jumps over the
     const weights = tokensOfTier(tokens, "font-weight");
     const leading = tokensOfTier(tokens, "leading");
     const tracking = tokensOfTier(tokens, "tracking");
-    return (_jsxs("div", { "data-slot": "type-ramp", className: "flex flex-col gap-14", children: [families.length > 0 && (_jsx("div", { className: "grid gap-x-12 gap-y-10 md:grid-cols-2", children: families.map((f) => (_jsxs("figure", { "data-slot": "type-family", className: "flex flex-col gap-5 border-t border-border pt-6", children: [_jsxs("div", { className: "flex flex-col gap-6", style: { fontFamily: `var(${f.name})` }, children: [_jsx("span", { className: "text-8xl leading-none font-light tracking-tighter", children: "Aa" }), _jsx("span", { className: "text-sm leading-relaxed break-all text-muted-foreground", children: "ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz 0123456789 &?!" })] }), _jsxs("figcaption", { className: "flex flex-col gap-0.5", children: [_jsx("code", { className: "font-mono text-xs font-medium", children: shortName(f, "font") }), _jsx("span", { className: "truncate font-mono text-xs text-muted-foreground", title: f.values.default, children: f.description ?? f.values.default })] })] }, f.name))) })), _jsx("ol", { "data-slot": "type-scale", className: "flex flex-col", children: steps.map((step) => (_jsxs("li", { "data-slot": "type-step", className: "grid grid-cols-1 gap-3 border-t border-border py-5 md:grid-cols-[11rem_minmax(0,1fr)] md:items-center md:gap-6", children: [_jsxs("div", { className: "flex flex-col gap-1", children: [_jsxs("span", { className: "flex items-baseline gap-2", children: [_jsx("code", { className: "font-mono text-xs font-semibold", children: shortName(step.size, "text") }), _jsx("span", { className: "font-mono text-xs text-muted-foreground", children: px(step.size.values.default) ?? step.size.values.default })] }), _jsx("span", { className: "font-mono text-xs text-muted-foreground", children: [step.lineHeight && `lh ${step.lineHeight.values.default}`, step.letterSpacing && `tr ${step.letterSpacing.values.default}`].filter(Boolean).join(" · ") }), step.description && _jsx("span", { className: "text-xs text-muted-foreground", children: step.description })] }), _jsx("p", { className: "min-w-0 truncate", style: {
+    return (_jsxs("div", { "data-slot": "type-ramp", className: "flex flex-col gap-14", children: [families.length > 0 && (_jsx("div", { className: "grid gap-x-12 gap-y-10 md:grid-cols-2", children: families.map((f) => (_jsxs("figure", { "data-slot": "type-family", className: "flex flex-col gap-5 border-t border-border pt-6", children: [_jsx("span", { className: "text-8xl leading-none font-light tracking-tighter", style: { fontFamily: `var(${f.name})` }, children: "Aa" }), _jsxs("figcaption", { className: "flex flex-col gap-0.5", children: [_jsx("code", { className: "font-mono text-xs font-medium", children: shortName(f, "font") }), _jsx("span", { className: "truncate font-mono text-xs text-muted-foreground", title: f.values.default, children: f.description ?? f.values.default })] })] }, f.name))) })), _jsx("ol", { "data-slot": "type-scale", className: "flex flex-col", children: steps.map((step) => (_jsxs("li", { "data-slot": "type-step", className: "grid grid-cols-1 gap-3 border-t border-border py-5 md:grid-cols-[11rem_minmax(0,1fr)] md:items-center md:gap-6", children: [_jsxs("div", { className: "flex flex-col gap-1", children: [_jsxs("span", { className: "flex items-baseline gap-2", children: [_jsx("code", { className: "font-mono text-xs font-semibold", children: shortName(step.size, "text") }), _jsx("span", { className: "font-mono text-xs text-muted-foreground", children: px(step.size.values.default) ?? step.size.values.default })] }), _jsx("span", { className: "font-mono text-xs text-muted-foreground", children: [step.lineHeight && `lh ${step.lineHeight.values.default}`, step.letterSpacing && `tr ${step.letterSpacing.values.default}`].filter(Boolean).join(" · ") }), step.description && _jsx("span", { className: "text-xs text-muted-foreground", children: step.description })] }), _jsx("p", { className: "min-w-0 truncate", style: {
                                 fontSize: `var(${step.name})`,
                                 lineHeight: step.lineHeight ? `var(${step.lineHeight.name})` : undefined,
                                 letterSpacing: step.letterSpacing ? `var(${step.letterSpacing.name})` : undefined,

package/dist/variant-matrix.d.ts

@@ -1,13 +1,17 @@
-import { type ReactNode } from "react";
+import { type ReactElement, type ReactNode } from "react";
 import type { ComponentEntry } from "./lib/manifest-types.js";
 /**
  * Every variant, rendered live. The first two axes form a grid; each further
  * axis gets its own row, with the others at their defaults. Pass `props` for
  * anything the component needs to render (an `options` list, a `value`).
  */
-export declare function VariantMatrix({ entry, props, children, axes: only, }: {
+export declare function VariantMatrix({ entry, props, children, axes: only, wrap, }: {
     entry: ComponentEntry;
     props?: Record<string, unknown>;
+    /** What each instance must sit in to work: a provider, its root. */
+    wrap?: ReactElement<{
+        children?: ReactNode;
+    }>;
     /** What to render inside each instance. Defaults to the component's name. */
     children?: ReactNode;
     /** Limit and order the axes shown. */

package/dist/variant-matrix.js

@@ -1,6 +1,7 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { Live } from "./lib/live.js";
+import { wrapIn } from "./lib/wrap.js";
 import { Grid3x3, Moon, Sun } from "lucide-react";
 import { useEffect, useState } from "react";
 import { cx } from "./lib/cx.js";
@@ -12,7 +13,7 @@ import { Frame, IconButton, Toolbar } from "./lib/ui.js";
  * axis gets its own row, with the others at their defaults. Pass `props` for
  * anything the component needs to render (an `options` list, a `value`).
  */
-export function VariantMatrix({ entry, props = {}, children, axes: only, }) {
+export function VariantMatrix({ entry, props = {}, children, axes: only, wrap, }) {
     const lookup = useLookup();
     const Component = lookup.componentFor(entry);
     const [theme, setTheme] = useState();
@@ -23,7 +24,7 @@ export function VariantMatrix({ entry, props = {}, children, axes: only, }) {
     if (axes.length === 0)
         return _jsxs("p", { className: "text-sm text-muted-foreground", children: [entry.name, " has no variants."] });
     const content = children ?? entry.name;
-    const render = (extra) => (_jsx(Live, { children: _jsx(Component, { ...props, ...coerce(extra), children: content }) }));
+    const render = (extra) => (_jsx(Live, { children: wrapIn(wrap, _jsx(Component, { ...props, ...coerce(extra), children: content })) }));
     const [rows, cols, ...rest] = axes;
     const toggle = (_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") }));
     return (_jsxs(Frame, { "data-slot": "variant-matrix", children: [_jsxs(Toolbar, { children: [_jsxs("span", { className: "flex items-center gap-2 pl-2 font-mono text-xs text-muted-foreground", children: [_jsx(Grid3x3, { "aria-hidden": true, className: "size-(--dt-size-xs)" }), cols ? `${rows.name} × ${cols.name}` : rows.name, rest.length > 0 && `, ${rest.map((a) => a.name).join(", ")}`] }), toggle] }), _jsxs("div", { "data-docs-stage": "", "data-theme": theme, className: "flex flex-col gap-12 bg-canvas px-6 py-8 text-canvas-foreground sm:px-8", children: [cols ? (_jsx("div", { className: "overflow-x-auto", tabIndex: 0, role: "region", "aria-label": "Variants", children: _jsxs("table", { className: "w-full border-collapse text-sm", children: [_jsxs("caption", { className: "sr-only", children: [entry.name, ": ", rows.name, " by ", cols.name] }), _jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", className: "w-0 p-0" }), cols.options.map((c) => (_jsx("th", { scope: "col", title: c.description, className: "px-4 pb-4 text-center font-mono text-xs font-normal text-muted-foreground", children: _jsx(OptionName, { axis: cols, option: c.name }) }, c.name)))] }) }), _jsx("tbody", { children: rows.options.map((r) => (_jsxs("tr", { children: [_jsx("th", { scope: "row", title: r.description, className: "py-4 pr-6 text-left font-mono text-xs font-normal whitespace-nowrap text-muted-foreground", children: _jsx(OptionName, { axis: rows, option: r.name }) }), cols.options.map((c) => (_jsx("td", { "data-slot": "variant-cell", className: "px-4 py-4 text-center align-middle", children: _jsx("span", { className: "inline-flex justify-center", children: render({ [rows.name]: r.name, [cols.name]: c.name }) }) }, c.name)))] }, r.name))) })] }) })) : (_jsx(AxisRow, { axis: rows, render: render })), rest.map((axis) => (_jsx(AxisRow, { axis: axis, render: render }, axis.name))), _jsx(States, { render: render, canDisable: "disabled" in entry.props })] })] }));

package/dist/workbench.js

@@ -2,11 +2,12 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { handlerNames } from "./lib/handlers.js";
 import { Live } from "./lib/live.js";
+import { wrapIn } from "./lib/wrap.js";
 import { Tabs } from "@base-ui/react/tabs";
 import { Toggle } from "@base-ui/react/toggle";
 import { ToggleGroup } from "@base-ui/react/toggle-group";
 import { Bot, Braces, Check, Code, Eye, ExternalLink, Link2, Maximize2, Minimize2, Minus, Monitor, Moon, PaintBucket, PersonStanding, Plus, RotateCcw, Ruler, SquareDashed, Sun, Trash2, Zap, } from "lucide-react";
-import { cloneElement, isValidElement, useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
 import { AxeReport, useAxe } from "./a11y-panel.js";
 import { CodeView } from "./code-view.js";
 import { Boundary } from "./lib/boundary.js";
@@ -231,7 +232,7 @@ export function Workbench({ entry, props: base = {}, children: initialText = ent
                                                 width: view.viewport === "fill" ? undefined : Number(view.viewport),
                                                 zoom: view.zoom === 100 ? undefined : view.zoom / 100,
                                                 filter: filterFor(view.vision, filterId),
-                                            }, children: _jsx("div", { ref: target, "data-slot": "workbench-target", className: "flex max-w-full items-center justify-center", children: _jsx(Boundary, { label: entry.name, children: wrap && isValidElement(wrap) ? cloneElement(wrap, undefined, node) : node }) }) }) }), view.measure && _jsx(Measure, { area: area, target: target })] }), _jsxs("div", { "data-slot": "workbench-controls", className: cx("flex flex-col gap-7 border-t border-border p-5 lg:border-t-0 lg:border-l", full ? "overflow-y-auto" : "lg:max-h-[44rem] lg:overflow-y-auto"), children: [_jsxs("div", { className: "-mt-1.5 -mb-2 flex min-h-9 items-center justify-between", children: [_jsx("p", { className: "text-sm font-medium", children: "Properties" }), _jsx(IconButton, { icon: RotateCcw, label: "Reset everything", onClick: reset, disabled: !changed, className: "disabled:pointer-events-none disabled:opacity-40" })] }), _jsx(StateControl, { value: state, onChange: setState, canDisable: canDisable }), axes.length > 0 && (_jsx(Section, { title: "Variants", children: axes.map((axis) => (_jsx(AxisControl, { axis: axis, value: variants[axis.name] ?? axis.default ?? "", onChange: (v) => setVariants((s) => ({ ...s, [axis.name]: v })) }, axis.name))) })), settable.length > 0 && (_jsx(Section, { title: "Props", children: settable.map(([name, p]) => {
+                                            }, children: _jsx("div", { ref: target, "data-slot": "workbench-target", className: "flex max-w-full items-center justify-center", children: _jsx(Boundary, { label: entry.name, children: wrapIn(wrap, node) }) }) }) }), view.measure && _jsx(Measure, { area: area, target: target })] }), _jsxs("div", { "data-slot": "workbench-controls", className: cx("flex flex-col gap-7 border-t border-border p-5 lg:border-t-0 lg:border-l", full ? "overflow-y-auto" : "lg:max-h-[44rem] lg:overflow-y-auto"), children: [_jsxs("div", { className: "-mt-1.5 -mb-2 flex min-h-9 items-center justify-between", children: [_jsx("p", { className: "text-sm font-medium", children: "Properties" }), _jsx(IconButton, { icon: RotateCcw, label: "Reset everything", onClick: reset, disabled: !changed, className: "disabled:pointer-events-none disabled:opacity-40" })] }), _jsx(StateControl, { value: state, onChange: setState, canDisable: canDisable }), axes.length > 0 && (_jsx(Section, { title: "Variants", children: axes.map((axis) => (_jsx(AxisControl, { axis: axis, value: variants[axis.name] ?? axis.default ?? "", onChange: (v) => setVariants((s) => ({ ...s, [axis.name]: v })) }, axis.name))) })), settable.length > 0 && (_jsx(Section, { title: "Props", children: settable.map(([name, p]) => {
                                             const current = name in values ? values[name] : base[name];
                                             const put = (v) => setValues((s) => ({ ...s, [name]: v }));
                                             const info = _jsx(PropInfo, { prop: p });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@designtools/docs",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Design system docs as a package: pages, navigation, search, a workbench per component, rules, patterns, brand pages and markdown for agents, generated from the @designtools/manifest and themed by your tokens. One Next adapter serves them inside your app or as a standalone site.",
   "type": "module",
   "license": "MIT",

package/src/adherence-summary.tsx

@@ -1,6 +1,6 @@
 import type { AdherenceReport, Counts } from "./lib/adherence-types";
 import { ChevronDown } from "lucide-react";
-import { cx } from "./lib/cx";
+import { accent, cx } from "./lib/cx";
 
 /**
  * The latest adherence report: how much of what the system could render comes
@@ -32,7 +32,7 @@ export function AdherenceSummary({ report }: { report: AdherenceReport }) {
                 aria-valuemax={100}
                 className="block h-2 overflow-hidden rounded-full bg-muted"
               >
-                <span className="block h-full rounded-full bg-primary" style={{ width: `${pct}%` }} />
+                <span className={cx("block h-full rounded-full", accent)} style={{ width: `${pct}%` }} />
               </span>
             )}
           </span>
@@ -46,6 +46,11 @@ export function AdherenceSummary({ report }: { report: AdherenceReport }) {
           ))}
         </dl>
       </div>
+      {report.unchecked?.map((note) => (
+        <p key={note} data-slot="adherence-unchecked" className="border-l-2 border-warning pl-4 text-sm">
+          {note}
+        </p>
+      ))}
       {s.replaceable.length === 0 && (
         <p className="text-sm text-muted-foreground">
           No component declares <code className="font-mono text-xs">@replaces</code>, so raw elements are not counted and the share is

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;
+}