@designtools/docs 0.0.0-stage → 0.1.0

package/dist/swatches.d.ts

@@ -0,0 +1,28 @@
+import { type Mode } from "./lib/manifest.js";
+import type { TokensManifest } from "./lib/manifest-types.js";
+/**
+ * Colour, painted from the tokens rather than restated. Each colour with a
+ * subdued pair is a card: its fill, subdued, hover and press, in light and dark
+ * side by side. Then the surfaces, then the utility colours. Every sample sits
+ * inside its own `data-theme`, so dark is shown as the dark tokens resolve, and
+ * every pair's contrast is measured on the colours the browser actually paints.
+ */
+export declare function SemanticSwatches({ tokens, modes, }: {
+    tokens: TokensManifest;
+    modes?: Mode[];
+}): import("react").JSX.Element;
+/**
+ * Each colour on each background, per mode: a label is measured on its own fill, and this is
+ * everything else, red text on the page, a brand fill on a dark section. Backgrounds are the
+ * canvas, surface and overlay and every named `--surface-<name>`; colours are each semantic fill
+ * and muted text. T: fine as text (4.5:1); S: fine as a shape only (3:1); none: neither.
+ * Measured on what the browser paints, inside each mode's `data-theme`.
+ */
+export declare function PageContrast({ tokens, modes }: {
+    tokens: TokensManifest;
+    modes?: Mode[];
+}): import("react").JSX.Element;
+/** The primitive ramps, one row per colour family, each step painted from its own token. */
+export declare function RampSwatches({ tokens }: {
+    tokens: TokensManifest;
+}): import("react").JSX.Element;

package/dist/swatches.js

