@designtools/blocks 0.1.0 → 0.2.0

package/reference/app/(design)/design/system/_components/prose.tsx

@@ -0,0 +1,26 @@
+/** The few markdown shapes editorial pages use: headings, paragraphs and bullet lists, with bold and code. */
+export function Markdown({ text }: { text: string }) {
+  const blocks = text.split(/\n{2,}/);
+  return (
+    <div className="flex max-w-prose flex-col gap-4">
+      {blocks.map((b, i) => {
+        if (b.startsWith("## ")) return <h2 key={i} className="pt-4 text-xl font-semibold">{b.slice(3)}</h2>;
+        if (b.split("\n").every((l) => l.startsWith("- ")))
+          return (
+            <ul key={i} className="flex list-disc flex-col gap-2 pl-5">
+              {b.split("\n").map((l) => (
+                <li key={l}>{inline(l.slice(2))}</li>
+              ))}
+            </ul>
+          );
+        return <p key={i}>{inline(b)}</p>;
+      })}
+    </div>
+  );
+}
+
+function inline(text: string) {
+  return text.split(/(\*\*[^*]+\*\*|`[^`]+`)/).map((part, i) =>
+    part.startsWith("**") ? <strong key={i}>{part.slice(2, -2)}</strong> : part.startsWith("`") ? <code key={i} className="font-mono text-[0.9em]">{part.slice(1, -1)}</code> : part,
+  );
+}

package/reference/app/(design)/design/system/_data.ts

@@ -0,0 +1,53 @@
+/**
+ * Everything the docs read, in one place, for the HTML pages and the markdown
+ * route alike: the manifest, the project's standards, the provenance of this
+ * build, and the editorial pages people write.
+ */
+
+import assetsJson from "@ds/manifest/assets.json";
+import componentsJson from "@ds/manifest/components.json";
+import patternsJson from "@ds/manifest/patterns.json";
+import rulesJson from "@ds/manifest/rules.json";
+import taxonomyJson from "@ds/manifest/taxonomy.json";
+import tokensJson from "@ds/manifest/tokens.json";
+import stack from "../../../../.mxa/stack.json";
+import adherenceJson from "./_adherence.json";
+import provenanceJson from "./_provenance.json";
+import type { AdherenceReport } from "./_blocks/lib/adherence-types";
+import type { AssetsManifest, PatternsManifest, RulesManifest, TaxonomyManifest } from "./_blocks/lib/manifest-types";
+import { readComponents, readTokens } from "./_blocks/lib/manifest";
+
+export const BASE = "/design/system";
+export const TITLE = "Demo design system";
+
+export const components = readComponents(componentsJson);
+export const tokens = readTokens(tokensJson);
+export const rules = rulesJson as RulesManifest;
+export const patterns = patternsJson as PatternsManifest;
+export const taxonomy = taxonomyJson as TaxonomyManifest;
+export const assets = assetsJson as AssetsManifest;
+export const baselines = stack.baselines as Record<string, unknown>;
+export const provenance = (provenanceJson as { line: string }).line;
+export const adherence = adherenceJson as unknown as AdherenceReport;
+
+export const manifestFiles = { components: componentsJson, tokens: tokensJson, rules: rulesJson, patterns: patternsJson, taxonomy: taxonomyJson, assets: assetsJson };
+
+/** Editorial pages: written by people, so they carry an author and a review date, never a commit. */
+export const editorial = {
+  brand: {
+    title: "Brand",
+    by: { author: "Demo studio", reviewed: "10 October 2026", status: "draft" as const },
+    lead: "Plain, calm and exact. We sound like the person in the room who has read the contract.",
+    body: [
+      "## Principles",
+      "",
+      "- **Say the thing.** A label names what happens; a message says what to do next.",
+      "- **Quiet by default.** One primary action a screen. Colour is for meaning, not decoration.",
+      "- **Nothing invented.** Every value comes from a token, every example from the real component.",
+      "",
+      "## Design language",
+      "",
+      "Generous space, a single teal for action, and greys that lean cool. Corners are soft but small: this is a ledger, not a toy. Motion is short and settles; nothing bounces.",
+    ].join("\n"),
+  },
+};

package/reference/app/(design)/design/system/manifest/[file]/route.ts

