@designtools/blocks 0.1.0 → 0.2.0

package/registry/props-table.tsx

@@ -1,4 +1,4 @@
-import { cx } from "./lib/cx";
+import { cx, target } from "./lib/cx";
 import { inline } from "./lib/text";
 import type { ComponentEntry, PropEntry } from "./lib/manifest-types";
 
@@ -20,7 +20,7 @@ export function PropsTable({ entry }: { entry: ComponentEntry }) {
       {own.length > 0 ? <Table rows={own} /> : <p className="text-sm text-muted-foreground">No props of its own.</p>}
       {[...byPackage.entries()].map(([pkg, inherited]) => (
         <details key={pkg} data-slot="props-inherited" className="rounded-md border border-border">
-          <summary className="cursor-pointer px-3 py-2 text-sm">
+          <summary className={cx(target, "flex cursor-pointer items-center px-3 py-2 text-sm")}>
             {inherited.length} props from <span className="font-mono">{pkg}</span>
           </summary>
           <div className="border-t border-border p-3">
@@ -46,7 +46,7 @@ export function PropsTable({ entry }: { entry: ComponentEntry }) {
 
 function Table({ rows }: { rows: [string, PropEntry][] }) {
   return (
-    <div className="overflow-x-auto">
+    <div className="overflow-x-auto" tabIndex={0} role="region" aria-label="Props">
       <table className="w-full min-w-[36rem] border-collapse text-left text-sm">
         <thead>
           <tr className="border-b border-border text-xs text-muted-foreground">
@@ -71,7 +71,7 @@ function Table({ rows }: { rows: [string, PropEntry][] }) {
                 <span className="flex flex-col items-start gap-1">
                   <code className={cx("font-mono text-xs font-medium", prop.deprecated !== undefined && "line-through")}>{name}</code>
                   {prop.required && (
-                    <span data-slot="props-required" className="rounded-sm bg-muted px-1 text-[0.625rem] text-muted-foreground">
+                    <span data-slot="props-required" className="rounded-sm bg-muted px-1 text-xs text-muted-foreground">
                       required
                     </span>
                   )}

package/registry/rule.tsx

@@ -7,9 +7,10 @@ import { ruleMarkdown } from "./lib/markdown";
 import type { RuleEntry } from "./lib/manifest-types";
 import { StatusBadge } from "./lib/status";
 import { inline, Prose } from "./lib/text";
+import { target } from "./lib/cx";
 
 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";
 
 /**
  * One rule, brand or interface, written for people: the statement, the line it
@@ -50,7 +51,7 @@ export function Rule({ rule, children }: { rule: RuleEntry; children?: ReactNode
     <article id={rule.id} data-slot="rule" className="flex scroll-mt-8 flex-col gap-4 rounded-lg border border-border p-5">
       <header className="flex flex-wrap items-center justify-between gap-3">
         <h3 className="text-lg font-semibold">
-          <a href={`#${rule.id}`} className="hover:underline">
+          <a href={`#${rule.id}`} className={`${target} inline-flex items-center hover:underline`}>
             {rule.title}
           </a>
         </h3>

package/registry/search.tsx

@@ -0,0 +1,134 @@
+"use client";
+
+import { Autocomplete } from "@base-ui/react/autocomplete";
+import { Dialog } from "@base-ui/react/dialog";
+import { useRouter } from "next/navigation";
+import { useEffect, useId, useMemo, useState } from "react";
+import { cx, target } from "./lib/cx";
+import { search, type SearchGroup, type SearchItem } from "./lib/search";
+
+const PLURAL: Record<SearchGroup["kind"], string> = { Component: "Components", Rule: "Rules", Pattern: "Patterns", Page: "Pages" };
+
+/**
+ * Find a component, a part, a rule, a pattern or a page by name, fuzzily, and go
+ * there. A wrong name finds the right thing ("Dropdown" finds Select, and says
+ * so). Opens with ⌘K or Ctrl+K anywhere, or / when you are not typing. Build the
+ * items with `searchIndex` from `lib/search`; the shell does, when you pass it the
+ * taxonomy. Navigation only: it does not search page text.
+ */
+export function DocsSearch({
+  items,
+  shortcuts = true,
+  className,
+}: {
+  items: SearchItem[];
+  /** Listen for ⌘K, Ctrl+K and /. Give one search on a page the shortcuts. */
+  shortcuts?: boolean;
+  className?: string;
+}) {
+  const router = useRouter();
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState("");
+  const [shortcut, setShortcut] = useState("Ctrl K");
+  const hintId = useId();
+  const groups = useMemo(() => search(items, query), [items, query]);
+
+  useEffect(() => {
+    if (/Mac|iPhone|iPad/.test(navigator.platform)) setShortcut("⌘K");
+    if (!shortcuts) return;
+    const onKey = (e: KeyboardEvent) => {
+      const typing = e.target instanceof HTMLElement && (e.target.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(e.target.tagName));
+      if ((e.key === "k" && (e.metaKey || e.ctrlKey)) || (e.key === "/" && !typing && !e.metaKey && !e.ctrlKey && !e.altKey)) {
+        e.preventDefault();
+        setOpen(true);
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [shortcuts]);
+
+  const go = (item: SearchItem) => {
+    setOpen(false);
+    setQuery("");
+    router.push(item.href);
+  };
+
+  return (
+    <Dialog.Root open={open} onOpenChange={(next) => (setOpen(next), next || setQuery(""))}>
+      <Dialog.Trigger
+        data-slot="docs-search-trigger"
+        className={cx(
+          target,
+          "flex w-full items-center justify-between gap-3 rounded-md border border-input bg-canvas px-3 text-sm text-muted-foreground hover:bg-muted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring",
+          className,
+        )}
+      >
+        <span>Search</span>
+        <kbd className="font-mono text-xs pointer-coarse:hidden">{shortcut}</kbd>
+      </Dialog.Trigger>
+      <Dialog.Portal>
+        <Dialog.Backdrop className="fixed inset-0 bg-canvas-foreground/30" />
+        <Dialog.Viewport className="fixed inset-0 flex items-start justify-center px-4 pt-[12dvh]">
+          <Dialog.Popup
+            data-slot="docs-search"
+            aria-label="Search the design system"
+            className="flex max-h-[min(36rem,80dvh)] w-full max-w-lg flex-col overflow-hidden rounded-lg border border-border bg-overlay text-overlay-foreground shadow-lg"
+          >
+            <Autocomplete.Root
+              open
+              inline
+              items={groups}
+              filter={null}
+              value={query}
+              onValueChange={(next) => setQuery(next)}
+              itemToStringValue={(item: SearchItem) => item.label}
+              autoHighlight="always"
+              keepHighlight
+            >
+              <Autocomplete.Input
+                aria-label="Search components, rules, patterns and pages"
+                aria-describedby={hintId}
+                placeholder="Search components, rules, patterns…"
+                className={cx(target, "w-full border-b border-border bg-transparent px-4 text-base outline-none placeholder:text-muted-foreground")}
+              />
+              <Dialog.Close className="sr-only">Close search</Dialog.Close>
+              <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain py-2">
+                <Autocomplete.Empty>
+                  <p className="px-4 py-6 text-sm text-muted-foreground">{query.trim() ? `Nothing called “${query.trim()}”.` : "Type a name, or a name you half remember."}</p>
+                </Autocomplete.Empty>
+                <Autocomplete.List>
+                  {(group: SearchGroup) => (
+                    <Autocomplete.Group key={group.kind} items={group.items} className="not-last:mb-2">
+                      <Autocomplete.GroupLabel className="px-4 py-1 text-xs font-medium text-muted-foreground">{PLURAL[group.kind]}</Autocomplete.GroupLabel>
+                      <Autocomplete.Collection>
+                        {(item: SearchGroup["items"][number]) => (
+                          <Autocomplete.Item
+                            key={item.href}
+                            value={item}
+                            onClick={() => go(item)}
+                            className={cx(
+                              target,
+                              "flex cursor-default items-center justify-between gap-3 px-4 py-2 text-sm outline-none select-none data-highlighted:bg-muted",
+                            )}
+                          >
+                            <span className="min-w-0 truncate font-medium">{item.label}</span>
+                            <span className="shrink-0 text-xs text-muted-foreground">
+                              {item.matched ? `for “${item.matched}”` : item.detail}
+                            </span>
+                          </Autocomplete.Item>
+                        )}
+                      </Autocomplete.Collection>
+                    </Autocomplete.Group>
+                  )}
+                </Autocomplete.List>
+              </div>
+              <p id={hintId} className="border-t border-border px-4 py-2 text-xs text-muted-foreground">
+                Arrow keys to move, Enter to go, Escape to close.
+              </p>
+            </Autocomplete.Root>
+          </Dialog.Popup>
+        </Dialog.Viewport>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+}

package/registry/shell.tsx

@@ -2,15 +2,19 @@
 
 import Link from "next/link";
 import { usePathname } from "next/navigation";
-import type { ReactNode } from "react";
-import { cx } from "./lib/cx";
-import { groupByCategory, slugOf } from "./lib/manifest";
+import { type ReactNode, useMemo } from "react";
+import { cx, target } from "./lib/cx";
+import { groupFamilies, slugOf } from "./lib/manifest";
 import { Prose } from "./lib/text";
-import type { ComponentsManifest, PatternsManifest, RulesManifest } from "./lib/manifest-types";
+import type { ComponentsManifest, PatternsManifest, RulesManifest, TaxonomyManifest } from "./lib/manifest-types";
+import { searchIndex } from "./lib/search";
+import { DocsSearch } from "./search";
 
 export interface DocsLink {
   label: string;
   href: string;
+  /** Shown beneath it while you are on it or one of them: a component's parts. */
+  children?: DocsLink[];
 }
 
 /**
@@ -24,7 +28,10 @@ export function DocsShell({
   manifest,
   rules,
   patterns,
+  terms,
+  search = true,
   title = "Design system",
+  logo,
   basePath = "/design/system",
   brand = [],
   foundations = [],
@@ -36,7 +43,13 @@ export function DocsShell({
   rules?: RulesManifest;
   /** Listed under Patterns, each at `${basePath}/patterns/${id}`. */
   patterns?: PatternsManifest;
+  /** The taxonomy, so search finds a component by a wrong name ("Dropdown" finds Select). */
+  terms?: TaxonomyManifest;
+  /** Search over components, parts, rules, patterns and pages, on ⌘K, Ctrl+K or /. On by default. */
+  search?: boolean;
   title?: string;
+  /** The client's logo, shown beside the title: the site is theirs. */
+  logo?: ReactNode;
   /** Component pages live at `${basePath}/components/${slug}`. */
   basePath?: string;
   /** Brand pages: principles, design language, voice, logo, imagery. */
@@ -48,6 +61,18 @@ export function DocsShell({
   children: ReactNode;
 }) {
   const current = usePathname();
+  const searchItems = useMemo(
+    () =>
+      searchIndex({
+        manifest,
+        rules: rules?.rules,
+        patterns: patterns?.patterns,
+        terms: terms?.terms,
+        pages: [...brand, ...foundations, ...(rules?.rules.length ? [{ label: "Rules", href: `${basePath}/rules` }] : []), ...standards],
+        basePath,
+      }),
+    [manifest, rules, patterns, terms, brand, foundations, standards, basePath],
+  );
   const groups = [
     ...(brand.length ? [{ heading: "Brand", links: brand }] : []),
     ...(foundations.length ? [{ heading: "Foundations", links: foundations }] : []),
@@ -57,9 +82,13 @@ export function DocsShell({
     ...(patterns?.patterns.length
       ? [{ heading: "Patterns", links: patterns.patterns.map((p) => ({ label: p.name, href: `${basePath}/patterns/${p.id}` })) }]
       : []),
-    ...groupByCategory(manifest).map((g) => ({
+    ...groupFamilies(manifest).map((g) => ({
       heading: g.category,
-      links: g.components.map((c) => ({ label: c.name, href: `${basePath}/components/${slugOf(c)}` })),
+      links: g.families.map(({ head, parts }) => ({
+        label: head.name,
+        href: `${basePath}/components/${slugOf(head)}`,
+        children: parts.map((p) => ({ label: p.name, href: `${basePath}/components/${slugOf(p)}` })),
+      })),
     })),
     ...(standards.length ? [{ heading: "Standards", links: standards }] : []),
   ];
@@ -73,20 +102,19 @@ export function DocsShell({
           </p>
           <ul className="flex flex-col">
             {group.links.map((link) => {
-              const active = current === link.href;
+              const open = current === link.href || link.children?.some((c) => c.href === current);
               return (
                 <li key={link.href}>
-                  <Link
-                    href={link.href}
-                    aria-current={active ? "page" : undefined}
-                    data-slot="docs-nav-link"
-                    className={cx(
-                      "block rounded-md px-2 py-1.5 hover:bg-muted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring",
-                      active && "bg-muted font-medium",
-                    )}
-                  >
-                    {link.label}
-                  </Link>
+                  <NavLink link={link} current={current} />
+                  {open && link.children?.length ? (
+                    <ul data-slot="docs-nav-parts" aria-label={`${link.label} parts`} className="ml-3 flex flex-col border-l border-border pl-2">
+                      {link.children.map((child) => (
+                        <li key={child.href}>
+                          <NavLink link={child} current={current} />
+                        </li>
+                      ))}
+                    </ul>
+                  ) : null}
                 </li>
               );
             })}
@@ -102,15 +130,31 @@ export function DocsShell({
         data-slot="docs-sidebar"
         className="hidden border-r border-border bg-surface text-surface-foreground md:sticky md:top-0 md:block md:h-dvh md:overflow-y-auto"
       >
-        <Link href={basePath} data-slot="docs-title" className="block px-6 pt-6 pb-2 font-semibold">
-          {title}
+        <Link href={basePath} data-slot="docs-title" className={cx(target, "flex flex-col items-start gap-2 px-6 pt-6 pb-2 font-semibold")}>
+          {logo && <span data-slot="docs-logo">{logo}</span>}
+          <span>{title}</span>
         </Link>
+        {search && (
+          <div className="px-4 pt-2">
+            <DocsSearch items={searchItems} />
+          </div>
+        )}
         {nav}
       </aside>
       <details data-slot="docs-nav-disclosure" className="border-b border-border bg-surface text-surface-foreground md:hidden">
-        <summary className="cursor-pointer px-4 py-3 font-semibold">{title}</summary>
+        <summary className={cx(target, "flex cursor-pointer items-center gap-3 px-4 py-3 font-semibold")}>
+          {logo && <span data-slot="docs-logo">{logo}</span>}
+          <span>{title}</span>
+        </summary>
         {nav}
       </details>
+      {search && (
+        // outside the disclosure, so a phone can search without opening the navigation; the
+        // sidebar's search owns the keyboard shortcut, so one key press opens one dialog
+        <div className="border-b border-border bg-surface px-4 py-2 md:hidden">
+          <DocsSearch items={searchItems} shortcuts={false} />
+        </div>
+      )}
       <main data-slot="docs-main" className="min-w-0 px-4 py-8 md:px-10 md:py-12">
         <div className="mx-auto flex max-w-5xl flex-col gap-12">{children}</div>
       </main>
@@ -139,7 +183,8 @@ export function DocsHeader({
   /** For a generated page: `Generated from acme-web@1.4.0 at 3f2a9c1`, from `designtools-manifest provenance`. */
   provenance?: string;
   /** For an editorial page. */
-  editorial?: { author: string; reviewed: string; status: "draft" | "published" };
+  /** `reviewer` when the person who signs it off is not the author: the studio writes, the client's brand lead reviews. */
+  editorial?: { author: string; reviewer?: string; reviewed: string; status: "draft" | "published" };
   children?: ReactNode;
 }) {
   return (
@@ -147,7 +192,7 @@ export function DocsHeader({
       {(provenance || editorial) && (
         <p data-slot="docs-provenance" className="text-xs text-muted-foreground">
           {editorial
-            ? `Written by ${editorial.author} · last reviewed ${editorial.reviewed} · ${editorial.status}`
+            ? `Written by ${editorial.author} · ${editorial.reviewer ? `reviewed by ${editorial.reviewer}, ` : "last reviewed "}${editorial.reviewed} · ${editorial.status}`
             : `${provenance} · generated from the code`}
         </p>
       )}
@@ -182,3 +227,21 @@ export function DocsSection({ title, lead, children }: { title: string; lead?: s
     </section>
   );
 }
+
+function NavLink({ link, current }: { link: DocsLink; current: string }) {
+  const active = current === link.href;
+  return (
+    <Link
+      href={link.href}
+      aria-current={active ? "page" : undefined}
+      data-slot="docs-nav-link"
+      className={cx(
+        target,
+        "flex items-center rounded-md px-2 py-1.5 hover:bg-muted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring",
+        active && "bg-muted font-medium",
+      )}
+    >
+      {link.label}
+    </Link>
+  );
+}

package/registry/standards.tsx

@@ -1,29 +1,37 @@
 import type { ReactNode } from "react";
+import { standardsSections } from "./lib/standards";
 
 /**
  * The project's performance budgets, accessibility target and support baseline,
  * rendered from the thresholds it already records (`.mxa/stack.json`
- * `baselines`), so the docs and the checks cannot disagree.
+ * `baselines`), so the docs and the checks cannot disagree. A value nobody has
+ * set is left out rather than shown as `null`; a note is shown as a sentence.
+ * Thresholds a client agrees beyond the schema (`textSize`, `touchTargets`) are
+ * titled from their keys.
  */
 export function Standards({ baselines, children }: { baselines: Record<string, unknown>; children?: ReactNode }) {
-  const sections = Object.entries(baselines).filter(([k]) => !k.startsWith("$"));
   return (
     <div data-slot="standards" className="flex flex-col gap-8">
-      {sections.map(([name, value]) => (
-        <section key={name} data-slot="standard" className="flex flex-col gap-2">
-          <h3 className="text-sm font-medium">{TITLES[name] ?? name}</h3>
-          {value && typeof value === "object" && !Array.isArray(value) ? (
-            <dl className="grid gap-x-6 gap-y-2 text-sm sm:grid-cols-[12rem_1fr]">
-              {Object.entries(value as Record<string, unknown>).map(([k, v]) => (
-                <div key={k} className="contents">
-                  <dt className="font-mono text-xs">{k}</dt>
-                  <dd className="text-muted-foreground">{show(v)}</dd>
+      {standardsSections(baselines).map((section) => (
+        <section key={section.key} data-slot="standard" className="flex flex-col gap-2">
+          <h3 className="text-sm font-medium">{section.title}</h3>
+          {section.rows.length === 1 && !section.rows[0].label ? (
+            <p className="text-sm">{section.rows[0].value}</p>
+          ) : section.rows.length ? (
+            <dl className="grid gap-x-6 gap-y-2 text-sm sm:grid-cols-[14rem_1fr]">
+              {section.rows.map((row) => (
+                <div key={row.label} className="contents">
+                  <dt className="text-muted-foreground">{row.label}</dt>
+                  <dd>{row.value}</dd>
                 </div>
               ))}
             </dl>
-          ) : (
-            <p className="text-sm text-muted-foreground">{show(value)}</p>
-          )}
+          ) : null}
+          {section.notes.map((note) => (
+            <p key={note} className="max-w-prose text-sm text-muted-foreground">
+              {note}
+            </p>
+          ))}
         </section>
       ))}
       {typeof baselines.$note === "string" && <p className="text-sm text-muted-foreground">{baselines.$note}</p>}
@@ -31,15 +39,3 @@ export function Standards({ baselines, children }: { baselines: Record<string, u
     </div>
   );
 }
-
-const TITLES: Record<string, string> = {
-  a11y: "Accessibility",
-  performance: "Performance budgets",
-  support: "Support",
-};
-
-function show(v: unknown): string {
-  if (Array.isArray(v)) return v.length ? v.join(", ") : "none set";
-  if (v && typeof v === "object") return JSON.stringify(v);
-  return String(v);
-}

package/registry/swatches.tsx

@@ -21,7 +21,7 @@ export function SemanticSwatches({
 }) {
   const colours = semanticColours(tokens);
   return (
-    <div data-slot="swatches" className="overflow-x-auto">
+    <div data-slot="swatches" className="overflow-x-auto" tabIndex={0} role="region" aria-label="Colours">
       <table className="w-full min-w-[32rem] border-collapse text-left text-sm">
         <thead>
           <tr className="border-b border-border text-xs text-muted-foreground">
@@ -110,7 +110,7 @@ function Swatch({
           {foreground && <span className="text-muted-foreground"> / {pointsAt(foreground)}</span>}
         </span>
         {grade && ratio !== null && (
-          <span data-slot="swatch-contrast" className={cx("text-muted-foreground", grade === "Fail" && "font-medium text-destructive")}>
+          <span data-slot="swatch-contrast" className={cx("text-muted-foreground", grade === "Fail" && "w-fit rounded-sm bg-destructive-subdued px-1 font-medium text-destructive-subdued-foreground")}>
             {ratio.toFixed(2)}:1 · {grade}
           </span>
         )}
@@ -119,6 +119,85 @@ function Swatch({
   );
 }
 
+/**
+ * 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"] }: { tokens: TokensManifest; modes?: Mode[] }) {
+  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 (
+    <div data-slot="page-contrast" className="flex flex-col gap-6">
+      {modes.map((mode) => (
+        <PageGrid key={mode} mode={mode} colours={colours} grounds={grounds} />
+      ))}
+    </div>
+  );
+}
+
+function PageGrid({ mode, colours, grounds }: { mode: Mode; colours: string[]; grounds: string[] }) {
+  const probe = useRef<HTMLDivElement>(null);
+  const [ratios, setRatios] = useState<Record<string, number | null>>({});
+  useEffect(() => {
+    const node = probe.current;
+    if (!node) return;
+    const paint = (v: string) => {
+      node.style.color = `var(${v})`;
+      return getComputedStyle(node).color;
+    };
+    const painted = Object.fromEntries([...colours, ...grounds].map((v) => [v, paint(v)]));
+    const out: Record<string, number | null> = {};
+    for (const c of colours) for (const g of grounds) out[`${c}|${g}`] = contrastRatio(painted[c], painted[g]);
+    setRatios(out);
+  }, [colours, grounds]);
+  return (
+    <div className="overflow-x-auto" tabIndex={0} role="region" aria-label={`Colours on each background, ${mode} mode`}>
+      <div ref={probe} data-theme={mode} hidden />
+      <table className="w-full min-w-[32rem] border-collapse text-left text-sm">
+        <caption className="pb-2 text-left text-sm font-medium capitalize">{mode}</caption>
+        <thead>
+          <tr className="border-b border-border text-xs text-muted-foreground">
+            <th scope="col" className="py-2 pr-4 font-medium">Colour</th>
+            {grounds.map((g) => (
+              <th key={g} scope="col" className="py-2 pr-4 font-mono font-medium">{g.slice(2)}</th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {colours.map((c) => (
+            <tr key={c} className="border-b border-border">
+              <th scope="row" className="py-2 pr-4 font-mono text-xs font-medium">{c.slice(2)}</th>
+              {grounds.map((g) => {
+                const r = ratios[`${c}|${g}`];
+                const mark = r == null ? "" : r >= 4.5 ? "text" : r >= 3 ? "shape" : "none";
+                return (
+                  <td key={g} className="py-2 pr-4">
+                    <div className="flex items-center gap-2">
+                      {/* only the sample takes the mode; the number is read on the page */}
+                      <span data-theme={mode} className="flex h-9 w-12 items-center justify-center rounded-md border border-(--border) text-base font-bold" style={{ background: `var(${g})`, color: `var(${c})` }} aria-hidden>
+                        Aa
+                      </span>
+                      {r != null && (
+                        <span className={cx("font-mono text-xs", mark === "none" && "rounded-sm bg-destructive-subdued px-1 text-destructive-subdued-foreground")}>
+                          {r.toFixed(1)} {mark}
+                        </span>
+                      )}
+                    </div>
+                  </td>
+                );
+              })}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
 /** The primitive ramps, one row per colour family, each step painted from its own token. */
 export function RampSwatches({ tokens }: { tokens: TokensManifest }) {
   return (
@@ -135,7 +214,7 @@ export function RampSwatches({ tokens }: { tokens: TokensManifest }) {
                 className="flex h-14 items-end p-1.5"
                 style={{ background: `var(${token.name})` }}
               >
-                <span className="rounded-sm bg-canvas/80 px-1 font-mono text-[0.625rem] text-canvas-foreground">{step}</span>
+                <span className="rounded-sm bg-canvas/80 px-1 font-mono text-xs text-canvas-foreground">{step}</span>
               </li>
             ))}
           </ol>

package/registry/usage.tsx

@@ -4,6 +4,7 @@ import { slugOf } from "./lib/manifest";
 import type { ComponentEntry, ComponentsManifest } from "./lib/manifest-types";
 import { StatusBadge } from "./lib/status";
 import { inline } from "./lib/text";
+import { target } from "./lib/cx";
 
 /**
  * When to use a component, when not, and what to use instead, under its status.
@@ -34,7 +35,7 @@ export function Usage({
           <span key={name}>
             {i > 0 && ", "}
             {c ? (
-              <Link href={`${basePath}/components/${slugOf(c)}`} className="underline underline-offset-2">
+              <Link href={`${basePath}/components/${slugOf(c)}`} className={`${target} inline-flex items-center underline underline-offset-2`}>
                 {name}
               </Link>
             ) : (

package/registry/variant-matrix.tsx

@@ -39,7 +39,7 @@ export function VariantMatrix({
   return (
     <div data-slot="variant-matrix" className="flex flex-col gap-8">
       {cols ? (
-        <div className="overflow-x-auto">
+        <div className="overflow-x-auto" tabIndex={0} role="region" aria-label="Variants">
           <table className="border-collapse text-sm">
             <caption className="sr-only">
               {entry.name}: {rows.name} by {cols.name}

package/registry/voice-terms.tsx

@@ -6,7 +6,7 @@ export function VoiceTerms({ terms }: { terms: TermEntry[] }) {
   const shown = [...terms.filter((t) => t.kind === "product"), ...terms.filter((t) => t.kind !== "product" && t.wrong?.length)];
   if (shown.length === 0) return <p className="text-sm text-muted-foreground">No terms yet. Add them to the taxonomy file.</p>;
   return (
-    <div data-slot="voice-terms" className="overflow-x-auto">
+    <div data-slot="voice-terms" className="overflow-x-auto" tabIndex={0} role="region" aria-label="Terms">
       <table className="w-full min-w-[28rem] border-collapse text-left text-sm">
         <thead>
           <tr className="border-b border-border text-xs text-muted-foreground">