@@ -0,0 +1,94 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { contrastRatio, wcagGrade } from "./lib/contrast.js";
+import { cx } from "./lib/cx.js";
+import { ramps, semanticColours, valueIn } from "./lib/manifest.js";
+/**
+ * Colour, painted from the tokens rather than restated. Each colour with a
+ * subdued pair is a card: its fill, subdued, hover and press, in light and dark
+ * side by side. Then the surfaces, then the utility colours. Every sample sits
+ * inside its own `data-theme`, so dark is shown as the dark tokens resolve, and
+ * every pair's contrast is measured on the colours the browser actually paints.
+ */
+export function SemanticSwatches({ tokens, modes = ["light", "dark"], }) {
+    const colours = semanticColours(tokens);
+    const byName = new Map(colours.map((c) => [c.name, c]));
+    const families = colours.filter((c) => byName.has(`${c.name}-subdued`)).map((c) => c.name);
+    const inFamily = new Set(families.flatMap((f) => [f, `${f}-subdued`, `${f}-hover`, `${f}-active`]));
+    const surfaces = colours.filter((c) => !inFamily.has(c.name) && c.foreground).map((c) => c.name);
+    const utility = colours.filter((c) => !inFamily.has(c.name) && !c.foreground).map((c) => c.name);
+    const step = (name, mode) => {
+        const token = byName.get(name)?.background;
+        return token && pointsAt(valueIn(token, mode));
+    };
+    return (_jsxs("div", { "data-slot": "swatches", className: "flex flex-col gap-10", children: [_jsx("div", { className: "grid gap-4 xl:grid-cols-2", children: families.map((f) => (_jsxs("article", { "data-slot": "swatch-family", className: "flex flex-col overflow-hidden rounded-xl border border-border bg-surface text-surface-foreground", children: [_jsxs("header", { className: "flex items-baseline justify-between gap-3 px-4 py-3", children: [_jsx("h3", { className: "text-lg capitalize", children: f.slice(2).replace(/-/g, " ") }), _jsx("code", { className: "font-mono text-xs text-muted-foreground", children: f })] }), _jsx("div", { className: cx("grid border-t border-border", modes.length > 1 && "sm:grid-cols-2"), children: modes.map((mode) => (_jsxs("div", { "data-theme": mode, className: "flex flex-col gap-2 bg-canvas p-3 text-canvas-foreground not-first:border-t not-first:border-border sm:not-first:border-t-0 sm:not-first:border-l", children: [_jsx("span", { className: "text-xs font-medium text-muted-foreground capitalize", children: mode }), _jsx(Chip, { name: f, label: "fill", step: step(f, mode), size: "lg" }), _jsxs("div", { className: "grid grid-cols-3 gap-2", children: [_jsx(Chip, { name: `${f}-subdued`, label: "subdued", step: step(`${f}-subdued`, mode) }), byName.has(`${f}-hover`) && _jsx(Chip, { name: `${f}-hover`, foreground: `${f}-foreground`, label: "hover" }), byName.has(`${f}-active`) && _jsx(Chip, { name: `${f}-active`, foreground: `${f}-foreground`, label: "press" })] })] }, mode))) })] }, f))) }), surfaces.length > 0 && (_jsxs("div", { className: "flex flex-col gap-3", children: [_jsx("h3", { className: "text-2xl tracking-tight", children: "Surfaces" }), _jsx("div", { className: cx("grid gap-4", modes.length > 1 && "lg:grid-cols-2"), children: modes.map((mode) => (_jsxs("div", { "data-theme": mode, className: "flex flex-col gap-2 rounded-xl border border-border bg-canvas p-3 text-canvas-foreground", children: [_jsx("span", { className: "text-xs font-medium text-muted-foreground capitalize", children: mode }), _jsx("div", { className: "grid grid-cols-2 gap-2 sm:grid-cols-3", children: surfaces.map((name) => (_jsx(Chip, { name: name, label: name.slice(2), step: step(name, mode), outlined: true }, name))) })] }, mode))) })] })), utility.length > 0 && (_jsxs("div", { className: "flex flex-col gap-3", children: [_jsx("h3", { className: "text-2xl tracking-tight", children: "Lines, focus and shadow" }), _jsx("div", { className: cx("grid gap-4", modes.length > 1 && "lg:grid-cols-2"), children: modes.map((mode) => (_jsxs("div", { "data-theme": mode, className: "flex flex-col gap-2 rounded-xl border border-border bg-canvas p-3 text-canvas-foreground", children: [_jsx("span", { className: "text-xs font-medium text-muted-foreground capitalize", children: mode }), _jsx("ul", { className: "grid grid-cols-2 gap-2", children: utility.map((name) => (_jsxs("li", { "data-slot": "swatch", className: "flex items-center gap-2 rounded-lg bg-surface p-2 text-surface-foreground", children: [_jsx("span", { "aria-hidden": true, className: "size-8 shrink-0 rounded-md border border-border", style: { background: `var(${name})` } }), _jsxs("span", { className: "flex min-w-0 flex-col font-mono text-xs", children: [_jsx("span", { className: "truncate font-medium", children: name.slice(2) }), _jsx("span", { className: "truncate text-muted-foreground", children: step(name, mode) })] })] }, name))) })] }, mode))) })] }))] }));
+}
+/** `var(--color-primary-500)` → `primary-500`: the step it points at, which is what a person compares. */
+function pointsAt(value) {
+    const m = value && /^var\(--color-([\w-]+)\)$/.exec(value);
+    if (m)
+        return m[1];
+    return value?.startsWith("oklch(") ? "generated" : value;
+}
+/**
+ * One background with its foreground on it, labelled in that foreground, with the
+ * contrast measured on what the browser paints. It reads its mode from the nearest
+ * `data-theme` around it.
+ */
+function Chip({ name, foreground = `${name}-foreground`, label, step, size = "md", outlined, }) {
+    const chip = useRef(null);
+    const [ratio, setRatio] = useState(null);
+    useEffect(() => {
+        const node = chip.current;
+        if (!node)
+            return;
+        const style = getComputedStyle(node);
+        setRatio(contrastRatio(style.color, style.backgroundColor));
+    }, [name, foreground]);
+    const grade = ratio === null ? null : wcagGrade(ratio);
+    const fails = grade === "Fail";
+    const measured = grade && ratio !== null ? `${ratio.toFixed(1)}:1 ${grade}` : undefined;
+    return (_jsxs("div", { ref: chip, "data-slot": "swatch", title: `${name} with ${foreground}${step ? ` · ${step}` : ""}${measured ? ` · ${measured}` : ""}`, className: cx("flex min-w-0 flex-col justify-between gap-3 rounded-lg p-3", size === "lg" ? "min-h-28" : "min-h-20", outlined && "border border-border"), style: { background: `var(${name})`, color: `var(${foreground})` }, children: [size === "lg" ? (_jsxs("span", { className: "flex items-start justify-between gap-2", children: [_jsx("span", { className: "text-3xl leading-none tracking-tight", children: "Aa" }), measured && (_jsx("span", { "data-slot": "swatch-contrast", className: cx("rounded-full px-2 py-0.5 font-mono text-xs whitespace-nowrap", fails ? "bg-destructive font-medium text-destructive-foreground" : "ring-1 ring-current/30"), children: measured }))] })) : (_jsx("span", { className: "text-base leading-none font-medium", children: "Aa" })), _jsxs("span", { className: "flex min-w-0 flex-col font-mono text-xs leading-snug", children: [_jsx("span", { className: "truncate font-medium", children: label }), size === "lg" ? (step && _jsx("span", { className: "truncate opacity-75", children: step })) : (measured && (_jsx("span", { "data-slot": "swatch-contrast", className: cx("truncate", fails ? "w-fit rounded-sm bg-destructive px-1 text-destructive-foreground" : "opacity-75"), children: measured })))] })] }));
+}
+/**
+ * Each colour on each background, per mode: a label is measured on its own fill, and this is
+ * everything else, red text on the page, a brand fill on a dark section. Backgrounds are the
+ * canvas, surface and overlay and every named `--surface-<name>`; colours are each semantic fill
+ * and muted text. T: fine as text (4.5:1); S: fine as a shape only (3:1); none: neither.
+ * Measured on what the browser paints, inside each mode's `data-theme`.
+ */
+export function PageContrast({ tokens, modes = ["light", "dark"] }) {
+    const names = new Set(semanticColours(tokens).map((c) => c.name));
+    const colours = [...names].filter((n) => names.has(`${n}-subdued`)).concat(names.has("--muted") ? ["--muted-foreground"] : []);
+    const grounds = ["--canvas", "--surface", "--overlay", ...[...names].filter((n) => n.startsWith("--surface-") && !n.endsWith("-foreground") && n !== "--surface-foreground")];
+    return (_jsx("div", { "data-slot": "page-contrast", className: "flex flex-col gap-6", children: modes.map((mode) => (_jsx(PageGrid, { mode: mode, colours: colours, grounds: grounds }, mode))) }));
+}
+function PageGrid({ mode, colours, grounds }) {
+    const probe = useRef(null);
+    const [ratios, setRatios] = useState({});
+    useEffect(() => {
+        const node = probe.current;
+        if (!node)
+            return;
+        const paint = (v) => {
+            node.style.color = `var(${v})`;
+            return getComputedStyle(node).color;
+        };
+        const painted = Object.fromEntries([...colours, ...grounds].map((v) => [v, paint(v)]));
+        const out = {};
+        for (const c of colours)
+            for (const g of grounds)
+                out[`${c}|${g}`] = contrastRatio(painted[c], painted[g]);
+        setRatios(out);
+    }, [colours, grounds]);
+    return (_jsxs("div", { className: "overflow-x-auto rounded-2xl border border-border bg-surface text-surface-foreground", tabIndex: 0, role: "region", "aria-label": `Colours on each background, ${mode} mode`, children: [_jsx("div", { ref: probe, "data-theme": mode, hidden: true }), _jsxs("table", { className: "w-full min-w-[32rem] border-collapse text-left text-sm", children: [_jsx("caption", { className: "border-b border-border px-4 py-3 text-left text-sm font-semibold capitalize", children: mode }), _jsx("thead", { children: _jsxs("tr", { className: "border-b border-border bg-muted/50 text-xs text-muted-foreground", children: [_jsx("th", { scope: "col", className: "px-4 py-2.5 font-medium", children: "Colour" }), grounds.map((g) => (_jsx("th", { scope: "col", className: "px-4 py-2.5 font-mono font-medium", children: g.slice(2) }, g)))] }) }), _jsx("tbody", { children: colours.map((c) => (_jsxs("tr", { className: "border-b border-border last:border-b-0", children: [_jsx("th", { scope: "row", className: "px-4 py-2.5 font-mono text-xs font-medium", children: c.slice(2) }), grounds.map((g) => {
+                                    const r = ratios[`${c}|${g}`];
+                                    const mark = r == null ? "" : r >= 4.5 ? "text" : r >= 3 ? "shape" : "none";
+                                    return (_jsx("td", { className: "px-4 py-2.5", children: _jsxs("div", { className: "flex items-center gap-2", children: [_jsx("span", { "data-theme": mode, className: "flex h-9 w-12 items-center justify-center rounded-lg border border-(--border) text-base font-bold", style: { background: `var(${g})`, color: `var(${c})` }, "aria-hidden": true, children: "Aa" }), r != null && (_jsxs("span", { className: cx("inline-flex items-center gap-1 rounded-full px-2 py-0.5 font-mono text-xs", mark === "text" && "bg-success-subdued text-success-subdued-foreground", mark === "shape" && "bg-muted text-muted-foreground", mark === "none" && "bg-destructive-subdued text-destructive-subdued-foreground"), children: [r.toFixed(1), " ", mark] }))] }) }, g));
+                                })] }, c))) })] })] }));
+}
+/** The primitive ramps, one row per colour family, each step painted from its own token. */
+export function RampSwatches({ tokens }) {
+    return (_jsx("div", { "data-slot": "ramps", className: "flex flex-col gap-5 overflow-x-auto", tabIndex: 0, role: "region", "aria-label": "Ramps", children: ramps(tokens).map((ramp) => (_jsxs("div", { "data-slot": "ramp", className: "grid min-w-[36rem] grid-cols-[6rem_1fr] items-center gap-4", children: [_jsx("p", { className: "font-mono text-xs font-medium capitalize", children: ramp.family }), _jsx("ol", { className: "grid grid-flow-col auto-cols-fr gap-1", children: ramp.steps.map(({ step, token }) => (_jsxs("li", { "data-slot": "ramp-step", title: `${token.name}: ${token.values.default ?? ""}`, className: "flex flex-col gap-1.5", children: [_jsx("span", { "aria-hidden": true, className: "h-12 rounded-md ring-1 ring-border ring-inset", style: { background: `var(${token.name})` } }), _jsx("span", { className: "text-center font-mono text-xs text-muted-foreground", children: step })] }, step))) })] }, ramp.family))) }));
+}