@@ -0,0 +1,15 @@
+import { manifestFiles } from "../../_data";
+
+export const dynamic = "force-static";
+
+export function generateStaticParams() {
+  return Object.keys(manifestFiles).map((name) => ({ file: `${name}.json` }));
+}
+
+/** The manifest served beside the docs, so an agent outside the repo gets the exact data, not prose about it. */
+export async function GET(_: Request, { params }: { params: Promise<{ file: string }> }) {
+  const { file } = await params;
+  const data = manifestFiles[file.replace(/\.json$/, "") as keyof typeof manifestFiles];
+  if (!data) return new Response(`# Not found\n\nNo manifest file called ${file}.\n`, { status: 404, headers: { "content-type": "text/markdown; charset=utf-8" } });
+  return Response.json(data);
+}

package/reference/app/(design)/design/system/md/[[...path]]/route.ts

@@ -0,0 +1,94 @@
+import {
+  adherenceMarkdown,
+  assetsMarkdown,
+  coloursMarkdown,
+  componentMarkdown,
+  generatedHeader,
+  editorialHeader,
+  glossaryMarkdown,
+  manifestLinks,
+  patternMarkdown,
+  ruleMarkdown,
+  scaleMarkdown,
+  standardsMarkdown,
+  systemMarkdown,
+  typeMarkdown,
+} from "../../_blocks/lib/markdown";
+import { findBySlug, groupByCategory, slugOf } from "../../_blocks/lib/manifest";
+import { adherence, assets, BASE, baselines, components, editorial, patterns, provenance, rules, taxonomy, TITLE, tokens } from "../../_data";
+
+/**
+ * The markdown form of every docs page, generated from the manifest rather
+ * than converted from HTML. proxy.ts sends `Accept: text/markdown` and `.md`
+ * requests here; a page that does not exist gets a markdown 404.
+ */
+export async function GET(_: Request, { params }: { params: Promise<{ path?: string[] }> }) {
+  const path = ((await params).path ?? []).join("/").replace(/\.md$/, "");
+  const page = render(path);
+  const canonical = `${BASE}${path ? `/${path}` : ""}`;
+  return new Response(page ?? `# Not found\n\nThere is no page at \`${canonical}\`. The index is at [${BASE}.md](${BASE}.md).\n`, {
+    status: page ? 200 : 404,
+    headers: {
+      "content-type": "text/markdown; charset=utf-8",
+      vary: "Accept",
+      link: `<${canonical}>; rel="canonical"`,
+    },
+  });
+}
+
+function render(path: string): string | undefined {
+  const generated = (md: string) => generatedHeader(provenance) + md;
+  const [section, id] = path.split("/");
+  switch (section) {
+    case "":
+      return generated(
+        [
+          `# ${TITLE}`,
+          "",
+          "The brand and the design system in one place. Every page here has a markdown form: add `.md` to its URL.",
+          "",
+          "## Pages",
+          "",
+          `- [Brand](${BASE}/brand.md), [logo](${BASE}/brand/logo.md), [imagery](${BASE}/brand/imagery.md), [voice and terms](${BASE}/brand/voice.md)`,
+          `- [Colour](${BASE}/colour.md), [type](${BASE}/type.md), [scale](${BASE}/scale.md)`,
+          `- [Rules](${BASE}/rules.md)`,
+          ...patterns.patterns.map((p) => `- Pattern: [${p.name}](${BASE}/patterns/${p.id}.md)`),
+          ...groupByCategory(components).flatMap((g) => g.components.map((c) => `- ${g.category}: [${c.name}](${BASE}/components/${slugOf(c)}.md), ${c.status ?? "status not set"}`)),
+          `- [Standards](${BASE}/standards.md), [vocabulary](${BASE}/vocabulary.md)`,
+          `- Everything in [one file](${BASE}/context.md)`,
+          "",
+          manifestLinks(`${BASE}/manifest`),
+        ].join("\n"),
+      );
+    case "context":
+      return systemMarkdown({ components, tokens, rules: rules.rules, patterns: patterns.patterns, terms: taxonomy.terms }, TITLE, provenance);
+    case "brand":
+      if (id === "logo") return generated(assetsMarkdown(assets.assets.filter((a) => a.kind === "logo")) + "\n" + rules.rules.filter((r) => r.kind === "brand").map(ruleMarkdown).join("\n"));
+      if (id === "imagery") return generated(assetsMarkdown(assets.assets.filter((a) => a.kind !== "logo")));
+      if (id === "voice") return generated(glossaryMarkdown(taxonomy.terms.filter((t) => t.kind === "product" || t.wrong?.length)));
+      if (!id) return editorialHeader(editorial.brand.by) + `# ${editorial.brand.title}\n\n${editorial.brand.lead}\n\n${editorial.brand.body}\n`;
+      return undefined;
+    case "colour":
+      return generated(coloursMarkdown(tokens));
+    case "type":
+      return generated(typeMarkdown(tokens));
+    case "scale":
+      return generated(scaleMarkdown(tokens));
+    case "rules":
+      return generated(["# Rules", "", ...rules.rules.map(ruleMarkdown)].join("\n"));
+    case "patterns": {
+      const p = patterns.patterns.find((x) => x.id === id);
+      return p && generated(patternMarkdown(p, 1));
+    }
+    case "components": {
+      const c = id ? findBySlug(components, id) : undefined;
+      return c && generated(componentMarkdown(c, 1));
+    }
+    case "standards":
+      return generated(standardsMarkdown(baselines) + "\n" + adherenceMarkdown(adherence));
+    case "vocabulary":
+      return generated(glossaryMarkdown(taxonomy.terms));
+    default:
+      return undefined;
+  }
+}

