@designtools/docs 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @designtools/docs
 
+## 0.3.0
+
+### Minor Changes
+
+- 16149e3: **design.md.** `<basePath>/design.md` is the brand in one file for work outside the repo's components: a page in another stack, a slide, a document. Its first half is written by people (`designMd.body` in the config); its second is generated from the manifest: colour roles as hex in each mode with their contrast, hover and pressed shades, ramps, type in rem and px, corners, assets, rules with their checks, what each component is for, and the words to use. Linked from the overview and copied from every page's actions menu.
+  
+  **The docs keep their own corners.** A project's `--radius-*` no longer reaches the docs' chrome, so a brand with large radii doesn't turn the docs into pills. Restyle them deliberately with `--docs-radius-*`. The project's own components inside `Live` keep the project's radii.
+  
+  **The logo page** opens on the first logo. The rules for every logo follow the logos, as rows, with how each is checked.
+  
+  **Served at the root.** `basePath: "/"` works: the overview link, the title link and `docsMatcher("/")`.
+  
+  **Smaller fixes.** The workbench's `wrap` now reaches the anatomy and variant views, so a component that needs a provider renders on every view. The type page drops the alphabet specimen. The standards page's targets read at body size. The vocabulary is one list, without letter groups. The adherence bar and the workbench's switch use the docs accent.
+
 ## 0.2.3
 
 ### Patch Changes

package/README.md

@@ -5,7 +5,7 @@ A design system's docs as a package: the brand and the system in one place, for
 - **Pages:** an overview (with an optional full-bleed hero), editorial brand pages, logo, imagery, voice, colour, type, scale, rules, patterns, standards, vocabulary, and a page per component.
 - **A workbench per component:** live on a stage at any viewport, zoom, background, mode or direction, with colour-vision simulation, outline and measure overlays, and states pinned without a pointer. A properties panel generated from the prop types, and tabs for the code of what is showing, the props, a log of every handler call, what an agent reads, and a full accessibility report.
 - **Navigation and search:** nested, collapsible, with a colour-mode switch, a phone drawer and an "On this page" rail; fuzzy search that finds a component by a wrong name.
-- **Markdown for agents:** every page at `.md` or on `Accept: text/markdown`, the whole system as one file, and the manifest as JSON.
+- **Markdown for agents:** every page at `.md` or on `Accept: text/markdown`, the whole system as one file, the manifest as JSON, and `design.md` (below).
 
 It ships compiled, with its own CSS scoped to the docs, and takes the brand from the project's tokens. A project writes a config and a handful of one-line route files; nothing is copied, so upgrading is a version bump.
 
@@ -81,6 +81,7 @@ pnpm add -D @designtools/manifest
 | `demonstrations` | Per rule id: an element shown on the rule, for one that needs persuading |
 | `baselines`, `adherence`, `provenance` | The standards page's targets, the adherence report, and the line naming the version and commit |
 | `overview` | `{ agentic: false }` drops the overview's "Why this is agentic"; `agenticLead` rewrites its opening line |
+| `designMd` | `{ body }`: the hand-written half of `design.md` (below) |
 | `hide` | Built-in pages to leave out |
 | `blocks` | Blocks replaced by the project's own (see Eject) |
 
