@designtools/docs 0.0.0-stage → 0.2.0

package/dist/lib/standards.js

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

package/dist/lib/status.d.ts

@@ -0,0 +1,6 @@
+export type Status = "stable" | "emerging" | "deprecated" | "confirmed" | "assumption" | "measured" | "draft" | "published";
+/** A status, everywhere one is shown: components, patterns, rules and editorial pages. Unset says so. */
+export declare function StatusBadge({ status, className }: {
+    status?: Status;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/lib/status.js

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

package/dist/lib/terms.d.ts

@@ -0,0 +1,15 @@
+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;
+/**
+ * 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.
+ */
+export declare function TermRow({ term, kind }: {
+    term: TermEntry;
+    kind?: boolean;
+}): import("react").JSX.Element;
+/** The column labels over a list of `TermRow`s, on a wide screen. */
+export declare function TermHead(): import("react").JSX.Element;

package/dist/lib/terms.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { X } from "lucide-react";
+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 (_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)))] }));
+}
+/**
+ * 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.
+ */
+export function TermRow({ term, kind }) {
+    return (_jsxs("div", { "data-slot": "term", className: "grid gap-x-8 gap-y-2 border-t border-border py-5 md:grid-cols-[minmax(10rem,14rem)_minmax(0,1fr)_minmax(0,1.3fr)] md:items-baseline", children: [_jsxs("dt", { className: "flex items-baseline gap-2", children: [_jsx("span", { className: "text-xl leading-snug tracking-tight", children: term.name }), kind && _jsx("span", { className: "font-mono text-xs text-muted-foreground", children: term.kind }), _jsx("span", { className: "sr-only", children: ", say this" })] }), _jsx("dd", { children: _jsx(WrongForms, { wrong: term.wrong }) }), _jsxs("dd", { className: "text-sm leading-relaxed text-muted-foreground", children: [term.note ? inline(term.note) : term.kind !== "product" ? `The ${term.kind}'s name in the code.` : null, term.ref && _jsx("code", { className: "ml-1 font-mono text-xs", children: term.ref })] })] }));
+}
+/** The column labels over a list of `TermRow`s, on a wide screen. */
+export function TermHead() {
+    return (_jsxs("div", { "aria-hidden": true, className: "hidden gap-x-8 pb-3 text-xs font-medium text-muted-foreground md:grid md:grid-cols-[minmax(10rem,14rem)_minmax(0,1fr)_minmax(0,1.3fr)]", children: [_jsx("span", { children: "Say" }), _jsx("span", { children: "Not" }), _jsx("span", { children: "Why" })] }));
+}

package/dist/lib/text.d.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from "react";
+/** JSDoc prose: paragraphs split on blank lines, `code` spans set as code. Nothing else is interpreted. */
+export declare function Prose({ text, className }: {
+    text: string;
+    className?: string;
+}): import("react").JSX.Element;
+/** One line of prose with its `code` spans. */
+export declare function inline(text: string): ReactNode[];

package/dist/lib/text.js

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

package/dist/lib/ui.d.ts