package/reference/app/(design)/design/system/preview/[slug]/[example]/page.tsx

@@ -0,0 +1,23 @@
+import { notFound } from "next/navigation";
+import { PreviewExample, PreviewSurface } from "../../../_blocks/preview-frame";
+import { findBySlug } from "../../../_blocks/lib/manifest";
+import { components } from "../../../_data";
+
+/** One example on its own: the target for the preview frame and for visual regression snapshots. */
+export default async function Preview({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ slug: string; example: string }>;
+  searchParams: Promise<{ theme?: string }>;
+}) {
+  const { slug, example } = await params;
+  const { theme } = await searchParams;
+  const entry = findBySlug(components, slug);
+  if (!entry?.examples) notFound();
+  return (
+    <PreviewSurface theme={theme}>
+      <PreviewExample entry={entry} example={decodeURIComponent(example)} />
+    </PreviewSurface>
+  );
+}

package/reference/app/(design)/layout.tsx

@@ -0,0 +1,16 @@
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import type { ReactNode } from "react";
+
+/**
+ * Every design page, under /design: never public. A 404 on a production deployment
+ * (VERCEL_ENV, or the host's equivalent), never indexed, kept on previews so a
+ * colleague can open a link. proxy.ts does the same for every docs URL, including
+ * the markdown and manifest route handlers, which no layout wraps.
+ */
+export const metadata: Metadata = { robots: { index: false, follow: false } };
+
+export default function DesignLayout({ children }: { children: ReactNode }) {
+  if (process.env.VERCEL_ENV === "production") notFound();
+  return children;
+}

package/reference/app/globals.css

@@ -0,0 +1,14 @@
+@import "tailwindcss";
+@import "./styles/tokens.css";
+@import "./styles/scale.css";
+
+/* The demo gitignores its generated blocks, and Tailwind skips ignored files unless told. */
+@source "./(design)/design/system/_blocks";
+
+@layer base {
+  html {
+    background: var(--canvas);
+    color: var(--canvas-foreground);
+    font-family: var(--font-sans);
+  }
+}

package/reference/app/layout.tsx

@@ -0,0 +1,16 @@
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "designtools demo",
+  robots: { index: false },
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

package/reference/designtools.json

@@ -0,0 +1,14 @@
+{
+  "manifest": {
+    "system": "src/ds",
+    "tokens": [
+      "app/styles/tokens.css",
+      "app/styles/scale.css"
+    ],
+    "docs": "/design/system",
+    "usage": "app/styles/tokens.usage.json"
+  },
+  "blocks": {
+    "dir": "app/(design)/design/system/_blocks"
+  }
+}

