@designtools/docs 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# @designtools/docs
+
+## 0.2.0
+
+### Minor Changes
+
+- a8e0eee: Editorial pages can be components: `body` takes React, with `markdown` for agents, and `DocsSection`, `Prose` and `Live` are exported for composing them. `Live` marks the project's own components inside the docs, and the docs' CSS never matches inside it: the docs' utilities no longer beat a project's responsive utilities on its components (a hero's `hidden lg:flex`), and a project's utilities no longer beat the docs' on their own elements, whichever stylesheet loads last. A legacy `:before` in the scoped CSS no longer invalidates its rule.
+  
+  The overview explains the system instead of listing every component: each part, why it exists, its count and a glimpse of it, then "Why this is agentic" for client and design leads (`overview` in the config tunes or drops it).
+  
+  Layout: the colour page drops its nested cards for open rows with a panel per mode; rules have an index and a two-column layout with the check beside the statement; pattern pages show the compositions first, status in the header and "Made of" below; variants sit on one stage without grid lines; vocabulary and voice share a calm term row (say, not, why) with a quiet search and a correction callout; navigation links read as links and group headings recede; section numbers align to their titles; the page header loses its rule; previous and next come before where the page came from, which is last; the phone drawer has room above its first item; the props tooltip is ink and opens at once.
+
+## 0.1.0
+
+### Minor Changes
+
+- 637fc1f: First release. A design system's docs as a package: every page generated from the manifest, rendering the project's real components; nested navigation, search and a colour-mode switch; a workbench per component (viewports, zoom, backgrounds, colour-vision simulation, outline and measure, pinned states, generated controls, an actions log, shareable links, code, props, the agent view and a full accessibility report); editorial pages, a full-bleed hero, and markdown for agents on every page.
+  
+  It ships compiled, with CSS scoped to `[data-designtools]` that reads the project's own tokens, so a project on @designtools/tokens is themed with nothing to set and any other sets a short list of variables, fonts and colours first. A Next adapter, `createDocs`, turns one config into the layout, the pages, their static params and metadata, the markdown and manifest routes and the preview route; `docsProxy` handles markdown negotiation and the production 404. The CLI writes the registry that reaches the project's components (`map`) and copies a block into the project when it needs more than the theme (`eject`, `status`, `show`).
+  
+  Replaces @designtools/blocks, whose blocks were copied into each project.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Made by Many Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,156 @@
-# Temporary Holding Version
+# @designtools/docs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A design system's docs as a package: the brand and the system in one place, for the people who make a product and the agents that build it with them. Every page is generated from [`@designtools/manifest`](../manifest)'s JSON and renders the project's real components.
+
+- **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.
+
+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.
+
+## Setup (Next App Router)
+
+```bash
+pnpm add @designtools/docs @base-ui/react lucide-react
+pnpm add -D @designtools/manifest
+```
+
+`axe-core` (MPL-2.0) is optional: add it for the accessibility report. Without it the report says so.
+
+1. Build the manifest, then write the registry, the one generated file, which reaches the project's components, examples and assets:
+
+   ```bash
+   designtools-manifest build
+   designtools-docs map        # writes app/(design)/design/system/_registry.tsx
+   ```
+
+2. Write the config, `app/(design)/design/system/docs.tsx`:
+
+   ```tsx
+   import components from "@ds/manifest/components.json";
+   import tokens from "@ds/manifest/tokens.json";
+   import rules from "@ds/manifest/rules.json";
+   // patterns, taxonomy, assets the same way
+   import { createDocs } from "@designtools/docs/next";
+   import Registry from "./_registry";
+
+   export const docs = createDocs({
+     title: "Acme design system",
+     registry: Registry,
+     manifest: { components, tokens, rules, patterns, taxonomy, assets },
+     logo: <img src={wordmark.src} alt="Acme" />,
+     editorial: [{ slug: "brand", title: "Principles", body: "## Principles\n\n- **Say the thing.** …", by: { author: "Studio", reviewed: "10 October 2026", status: "draft" } }],
+   });
+   ```
+
+3. Add the routes, each one line:
+
+   | File | Contents |
+   | --- | --- |
+   | `(docs)/layout.tsx` | `export default docs.Layout;` |
+   | `(docs)/[[...slug]]/page.tsx` | `export default docs.Page;` `export const generateStaticParams = docs.generateStaticParams;` `export const generateMetadata = docs.generateMetadata;` |
+   | `md/[[...path]]/route.ts` | `export const GET = docs.markdown;` |
+   | `manifest/[file]/route.ts` | `export const GET = docs.manifest;` `export const generateStaticParams = docs.manifestParams;` |
+   | `preview/[slug]/[example]/page.tsx` | `export default docs.Preview;` |
+
+4. In `proxy.ts`, the markdown negotiation and a 404 for every docs URL on production:
+
+   ```ts
+   import { docsProxy } from "@designtools/docs/next/proxy";
+   export const proxy = docsProxy({ basePath: "/design/system" });
+   export const config = { matcher: ["/design/system", "/design/system.md", "/design/system/:path*"] };
+   ```
+
+   Keep the `(design)` route group's layout calling `notFound()` on production too, for the pages.
+
+5. Give `<html>` `suppressHydrationWarning`: the colour-mode switch sets `data-theme` on it before the first paint.
+
+**Standalone:** the same files in their own Next app (`apps/docs` in a workspace), with the manifest and the system imported from the system's package. `designtools-docs map --manifest <path>` reads another package's manifest and imports from its root.
+
+## Config
+
+| Key | What |
+| --- | --- |
+| `title`, `basePath`, `logo` | The site's name, where it is served (`/design/system`), and the client's mark |
+| `registry` | The generated registry from `designtools-docs map` |
+| `manifest` | The manifest files, as imported JSON |
+| `hero` | A full-bleed introduction across the top of the overview; without it the overview has a plain header and `lead` |
+| `editorial` | Pages people write, each with its author and status, in the brand, foundations or standards group: markdown, or components (below) |
+| `workbench` | Per component: starting `props`, text `children`, richer `content` (a Card's parts), and a `wrap` element for the provider or root it needs |
+| `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 |
+| `hide` | Built-in pages to leave out |
+| `blocks` | Blocks replaced by the project's own (see Eject) |
+
+## Editorial pages with components
+
+A page that has to show rather than tell (the brand on two surfaces, the status colours in their real jobs) takes React as its `body`, with `markdown` for agents:
+
+```tsx
+import { DocsSection, Live, Prose } from "@designtools/docs/next";
+
+editorial: [{
+  slug: "foundations/two-surfaces", section: "foundations", title: "One system, two surfaces", by,
+  body: (
+    <DocsSection title="Side by side">
+      <Prose text="The same tokens and components, set for two jobs." />
+      <Live><MarketingSlice /><AppSlice /></Live>
+    </DocsSection>
+  ),
+  markdown: "## Side by side\n\nThe same tokens and components, set for two jobs.",
+}]
+```
+
+`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.
+
+## 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):
+
+| Variables | Used for |
+| --- | --- |
+| `--canvas`, `--surface`, `--overlay`, `--muted`, each with `-foreground` | Page, panels, popups, quiet fills and their text |
+| `--border`, `--input`, `--ring`, `--shadow` | Lines, control edges, focus, shadow colour |
+| `--primary`, `--primary-foreground`, `--primary-subdued`, `--primary-subdued-foreground`, `--primary-hover` | Action and emphasis |
+| `--success`, `--destructive`, `--warning`, with `-foreground`, `-subdued`, `-subdued-foreground` | Status |
+| `--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-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.
+
+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.
+
+## Eject
+
+When a block has to change more than the theme allows:
+
+```bash
+designtools-docs eject usage
+```
+
+copies its source into the project (`_blocks/usage.tsx` beside the registry), with its imports pointed at the package, and prints the line for the config: `blocks: { Usage: Usage }`. That block is the project's; every other block keeps upgrading. `designtools-docs status` compares ejected blocks with the installed version, and `designtools-docs show <block>` prints the new one.
+
+## CLI
+
+```
+designtools-docs map [--check]        Write the registry from the manifest
+designtools-docs eject <block…>       Copy blocks' source into the project
+designtools-docs status               Compare ejected blocks with this version
+designtools-docs list                 List the blocks
+designtools-docs show <block>         Print this version of a block
+```
+
+The registry's path is `docs.registry` in `designtools.json` (default `app/(design)/design/system/_registry.tsx`), ejected blocks go to `docs.blocks` (default `_blocks` beside it), and the manifest is found from `manifest.system`.
+
+## Composing pages yourself
+
+Every block is exported from `@designtools/docs` (`DocsShell`, `Workbench`, `Usage`, `Examples`, `SemanticSwatches`, …) for a project that wants pages the adapter does not make. Render them inside the generated `Registry` and a `DocsShell`, and import `@designtools/docs/styles.css`.
+
+## Licence
+
+MIT, Made by Many.

package/dist/a11y-panel.d.ts

@@ -0,0 +1,58 @@
+import { type ReactNode, type RefObject } from "react";
+import type { ComponentEntry } from "./lib/manifest-types.js";
+interface Node {
+    target: string;
+    html: string;
+    summary?: string;
+}
+interface Finding {
+    id: string;
+    impact: string | null;
+    help: string;
+    description: string;
+    helpUrl: string;
+    nodes: Node[];
+}
+export interface AxeResult {
+    violations: Finding[];
+    incomplete: Finding[];
+    passes: Finding[];
+    version: string;
+}
+type Status = "idle" | "running" | "done" | "failed";
+/**
+ * Runs axe-core over an element and keeps the result: on demand, or again
+ * whenever `watch` changes, debounced. axe loads on the first run, so a page
+ * that never checks never ships it.
+ */
+export declare function useAxe(target: RefObject<HTMLElement | null>, { auto, watch }?: {
+    auto?: boolean;
+    watch?: unknown;
+}): {
+    status: Status;
+    result: AxeResult | null;
+    run: () => Promise<void>;
+};
+/**
+ * The whole of an axe run, as a report: what failed, on which elements and how
+ * to fix it; what axe could not decide and a person must; what passed; and the
+ * checks no tool makes, from the component's own `@role`, `@keyboard` and `@aria`.
+ */
+export declare function AxeReport({ status, result, run, entry, scope, }: {
+    status: Status;
+    result: AxeResult | null;
+    run: () => void;
+    entry?: ComponentEntry;
+    /** What was checked, in a line: "Button, variant outline, in dark mode". */
+    scope?: string;
+}): import("react").JSX.Element;
+/**
+ * Runs axe-core over what it wraps, on demand, and shows the full report under
+ * it. A clean run is not a pass: axe catches roughly a third of WCAG problems,
+ * so the report lists the checks a person makes too.
+ */
+export declare function A11yPanel({ entry, children }: {
+    entry?: ComponentEntry;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export {};

package/dist/a11y-panel.js

@@ -0,0 +1,75 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { ArrowUpRight, ChevronDown, CircleAlert, CircleCheck, CircleHelp, Hand, LoaderCircle, RotateCcw } from "lucide-react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { cx } from "./lib/cx.js";
+/**
+ * Runs axe-core over an element and keeps the result: on demand, or again
+ * whenever `watch` changes, debounced. axe loads on the first run, so a page
+ * that never checks never ships it.
+ */
+export function useAxe(target, { auto = false, watch } = {}) {
+    const [status, setStatus] = useState("idle");
+    const [result, setResult] = useState(null);
+    const run = useCallback(async () => {
+        if (!target.current)
+            return;
+        setStatus("running");
+        try {
+            const axe = (await import("axe-core")).default;
+            const r = await axe.run(target.current, { resultTypes: ["violations", "incomplete", "passes"] });
+            const map = (list) => list.map((v) => ({
+                id: v.id,
+                impact: v.impact ?? null,
+                help: v.help,
+                description: v.description,
+                helpUrl: v.helpUrl,
+                nodes: v.nodes.map((n) => ({ target: n.target.join(" "), html: n.html, summary: n.failureSummary })),
+            }));
+            setResult({ violations: map(r.violations), incomplete: map(r.incomplete), passes: map(r.passes), version: axe.version });
+            setStatus("done");
+        }
+        catch {
+            setStatus("failed");
+        }
+    }, [target]);
+    useEffect(() => {
+        if (!auto)
+            return;
+        const timer = setTimeout(run, 400);
+        return () => clearTimeout(timer);
+    }, [auto, run, watch]);
+    return { status, result, run };
+}
+const SEVERE = new Set(["critical", "serious"]);
+/**
+ * The whole of an axe run, as a report: what failed, on which elements and how
+ * to fix it; what axe could not decide and a person must; what passed; and the
+ * checks no tool makes, from the component's own `@role`, `@keyboard` and `@aria`.
+ */
+export function AxeReport({ status, result, run, entry, scope, }) {
+    return (_jsxs("div", { "data-slot": "a11y-report", className: "flex flex-col gap-8", children: [_jsxs("div", { className: "flex flex-wrap items-end justify-between gap-6", children: [_jsxs("dl", { className: "flex flex-wrap gap-x-10 gap-y-4", children: [_jsx(Count, { label: "Violations", value: result?.violations.length, tone: result?.violations.length ? "bad" : "good" }), _jsx(Count, { label: "Needs a person", value: result?.incomplete.length }), _jsx(Count, { label: "Passed", value: result?.passes.length })] }), _jsxs("div", { className: "flex items-center gap-3", children: [_jsx("span", { className: "text-xs text-muted-foreground", "aria-live": "polite", children: status === "running" ? "Checking…" : status === "failed" ? "axe could not run. Is axe-core installed?" : result ? `axe-core ${result.version}` : "" }), _jsxs("button", { type: "button", onClick: run, disabled: status === "running", className: "inline-flex min-h-9 cursor-pointer items-center gap-2 rounded-lg border border-border px-3 text-sm font-medium hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring disabled:cursor-wait disabled:opacity-60", children: [status === "running" ? _jsx(LoaderCircle, { "aria-hidden": true, className: "size-4 animate-spin" }) : _jsx(RotateCcw, { "aria-hidden": true, className: "size-4" }), result ? "Check again" : "Run axe"] })] })] }), scope && _jsxs("p", { className: "-mt-4 text-sm text-muted-foreground", children: ["Checked: ", scope, "."] }), result && result.violations.length === 0 && (_jsxs("p", { className: "flex items-center gap-2 text-sm text-success-subdued-foreground", children: [_jsx(CircleCheck, { "aria-hidden": true, className: "size-4" }), "No violations in what axe can measure. That is about a third of WCAG; the rest is below."] })), result && result.violations.length > 0 && (_jsx(Group, { title: "Violations", icon: CircleAlert, children: result.violations.map((f) => (_jsx(FindingRow, { finding: f, open: true }, f.id))) })), result && result.incomplete.length > 0 && (_jsx(Group, { title: "Needs a person", icon: CircleHelp, lead: "axe found these but could not decide them: look at each.", children: result.incomplete.map((f) => (_jsx(FindingRow, { finding: f }, f.id))) })), _jsx(Group, { title: "Check by hand", icon: Hand, lead: "What no tool measures. Try each with a keyboard and a screen reader.", children: _jsxs("ul", { className: "flex flex-col divide-y divide-border border-y border-border text-sm", children: [_jsx(Manual, { children: "Tab reaches it, and the focus ring is visible on every background it sits on." }), entry?.a11y?.keyboard?.length ? (_jsxs(Manual, { children: ["It answers", " ", entry.a11y.keyboard.map((k, i) => (_jsxs("span", { children: [i > 0 && (i === entry.a11y.keyboard.length - 1 ? " and " : ", "), _jsx("kbd", { className: "rounded-sm border border-border px-1.5 font-mono text-xs", children: k })] }, k))), "."] })) : null, _jsxs(Manual, { children: ["A screen reader announces its name", entry?.a11y?.role ? (_jsxs(_Fragment, { children: [" ", "and its role, ", _jsx("code", { className: "font-mono text-xs", children: entry.a11y.role })] })) : (" and its role"), ", and any change of state."] }), _jsx(Manual, { children: "It still works at 200% zoom, and at a phone's width." }), entry?.aria && (_jsxs(Manual, { children: ["It follows its", " ", _jsxs("a", { href: entry.aria, className: "inline-flex items-center gap-0.5 font-medium underline decoration-border underline-offset-4 hover:decoration-current", children: ["ARIA pattern ", _jsx(ArrowUpRight, { "aria-hidden": true, className: "size-3.5" })] }), "."] }))] }) }), result && result.passes.length > 0 && (_jsxs("details", { className: "group", children: [_jsxs("summary", { className: "flex min-h-(--docs-target,2.75rem) w-fit cursor-pointer list-none items-center gap-2 text-sm font-medium [&::-webkit-details-marker]:hidden", children: [_jsx(CircleCheck, { "aria-hidden": true, className: "size-4 text-muted-foreground" }), result.passes.length, " checks passed", _jsx(ChevronDown, { "aria-hidden": true, className: "size-4 text-muted-foreground transition-transform group-open:rotate-180" })] }), _jsx("ul", { className: "mt-2 grid gap-x-8 gap-y-1.5 text-sm text-muted-foreground sm:grid-cols-2", children: result.passes.map((p) => (_jsxs("li", { className: "flex items-baseline justify-between gap-3", children: [_jsx("span", { children: p.help }), _jsxs("span", { className: "font-mono text-xs tabular-nums", children: ["\u00D7", p.nodes.length] })] }, p.id))) })] }))] }));
+}
+function Count({ label, value, tone }) {
+    return (_jsxs("div", { className: "flex flex-col gap-1", children: [_jsx("dt", { className: "text-xs text-muted-foreground", children: label }), _jsx("dd", { className: cx("text-4xl leading-none font-light tracking-tight tabular-nums", tone === "bad" && "text-destructive-subdued-foreground", value === undefined && "text-muted-foreground"), children: value ?? "–" })] }));
+}
+function Group({ title, icon: Icon, lead, children }) {
+    return (_jsxs("section", { className: "flex flex-col gap-3", children: [_jsxs("div", { className: "flex flex-col gap-1", children: [_jsxs("h4", { className: "flex items-center gap-2 text-base font-medium", children: [_jsx(Icon, { "aria-hidden": true, className: "size-4 text-muted-foreground" }), title] }), lead && _jsx("p", { className: "text-sm text-muted-foreground", children: lead })] }), _jsx("div", { className: "flex flex-col gap-2", children: children })] }));
+}
+function Manual({ children }) {
+    return (_jsxs("li", { className: "flex items-start gap-3 py-3", children: [_jsx("span", { "aria-hidden": true, className: "mt-1.5 size-1.5 shrink-0 rounded-full bg-muted-foreground" }), _jsx("span", { children: children })] }));
+}
+function FindingRow({ finding: f, open }) {
+    const severe = SEVERE.has(f.impact ?? "");
+    return (_jsxs("details", { open: open, className: "group rounded-lg border border-border", children: [_jsxs("summary", { className: "flex min-h-(--docs-target,2.75rem) cursor-pointer list-none items-center gap-3 px-4 py-2 text-sm [&::-webkit-details-marker]:hidden", children: [_jsx("span", { className: cx("rounded-full px-2 py-0.5 text-xs font-medium capitalize", severe ? "bg-destructive-subdued text-destructive-subdued-foreground" : "bg-muted text-muted-foreground"), children: f.impact ?? "unrated" }), _jsx("span", { className: "min-w-0 flex-1 font-medium", children: f.help }), _jsxs("span", { className: "font-mono text-xs text-muted-foreground", children: [f.nodes.length, " ", f.nodes.length === 1 ? "element" : "elements"] }), _jsx(ChevronDown, { "aria-hidden": true, className: "size-4 text-muted-foreground transition-transform group-open:rotate-180" })] }), _jsxs("div", { className: "flex flex-col gap-3 border-t border-border px-4 py-3 text-sm", children: [_jsxs("p", { className: "text-muted-foreground", children: [f.description, " ", _jsxs("a", { href: f.helpUrl, className: "inline-flex items-center gap-0.5 font-medium text-canvas-foreground underline decoration-border underline-offset-4 hover:decoration-current", children: ["How to fix ", _jsx(ArrowUpRight, { "aria-hidden": true, className: "size-3.5" })] })] }), _jsx("ul", { className: "flex flex-col gap-2", children: f.nodes.map((n, i) => (_jsxs("li", { className: "flex flex-col gap-1.5 rounded-md bg-muted/60 p-3", children: [_jsx("code", { className: "font-mono text-xs text-muted-foreground", children: n.target }), _jsx("code", { className: "font-mono text-xs break-all", children: n.html }), n.summary && _jsx("p", { className: "text-xs whitespace-pre-line text-muted-foreground", children: n.summary })] }, `${n.target}-${i}`))) })] })] }));
+}
+/**
+ * Runs axe-core over what it wraps, on demand, and shows the full report under
+ * it. A clean run is not a pass: axe catches roughly a third of WCAG problems,
+ * so the report lists the checks a person makes too.
+ */
+export function A11yPanel({ entry, children }) {
+    const box = useRef(null);
+    const axe = useAxe(box);
+    return (_jsxs("div", { "data-slot": "a11y-panel", className: "flex flex-col gap-6", children: [_jsx("div", { ref: box, "data-slot": "a11y-target", children: children }), _jsx(AxeReport, { ...axe, entry: entry })] }));
+}

package/dist/adherence-summary.d.ts

@@ -0,0 +1,9 @@
+import type { AdherenceReport } from "./lib/adherence-types.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
+ * component's variants. It informs; it never blocks.
+ */
+export declare function AdherenceSummary({ report }: {
+    report: AdherenceReport;
+}): import("react").JSX.Element;

package/dist/adherence-summary.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronDown } from "lucide-react";
+import { 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
+ * component's variants. It informs; it never blocks.
+ */
+export function AdherenceSummary({ report }) {
+    const s = report.summary;
+    const stats = [
+        ["Components used", `${s.componentsUsed} of ${s.componentsUsed + s.componentsUnused.length}`],
+        ["Raw elements", String(s.rawElements)],
+        ["Off-system values", String(s.offSystemValues)],
+        ["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
+                            .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."] })] }));
+}
+function Row({ name, counts }) {
+    return (_jsxs("tr", { className: "border-b border-border last:border-b-0", children: [_jsx("th", { scope: "row", className: "px-4 py-3 font-mono text-xs font-normal", children: name }), _jsx("td", { className: cx("px-4 py-3 tabular-nums", counts.share !== null && counts.share < 0.9 && "font-medium"), children: share(counts.share) }), _jsx("td", { className: "px-4 py-3 tabular-nums", children: counts.rawElements }), _jsx("td", { className: "px-4 py-3 tabular-nums", children: counts.offSystemValues }), _jsx("td", { className: "px-4 py-3 tabular-nums", children: counts.overrides })] }));
+}
+function share(value) {
+    return value === null ? "n/a" : `${Math.round(value * 1000) / 10}%`;
+}

package/dist/agent-view.d.ts

@@ -0,0 +1,19 @@
+import type { ReactNode } from "react";
+import type { ComponentEntry } from "./lib/manifest-types.js";
+/**
+ * What an agent needs to know, as copyable markdown: a component's status,
+ * usage, canonical example, do and don't, props, variants and parts, or any
+ * other block's markdown form. Generated from the manifest; nothing in it is
+ * written twice and nothing is written by a model.
+ */
+export declare function AgentInstructions({ entry, markdown }: {
+    entry?: ComponentEntry;
+    markdown?: string;
+}): import("react").JSX.Element;
+/** The same thing two ways, on a switch: as a person sees it, and as an agent reads it. Pass a component entry, or any block's markdown. */
+export declare function AgentView({ entry, markdown, label, children, }: {
+    entry?: ComponentEntry;
+    markdown?: string;
+    label?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/agent-view.js

@@ -0,0 +1,23 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Bot, Eye } from "lucide-react";
+import { CodeView } from "./code-view.js";
+import { componentMarkdown } from "./lib/markdown.js";
+import { Segmented, SegmentedList, SegmentedPanel } from "./lib/ui.js";
+/**
+ * What an agent needs to know, as copyable markdown: a component's status,
+ * usage, canonical example, do and don't, props, variants and parts, or any
+ * other block's markdown form. Generated from the manifest; nothing in it is
+ * written twice and nothing is written by a model.
+ */
+export function AgentInstructions({ entry, markdown }) {
+    const code = markdown ?? (entry ? componentMarkdown(entry) : "");
+    return (_jsx("div", { "data-slot": "agent-instructions", className: "flex flex-col gap-2", children: _jsx(CodeView, { code: code, lang: "markdown", label: "For agents: paste into a prompt", wrap: true }) }));
+}
+/** The same thing two ways, on a switch: as a person sees it, and as an agent reads it. Pass a component entry, or any block's markdown. */
+export function AgentView({ entry, markdown, label, children, }) {
+    return (_jsxs(Segmented, { defaultValue: "rendered", className: "gap-4", children: [_jsx("div", { "data-slot": "agent-view", className: "flex", children: _jsx(SegmentedList, { label: `${label ?? entry?.name ?? "This"}, two ways`, items: [
+                        { value: "rendered", label: "For people", icon: Eye },
+                        { value: "agent", label: "For agents", icon: Bot },
+                    ] }) }), _jsx(SegmentedPanel, { value: "rendered", children: children }), _jsx(SegmentedPanel, { value: "agent", children: _jsx(AgentInstructions, { entry: entry, markdown: markdown }) })] }));
+}

package/dist/anatomy.d.ts

@@ -0,0 +1,12 @@
+import { 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, }: {
+    entry: ComponentEntry;
+    /** The example to point into. Defaults to the canonical example, else the bare component. */
+    children?: ReactNode;
+}): import("react").JSX.Element;

package/dist/anatomy.js

@@ -0,0 +1,39 @@
+"use client";
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Live } from "./lib/live.js";
+import { Layers } from "lucide-react";
+import { useEffect, useId, useRef, useState } from "react";
+import { cx, target } from "./lib/cx.js";
+import { renderExample, useLookup } from "./lib/lookup.js";
+import { Frame, Stage, Toolbar } from "./lib/ui.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 function Anatomy({ entry, children, }) {
+    const lookup = useLookup();
+    const id = useId();
+    const box = useRef(null);
+    const [active, setActive] = useState(null);
+    const [counts, setCounts] = useState({});
+    useEffect(() => {
+        const node = box.current;
+        if (!node)
+            return;
+        const measure = () => setCounts(Object.fromEntries(entry.slots.map((s) => [s, node.querySelectorAll(`[data-slot="${CSS.escape(s)}"]`).length])));
+        measure();
+        const observer = new MutationObserver(measure);
+        observer.observe(node, { subtree: true, childList: true, attributes: true, attributeFilter: ["data-slot"] });
+        return () => observer.disconnect();
+    }, [entry.slots]);
+    if (entry.slots.length === 0) {
+        return _jsxs("p", { className: "text-sm text-muted-foreground", children: [entry.name, " renders no data-slot parts."] });
+    }
+    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 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/ask-claude.d.ts

@@ -0,0 +1,14 @@
+import type { ComponentEntry } from "./lib/manifest-types.js";
+/**
+ * Copies a ready-made prompt for Claude: the component, its source file, the
+ * variant and example in view, and what should change. Paste it into Claude
+ * Code in the project and it starts from the right file.
+ */
+export declare function AskClaude({ entry, variant, example, }: {
+    entry: ComponentEntry;
+    /** The variant in view, e.g. `{ intent: "success" }`. */
+    variant?: Record<string, string>;
+    /** The example in view, by export name. */
+    example?: string;
+}): import("react").JSX.Element;
+export declare function promptFor(entry: ComponentEntry, request: string, variant?: Record<string, string>, example?: string): string;

package/dist/ask-claude.js

@@ -0,0 +1,40 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Check, Copy, Sparkles } from "lucide-react";
+import { useId, useState } from "react";
+import { importOf } from "./lib/manifest.js";
+/**
+ * Copies a ready-made prompt for Claude: the component, its source file, the
+ * variant and example in view, and what should change. Paste it into Claude
+ * Code in the project and it starts from the right file.
+ */
+export function AskClaude({ entry, variant, example, }) {
+    const id = useId();
+    const [request, setRequest] = useState("");
+    const [copied, setCopied] = useState(false);
+    const copy = async () => {
+        try {
+            await navigator.clipboard.writeText(promptFor(entry, request, variant, example));
+            setCopied(true);
+            setTimeout(() => setCopied(false), 1500);
+        }
+        catch {
+            // clipboard refused: nothing changes
+        }
+    };
+    return (_jsxs("div", { "data-slot": "ask-claude", className: "flex flex-col gap-4 rounded-2xl border border-border bg-surface p-5 text-surface-foreground shadow-xs sm:p-6", children: [_jsxs("div", { className: "flex items-start gap-3", children: [_jsx("span", { className: "flex size-9 shrink-0 items-center justify-center rounded-lg bg-primary-subdued text-primary-subdued-foreground", children: _jsx(Sparkles, { "aria-hidden": true, className: "size-(--dt-size-xs)" }) }), _jsxs("span", { className: "flex flex-col gap-0.5", children: [_jsxs("label", { htmlFor: id, className: "text-base font-semibold tracking-tight", children: ["Ask Claude to change ", entry.name] }), _jsxs("span", { className: "text-sm text-muted-foreground", children: ["Copies a prompt naming the file", example ? ", the example" : "", ", its parts and the variant, ready to paste into Claude Code."] })] })] }), _jsxs("div", { className: "flex flex-col overflow-hidden rounded-xl border border-input bg-canvas focus-within:outline-2 focus-within:outline-ring", children: [_jsx("textarea", { id: id, rows: 3, value: request, onChange: (e) => setRequest(e.target.value), placeholder: `What should change about ${entry.name}?`, className: "resize-none bg-transparent px-4 py-3 text-base outline-none placeholder:text-muted-foreground" }), _jsxs("div", { className: "flex items-center justify-between gap-3 px-2 pb-2 pl-4", children: [_jsx("code", { className: "truncate font-mono text-xs text-muted-foreground", children: entry.source }), _jsxs("button", { type: "button", onClick: copy, className: "inline-flex min-h-(--docs-target,2.75rem) shrink-0 cursor-pointer items-center gap-2 rounded-lg bg-primary px-4 text-sm font-medium text-primary-foreground hover:bg-primary-hover focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring", children: [copied ? _jsx(Check, { "aria-hidden": true, className: "size-(--dt-size-xs)" }) : _jsx(Copy, { "aria-hidden": true, className: "size-(--dt-size-xs)" }), copied ? "Copied" : "Copy prompt"] })] })] }), _jsx("span", { className: "sr-only", "aria-live": "polite", children: copied ? "Prompt copied" : "" })] }));
+}
+export function promptFor(entry, request, variant, example) {
+    const lines = [`Component: ${entry.name}, exported as ${entry.export} from ${entry.source} (imported from "${importOf(entry)}")`];
+    const shown = Object.entries(variant ?? {});
+    if (shown.length)
+        lines.push(`Variant in view: ${shown.map(([k, v]) => `${k}="${v}"`).join(", ")}`);
+    if (example && entry.examples)
+        lines.push(`Example in view: ${example}, from ${entry.examples.source}`);
+    if (entry.status && entry.status !== "stable")
+        lines.push(`Status: ${entry.status}${entry.statusNote ? `. ${entry.statusNote}` : ""}`);
+    if (entry.slots.length)
+        lines.push(`Its parts (data-slot): ${entry.slots.join(", ")}`);
+    lines.push("", request.trim() || "What should change: ");
+    return lines.join("\n");
+}