@@ -0,0 +1,100 @@
+import { type LucideIcon } from "lucide-react";
+import { type ComponentProps, type ReactNode } from "react";
+/**
+ * The pieces every block is built from, so the docs read as one thing: the stage a
+ * component is shown on, the frame around a stage, small icon buttons, a segmented
+ * control and a copy button. All drawn from the semantic tokens.
+ */
+/**
+ * Where a component is shown: the page's canvas with a faint dot grid, so the
+ * component reads as an object on a surface rather than more page. `theme` renders
+ * it in one mode whatever the page is in; `width` narrows it to a phone.
+ */
+export declare function Stage({ theme, width, className, children, ...props }: {
+    theme?: "light" | "dark";
+    width?: number;
+    className?: string;
+    children: ReactNode;
+} & Omit<ComponentProps<"div">, "className">): import("react").JSX.Element;
+/** A rounded card that frames a stage and its toolbar: every example, playground and preview sits in one. */
+export declare function Frame({ className, children, ...props }: ComponentProps<"div">): import("react").JSX.Element;
+/** The bar along the top of a frame. */
+export declare function Toolbar({ className, children }: {
+    className?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * A small icon button: drawn at 32px, pressed at the docs' target size (44px by
+ * default) through a transparent ring, so a toolbar stays tight and every button
+ * is still easy to hit.
+ */
+export declare function IconButton({ icon: Icon, label, pressed, className, ...props }: {
+    icon: LucideIcon;
+    label: string;
+    pressed?: boolean;
+} & Omit<ComponentProps<"button">, "children">): import("react").JSX.Element;
+/** An `IconButton` that goes somewhere: opening an example on its own, a source file. */
+export declare function IconLink({ icon: Icon, label, className, ...props }: {
+    icon: LucideIcon;
+    label: string;
+} & Omit<ComponentProps<"a">, "children">): import("react").JSX.Element;
+/** Copies text, and says so: an icon button, or a labelled one with `withLabel`. */
+export declare function CopyButton({ text, label, withLabel, className }: {
+    text: string;
+    label?: string;
+    withLabel?: boolean;
+    className?: string;
+}): import("react").JSX.Element;
+/**
+ * Two to four views of one thing, as a pill track with the chosen one raised.
+ * Tabs underneath, so arrow keys move between them and each panel is labelled by
+ * its tab. Put a `SegmentedList` where the switch belongs and a `SegmentedPanel`
+ * for each view.
+ */
+export declare function Segmented({ defaultValue, className, children }: {
+    defaultValue: string;
+    className?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** The track of a `Segmented`: put it where the switch belongs, usually a toolbar. */
+export declare function SegmentedList({ items, label }: {
+    items: {
+        value: string;
+        label: string;
+        icon?: LucideIcon;
+    }[];
+    label: string;
+}): import("react").JSX.Element;
+export declare function SegmentedPanel({ value, className, children }: {
+    value: string;
+    className?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** A small label above a group of controls or a column. */
+export declare function Eyebrow({ className, children }: {
+    className?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * A toolbar menu for one setting: the trigger shows an icon and, when the setting
+ * is not at its default, its current value; the menu lists every option with the
+ * chosen one checked. For viewport, background, colour vision and the like.
+ */
+export declare function ToolbarMenu<T extends string>({ icon: Icon, label, value, fallback, options, onChange, swatch, }: {
+    icon: LucideIcon;
+    /** What the setting is, for the trigger's name and the menu's heading. */
+    label: string;
+    value: T;
+    /** The default: while chosen, the trigger shows only its icon. */
+    fallback: T;
+    options: {
+        value: T;
+        label: string;
+        note?: string;
+    }[];
+    onChange: (value: T) => void;
+    /** A colour to paint beside each option: for backgrounds. */
+    swatch?: (value: T) => string | undefined;
+}): import("react").JSX.Element;
+/** A thin upright rule between groups of toolbar controls. */
+export declare function ToolbarDivider(): import("react").JSX.Element;

package/dist/lib/ui.js

@@ -0,0 +1,89 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Menu } from "@base-ui/react/menu";
+import { Tabs } from "@base-ui/react/tabs";
+import { Check, ChevronDown, Copy } from "lucide-react";
+import { useState } from "react";
+import { cx } from "./cx.js";
+/**
+ * The pieces every block is built from, so the docs read as one thing: the stage a
+ * component is shown on, the frame around a stage, small icon buttons, a segmented
+ * control and a copy button. All drawn from the semantic tokens.
+ */
+/**
+ * Where a component is shown: the page's canvas with a faint dot grid, so the
+ * component reads as an object on a surface rather than more page. `theme` renders
+ * it in one mode whatever the page is in; `width` narrows it to a phone.
+ */
+export function Stage({ theme, width, className, children, ...props }) {
+    return (_jsx("div", { "data-slot": "stage", "data-docs-stage": "", "data-theme": theme, className: cx("relative flex min-w-0 items-center justify-center overflow-auto bg-canvas p-8 text-canvas-foreground sm:p-10", "bg-[radial-gradient(color-mix(in_oklch,var(--border)_85%,transparent)_1px,transparent_1px)] [background-size:14px_14px]", className), ...props, children: width ? (_jsx("div", { className: "w-full rounded-lg border border-dashed border-border p-4", style: { maxWidth: width }, children: children })) : (children) }));
+}
+/** A rounded card that frames a stage and its toolbar: every example, playground and preview sits in one. */
+export function Frame({ className, children, ...props }) {
+    return (_jsx("div", { "data-slot": "frame", className: cx("flex min-w-0 flex-col overflow-hidden rounded-xl border border-border bg-surface text-surface-foreground shadow-xs", className), ...props, children: children }));
+}
+/** The bar along the top of a frame. */
+export function Toolbar({ className, children }) {
+    return (_jsx("div", { "data-slot": "frame-toolbar", className: cx("flex min-h-12 flex-wrap items-center justify-between gap-2 border-b border-border px-2 py-1.5", className), children: children }));
+}
+/**
+ * A small icon button: drawn at 32px, pressed at the docs' target size (44px by
+ * default) through a transparent ring, so a toolbar stays tight and every button
+ * is still easy to hit.
+ */
+export function IconButton({ icon: Icon, label, pressed, className, ...props }) {
+    return (_jsx("button", { type: "button", "aria-label": label, title: label, "aria-pressed": pressed, className: cx("relative inline-flex size-8 shrink-0 cursor-pointer items-center justify-center rounded-md text-muted-foreground transition-colors duration-(--dt-duration-fast)", "after:absolute after:-inset-[calc((var(--docs-target,2.75rem)-2rem)/2)] after:content-['']", "hover:bg-muted hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring aria-pressed:bg-muted aria-pressed:text-canvas-foreground", className), ...props, children: _jsx(Icon, { "aria-hidden": true, className: "size-(--dt-size-xs)" }) }));
+}
+/** An `IconButton` that goes somewhere: opening an example on its own, a source file. */
+export function IconLink({ icon: Icon, label, className, ...props }) {
+    return (_jsx("a", { "aria-label": label, title: label, className: cx("relative inline-flex size-8 shrink-0 cursor-pointer items-center justify-center rounded-md text-muted-foreground transition-colors duration-(--dt-duration-fast)", "after:absolute after:-inset-[calc((var(--docs-target,2.75rem)-2rem)/2)] after:content-['']", "hover:bg-muted hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring", className), ...props, children: _jsx(Icon, { "aria-hidden": true, className: "size-(--dt-size-xs)" }) }));
+}
+/** Copies text, and says so: an icon button, or a labelled one with `withLabel`. */
+export function CopyButton({ text, label = "Copy", withLabel, className }) {
+    const [copied, setCopied] = useState(false);
+    const copy = async () => {
+        try {
+            await navigator.clipboard.writeText(text);
+            setCopied(true);
+            setTimeout(() => setCopied(false), 1500);
+        }
+        catch {
+            // clipboard refused (an insecure origin, a denied permission): nothing changes
+        }
+    };
+    return (_jsxs(_Fragment, { children: [withLabel ? (_jsxs("button", { type: "button", onClick: copy, className: cx("inline-flex min-h-(--docs-target,2.75rem) cursor-pointer items-center gap-2 rounded-md border border-border bg-surface px-3 text-sm font-medium text-surface-foreground shadow-xs hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring", className), children: [copied ? _jsx(Check, { "aria-hidden": true, className: "size-(--dt-size-xs)" }) : _jsx(Copy, { "aria-hidden": true, className: "size-(--dt-size-xs) text-muted-foreground" }), copied ? "Copied" : label] })) : (_jsx(IconButton, { icon: copied ? Check : Copy, label: copied ? "Copied" : label, onClick: copy, className: className })), _jsx("span", { className: "sr-only", "aria-live": "polite", children: copied ? "Copied" : "" })] }));
+}
+/**
+ * Two to four views of one thing, as a pill track with the chosen one raised.
+ * Tabs underneath, so arrow keys move between them and each panel is labelled by
+ * its tab. Put a `SegmentedList` where the switch belongs and a `SegmentedPanel`
+ * for each view.
+ */
+export function Segmented({ defaultValue, className, children }) {
+    return (_jsx(Tabs.Root, { "data-slot": "segmented", defaultValue: defaultValue, className: cx("flex min-w-0 flex-col", className), children: children }));
+}
+/** The track of a `Segmented`: put it where the switch belongs, usually a toolbar. */
+export function SegmentedList({ items, label }) {
+    return (_jsx(Tabs.List, { "aria-label": label, "data-slot": "segmented-list", className: "relative flex items-center gap-0.5 rounded-lg border border-border p-0.5", children: items.map(({ value, label: text, icon: Icon }) => (_jsxs(Tabs.Tab, { value: value, className: cx("relative inline-flex h-7 cursor-pointer items-center gap-1.5 rounded-md px-2.5 text-xs font-medium text-muted-foreground transition-colors duration-(--dt-duration-fast)", "after:absolute after:inset-x-0 after:-inset-y-[calc((var(--docs-target,2.75rem)-1.75rem)/2)] after:content-['']", "hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring data-active:bg-muted data-active:text-canvas-foreground"), children: [Icon && _jsx(Icon, { "aria-hidden": true, className: "size-(--dt-size-xs)" }), text] }, value))) }));
+}
+export function SegmentedPanel({ value, className, children }) {
+    return (_jsx(Tabs.Panel, { value: value, className: cx("min-w-0 outline-none focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-ring", className), children: children }));
+}
+/** A small label above a group of controls or a column. */
+export function Eyebrow({ className, children }) {
+    return _jsx("p", { className: cx("text-xs font-medium tracking-wide text-muted-foreground uppercase", className), children: children });
+}
+/**
+ * A toolbar menu for one setting: the trigger shows an icon and, when the setting
+ * is not at its default, its current value; the menu lists every option with the
+ * chosen one checked. For viewport, background, colour vision and the like.
+ */
+export function ToolbarMenu({ icon: Icon, label, value, fallback, options, onChange, swatch, }) {
+    const current = options.find((o) => o.value === value);
+    const changed = value !== fallback;
+    return (_jsxs(Menu.Root, { children: [_jsxs(Menu.Trigger, { "aria-label": `${label}: ${current?.label ?? value}`, title: label, className: cx("relative inline-flex h-8 shrink-0 cursor-pointer items-center gap-1.5 rounded-md px-2 text-xs font-medium text-muted-foreground transition-colors duration-(--dt-duration-fast)", "after:absolute after:inset-x-0 after:-inset-y-[calc((var(--docs-target,2.75rem)-2rem)/2)] after:content-['']", "hover:bg-muted hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring data-popup-open:bg-muted data-popup-open:text-canvas-foreground", changed && "bg-muted text-canvas-foreground"), children: [swatch && swatch(value) ? (_jsx("span", { "aria-hidden": true, className: "size-3.5 rounded-full ring-1 ring-border", style: { background: swatch(value) } })) : (_jsx(Icon, { "aria-hidden": true, className: "size-(--dt-size-xs)" })), changed && _jsx("span", { className: "max-w-28 truncate", children: current?.label ?? value }), _jsx(ChevronDown, { "aria-hidden": true, className: "size-3 opacity-60" })] }), _jsx(Menu.Portal, { children: _jsx(Menu.Positioner, { "data-designtools": "", sideOffset: 6, align: "start", className: "z-50", children: _jsx(Menu.Popup, { className: "min-w-56 rounded-xl border border-border bg-overlay p-1.5 text-overlay-foreground shadow-lg transition-[opacity,scale] duration-(--dt-duration-fast) data-ending-style:scale-95 data-ending-style:opacity-0 data-starting-style:scale-95 data-starting-style:opacity-0", children: _jsxs(Menu.Group, { children: [_jsx(Menu.GroupLabel, { className: "px-3 pt-1.5 pb-1 text-xs text-muted-foreground", children: label }), _jsx(Menu.RadioGroup, { value: value, onValueChange: (v) => onChange(v), children: options.map((o) => (_jsxs(Menu.RadioItem, { value: o.value, closeOnClick: true, className: "grid min-h-(--docs-target,2.75rem) cursor-pointer grid-cols-[1rem_1fr] items-center gap-3 rounded-md px-3 text-sm outline-none select-none data-highlighted:bg-muted", children: [_jsx(Menu.RadioItemIndicator, { keepMounted: true, className: "flex items-center justify-center data-unchecked:invisible", children: _jsx(Check, { "aria-hidden": true, className: "size-4" }) }), _jsxs("span", { className: "flex items-center gap-2.5", children: [swatch?.(o.value) && _jsx("span", { "aria-hidden": true, className: "size-4 shrink-0 rounded-full ring-1 ring-border", style: { background: swatch(o.value) } }), _jsxs("span", { className: "flex flex-col", children: [o.label, o.note && _jsx("span", { className: "text-xs text-muted-foreground", children: o.note })] })] })] }, o.value))) })] }) }) }) })] }));
+}
+/** A thin upright rule between groups of toolbar controls. */
+export function ToolbarDivider() {
+    return _jsx("span", { "aria-hidden": true, className: "mx-1 h-5 w-px shrink-0 bg-border" });
+}

package/dist/lib/vision.d.ts

@@ -0,0 +1,18 @@
+/**
+ * How the preview looks to people who see colour differently, or less sharply.
+ * SVG colour matrices for the three common colour-vision deficiencies and for no
+ * colour at all, from Machado, Oliveira and Fernandes (2009) at full severity, and
+ * a blur for low acuity. A simulation is a prompt to look again, not a test.
+ */
+export type Vision = "typical" | "protanopia" | "deuteranopia" | "tritanopia" | "achromatopsia" | "blurred";
+export declare const VISIONS: {
+    value: Vision;
+    label: string;
+    note: string;
+}[];
+/** The filters, once per page; `filterFor` points an element at one. */
+export declare function VisionFilters({ id }: {
+    id: string;
+}): import("react").JSX.Element;
+/** The CSS `filter` for a vision, given the id the filters were rendered with. */
+export declare function filterFor(vision: Vision, id: string): string | undefined;

package/dist/lib/vision.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+export const VISIONS = [
+    { value: "typical", label: "Typical", note: "No simulation" },
+    { value: "protanopia", label: "Protanopia", note: "No red cones, about 1% of men" },
+    { value: "deuteranopia", label: "Deuteranopia", note: "No green cones, about 1% of men" },
+    { value: "tritanopia", label: "Tritanopia", note: "No blue cones, rare" },
+    { value: "achromatopsia", label: "Achromatopsia", note: "No colour at all" },
+    { value: "blurred", label: "Blurred", note: "Low acuity, or a screen far away" },
+];
+const MATRICES = {
+    protanopia: "0.152 1.053 -0.205 0 0  0.115 0.786 0.099 0 0  -0.004 -0.048 1.052 0 0  0 0 0 1 0",
+    deuteranopia: "0.367 0.861 -0.228 0 0  0.280 0.673 0.047 0 0  -0.012 0.043 0.969 0 0  0 0 0 1 0",
+    tritanopia: "1.256 -0.077 -0.179 0 0  -0.078 0.931 0.148 0 0  0.005 0.691 0.304 0 0  0 0 0 1 0",
+    achromatopsia: "0.299 0.587 0.114 0 0  0.299 0.587 0.114 0 0  0.299 0.587 0.114 0 0  0 0 0 1 0",
+};
+/** The filters, once per page; `filterFor` points an element at one. */
+export function VisionFilters({ id }) {
+    return (_jsx("svg", { "aria-hidden": true, width: "0", height: "0", className: "absolute", children: Object.entries(MATRICES).map(([name, values]) => (_jsx("filter", { id: `${id}-${name}`, colorInterpolationFilters: "linearRGB", children: _jsx("feColorMatrix", { type: "matrix", values: values }) }, name))) }));
+}
+/** The CSS `filter` for a vision, given the id the filters were rendered with. */
+export function filterFor(vision, id) {
+    if (vision === "typical")
+        return undefined;
+    if (vision === "blurred")
+        return "blur(1.5px)";
+    return `url(#${id}-${vision})`;
+}

package/dist/logo-usage.d.ts

@@ -0,0 +1,14 @@
+import type { AssetEntry, RuleEntry } from "./lib/manifest-types.js";
+/**
+ * Each logo on the surfaces it may sit on, at its minimum size, with its clear
+ * space drawn, and the brand rules that govern it: rules for every logo once,
+ * above them, and a rule naming one logo under that logo. Surfaces are semantic
+ * colour names painted from the light-mode tokens whatever the docs' mode, because a
+ * brand book's surfaces are fixed colours (white, the brand colour, an off-white),
+ * and dark mode would otherwise show the logo on a surface the brand forbids.
+ */
+export declare function LogoUsage({ assets, rules, rulesHref }: {
+    assets: AssetEntry[];
+    rules?: RuleEntry[];
+    rulesHref?: string;
+}): import("react").JSX.Element;

package/dist/logo-usage.js

@@ -0,0 +1,45 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Scale } from "lucide-react";
+import { useLookup } from "./lib/lookup.js";
+import { StatusBadge } from "./lib/status.js";
+import { inline } from "./lib/text.js";
+const LENGTH = /^\s*(\d+(?:\.\d+)?)(px|rem|em)\b/;
+/**
+ * Each logo on the surfaces it may sit on, at its minimum size, with its clear
+ * space drawn, and the brand rules that govern it: rules for every logo once,
+ * above them, and a rule naming one logo under that logo. Surfaces are semantic
+ * colour names painted from the light-mode tokens whatever the docs' mode, because a
+ * brand book's surfaces are fixed colours (white, the brand colour, an off-white),
+ * and dark mode would otherwise show the logo on a surface the brand forbids.
+ */
+export function LogoUsage({ assets, rules = [], rulesHref }) {
+    const lookup = useLookup();
+    const logos = assets.filter((a) => a.kind === "logo");
+    if (logos.length === 0)
+        return _jsx("p", { className: "text-sm text-muted-foreground", children: "No logos in the brand folder yet." });
+    const brand = rules.filter((r) => r.kind === "brand");
+    const general = brand.filter((r) => (r.appliesTo ?? []).some((x) => ["logo", "logos"].includes(x.toLowerCase())));
+    return (_jsxs("div", { "data-slot": "logo-usage", className: "flex flex-col gap-16", children: [general.length > 0 && _jsx(RuleList, { rules: general, rulesHref: rulesHref }), logos.map((logo) => {
+                const src = lookup.assetUrl(logo);
+                const names = new Set([logo.name.toLowerCase(), logo.file.toLowerCase()]);
+                const own = brand.filter((r) => !general.includes(r) && (r.appliesTo ?? []).some((x) => names.has(x.toLowerCase())));
+                const clear = LENGTH.exec(logo.clearSpace ?? "");
+                const min = LENGTH.exec(logo.minSize ?? "");
+                const surfaces = logo.surfaces?.length ? logo.surfaces : ["canvas"];
+                const paint = (surface) => ({ background: `var(--${surface})`, color: `var(--${surface}-foreground, var(--canvas-foreground))` });
+                const facts = [
+                    [
+                        "Minimum size",
+                        _jsxs("span", { className: "flex flex-wrap items-center gap-3", children: [logo.minSize ?? "not set", src && min && (_jsx("span", { "data-slot": "logo-min-size", "data-theme": "light", className: "inline-flex rounded-md border border-border p-2", style: paint(surfaces[0]), children: _jsx("img", { src: src, alt: "", "aria-hidden": true, className: "block w-auto", style: { height: `${min[1]}${min[2]}` } }) }))] }, "m"),
+                    ],
+                    ["Clear space", logo.clearSpace ?? "not set"],
+                ];
+                if (logo.width && logo.height)
+                    facts.push(["Proportions", _jsxs("span", { className: "font-mono text-xs", children: [logo.width, " \u00D7 ", logo.height] }, "p")]);
+                return (_jsxs("section", { "data-slot": "logo", className: "flex flex-col gap-5", children: [_jsxs("header", { className: "flex flex-col gap-1.5", children: [_jsx("h3", { className: "text-3xl tracking-tight", children: logo.name }), logo.usage && _jsx("p", { className: "max-w-2xl text-base text-muted-foreground", children: inline(logo.usage) })] }), _jsxs("div", { className: "grid gap-3 lg:grid-cols-[minmax(0,2fr)_minmax(0,1fr)]", children: [_jsxs("div", { "data-slot": "logo-surface", "data-theme": "light", className: "relative flex min-h-72 items-center justify-center overflow-hidden rounded-2xl border border-border p-10", style: paint(surfaces[0]), children: [_jsx("span", { className: "absolute top-4 left-4 font-mono text-xs opacity-70", children: surfaces[0] }), _jsxs("span", { className: "relative inline-flex", children: [_jsx("span", { "data-slot": "logo-clear-space", className: "inline-flex border border-dashed", style: { padding: clear ? `calc(${clear[1]}${clear[2]} * 2)` : "1.5rem", borderColor: "color-mix(in oklch, currentColor 45%, transparent)" }, title: `Clear space: ${logo.clearSpace ?? "not set"}`, children: src ? _jsx("img", { src: src, alt: logo.alt ?? logo.name, className: "block h-16 w-auto sm:h-20" }) : _jsx("span", { className: "text-xs", children: logo.file }) }), clear && (_jsx("span", { className: "absolute -bottom-6 left-1/2 -translate-x-1/2 font-mono text-xs whitespace-nowrap opacity-70", children: "clear space, shown at 2\u00D7" }))] })] }), _jsxs("ul", { className: "grid grid-cols-2 gap-3 lg:grid-cols-1 lg:grid-rows-3", children: [surfaces.slice(1).map((surface) => (_jsxs("li", { "data-slot": "logo-surface", "data-theme": "light", className: "relative flex min-h-28 items-center justify-center rounded-2xl border border-border p-6", style: paint(surface), children: [_jsx("span", { className: "absolute top-3 left-3 font-mono text-xs opacity-70", children: surface }), src && _jsx("img", { src: src, alt: "", "aria-hidden": true, className: "block h-9 w-auto" })] }, surface))), surfaces.length === 1 && (_jsxs("li", { className: "col-span-2 flex items-center rounded-2xl border border-dashed border-border p-6 text-sm text-muted-foreground lg:col-span-1 lg:row-span-3", children: ["Only on ", surfaces[0], "."] }))] })] }), _jsx("dl", { className: "grid gap-x-10 gap-y-5 sm:grid-cols-3", children: facts.map(([term, detail]) => (_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsx("dt", { className: "text-xs font-medium text-muted-foreground", children: term }), _jsx("dd", { className: "text-sm", children: detail })] }, term))) }), own.length > 0 && _jsx(RuleList, { rules: own, rulesHref: rulesHref })] }, logo.file));
+            })] }));
+}
+function RuleList({ rules, rulesHref }) {
+    return (_jsx("ul", { "data-slot": "logo-rules", className: "grid gap-x-12 sm:grid-cols-2", children: rules.map((r) => (_jsx("li", { className: "border-t border-border", children: _jsxs("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", children: [_jsxs("span", { className: "flex items-center justify-between gap-2", children: [_jsxs("span", { className: "flex items-center gap-2 text-base font-medium group-hover:underline group-hover:underline-offset-4", children: [_jsx(Scale, { "aria-hidden": true, className: "size-(--dt-size-xs) text-muted-foreground" }), r.title] }), _jsx(StatusBadge, { status: r.status })] }), _jsx("span", { className: "text-muted-foreground", children: inline(r.statement) })] }) }, r.id))) }));
+}

package/dist/next/config.d.ts

@@ -0,0 +1,105 @@
+import type { ComponentType, ReactElement, ReactNode } from "react";
+import type { AdherenceReport } from "../lib/adherence-types.js";
+/** A page people write: brand, principles, a design language, with its author and how settled it is. */
+export type EditorialPage = EditorialBase & ({
+    /** Markdown: `##` and `###` sections, paragraphs, bullet lists, bold, code and links; a list whose items open in bold is a set of principles. */
+    body: string;
+    markdown?: undefined;
+} | {
+    /**
+     * The page as React: real components from the project's system beside the docs' own `DocsSection`
+     * and `Prose`, for a page that has to show rather than tell. Rendered as is, under the page header.
+     */
+    body: ReactNode;
+    /** What agents read instead, at the page's `.md`: the same page, in words. */
+    markdown: string;
+});
+interface EditorialBase {
+    /** Its path under the docs, e.g. `brand` or `brand/accessibility`. */
+    slug: string;
+    title: string;
+    lead?: string;
+    by: {
+        author: string;
+        reviewer?: string;
+        reviewed: string;
+        status: "draft" | "published";
+    };
+    /** The navigation group it sits in. Default: brand. */
+    section?: "brand" | "foundations" | "standards";
+    /** Its label in the navigation, when shorter than its title. */
+    nav?: string;
+}
+/** What a component needs to render on its workbench. */
+export interface WorkbenchSetup {
+    /** Starting props: what it needs to render at all (a Select's options). */
+    props?: Record<string, unknown>;
+    /** Text inside it. "" for a component that takes none. */
+    children?: string;
+    /** Children richer than text: a Card's parts, a Tabs' list and panels. */
+    content?: ReactNode;
+    /** What it must sit inside to work: a provider, the root a part belongs to. */
+    wrap?: ReactElement<{
+        children?: ReactNode;
+    }>;
+}
+/** The built-in generated pages, each of which can be turned off. */
+export type BuiltInPage = "logo" | "imagery" | "voice" | "colour" | "type" | "scale" | "rules" | "patterns" | "components" | "standards" | "vocabulary";
+/**
+ * Everything one site of docs needs: the manifest it renders, the registry that
+ * reaches the project's components, the brand around it, and what each part
+ * says. The pages, their order, the navigation, search and the markdown for
+ * agents all come from this.
+ */
+export interface DocsConfig {
+    title: string;
+    /** Where the docs are served. Default: `/design/system`. */
+    basePath?: string;
+    /** The client's logo, beside the title in the navigation. */
+    logo?: ReactNode;
+    /** A full-bleed introduction across the top of the overview. Without one the overview has a plain header. */
+    hero?: ReactNode;
+    /** The overview's lead, when there is no hero. */
+    lead?: string;
+    /**
+     * The overview after its hero or header: `agentic: false` drops "Why this is agentic", and `agenticLead`
+     * replaces the line that opens it.
+     */
+    overview?: {
+        agentic?: boolean;
+        agenticLead?: string;
+    };
+    /** The generated registry (`designtools-docs map`): a provider for the project's components, examples and assets. */
+    registry: ComponentType<{
+        children: ReactNode;
+    }>;
+    /** The manifest, as `designtools-manifest build` writes it. */
+    manifest: {
+        components: unknown;
+        tokens: unknown;
+        rules?: unknown;
+        patterns?: unknown;
+        taxonomy?: unknown;
+        assets?: unknown;
+    };
+    /** `.mxa/stack.json`'s baselines, for the standards page. */
+    baselines?: Record<string, unknown>;
+    /** `designtools-manifest provenance`'s line: the version and commit the docs were built from. */
+    provenance?: string;
+    /** `designtools-adherence --json`, for the standards page. */
+    adherence?: AdherenceReport;
+    /** Pages people write, in the order they appear. */
+    editorial?: EditorialPage[];
+    /** Built-in pages to leave out. */
+    hide?: BuiltInPage[];
+    /** Per component, by name: what it needs on its workbench. */
+    workbench?: Record<string, WorkbenchSetup>;
+    /** Per rule, by id: a demonstration shown on its card, for a rule that needs persuading. */
+    demonstrations?: Record<string, ReactNode>;
+    /**
+     * Blocks replaced by the project's own, by name: `{ Usage: LocalUsage }`.
+     * `designtools-docs eject <block>` copies one into the project to start from.
+     */
+    blocks?: Partial<Record<string, ComponentType<any>>>;
+}
+export {};

package/dist/next/config.js

@@ -0,0 +1 @@
+export {};