@@ -105,6 +106,29 @@ editorial: [{
 
 `DocsSection` and `Prose` give the page the docs' own sections and type. Wrap the project's components in `Live`: the docs' styles never reach inside it, so the components look exactly as they do in the product. `markdown` is what the page's `.md` carries.
 
+## design.md
+
+`<basePath>/design.md` is the brand in one file, for anything made outside the repo's components: a page built in another stack, a slide, a document, a prompt to an image tool. `context.md` is for building in the repo, from the components; `design.md` is for everything else, from the values.
+
+It has two halves. The first is written by people, in the client's voice, and comes from `designMd.body`: what comes first when guidance conflicts, how to work, the reflexes to avoid, what to check before calling it done. The second is generated from the manifest, so it is never stale: each colour role with the text that goes on it as hex in light and dark and their contrast, the hover and pressed shades, the ramps, type in rem and px, corners, the brand assets and their use, every rule with how it's checked, what each component is for, and the words to use and avoid. Without a `body` it still serves, with the values alone and a line saying the first half isn't written.
+
+```tsx
+designMd: {
+  body: [
+    "## What comes first",
+    "",
+    "1. People before polish: a face and a name beat an illustration.",
+    "2. Proof beside every promise.",
+    "",
+    "## Reflexes to avoid",
+    "",
+    "- Yellow text on white. It fails, and it isn't the brand.",
+  ].join("\n"),
+},
+```
+
+The overview links it, and every page's actions menu copies it.
+
 ## Theming
 
 The docs read the project's own variables, so a project on [`@designtools/tokens`](../tokens) is themed with nothing to set. Any other project sets these on the docs (or anywhere above them):
@@ -118,10 +142,10 @@ The docs read the project's own variables, so a project on [`@designtools/tokens
 | `--docs-font-sans`, `--docs-font-mono` (else `--font-sans`, `--font-mono`) | The docs' type |
 | `--docs-display` (else `--font-display`, else the sans) | Headings |
 | `--docs-accent` (else `--primary`) | The current page's marker and the active tab: always a fill or a bar, never text |
-| `--docs-radius-sm` … `--docs-radius-2xl` (else `--radius-*`) | Corners |
+| `--docs-radius-sm` … `--docs-radius-2xl` | Corners. The docs keep their own modest radii and never take the project's `--radius-*`: a brand of very round corners would turn every docs panel into a pill. Set these to change them on purpose |
 | `--docs-target` (44px) | The smallest pressable size |
 
-Text sizes, leading, tracking, weights, shadows, control sizes and motion follow the project's `--text-*`, `--leading-*`, `--tracking-*`, `--font-weight-*`, `--shadow-*`, `--size-*`, `--duration-*` and `--ease-*` where it has them. Every value has a fallback, so the docs render on a project with none of it.
+Text sizes, leading, tracking, weights, shadows, control sizes and motion follow the project's `--text-*`, `--leading-*`, `--tracking-*`, `--font-weight-*`, `--shadow-*`, `--size-*`, `--duration-*` and `--ease-*` where it has them. Corners don't: the docs keep their own. Every value has a fallback, so the docs render on a project with none of it.
 
 The CSS is scoped to `[data-designtools]`, so it styles the docs and nothing else. It never matches inside `Live` (`[data-docs-content]`), which marks everywhere the project's components render: examples, the workbench, variants, anatomy, rule demonstrations, the hero and the logo. There only the project's CSS applies, responsive utilities included. On the docs' own elements its rules carry one attribute more than a project utility of the same name, so neither side's utilities leak into the other, whichever stylesheet loads last.
 

package/dist/adherence-summary.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { ChevronDown } from "lucide-react";
-import { cx } from "./lib/cx.js";
+import { accent, cx } from "./lib/cx.js";
 /**
  * The latest adherence report: how much of what the system could render comes
  * from it, the classes that bypass the tokens, and where a className fights a
@@ -15,7 +15,7 @@ export function AdherenceSummary({ report }) {
         ["Overrides", String(s.overrides)],
     ];
     const pct = s.share === null ? null : Math.round(s.share * 100);
-    return (_jsxs("div", { "data-slot": "adherence-summary", className: "flex flex-col gap-6", children: [_jsxs("div", { className: "grid gap-x-12 gap-y-8 border-t border-border pt-6 lg:grid-cols-[minmax(0,1fr)_minmax(0,1.6fr)]", children: [_jsxs("div", { "data-slot": "adherence-share", className: "flex flex-col gap-4", children: [_jsx("span", { className: "text-sm font-medium text-muted-foreground", children: "From the system" }), _jsxs("span", { className: "flex flex-col gap-3", children: [_jsx("span", { className: "text-7xl leading-none font-light tracking-tighter tabular-nums", children: share(s.share) }), pct !== null && (_jsx("span", { role: "meter", "aria-label": "Share from the system", "aria-valuenow": pct, "aria-valuemin": 0, "aria-valuemax": 100, className: "block h-2 overflow-hidden rounded-full bg-muted", children: _jsx("span", { className: "block h-full rounded-full bg-primary", style: { width: `${pct}%` } }) }))] })] }), _jsx("dl", { className: "grid grid-cols-2 gap-x-8 gap-y-6 self-end", children: stats.map(([label, value]) => (_jsxs("div", { "data-slot": "adherence-stat", className: "flex flex-col gap-1", children: [_jsx("dt", { className: "text-xs text-muted-foreground", children: label }), _jsx("dd", { className: "text-4xl font-light tracking-tight tabular-nums", children: value })] }, label))) })] }), s.replaceable.length === 0 && (_jsxs("p", { className: "text-sm text-muted-foreground", children: ["No component declares ", _jsx("code", { className: "font-mono text-xs", children: "@replaces" }), ", so raw elements are not counted and the share is not yet meaningful."] })), report.routes.length > 0 && (_jsx("div", { className: "overflow-x-auto rounded-2xl border border-border bg-surface text-surface-foreground", tabIndex: 0, role: "region", "aria-label": "Adherence by route", children: _jsxs("table", { className: "w-full min-w-[32rem] border-collapse text-left text-sm", children: [_jsx("caption", { className: "sr-only", children: "Adherence by route" }), _jsx("thead", { children: _jsx("tr", { className: "border-b border-border bg-muted/50 text-xs text-muted-foreground", children: ["Route", "From the system", "Raw", "Off-system", "Overrides"].map((h) => (_jsx("th", { scope: "col", className: "px-4 py-2.5 font-medium", children: h }, h))) }) }), _jsx("tbody", { children: report.routes.map((r) => (_jsx(Row, { name: r.route, counts: r.counts }, r.route))) })] }) })), report.files.some((f) => f.raw.length || f.offSystem.length || f.overrides.length) && (_jsxs("details", { "data-slot": "adherence-findings", className: "group overflow-hidden rounded-2xl border border-border bg-surface text-surface-foreground", children: [_jsxs("summary", { className: "flex min-h-(--docs-target,2.75rem) cursor-pointer list-none items-center justify-between px-4 text-sm font-medium hover:bg-muted [&::-webkit-details-marker]:hidden", children: ["Findings by file", _jsx(ChevronDown, { "aria-hidden": true, className: "size-(--dt-size-xs) text-muted-foreground transition-transform group-open:rotate-180" })] }), _jsx("ul", { className: "flex flex-col divide-y divide-border border-t border-border text-sm", children: report.files
+    return (_jsxs("div", { "data-slot": "adherence-summary", className: "flex flex-col gap-6", children: [_jsxs("div", { className: "grid gap-x-12 gap-y-8 border-t border-border pt-6 lg:grid-cols-[minmax(0,1fr)_minmax(0,1.6fr)]", children: [_jsxs("div", { "data-slot": "adherence-share", className: "flex flex-col gap-4", children: [_jsx("span", { className: "text-sm font-medium text-muted-foreground", children: "From the system" }), _jsxs("span", { className: "flex flex-col gap-3", children: [_jsx("span", { className: "text-7xl leading-none font-light tracking-tighter tabular-nums", children: share(s.share) }), pct !== null && (_jsx("span", { role: "meter", "aria-label": "Share from the system", "aria-valuenow": pct, "aria-valuemin": 0, "aria-valuemax": 100, className: "block h-2 overflow-hidden rounded-full bg-muted", children: _jsx("span", { className: cx("block h-full rounded-full", accent), style: { width: `${pct}%` } }) }))] })] }), _jsx("dl", { className: "grid grid-cols-2 gap-x-8 gap-y-6 self-end", children: stats.map(([label, value]) => (_jsxs("div", { "data-slot": "adherence-stat", className: "flex flex-col gap-1", children: [_jsx("dt", { className: "text-xs text-muted-foreground", children: label }), _jsx("dd", { className: "text-4xl font-light tracking-tight tabular-nums", children: value })] }, label))) })] }), report.unchecked?.map((note) => (_jsx("p", { "data-slot": "adherence-unchecked", className: "border-l-2 border-warning pl-4 text-sm", children: note }, note))), s.replaceable.length === 0 && (_jsxs("p", { className: "text-sm text-muted-foreground", children: ["No component declares ", _jsx("code", { className: "font-mono text-xs", children: "@replaces" }), ", so raw elements are not counted and the share is not yet meaningful."] })), report.routes.length > 0 && (_jsx("div", { className: "overflow-x-auto rounded-2xl border border-border bg-surface text-surface-foreground", tabIndex: 0, role: "region", "aria-label": "Adherence by route", children: _jsxs("table", { className: "w-full min-w-[32rem] border-collapse text-left text-sm", children: [_jsx("caption", { className: "sr-only", children: "Adherence by route" }), _jsx("thead", { children: _jsx("tr", { className: "border-b border-border bg-muted/50 text-xs text-muted-foreground", children: ["Route", "From the system", "Raw", "Off-system", "Overrides"].map((h) => (_jsx("th", { scope: "col", className: "px-4 py-2.5 font-medium", children: h }, h))) }) }), _jsx("tbody", { children: report.routes.map((r) => (_jsx(Row, { name: r.route, counts: r.counts }, r.route))) })] }) })), report.files.some((f) => f.raw.length || f.offSystem.length || f.overrides.length) && (_jsxs("details", { "data-slot": "adherence-findings", className: "group overflow-hidden rounded-2xl border border-border bg-surface text-surface-foreground", children: [_jsxs("summary", { className: "flex min-h-(--docs-target,2.75rem) cursor-pointer list-none items-center justify-between px-4 text-sm font-medium hover:bg-muted [&::-webkit-details-marker]:hidden", children: ["Findings by file", _jsx(ChevronDown, { "aria-hidden": true, className: "size-(--dt-size-xs) text-muted-foreground transition-transform group-open:rotate-180" })] }), _jsx("ul", { className: "flex flex-col divide-y divide-border border-t border-border text-sm", children: report.files
                             .filter((f) => f.raw.length || f.offSystem.length || f.overrides.length)
                             .map((f) => (_jsxs("li", { className: "flex flex-col gap-1.5 px-4 py-3", children: [_jsx("code", { className: "font-mono text-xs", children: f.file }), _jsxs("ul", { className: "flex flex-col gap-0.5 text-muted-foreground", children: [f.raw.map((r) => (_jsxs("li", { children: ["line ", r.line, ": a raw ", _jsxs("code", { className: "font-mono text-xs", children: ["<", r.element, ">"] }), " where ", r.replacedBy.join(" or "), " would do"] }, `r${r.line}:${r.column}`))), f.offSystem.map((o) => (_jsxs("li", { children: ["line ", o.line, ": ", _jsx("code", { className: "font-mono text-xs", children: o.class }), " is ", o.kind === "status-text" ? "a status fill used as text; use its subdued foreground" : o.kind === "palette" ? "a palette step, not a semantic token" : "an arbitrary value"] }, `o${o.line}:${o.column}:${o.class}`))), f.overrides.map((o) => (_jsxs("li", { children: ["line ", o.line, ": ", _jsx("code", { className: "font-mono text-xs", children: o.classes.map((c) => c.class).join(" ") }), " on ", o.component, " changes its", " ", [...new Set(o.classes.map((c) => c.kind))].join(" and "), ": is a variant missing?"] }, `v${o.line}:${o.column}`)))] })] }, f.file))) })] })), _jsxs("p", { className: "text-xs text-muted-foreground", children: ["A report, never a gate: ", report.generator, ", over ", s.files, " files. Lookalikes (a div styled like a Card) are not detected."] })] }));
 }

package/dist/anatomy.d.ts

@@ -1,12 +1,16 @@
-import { type ReactNode } from "react";
+import { type ReactElement, type ReactNode } from "react";
 import type { ComponentEntry } from "./lib/manifest-types.js";
 /**
  * A component's parts, by `data-slot`. Point at a part to outline every element
  * carrying it in the example. A part that does not appear may render in a
  * portal or only in some states.
  */
-export declare function Anatomy({ entry, children, }: {
+export declare 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;
 }): import("react").JSX.Element;

package/dist/anatomy.js

@@ -1,6 +1,7 @@
 "use client";
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 import { Live } from "./lib/live.js";
+import { wrapIn } from "./lib/wrap.js";
 import { Layers } from "lucide-react";
 import { useEffect, useId, useRef, useState } from "react";
 import { cx, target } from "./lib/cx.js";
@@ -11,7 +12,7 @@ import { Frame, Stage, Toolbar } from "./lib/ui.js";
  * carrying it in the example. A part that does not appear may render in a
  * portal or only in some states.
  */
-export function Anatomy({ entry, children, }) {
+export function Anatomy({ entry, children, wrap, }) {
     const lookup = useLookup();
     const id = useId();
     const box = useRef(null);
@@ -33,7 +34,7 @@ export function Anatomy({ entry, children, }) {
     const Component = lookup.componentFor(entry);
     const module = lookup.examplesFor(entry);
     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 ? (_jsx(Live, { children: _jsx(Component, { children: entry.name }) })) : null);
+    const example = children ?? (module && first ? renderExample(module[first], first) : Component ? (_jsx(Live, { children: wrapIn(wrap, _jsx(Component, { children: entry.name })) })) : null);
     const shown = entry.slots.filter((slot) => counts[slot]).length;
     return (_jsxs(Frame, { "data-slot": "anatomy", children: [active && (_jsx("style", { children: `[data-anatomy="${id}"] [data-slot="${active.replace(/"/g, '\\"')}"] { outline: 2px solid var(--ring); outline-offset: 3px; border-radius: var(--radius-sm); background-color: color-mix(in oklch, var(--ring) 10%, transparent); }` })), _jsxs("div", { className: "grid lg:grid-cols-[minmax(0,1fr)_17rem]", children: [_jsxs("div", { className: "flex min-w-0 flex-col", children: [_jsx(Toolbar, { children: _jsxs("span", { className: "flex items-center gap-2 pl-2 text-xs font-medium text-muted-foreground", children: [_jsx(Layers, { "aria-hidden": true, className: "size-(--dt-size-xs)" }), entry.slots.length, " ", entry.slots.length === 1 ? "part" : "parts", shown < entry.slots.length && ` · ${shown} in this example`] }) }), _jsx(Stage, { className: "min-h-64 flex-1", children: _jsx("div", { ref: box, "data-anatomy": id, "data-slot": "anatomy-example", className: "min-w-0", children: example }) })] }), _jsxs("div", { className: "flex flex-col gap-2 border-t border-border p-3 lg:border-t-0 lg:border-l", children: [_jsx("p", { className: "px-2 pt-1 text-xs text-muted-foreground", children: "Point at a part to find it." }), _jsx("ol", { "data-slot": "anatomy-parts", className: "flex flex-col gap-0.5 text-sm", onMouseLeave: () => setActive(null), children: entry.slots.map((slot, i) => (_jsx("li", { children: _jsxs("button", { type: "button", onMouseEnter: () => setActive(slot), onFocus: () => setActive(slot), onBlur: () => setActive(null), onClick: () => setActive(slot), className: cx(target, "group flex w-full items-center gap-3 rounded-lg px-2 text-left hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring", active === slot && "bg-muted", !counts[slot] && "text-muted-foreground"), children: [_jsx("span", { "aria-hidden": true, className: cx("flex size-6 shrink-0 items-center justify-center rounded-full border border-border font-mono text-xs", active === slot && "border-transparent bg-primary text-primary-foreground"), children: i + 1 }), _jsx("code", { className: "min-w-0 flex-1 truncate font-mono text-xs", children: slot }), _jsx("span", { className: "text-xs text-muted-foreground", children: counts[slot] ? `×${counts[slot]}` : "not shown" })] }) }, slot))) }), entry.variants?.parts && (_jsxs("p", { className: "mt-auto px-2 pt-2 text-xs text-muted-foreground", children: ["Styled in ", _jsx("code", { className: "font-mono", children: entry.variants.config }), ": ", entry.variants.parts.join(", ")] }))] })] })] }));
 }

package/dist/glossary.d.ts

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

package/dist/glossary.js

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

package/dist/lib/adherence-types.d.ts

@@ -33,6 +33,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. */
 export interface Counts {

package/dist/lib/colour.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 declare function parseColour(css: string): Rgb | undefined;
+/** `#rrggbb` for a CSS colour, or undefined. */
+export declare function toHex(css: string): string | undefined;
+/** WCAG 2 relative luminance. */
+export declare function luminance([r, g, b]: Rgb): number;
+/** WCAG 2 contrast ratio between two colours. */
+export declare function ratio(a: Rgb, b: Rgb): number;

package/dist/lib/colour.js

@@ -0,0 +1,99 @@
+/**
+ * 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.
+ */
+/** 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) {
+    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));
+    }
+    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)));
+    }
+    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) {
+    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]) {
+    const channel = (v) => {
+        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, b) {
+    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, C, H) {
+    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));
+}
+function oklabToLinear(L, C, H) {
+    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) {
+    return rgb.every((v) => v >= -0.0001 && v <= 1.0001);
+}
+function gamma(v) {
+    return v <= 0.0031308 ? 12.92 * v : 1.055 * v ** (1 / 2.4) - 0.055;
+}

package/dist/lib/contrast.js

@@ -3,6 +3,7 @@
  * the stylesheet: a 1px canvas turns any computed CSS colour (oklch, color-mix,
  * a var chain) into sRGB bytes. Browser only.
  */
+import { luminance } from "./colour.js";
 let context = null;
 function rgb(css) {
     if (typeof document === "undefined")
@@ -21,13 +22,6 @@ function rgb(css) {
     const [r, g, b] = context.getImageData(0, 0, 1, 1).data;
     return [r, g, b];
 }
-function luminance([r, g, b]) {
-    const channel = (v) => {
-        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, background) {
     const a = rgb(foreground);

package/dist/lib/design-md.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 { TokensManifest, AssetEntry, ComponentsManifest, RuleEntry, TermEntry } from "./manifest-types.js";
+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 declare function designMarkdown({ title, base, provenance, components, tokens, rules, assets, terms, body }: DesignMdInput): string;

package/dist/lib/design-md.js

@@ -0,0 +1,176 @@
+/**
+ * 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 { groupByCategory, ramps, semanticColours, shortName, tokensOfTier, typeScale, valueIn } from "./manifest.js";
+import { assetsMarkdown, manifestLinks } from "./markdown.js";
+import { parseColour, ratio, toHex } from "./colour.js";
+export function designMarkdown({ title, base, provenance, components, tokens, rules = [], assets = [], terms = [], body }) {
+    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) {
+    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"].map((m) => resolve(c.background, m));
+        const fg = c.foreground ? ["light", "dark"].map((m) => resolve(c.foreground, m)) : undefined;
+        const contrast = fg
+            ? ["light", "dark"]
+                .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();
+        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();
+        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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    const out = [];
+    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) {
+    const byName = new Map(tokens.tokens.map((t) => [t.name, t]));
+    return function resolve(token, mode, depth = 0) {
+        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) {
+    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) {
+    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) {
+    if (!value)
+        return "";
+    const hex = toHex(value);
+    return hex ? `\`${hex}\`` : `\`${value.replace(/\|/g, "\\|")}\``;
+}

package/dist/lib/markdown.js

@@ -234,6 +234,7 @@ export function adherenceMarkdown(report) {
         "",
         "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/dist/lib/terms.d.ts

@@ -2,7 +2,7 @@ import type { TermEntry } from "./manifest-types.js";
 /** The wrong forms of a term: quiet chips, each with a cross, so "not this" reads without shouting. */
 export declare function WrongForms({ wrong }: {
     wrong?: string[];
-}): import("react").JSX.Element;
+}): import("react").JSX.Element | null;
 /**
  * One term on one row: the word to use, the words not to, and why. Three columns on a wide screen, under
  * the labels `TermHead` draws; stacked on a phone.

package/dist/lib/terms.js

@@ -4,7 +4,7 @@ import { inline } from "./text.js";
 /** The wrong forms of a term: quiet chips, each with a cross, so "not this" reads without shouting. */
 export function WrongForms({ wrong }) {
     if (!wrong?.length)
-        return _jsx("span", { className: "text-sm text-muted-foreground", children: "None" });
+        return null;
     return (_jsxs("span", { className: "flex flex-wrap gap-1.5", children: [_jsx("span", { className: "sr-only", children: "Not " }), wrong.map((w) => (_jsxs("span", { "data-slot": "term-wrong", className: "inline-flex min-h-7 items-center gap-1 rounded-md bg-muted px-2 text-sm text-muted-foreground", children: [_jsx(X, { "aria-hidden": true, className: "size-3 shrink-0" }), _jsx("span", { className: "line-through decoration-current/40", children: w })] }, w)))] }));
 }
 /**

package/dist/lib/wrap.d.ts

@@ -0,0 +1,5 @@
+import { 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 declare function wrapIn(wrap: ReactElement<{
+    children?: ReactNode;
+}> | undefined, node: ReactNode): ReactNode;

package/dist/lib/wrap.js

@@ -0,0 +1,5 @@
+import { cloneElement, isValidElement } 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, node) {
+    return wrap && isValidElement(wrap) ? cloneElement(wrap, undefined, node) : node;
+}