package/dist/theme-switch.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Runs before the first paint, so a saved choice never flashes the other mode. It
+ * sets `data-theme` on <html>, which the generated tokens read, so give <html>
+ * `suppressHydrationWarning`. System sets nothing and leaves it to the media query.
+ */
+export declare const themeScript = "try{var t=localStorage.getItem(\"docs-theme\");if(t===\"light\"||t===\"dark\")document.documentElement.dataset.theme=t}catch(e){}";
+/**
+ * Writes `themeScript` into the server's HTML, once, ahead of the page. Through
+ * Next's `useServerInsertedHTML`, because React will not run a <script> a client
+ * component renders, and says so. The shell calls it; call it once yourself if the
+ * switch lives somewhere else.
+ */
+export declare function useThemeScript(): void;
+/**
+ * System, light or dark for the whole site, as three icons in a track. Kept per
+ * viewer. Each is a 44px target however small it is drawn.
+ */
+export declare function ThemeSwitch({ className }: {
+    className?: string;
+}): import("react").JSX.Element;

package/dist/theme-switch.js

@@ -0,0 +1,68 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Monitor, Moon, Sun } from "lucide-react";
+import { useServerInsertedHTML } from "next/navigation";
+import { useEffect, useRef, useState } from "react";
+import { cx } from "./lib/cx.js";
+const MODES = [
+    { mode: "system", label: "System", Icon: Monitor },
+    { mode: "light", label: "Light", Icon: Sun },
+    { mode: "dark", label: "Dark", Icon: Moon },
+];
+const KEY = "docs-theme";
+/**
+ * Runs before the first paint, so a saved choice never flashes the other mode. It
+ * sets `data-theme` on <html>, which the generated tokens read, so give <html>
+ * `suppressHydrationWarning`. System sets nothing and leaves it to the media query.
+ */
+export const themeScript = `try{var t=localStorage.getItem("${KEY}");if(t==="light"||t==="dark")document.documentElement.dataset.theme=t}catch(e){}`;
+/**
+ * Writes `themeScript` into the server's HTML, once, ahead of the page. Through
+ * Next's `useServerInsertedHTML`, because React will not run a <script> a client
+ * component renders, and says so. The shell calls it; call it once yourself if the
+ * switch lives somewhere else.
+ */
+export function useThemeScript() {
+    const done = useRef(false);
+    useServerInsertedHTML(() => {
+        if (done.current)
+            return null;
+        done.current = true;
+        // biome-ignore lint/security/noDangerouslySetInnerHtml: a fixed string, written here, with nothing from the request in it
+        return _jsx("script", { dangerouslySetInnerHTML: { __html: themeScript } });
+    });
+}
+function apply(mode) {
+    const root = document.documentElement;
+    if (mode === "system")
+        delete root.dataset.theme;
+    else
+        root.dataset.theme = mode;
+    try {
+        if (mode === "system")
+            localStorage.removeItem(KEY);
+        else
+            localStorage.setItem(KEY, mode);
+    }
+    catch {
+        // private windows and blocked storage: the choice lasts for this page only
+    }
+}
+/**
+ * System, light or dark for the whole site, as three icons in a track. Kept per
+ * viewer. Each is a 44px target however small it is drawn.
+ */
+export function ThemeSwitch({ className }) {
+    const [mode, setMode] = useState("system");
+    useEffect(() => {
+        const t = document.documentElement.dataset.theme;
+        if (t === "light" || t === "dark")
+            setMode(t);
+    }, []);
+    return (_jsx("div", { role: "group", "aria-label": "Colour mode", "data-slot": "docs-theme-switch", className: cx("flex items-center rounded-full bg-muted p-0.5", className), children: MODES.map(({ mode: m, label, Icon }) => (_jsx("button", { type: "button", "aria-pressed": mode === m, "aria-label": label, title: label, onClick: () => {
+                setMode(m);
+                apply(m);
+            }, 
+            // drawn at 32px; the transparent ring of padding makes each a 44px target
+            className: "relative -my-1.5 inline-flex size-(--docs-target,2.75rem) cursor-pointer items-center justify-center rounded-full p-1.5 text-muted-foreground transition-colors duration-(--dt-duration-fast) first:-ml-1.5 last:-mr-1.5 hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring aria-pressed:text-canvas-foreground", children: _jsx("span", { "aria-hidden": true, className: cx("flex size-full items-center justify-center rounded-full transition-colors duration-(--dt-duration-fast)", mode === m && "bg-surface shadow-xs ring-1 ring-border"), children: _jsx(Icon, { className: "size-(--dt-size-xs)" }) }) }, m))) }));
+}