package/reference/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@designtools/example-demo",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "setup": "pnpm tokens && pnpm manifest && pnpm blocks && pnpm adherence",
+    "tokens": "generate-tokens --primary \"#4e9caf\" --neutral \"#8a8f98\" --background \"sand=#efe9dc/#2b2721\" --format tailwind-v4 --out app/styles/tokens.css --usage app/styles/tokens.usage.json",
+    "manifest": "designtools-manifest build && designtools-manifest provenance --json > 'app/(design)/design/system/_provenance.json'",
+    "blocks": "rm -rf 'app/(design)/design/system/_blocks' && designtools-blocks add --all && designtools-blocks map",
+    "dev": "next dev --port 4310",
+    "build": "next build",
+    "typecheck": "tsc --noEmit",
+    "adherence": "designtools-adherence --json 'app/(design)/design/system/_adherence.json' > /dev/null"
+  },
+  "dependencies": {
+    "@base-ui/react": "1.6.0",
+    "axe-core": "4.14.0",
+    "fuzzysort": "4.0.2",
+    "next": "16.3.8",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "shiki": "4.5.0",
+    "tailwind-merge": "3.6.0",
+    "tailwind-variants": "3.3.1"
+  },
+  "devDependencies": {
+    "@designtools/adherence": "workspace:*",
+    "@designtools/blocks": "workspace:*",
+    "@designtools/manifest": "workspace:*",
+    "@designtools/tokens": "workspace:*",
+    "@tailwindcss/postcss": "4.3.3",
+    "@types/node": "^24",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "tailwindcss": "4.3.3",
+    "typescript": "~6.0.3"
+  }
+}

package/reference/proxy.ts

@@ -0,0 +1,55 @@
+import { NextResponse, type NextRequest } from "next/server";
+
+const BASE = "/design/system";
+
+/**
+ * One URL, two formats. A docs URL answers `Accept: text/markdown`, or the same
+ * path with `.md`, with markdown generated from the manifest. Negotiation is on
+ * Accept only, never the user agent, so every response says `Vary: Accept`,
+ * and the HTML links to its markdown.
+ *
+ * Never public: on a production deployment every docs URL, in every format, is a
+ * 404. The (design) layout does the same for the pages, the preview route among
+ * them; this also covers the markdown and manifest route handlers, which no
+ * layout wraps.
+ */
+export function proxy(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+  if (process.env.VERCEL_ENV === "production") {
+    return new NextResponse("Not found\n", { status: 404, headers: { "x-robots-tag": "noindex" } });
+  }
+  if (pathname.startsWith(`${BASE}/md`) || pathname.startsWith(`${BASE}/manifest/`) || pathname.startsWith(`${BASE}/preview/`)) {
+    return NextResponse.next();
+  }
+  const wantsMarkdown = pathname.endsWith(".md") || prefersMarkdown(request.headers.get("accept"));
+  const page = pathname.replace(/\.md$/, "").replace(/\/$/, "");
+  if (wantsMarkdown) {
+    const url = request.nextUrl.clone();
+    url.pathname = `${BASE}/md${page.slice(BASE.length)}`;
+    return NextResponse.rewrite(url, { headers: { vary: "Accept", "x-robots-tag": "noindex" } });
+  }
+  // Next 16 replaces Vary on page responses with its own, so this one does not survive on HTML;
+  // the markdown responses keep theirs. See the demo README.
+  const res = NextResponse.next();
+  res.headers.set("vary", "Accept");
+  res.headers.set("link", `<${page}.md>; rel="alternate"; type="text/markdown"`);
+  res.headers.set("x-robots-tag", "noindex");
+  return res;
+}
+
+/** text/markdown ranked above text/html in the Accept header. */
+function prefersMarkdown(accept: string | null): boolean {
+  if (!accept) return false;
+  const q = (type: string) => {
+    for (const part of accept.split(",")) {
+      const [name, ...params] = part.trim().split(";");
+      if (name.trim() !== type) continue;
+      const weight = params.map((p) => p.trim()).find((p) => p.startsWith("q="));
+      return weight ? Number(weight.slice(2)) : 1;
+    }
+    return 0;
+  };
+  return q("text/markdown") > 0 && q("text/markdown") >= q("text/html");
+}
+
+export const config = { matcher: ["/design/system", "/design/system.md", "/design/system/:path*"] };

package/registry/a11y-panel.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { useRef, useState, type ReactNode } from "react";
-import { cx } from "./lib/cx";
+import { cx, target } from "./lib/cx";
 import type { ComponentEntry } from "./lib/manifest-types";
 
 interface Finding {
@@ -51,12 +51,12 @@ export function A11yPanel({ entry, children }: { entry?: ComponentEntry; childre
             type="button"
             onClick={run}
             disabled={status === "running"}
-            className="rounded-md border border-border px-3 py-1.5 font-medium hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring disabled:opacity-50"
+            className={cx(target, "rounded-md border border-border px-3 py-1.5 font-medium hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring disabled:opacity-50")}
           >
             {status === "running" ? "Checking…" : status === "done" ? "Check again" : "Check with axe"}
           </button>
           {entry?.aria && (
-            <a href={entry.aria} className="text-xs underline underline-offset-2">
+            <a href={entry.aria} className={cx(target, "inline-flex items-center text-xs underline underline-offset-2")}>
               ARIA pattern it follows
             </a>
           )}

package/registry/adherence-summary.tsx

@@ -1,5 +1,5 @@
 import type { AdherenceReport, Counts } from "./lib/adherence-types";
-import { cx } from "./lib/cx";
+import { cx, target } from "./lib/cx";
 
 /**
  * The latest adherence report: how much of what the system could render comes
@@ -32,7 +32,7 @@ export function AdherenceSummary({ report }: { report: AdherenceReport }) {
         </p>
       )}
       {report.routes.length > 0 && (
-        <div className="overflow-x-auto">
+        <div className="overflow-x-auto" tabIndex={0} role="region" aria-label="Adherence by route">
           <table className="w-full min-w-[32rem] border-collapse text-left text-sm">
             <caption className="sr-only">Adherence by route</caption>
             <thead>
@@ -54,7 +54,7 @@ export function AdherenceSummary({ report }: { report: AdherenceReport }) {
       )}
       {report.files.some((f) => f.raw.length || f.offSystem.length || f.overrides.length) && (
         <details data-slot="adherence-findings" className="rounded-md border border-border">
-          <summary className="cursor-pointer px-3 py-2 text-sm">Findings by file</summary>
+          <summary className={cx(target, "flex cursor-pointer items-center px-3 py-2 text-sm")}>Findings by file</summary>
           <ul className="flex flex-col divide-y divide-border border-t border-border text-sm">
             {report.files
               .filter((f) => f.raw.length || f.offSystem.length || f.overrides.length)
@@ -69,7 +69,7 @@ export function AdherenceSummary({ report }: { report: AdherenceReport }) {
                     ))}
                     {f.offSystem.map((o) => (
                       <li key={`o${o.line}:${o.column}:${o.class}`}>
-                        line {o.line}: <code className="font-mono text-xs">{o.class}</code> is {o.kind === "palette" ? "a palette step, not a semantic token" : "an arbitrary value"}
+                        line {o.line}: <code className="font-mono text-xs">{o.class}</code> 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"}
                       </li>
                     ))}
                     {f.overrides.map((o) => (

package/registry/agent-view.tsx

@@ -5,6 +5,7 @@ import type { ReactNode } from "react";
 import { CodeView } from "./code-view";
 import { componentMarkdown } from "./lib/markdown";
 import type { ComponentEntry } from "./lib/manifest-types";
+import { target } from "./lib/cx";
 
 /**
  * What an agent needs to know, as copyable markdown: a component's status,
@@ -22,7 +23,7 @@ export function AgentInstructions({ entry, markdown }: { entry?: ComponentEntry;
 }
 
 const tab =
-  "-mb-px border-b-2 border-transparent px-1 pb-2 text-sm text-muted-foreground hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring data-[active]:border-primary data-[active]:font-medium data-[active]:text-canvas-foreground";
+  target + " -mb-px border-b-2 border-transparent px-1 pb-2 text-sm text-muted-foreground hover:text-canvas-foreground focus-visible:outline-2 focus-visible:outline-ring data-[active]:border-primary data-[active]:font-medium data-[active]:text-canvas-foreground";
 
 /** The same thing two ways: as a person sees it, and as an agent reads it. Pass a component entry, or any block's markdown. */
 export function AgentView({

package/registry/anatomy.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { useEffect, useId, useRef, useState, type ReactNode } from "react";
-import { cx } from "./lib/cx";
+import { cx, target } from "./lib/cx";
 import { componentFor, examplesFor, renderExample } from "./lib/lookup";
 import type { ComponentEntry } from "./lib/manifest-types";
 
@@ -68,7 +68,8 @@ export function Anatomy({
               onBlur={() => setActive(null)}
               onClick={() => setActive(slot)}
               className={cx(
-                "flex w-full items-baseline justify-between gap-3 rounded-md px-2 py-1.5 text-left hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring",
+                target,
+                "flex w-full items-center justify-between gap-3 rounded-md px-2 py-1.5 text-left hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring",
                 active === slot && "bg-muted",
               )}
             >

package/registry/ask-claude.tsx

@@ -1,7 +1,9 @@
 "use client";
 
 import { useId, useState } from "react";
+import { importOf } from "./lib/manifest";
 import type { ComponentEntry } from "./lib/manifest-types";
+import { target } from "./lib/cx";
 
 /**
  * Copies a ready-made prompt for Claude: the component, its source file, the
@@ -47,7 +49,7 @@ export function AskClaude({
         <button
           type="button"
           onClick={copy}
-          className="rounded-md bg-primary px-3 py-1.5 text-sm font-medium text-primary-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring"
+          className={`${target} rounded-md bg-primary px-3 py-1.5 text-sm font-medium text-primary-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring`}
         >
           {copied ? "Copied" : "Copy prompt"}
         </button>
@@ -60,7 +62,7 @@ export function AskClaude({
 }
 
 export function promptFor(entry: ComponentEntry, request: string, variant?: Record<string, string>, example?: string): string {
-  const lines = [`Component: ${entry.name}, exported as ${entry.export} from ${entry.source}`];
+  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}`);

package/registry/code-view.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { useEffect, useState } from "react";
-import { cx } from "./lib/cx";
+import { cx, target } from "./lib/cx";
 
 /* Shiki writes both themes as CSS variables; these pick the one for the page's mode. */
 const THEME_CSS = `
@@ -52,7 +52,7 @@ export function CodeView({
       <style>{THEME_CSS}</style>
       <figcaption className="flex items-center justify-between border-b border-border px-4 py-2 text-xs text-muted-foreground">
         <span>{label}</span>
-        <button type="button" onClick={copy} className="rounded-sm px-2 py-1 hover:bg-canvas focus-visible:outline-2 focus-visible:outline-ring">
+        <button type="button" onClick={copy} className={cx(target, "rounded-sm px-2 py-1 hover:bg-canvas focus-visible:outline-2 focus-visible:outline-ring")}>
           {copied ? "Copied" : "Copy"}
         </button>
       </figcaption>
@@ -62,10 +62,13 @@ export function CodeView({
       {html ? (
         <div
           className={cx("overflow-x-auto p-4 font-mono text-xs leading-relaxed", wrap && "[&_pre]:break-words [&_pre]:whitespace-pre-wrap")}
+          tabIndex={0}
+          role="region"
+          aria-label={label}
           dangerouslySetInnerHTML={{ __html: html }}
         />
       ) : (
-        <pre className={cx("overflow-x-auto p-4 font-mono text-xs leading-relaxed", wrap && "break-words whitespace-pre-wrap")}>
+        <pre tabIndex={0} aria-label={label} className={cx("overflow-x-auto p-4 font-mono text-xs leading-relaxed", wrap && "break-words whitespace-pre-wrap")}>
           <code>{code}</code>
         </pre>
       )}

package/registry/examples.tsx

@@ -2,7 +2,7 @@
 
 import { CodeView } from "./code-view";
 import { Boundary } from "./lib/boundary";
-import { cx } from "./lib/cx";
+import { cx, target } from "./lib/cx";
 import { examplesFor, Missing, renderExample } from "./lib/lookup";
 import type { ComponentEntry, ExampleRef } from "./lib/manifest-types";
 import { inline } from "./lib/text";
@@ -63,10 +63,11 @@ function Example({ example, kind, value, href }: { example: ExampleRef; kind: ke
           <span className="flex items-baseline gap-2">
             {LABEL[kind] && (
               <span
+                // a measured pairing, not a fill colour used as text (text-success read 3.9:1 on the canvas)
                 className={cx(
-                  "font-medium",
-                  kind === "do" && "text-success",
-                  kind === "dont" && "text-destructive",
+                  "rounded-sm px-1.5 font-medium",
+                  kind === "do" && "bg-success-subdued text-success-subdued-foreground",
+                  kind === "dont" && "bg-destructive-subdued text-destructive-subdued-foreground",
                 )}
               >
                 {kind === "do" ? "✓ " : kind === "dont" ? "✕ " : ""}
@@ -76,7 +77,7 @@ function Example({ example, kind, value, href }: { example: ExampleRef; kind: ke
             <code className="font-mono text-xs text-muted-foreground">{example.name}</code>
           </span>
           {href && (
-            <a href={href} className="text-xs underline underline-offset-2">
+            <a href={href} className={cx(target, "inline-flex items-center text-xs underline underline-offset-2")}>
               Open alone
             </a>
           )}
@@ -84,7 +85,7 @@ function Example({ example, kind, value, href }: { example: ExampleRef; kind: ke
         {example.description && <span className="text-muted-foreground">{inline(example.description)}</span>}
         {example.code && (
           <details>
-            <summary className="cursor-pointer text-xs text-muted-foreground">Code</summary>
+            <summary className={cx(target, "flex w-fit cursor-pointer items-center text-xs text-muted-foreground")}>Code</summary>
             <div className="mt-2">
               <CodeView code={example.code} label={example.name} />
             </div>

package/registry/glossary.tsx

@@ -3,6 +3,7 @@
 import { useId, useState } from "react";
 import type { TermEntry } from "./lib/manifest-types";
 import { inline } from "./lib/text";
+import { target } from "./lib/cx";
 
 /** Every name in the system, searchable by its wrong forms too, so a wrong name finds the right one. */
 export function Glossary({ terms }: { terms: TermEntry[] }) {
@@ -24,7 +25,7 @@ export function Glossary({ terms }: { terms: TermEntry[] }) {
           value={query}
           onChange={(e) => setQuery(e.target.value)}
           placeholder="Try a name you half remember"
-          className="h-(--size-xl) max-w-sm rounded-md border border-input bg-canvas px-3 text-sm focus-visible:outline-2 focus-visible:outline-ring"
+          className={`${target} h-(--size-xl) max-w-sm rounded-md border border-input bg-canvas px-3 text-sm focus-visible:outline-2 focus-visible:outline-ring`}
         />
       </div>
       <p aria-live="polite" className="text-sm text-muted-foreground">

package/registry/lib/adherence-types.ts

@@ -127,8 +127,10 @@ export interface RawElement {
 /**
  * `palette`: a primitive ramp step used directly, `bg-blue-500` or `text-primary-500`.
  * `arbitrary`: a value in brackets, `p-[13px]` or `bg-[#fff]`.
+ * `status-text`: a status fill used as text, `text-destructive`: use `text-destructive-subdued-foreground`,
+ * which reads on every background, or neutral text with an icon for a warning.
  */
-export type OffSystemKind = "palette" | "arbitrary";
+export type OffSystemKind = "palette" | "arbitrary" | "status-text";
 
 export interface OffSystemValue {
   /** The class as written, variants included: `hover:bg-blue-500`. */

package/registry/lib/cx.ts

@@ -1,3 +1,11 @@
+/**
+ * The smallest a pressable thing in the docs may be: 44px by default (WCAG 2.5.5).
+ * A client with its own rule sets `--docs-target` on the docs layout (`3rem` for
+ * 48px), so the site that states the rule also meets it. Links inside a sentence
+ * are exempt, as WCAG exempts them.
+ */
+export const target = "min-h-[var(--docs-target,2.75rem)] min-w-[var(--docs-target,2.75rem)]";
+
 /** Join class names, skipping the falsy ones. */
 export function cx(...classes: (string | false | null | undefined)[]): string {
   return classes.filter(Boolean).join(" ");