package/dist/type-ramp.d.ts

@@ -0,0 +1,10 @@
+import type { TokensManifest } from "./lib/manifest-types.js";
+/**
+ * Type, set in its own tokens: each family as a specimen, then the scale, each
+ * size with the leading and tracking Tailwind pairs with it, then weights,
+ * leading and tracking on their own. Every sample reads its token; nothing is restated.
+ */
+export declare function TypeRamp({ tokens, sample, }: {
+    tokens: TokensManifest;
+    sample?: string;
+}): import("react").JSX.Element;

package/dist/type-ramp.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { shortName, tokensOfTier, typeScale, withGroupDescriptions } from "./lib/manifest.js";
+/** `1.125rem` → `18px`, so a person reads the size they know. */
+function px(value) {
+    const m = value && /^(\d*\.?\d+)rem$/.exec(value.trim());
+    return m ? `${Math.round(Number(m[1]) * 16 * 100) / 100}px` : undefined;
+}
+/**
+ * Type, set in its own tokens: each family as a specimen, then the scale, each
+ * size with the leading and tracking Tailwind pairs with it, then weights,
+ * leading and tracking on their own. Every sample reads its token; nothing is restated.
+ */
+export function TypeRamp({ tokens, sample = "The quick brown fox jumps over the lazy dog", }) {
+    const steps = withGroupDescriptions(typeScale(tokens).map((s) => ({ ...s, description: s.size.description })));
+    const families = tokensOfTier(tokens, "font");
+    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: {
+                                fontSize: `var(${step.name})`,
+                                lineHeight: step.lineHeight ? `var(${step.lineHeight.name})` : undefined,
+                                letterSpacing: step.letterSpacing ? `var(${step.letterSpacing.name})` : undefined,
+                                fontWeight: step.fontWeight ? `var(${step.fontWeight.name})` : undefined,
+                            }, children: sample })] }, step.name))) }), weights.length > 0 && (_jsx(Group, { title: "Weights", children: _jsx("ul", { className: "grid grid-cols-2 gap-x-10 gap-y-8 sm:grid-cols-4", children: weights.map((t) => (_jsxs("li", { className: "flex flex-col gap-3 border-t border-border pt-4", children: [_jsx("span", { className: "text-4xl leading-none tracking-tight", style: { fontWeight: `var(${t.name})` }, children: "Aa" }), _jsx(Meta, { token: t, prefix: "font-weight" })] }, t.name))) }) })), (leading.length > 0 || tracking.length > 0) && (_jsxs("div", { className: "grid gap-10 lg:grid-cols-2", children: [leading.length > 0 && (_jsx(Group, { title: "Leading", children: _jsx("ul", { className: "flex flex-col", children: leading.map((t) => (_jsxs("li", { className: "grid grid-cols-[6rem_minmax(0,1fr)] gap-4 border-t border-border py-4", children: [_jsx(Meta, { token: t, prefix: "leading" }), _jsxs("span", { className: "line-clamp-2 text-sm", style: { lineHeight: `var(${t.name})` }, children: [sample, ". ", sample, "."] })] }, t.name))) }) })), tracking.length > 0 && (_jsx(Group, { title: "Tracking", children: _jsx("ul", { className: "flex flex-col", children: tracking.map((t) => (_jsxs("li", { className: "grid grid-cols-[6rem_minmax(0,1fr)] items-center gap-4 border-t border-border py-4", children: [_jsx(Meta, { token: t, prefix: "tracking" }), _jsx("span", { className: "truncate text-lg font-medium", style: { letterSpacing: `var(${t.name})` }, children: sample })] }, t.name))) }) }))] }))] }));
+}
+function Group({ title, children }) {
+    return (_jsxs("div", { "data-slot": "type-table", className: "flex flex-col gap-4", children: [_jsx("h3", { className: "text-2xl tracking-tight", children: title }), children] }));
+}
+function Meta({ token, prefix }) {
+    return (_jsxs("span", { className: "flex min-w-0 flex-col font-mono text-xs", children: [_jsx("span", { className: "font-medium", children: shortName(token, prefix) }), _jsx("span", { className: "truncate text-muted-foreground", title: token.values.default, children: token.values.default })] }));
+}

package/dist/usage.d.ts

@@ -0,0 +1,13 @@
+import type { ComponentEntry, ComponentsManifest } from "./lib/manifest-types.js";
+/**
+ * When to use a component and when not, side by side, with what to use instead;
+ * then its facts in one strip: status, role, keys, the primitive it wraps and the
+ * elements it replaces. Written by people as JSDoc (`@use`, `@avoid`, `@instead`,
+ * `@status`, `@role`, `@keyboard`); a component without them says so.
+ */
+export declare function Usage({ entry, manifest, basePath, }: {
+    entry: ComponentEntry;
+    /** To link `instead` names that are components. */
+    manifest?: ComponentsManifest;
+    basePath?: string;
+}): import("react").JSX.Element;

package/dist/usage.js

@@ -0,0 +1,55 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ArrowUpRight, CircleCheck, CircleX } from "lucide-react";
+import Link from "next/link";
+import { cx } from "./lib/cx.js";
+import { slugOf } from "./lib/manifest.js";
+import { StatusBadge } from "./lib/status.js";
+import { inline } from "./lib/text.js";
+/**
+ * When to use a component and when not, side by side, with what to use instead;
+ * then its facts in one strip: status, role, keys, the primitive it wraps and the
+ * elements it replaces. Written by people as JSDoc (`@use`, `@avoid`, `@instead`,
+ * `@status`, `@role`, `@keyboard`); a component without them says so.
+ */
+export function Usage({ entry, manifest, basePath = "/design/system", }) {
+    const usage = entry.usage;
+    const known = new Map((manifest?.components ?? []).map((c) => [c.name, c]));
+    const instead = usage?.instead?.length ? (_jsxs("p", { className: "flex flex-wrap items-center gap-x-3 gap-y-1 text-sm text-muted-foreground", children: ["Use instead", usage.instead.map((name) => {
+                const c = known.get(name);
+                return c ? (_jsxs(Link, { href: `${basePath}/components/${slugOf(c)}`, className: "relative inline-flex items-center gap-0.5 text-canvas-foreground underline decoration-border underline-offset-4 hover:decoration-current focus-visible:outline-2 focus-visible:outline-ring after:absolute after:-inset-3 after:content-['']", children: [name, _jsx(ArrowUpRight, { "aria-hidden": true, className: "size-3.5 text-muted-foreground" })] }, name)) : (_jsx("span", { className: "font-medium text-canvas-foreground", children: name }, name));
+            })] })) : null;
+    const facts = [["Status", _jsx(Status, { entry: entry }, "s")]];
+    if (entry.a11y?.role)
+        facts.push(["Role", _jsx("code", { className: "font-mono text-xs", children: entry.a11y.role }, "r")]);
+    if (entry.a11y?.keyboard?.length)
+        facts.push([
+            "Keyboard",
+            _jsx("span", { className: "flex flex-wrap gap-1", children: entry.a11y.keyboard.map((k) => (_jsx("kbd", { className: "rounded-sm border border-border px-1.5 font-mono text-xs leading-5", children: k }, k))) }, "k"),
+        ]);
+    if (entry.primitive)
+        facts.push(["Built on", _jsx(Source, { href: entry.primitive }, "p")]);
+    if (entry.replaces?.length)
+        facts.push([
+            "Replaces",
+            _jsx("span", { className: "flex flex-wrap gap-1", children: entry.replaces.map((r) => (_jsx("code", { className: "font-mono text-xs", children: `<${r}>` }, r))) }, "x"),
+        ]);
+    return (_jsxs("div", { "data-slot": "usage", className: "flex flex-col gap-10", children: [usage?.use || usage?.avoid ? (_jsxs("div", { className: "grid gap-10 md:grid-cols-2 md:gap-12", children: [_jsx(Column, { tone: "do", title: "Use it for", children: usage?.use ? inline(usage.use) : _jsx("span", { className: "text-muted-foreground", children: "Not written yet." }) }), _jsx(Column, { tone: "dont", title: "Not for", footer: instead, children: usage?.avoid ? inline(usage.avoid) : _jsx("span", { className: "text-muted-foreground", children: "Not written yet." }) })] })) : (_jsxs("p", { className: "text-base text-muted-foreground", children: ["No usage guidance yet. Add ", _jsx("code", { className: "font-mono text-sm", children: "@use" }), ", ", _jsx("code", { className: "font-mono text-sm", children: "@avoid" }), " and", " ", _jsx("code", { className: "font-mono text-sm", children: "@instead" }), " to its JSDoc."] })), _jsx("dl", { "data-slot": "usage-facts", className: "flex flex-wrap gap-x-12 gap-y-6", children: facts.map(([term, detail]) => (_jsxs("div", { className: "flex min-w-0 flex-col gap-2", children: [_jsx("dt", { className: "text-xs text-muted-foreground", children: term }), _jsx("dd", { className: "text-sm", children: detail })] }, term))) })] }));
+}
+/** One side of when to use it: a hairline, a small label with its icon in the status colour, and the guidance at reading size. */
+function Column({ tone, title, footer, children }) {
+    const Icon = tone === "do" ? CircleCheck : CircleX;
+    return (_jsxs("div", { className: "flex flex-col gap-3 border-t border-border pt-5", children: [_jsxs("p", { className: "flex items-center gap-2 text-sm text-muted-foreground", children: [_jsx(Icon, { "aria-hidden": true, className: cx("size-4", tone === "do" ? "text-success-subdued-foreground" : "text-destructive-subdued-foreground") }), title] }), _jsx("p", { className: "text-lg leading-relaxed text-canvas-foreground/85 [&_code]:bg-transparent [&_code]:p-0 [&_code]:text-[0.875em]", children: children }), footer] }));
+}
+function Status({ entry }) {
+    return (_jsxs("span", { className: "flex flex-col items-start gap-1.5", children: [_jsx(StatusBadge, { status: entry.status }), entry.statusNote && _jsx("span", { className: "text-xs text-muted-foreground", children: inline(entry.statusNote) })] }));
+}
+/** A primitive: a link names the site and the page (`Base UI · avatar`), a package path shows as code. */
+function Source({ href }) {
+    if (!/^https?:/.test(href))
+        return _jsx("code", { className: "font-mono text-xs", children: href });
+    const url = new URL(href);
+    const name = url.pathname.split("/").filter(Boolean).pop() ?? "";
+    const host = url.host.replace(/^www\./, "");
+    const site = host === "base-ui.com" ? "Base UI" : host.replace(/\.[a-z]+$/, "");
+    return (_jsxs("a", { href: href, title: href, className: "group inline-flex items-center gap-1 whitespace-nowrap hover:underline hover:underline-offset-4 focus-visible:outline-2 focus-visible:outline-ring", children: [site, name && _jsxs("span", { className: "text-muted-foreground", children: ["\u00B7 ", name] }), _jsx(ArrowUpRight, { "aria-hidden": true, className: "size-3.5 text-muted-foreground" })] }));
+}

package/dist/variant-matrix.d.ts

@@ -0,0 +1,15 @@
+import { 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, }: {
+    entry: ComponentEntry;
+    props?: Record<string, unknown>;
+    /** What to render inside each instance. Defaults to the component's name. */
+    children?: ReactNode;
+    /** Limit and order the axes shown. */
+    axes?: string[];
+}): import("react").JSX.Element;

package/dist/variant-matrix.js

@@ -0,0 +1,53 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Grid3x3, Moon, Sun } from "lucide-react";
+import { useEffect, useState } from "react";
+import { cx } from "./lib/cx.js";
+import { coerce, Missing, useLookup } from "./lib/lookup.js";
+import { installPseudoStates } from "./lib/pseudo.js";
+import { Frame, IconButton, Toolbar } from "./lib/ui.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 function VariantMatrix({ entry, props = {}, children, axes: only, }) {
+    const lookup = useLookup();
+    const Component = lookup.componentFor(entry);
+    const [theme, setTheme] = useState();
+    const all = entry.variants?.axes ?? [];
+    const axes = only ? only.map((n) => all.find((a) => a.name === n)).filter((a) => !!a) : all;
+    if (!Component)
+        return _jsx(Missing, { name: entry.name });
+    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(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("div", { "data-slot": "variant-matrix", className: "flex flex-col gap-6", children: [cols ? (_jsxs(Frame, { 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)" }), rows.name, " \u00D7 ", cols.name] }), toggle] }), _jsx("div", { "data-docs-stage": "", "data-theme": theme, className: "overflow-x-auto bg-canvas text-canvas-foreground", 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", { className: "border-b border-border", children: [_jsx("th", { scope: "col", className: "w-0 p-0" }), cols.options.map((c) => (_jsx("th", { scope: "col", title: c.description, className: "px-4 py-3 text-center font-mono text-xs font-medium text-muted-foreground", children: _jsx(OptionName, { axis: cols, option: c.name }) }, c.name)))] }) }), _jsx("tbody", { children: rows.options.map((r) => (_jsxs("tr", { className: "border-b border-border last:border-b-0", children: [_jsx("th", { scope: "row", title: r.description, className: "border-r border-border px-4 py-5 text-left font-mono text-xs font-medium 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-5 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, theme: theme, toggle: toggle })), rest.map((axis) => (_jsx(AxisRow, { axis: axis, render: render, theme: theme, toggle: toggle }, axis.name))), _jsx(States, { render: render, theme: theme, toggle: toggle, canDisable: "disabled" in entry.props })] }));
+}
+/**
+ * The component at its defaults in each state at once: at rest, hovered, focused,
+ * pressed and disabled, pinned without a pointer or a keyboard, so states are
+ * reviewed side by side rather than by mousing over each.
+ */
+function States({ render, theme, toggle, canDisable, }) {
+    useEffect(() => installPseudoStates(), []);
+    const states = [
+        { name: "rest" },
+        { name: "hover", pseudo: "hover" },
+        { name: "focus", pseudo: "focus" },
+        { name: "press", pseudo: "active" },
+        ...(canDisable ? [{ name: "disabled", extra: { disabled: "true" } }] : []),
+    ];
+    return (_jsxs(Frame, { "data-slot": "variant-states", children: [_jsxs(Toolbar, { children: [_jsx("span", { className: "pl-2 font-mono text-xs text-muted-foreground", children: "state" }), toggle] }), _jsx("div", { "data-docs-stage": "", "data-theme": theme, className: "flex flex-wrap items-end justify-center gap-x-10 gap-y-6 bg-canvas px-6 py-8 text-canvas-foreground", children: states.map((s) => (_jsxs("figure", { className: "flex flex-col items-center gap-3", children: [_jsx("div", { "data-pseudo": s.pseudo, children: render(s.extra ?? {}) }), _jsx("figcaption", { className: "font-mono text-xs text-muted-foreground", children: s.name })] }, s.name))) })] }));
+}
+function AxisRow({ axis, render, theme, toggle, }) {
+    return (_jsxs(Frame, { "data-slot": "variant-axis", children: [_jsxs(Toolbar, { children: [_jsx("span", { className: "pl-2 font-mono text-xs text-muted-foreground", children: axis.name }), toggle] }), _jsx("div", { "data-docs-stage": "", "data-theme": theme, className: "flex flex-wrap items-end justify-center gap-x-10 gap-y-6 bg-canvas px-6 py-8 text-canvas-foreground", children: axis.options.map((o) => (_jsxs("figure", { className: "flex flex-col items-center gap-3", children: [render({ [axis.name]: o.name }), _jsx("figcaption", { className: "font-mono text-xs text-muted-foreground", title: o.description, children: _jsx(OptionName, { axis: axis, option: o.name }) })] }, o.name))) })] }));
+}
+/** An option's name, with the default marked by a dot and said for screen readers. */
+function OptionName({ axis, option }) {
+    const isDefault = axis.default === option;
+    return (_jsxs("span", { className: cx("inline-flex items-center gap-1.5", isDefault && "text-canvas-foreground"), children: [option, isDefault && (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": true, className: "size-1.5 rounded-full bg-[var(--docs-accent,var(--primary))]" }), _jsx("span", { className: "sr-only", children: "(default)" })] }))] }));
+}

package/dist/voice-terms.d.ts

@@ -0,0 +1,5 @@
+import type { TermEntry } from "./lib/manifest-types.js";
+/** The words to use, beside the ones not to: the product's words first, then the system's names that have wrong forms. */
+export declare function VoiceTerms({ terms }: {
+    terms: TermEntry[];
+}): import("react").JSX.Element;

package/dist/voice-terms.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { inline } from "./lib/text.js";
+/** The words to use, beside the ones not to: the product's words first, then the system's names that have wrong forms. */
+export function VoiceTerms({ terms }) {
+    const product = terms.filter((t) => t.kind === "product");
+    const system = terms.filter((t) => t.kind !== "product" && t.wrong?.length);
+    if (product.length + system.length === 0)
+        return _jsx("p", { className: "text-sm text-muted-foreground", children: "No terms yet. Add them to the taxonomy file." });
+    return (_jsxs("div", { "data-slot": "voice-terms", className: "flex flex-col gap-12", children: [product.length > 0 && _jsx(Group, { title: "In the product", terms: product }), system.length > 0 && _jsx(Group, { title: "In the system", terms: system })] }));
+}
+function Group({ title, terms }) {
+    return (_jsxs("section", { className: "flex flex-col gap-2", children: [_jsx("h3", { className: "text-xs font-medium tracking-wide text-muted-foreground uppercase", children: title }), _jsx("dl", { className: "grid gap-x-12 sm:grid-cols-2", children: terms.map((t) => (_jsxs("div", { "data-slot": "term", className: "flex flex-col gap-1.5 border-t border-border py-5", children: [_jsxs("dt", { className: "text-3xl tracking-tight", children: [t.name, _jsx("span", { className: "sr-only", children: ", say this" })] }), (t.wrong ?? []).length > 0 && (_jsxs("dd", { className: "flex flex-wrap gap-x-3 text-base text-muted-foreground", children: [_jsx("span", { className: "sr-only", children: "not " }), (t.wrong ?? []).map((w) => (_jsx("s", { className: "decoration-destructive decoration-2", children: w }, w)))] })), (t.note || t.kind !== "product") && (_jsx("dd", { className: "text-sm text-muted-foreground", children: t.note ? inline(t.note) : `The ${t.kind}'s name in the code.` }))] }, `${t.kind}:${t.name}`))) })] }));
+}

package/dist/workbench.d.ts

@@ -0,0 +1,33 @@
+import { type ReactElement, type ReactNode } from "react";
+import type { ComponentEntry } from "./lib/manifest-types.js";
+/**
+ * A component's one main area. On the stage: the component live, at any viewport
+ * and zoom, on any background, in either mode or direction, as people with
+ * different colour vision see it, with its boxes outlined or measured, and pinned
+ * at rest, hovered, focused, pressed or disabled. Beside it: a property for each
+ * variant and each prop, generated from their types. Under it: the code for
+ * exactly what is showing, the props, a log of every handler that fires, what an
+ * agent reads, and a full accessibility report that re-runs as anything changes.
+ * Every setting is in the URL, so a configuration can be shared as a link.
+ *
+ * Pass `props` for what it needs to render at all (its starting values), `content`
+ * for children richer than text (a Card's parts), and `wrap` for what it must sit
+ * inside to work (a provider, the root a part belongs to): an element, which the
+ * component is rendered into.
+ */
+export declare function Workbench({ entry, props: base, children: initialText, content, wrap, backgrounds, previewHref, }: {
+    entry: ComponentEntry;
+    props?: Record<string, unknown>;
+    /** Text content, editable here. Pass "" for a component without children. */
+    children?: string;
+    /** Children richer than text; replaces the text control. */
+    content?: ReactNode;
+    /** An element to render the component inside: a provider, or the root a part needs. */
+    wrap?: ReactElement<{
+        children?: ReactNode;
+    }>;
+    /** Named backgrounds the brand has (`surface-stone`), offered on the stage beside canvas, surface and muted. */
+    backgrounds?: string[];
+    /** The preview route for its canonical example, opened from the toolbar. */
+    previewHref?: string;
+}): import("react").JSX.Element;