@designtools/blocks 0.1.0 → 0.2.0

package/registry/lib/manifest-types.ts

@@ -36,6 +36,12 @@ export interface ComponentEntry {
   export: string;
   /** The file that exports it. */
   source: string;
+  /**
+   * The module specifier an app imports it by, through the tsconfig path alias
+   * that reaches the system folder (`@ds/button/button`). Absent when no alias does,
+   * in which case `source` is the only honest answer.
+   */
+  import?: string;
   /** The component's JSDoc, or its variant config's when the component has none. */
   description?: string;
   /** `@category`. Blocks group components without one under "Components". */
@@ -182,6 +188,8 @@ export interface TokenEntry {
   description?: string;
   /** The stylesheet that first declares it. */
   source: string;
+  /** Later stylesheets whose declaration replaced a value, in the order read: an override layer. */
+  overriddenIn?: string[];
 }
 
 /** rules.json: brand and interface rules in one format. */
@@ -206,8 +214,11 @@ export interface RuleEntry {
   exceptions?: string[];
   /** Tokens it rests on, e.g. `--size-2xl`. */
   tokens?: string[];
-  /** Confirmed with the client, or an assumption still to confirm. */
-  status: "confirmed" | "assumption";
+  /**
+   * Confirmed with the client, an assumption still to confirm, or measured: generated from the
+   * tokens (where a colour can be text), a fact that changes when they do, not a decision.
+   */
+  status: "confirmed" | "assumption" | "measured";
   /** How it is proved: a test, a lint rule, an audit, or a person. */
   check?: { kind: "test" | "lint" | "audit" | "manual"; ref?: string; description?: string };
   source: string;

package/registry/lib/manifest.ts

@@ -46,6 +46,14 @@ export function componentKey(entry: Pick<ComponentEntry, "source" | "export">):
 }
 
 /** `RadioGroup` → `radio-group`, for URLs. */
+/**
+ * What an app writes to import it: the alias the manifest found (`@ds/button/button`),
+ * or the file's path when no alias reaches the system folder.
+ */
+export function importOf(entry: Pick<ComponentEntry, "import" | "source">): string {
+  return entry.import ?? entry.source.replace(/\.(tsx?|jsx?)$/, "");
+}
+
 export function slugOf(entry: Pick<ComponentEntry, "name">): string {
   return entry.name
     .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
@@ -81,6 +89,44 @@ export function groupByCategory(manifest: ComponentsManifest): CategoryGroup[] {
     .map(([category, components]) => ({ category, components }));
 }
 
+export interface Family {
+  /** The component with the `@category`: Card. */
+  head: ComponentEntry;
+  /** The rest of its file, which has none of its own: CardHeader, CardTitle. */
+  parts: ComponentEntry[];
+}
+
+/**
+ * Each category's components with their parts folded under them, so a reader
+ * sees nine components rather than fourteen pages. A part is a component with
+ * no `@category` of its own in a file whose first categorised component heads it.
+ */
+export function groupFamilies(manifest: ComponentsManifest): { category: string; families: Family[] }[] {
+  return groupByCategory(manifest).map(({ category, components }) => {
+    const families: Family[] = [];
+    const heads = new Map<string, Family>();
+    for (const c of components) {
+      const head = heads.get(c.source);
+      if (head && !c.category) {
+        head.parts.push(c);
+        continue;
+      }
+      const family = { head: c, parts: [] };
+      families.push(family);
+      if (c.category && !heads.has(c.source)) heads.set(c.source, family);
+    }
+    // a part whose name sorts before its head's was listed before the head was known: it joins it now
+    const kept = families.filter((f) => {
+      const head = heads.get(f.head.source);
+      if (!head || head === f || f.head.category) return true;
+      head.parts.push(f.head);
+      return false;
+    });
+    for (const f of kept) f.parts.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    return { category, families: kept };
+  });
+}
+
 export function tokensOfTier(manifest: TokensManifest, tier: TokenTier): TokenEntry[] {
   return manifest.tokens.filter((t) => t.tier === tier);
 }

package/registry/lib/markdown.ts

@@ -8,8 +8,9 @@
  * an agent can tell what each part is. Status travels with everything.
  */
 
-import { groupByCategory, ramps, semanticColours, shortName, slugOf, tokensOfTier, typeScale, valueIn } from "./manifest";
+import { groupByCategory, importOf, ramps, semanticColours, shortName, slugOf, tokensOfTier, typeScale, valueIn } from "./manifest";
 import type { AdherenceReport } from "./adherence-types";
+import { standardsSections } from "./standards";
 import type {
   AssetEntry,
   ComponentEntry,
@@ -31,16 +32,21 @@ export function generatedHeader(provenance: string): string {
 }
 
 /** An editorial page: who wrote it, when it was last reviewed, and whether it is settled. */
-export function editorialHeader({ author, reviewed, status }: { author: string; reviewed: string; status: "draft" | "published" }): string {
-  return `> Written by ${author}. Last reviewed ${reviewed}. Status: ${status}.\n\n`;
+export function editorialHeader({ author, reviewer, reviewed, status }: { author: string; reviewer?: string; reviewed: string; status: "draft" | "published" }): string {
+  return `> Written by ${author}. ${reviewer ? `Reviewed by ${reviewer}, ${reviewed}` : `Last reviewed ${reviewed}`}. Status: ${status}.\n\n`;
 }
 
 // ------------------------------------------------------------ components
 
-export function componentMarkdown(entry: ComponentEntry): string {
-  const out: string[] = [`## ${entry.name}`, ""];
+/**
+ * A component as an agent reads it. `level` is its heading's: 1 when it is the
+ * whole page (`/components/button.md`), 2 inside a longer document (`context.md`),
+ * so a page never opens with the same heading twice.
+ */
+export function componentMarkdown(entry: ComponentEntry, level: 1 | 2 = 2): string {
+  const out: string[] = [`${"#".repeat(level)} ${entry.name}`, ""];
   out.push(`Status: ${entry.status ?? "not set"}${entry.statusNote ? `. ${entry.statusNote}` : ""}`, "");
-  out.push(`\`import { ${entry.export} } from "${entry.source.replace(/\.(tsx?|jsx?)$/, "")}"\``, "");
+  out.push(`\`import { ${entry.export} } from "${importOf(entry)}"\``, "");
   if (entry.description) out.push(entry.description, "");
 
   if (entry.usage) {
@@ -98,8 +104,11 @@ function examplesMarkdown(canonical: ExampleRef | undefined, dos: ExampleRef[],
     out.push("Copy this one:");
     fence("example", canonical);
   }
-  for (const d of dos) fence("do", d);
-  for (const d of donts) fence("dont", d);
+  // in pairs, as the page shows them: the first do beside the first don't
+  for (let i = 0; i < Math.max(dos.length, donts.length); i++) {
+    if (dos[i]) fence("do", dos[i]);
+    if (donts[i]) fence("dont", donts[i]);
+  }
   for (const o of other) fence("example", o);
   return out;
 }
@@ -174,8 +183,9 @@ export function ruleMarkdown(rule: RuleEntry): string {
   return end(out);
 }
 
-export function patternMarkdown(pattern: PatternEntry): string {
-  const out = [`## ${pattern.name}`, "", `Status: ${pattern.status ?? "not set"}`, ""];
+/** A pattern; `level` as for `componentMarkdown`. */
+export function patternMarkdown(pattern: PatternEntry, level: 1 | 2 = 2): string {
+  const out = [`${"#".repeat(level)} ${pattern.name}`, "", `Status: ${pattern.status ?? "not set"}`, ""];
   if (pattern.description) out.push(pattern.description, "");
   if (pattern.components.length) out.push(`Composes: ${pattern.components.join(", ")}`, "");
   for (const ex of pattern.examples) {
@@ -201,8 +211,13 @@ export function assetsMarkdown(assets: AssetEntry[]): string {
 
 /** `.mxa/stack.json` baselines, or anything shaped like them: a table of name and target. */
 export function standardsMarkdown(baselines: Record<string, unknown>): string {
-  const out = ["## Standards", "", "| Standard | Target |", "| --- | --- |"];
-  for (const [name, value] of flatten(baselines)) out.push(`| ${name} | ${cell(value)} |`);
+  const out = ["## Standards", ""];
+  for (const section of standardsSections(baselines)) {
+    out.push(`### ${section.title}`, "");
+    for (const row of section.rows) out.push(row.label ? `- ${row.label}: ${row.value}` : row.value);
+    if (section.rows.length) out.push("");
+    for (const note of section.notes) out.push(note, "");
+  }
   return end(out);
 }
 
@@ -216,7 +231,7 @@ export function adherenceMarkdown(report: AdherenceReport): string {
     "A report, never a gate.",
     "",
     `- From the system: ${pct(s.share)} (${s.systemUses} system uses, ${s.rawElements} raw elements a component replaces)`,
-    `- Off-system values: ${s.offSystemValues} (${s.offSystem.palette} palette steps, ${s.offSystem.arbitrary} arbitrary values)`,
+    `- Off-system values: ${s.offSystemValues} (${s.offSystem.palette} palette steps, ${s.offSystem.arbitrary} arbitrary values, ${s.offSystem["status-text"] ?? 0} status colours as text)`,
     `- Overrides: ${s.overrides}`,
     `- Components never used: ${s.componentsUnused.length ? s.componentsUnused.join(", ") : "none"}`,
     "",
@@ -244,8 +259,8 @@ export function systemMarkdown(
   );
   if (input.tokens) out.push(coloursMarkdown(input.tokens), typeMarkdown(input.tokens), scaleMarkdown(input.tokens));
   if (input.rules?.length) out.push("# Rules", "", ...input.rules.map(ruleMarkdown));
-  if (input.patterns?.length) out.push("# Patterns", "", ...input.patterns.map(patternMarkdown));
-  for (const group of groupByCategory(input.components)) out.push(`# ${group.category}`, "", ...group.components.map(componentMarkdown));
+  if (input.patterns?.length) out.push("# Patterns", "", ...input.patterns.map((p) => patternMarkdown(p)));
+  for (const group of groupByCategory(input.components)) out.push(`# ${group.category}`, "", ...group.components.map((c) => componentMarkdown(c)));
   if (input.terms?.length) out.push(glossaryMarkdown(input.terms));
   return end(out);
 }
@@ -268,16 +283,6 @@ function cell(value: unknown): string {
   return String(value).replace(/\|/g, "\\|").replace(/\s*\n\s*/g, " ");
 }
 
-function flatten(value: unknown, prefix = ""): [string, string][] {
-  if (value && typeof value === "object" && !Array.isArray(value)) {
-    return Object.entries(value as Record<string, unknown>)
-      .filter(([k]) => !k.startsWith("$"))
-      .flatMap(([k, v]) => flatten(v, prefix ? `${prefix} ${k}` : k));
-  }
-  if (Array.isArray(value)) return value.length ? [[prefix, value.join(", ")]] : [];
-  return [[prefix, String(value)]];
-}
-
 function end(lines: string[]): string {
   return lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
 }

package/registry/lib/search.ts

@@ -0,0 +1,99 @@
+/**
+ * The docs search: components, their parts, rules, patterns and pages, matched
+ * fuzzily on their names, with the taxonomy's wrong forms as aliases, so
+ * "dropdown" finds Select and "buton" finds Button. It aids navigation and does
+ * nothing else: no full text, no index to build, because the manifest is small
+ * enough to search in the browser. The same query always gives the same order.
+ */
+
+import fuzzysort from "fuzzysort";
+import { groupFamilies, slugOf } from "./manifest";
+import type { ComponentsManifest, PatternEntry, RuleEntry, TermEntry } from "./manifest-types";
+
+export type SearchKind = "Component" | "Rule" | "Pattern" | "Page";
+
+export interface SearchItem {
+  kind: SearchKind;
+  label: string;
+  href: string;
+  /** The taxonomy's wrong forms for it: typing one finds it, and the result says so. */
+  wrong: string[];
+  /** Anything else it answers to quietly, such as a rule's id. */
+  also?: string[];
+  /** One short line under the label: a category, "part of Card", a rule's kind. */
+  detail?: string;
+}
+
+export interface SearchGroup {
+  kind: SearchKind;
+  /** `matched` is the wrong form a result was found by ("Dropdown" for Select). */
+  items: (SearchItem & { matched?: string })[];
+}
+
+const ORDER: SearchKind[] = ["Component", "Rule", "Pattern", "Page"];
+
+export function searchIndex({
+  manifest,
+  rules = [],
+  patterns = [],
+  terms = [],
+  pages = [],
+  basePath = "/design/system",
+}: {
+  manifest: ComponentsManifest;
+  rules?: RuleEntry[];
+  patterns?: PatternEntry[];
+  terms?: TermEntry[];
+  pages?: { label: string; href: string }[];
+  basePath?: string;
+}): SearchItem[] {
+  const wrong = new Map<string, string[]>();
+  for (const t of terms) if (t.wrong?.length) wrong.set(t.name.toLowerCase(), t.wrong);
+  const wrongOf = (name: string) => wrong.get(name.toLowerCase()) ?? [];
+
+  const items: SearchItem[] = [];
+  for (const { category, families } of groupFamilies(manifest)) {
+    for (const { head, parts } of families) {
+      items.push({ kind: "Component", label: head.name, href: `${basePath}/components/${slugOf(head)}`, wrong: wrongOf(head.name), detail: category });
+      for (const p of parts) {
+        items.push({ kind: "Component", label: p.name, href: `${basePath}/components/${slugOf(p)}`, wrong: wrongOf(p.name), detail: `part of ${head.name}` });
+      }
+    }
+  }
+  for (const r of rules) {
+    items.push({ kind: "Rule", label: r.title, href: `${basePath}/rules#${r.id}`, wrong: wrongOf(r.title), also: [r.id.replace(/-/g, " ")], detail: r.kind === "brand" ? "Brand rule" : "Interface rule" });
+  }
+  for (const p of patterns) items.push({ kind: "Pattern", label: p.name, href: `${basePath}/patterns/${p.id}`, wrong: wrongOf(p.name) });
+  for (const p of pages) items.push({ kind: "Page", label: p.label, href: p.href, wrong: [] });
+  return items;
+}
+
+/**
+ * The matches for a query, grouped by kind (components, rules, patterns, pages),
+ * best first within each, at most `perGroup` of each. A match found only through
+ * an alias says which: `matched` is the wrong form typed ("Dropdown").
+ */
+export function search(items: SearchItem[], query: string, perGroup = 6): SearchGroup[] {
+  const q = query.trim();
+  if (!q) return [];
+  const results = fuzzysort.go(q, items, { keys: ["label", (item: SearchItem) => item.wrong.join(" / "), (item: SearchItem) => (item.also ?? []).join(" / ")], limit: 0, threshold: 0.3 });
+  const ranked = [...results].sort(
+    (a, b) => b.score - a.score || ORDER.indexOf(a.obj.kind) - ORDER.indexOf(b.obj.kind) || (a.obj.label < b.obj.label ? -1 : a.obj.label > b.obj.label ? 1 : 0),
+  );
+  return ORDER.map((kind) => ({
+    kind,
+    items: ranked
+      .filter((r) => r.obj.kind === kind)
+      .slice(0, perGroup)
+      .map((r) => {
+        const viaWrong = (r[1]?.score ?? 0) > Math.max(r[0]?.score ?? 0, r[2]?.score ?? 0);
+        // the wrong form that matched best, to say why a result is here ("Dropdown" for Select)
+        const alias = viaWrong
+          ? r.obj.wrong
+              .map((a) => ({ a, score: fuzzysort.single(q, a)?.score ?? 0 }))
+              .sort((x, y) => y.score - x.score)[0]?.a
+          : undefined;
+        return alias ? { ...r.obj, matched: alias } : r.obj;
+      }),
+  })).filter((g) => g.items.length > 0);
+}

package/registry/lib/standards.ts

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

package/registry/lib/status.tsx

@@ -1,6 +1,6 @@
 import { cx } from "./cx";
 
-type Any = "stable" | "emerging" | "deprecated" | "confirmed" | "assumption" | "draft" | "published";
+type Any = "stable" | "emerging" | "deprecated" | "confirmed" | "assumption" | "measured" | "draft" | "published";
 
 const LOOK: Record<Any, string> = {
   stable: "bg-success-subdued text-success-subdued-foreground",
@@ -8,6 +8,8 @@ const LOOK: Record<Any, string> = {
   published: "bg-success-subdued text-success-subdued-foreground",
   emerging: "bg-warning-subdued text-warning-subdued-foreground",
   assumption: "bg-warning-subdued text-warning-subdued-foreground",
+  // generated from the tokens: a fact, not a decision, so neither settled nor pending
+  measured: "bg-muted text-muted-foreground",
   draft: "bg-warning-subdued text-warning-subdued-foreground",
   deprecated: "bg-destructive-subdued text-destructive-subdued-foreground",
 };

package/registry/logo-usage.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { target } from "./lib/cx";
 import { assetUrl } from "./lib/lookup";
 import type { AssetEntry, RuleEntry } from "./lib/manifest-types";
 import { StatusBadge } from "./lib/status";
@@ -9,18 +10,24 @@ const LENGTH = /^\s*(\d+(?:\.\d+)?)(px|rem|em)\b/;
 
 /**
  * Each logo on the surfaces it may sit on, at its minimum size, with its clear
- * space drawn, and the brand rules that govern it. Surfaces are semantic colour
- * names, so the panels paint from the tokens.
+ * space drawn, and the brand rules that govern it: rules for every logo once,
+ * above them, and a rule naming one logo under that logo. Surfaces are semantic
+ * colour names painted from the light-mode tokens whatever the docs' mode, because a
+ * brand book's surfaces are fixed colours (white, the brand colour, an off-white),
+ * and dark mode would otherwise show the logo on a surface the brand forbids.
  */
 export function LogoUsage({ assets, rules = [], rulesHref }: { assets: AssetEntry[]; rules?: RuleEntry[]; rulesHref?: string }) {
   const logos = assets.filter((a) => a.kind === "logo");
   if (logos.length === 0) return <p className="text-sm text-muted-foreground">No logos in the brand folder yet.</p>;
+  const brand = rules.filter((r) => r.kind === "brand");
+  const general = brand.filter((r) => (r.appliesTo ?? []).some((x) => ["logo", "logos"].includes(x.toLowerCase())));
   return (
     <div data-slot="logo-usage" className="flex flex-col gap-10">
+      {general.length > 0 && <RuleList rules={general} rulesHref={rulesHref} boxed />}
       {logos.map((logo) => {
         const src = assetUrl(logo);
-        const names = new Set(["logo", "logos", logo.name.toLowerCase(), logo.file.toLowerCase()]);
-        const governing = rules.filter((r) => r.kind === "brand" && (r.appliesTo ?? []).some((x) => names.has(x.toLowerCase())));
+        const names = new Set([logo.name.toLowerCase(), logo.file.toLowerCase()]);
+        const own = brand.filter((r) => !general.includes(r) && (r.appliesTo ?? []).some((x) => names.has(x.toLowerCase())));
         const clear = LENGTH.exec(logo.clearSpace ?? "");
         const min = LENGTH.exec(logo.minSize ?? "");
         return (
@@ -34,6 +41,7 @@ export function LogoUsage({ assets, rules = [], rulesHref }: { assets: AssetEntr
                 <li
                   key={surface}
                   data-slot="logo-surface"
+                  data-theme="light"
                   className="flex min-h-40 flex-col items-center justify-center gap-3 rounded-lg border border-border p-6"
                   style={{ background: `var(--${surface})`, color: `var(--${surface}-foreground, var(--canvas-foreground))` }}
                 >
@@ -45,7 +53,7 @@ export function LogoUsage({ assets, rules = [], rulesHref }: { assets: AssetEntr
                   >
                     {src ? <img src={src} alt={logo.alt ?? logo.name} className="block h-12 w-auto" /> : <span className="text-xs">{logo.file}</span>}
                   </span>
-                  <span className="font-mono text-xs opacity-80">{surface}</span>
+                  <span className="font-mono text-xs">{surface}</span>
                 </li>
               ))}
             </ul>
@@ -53,7 +61,17 @@ export function LogoUsage({ assets, rules = [], rulesHref }: { assets: AssetEntr
               <dt className="font-medium">Minimum size</dt>
               <dd className="flex items-center gap-3 text-muted-foreground">
                 {logo.minSize ?? "not set"}
-                {src && min && <img src={src} alt="" aria-hidden className="w-auto" style={{ height: `${min[1]}${min[2]}` }} />}
+                {src && min && (
+                  // on the logo's own first surface, so a reversed (white) logo is visible at the size it is shown at
+                  <span
+                    data-slot="logo-min-size"
+                    data-theme="light"
+                    className="inline-flex rounded-md border border-border p-2"
+                    style={{ background: `var(--${logo.surfaces?.[0] ?? "canvas"})` }}
+                  >
+                    <img src={src} alt="" aria-hidden className="block w-auto" style={{ height: `${min[1]}${min[2]}` }} />
+                  </span>
+                )}
               </dd>
               <dt className="font-medium">Clear space</dt>
               <dd className="text-muted-foreground">{logo.clearSpace ?? "not set"}</dd>
@@ -66,22 +84,29 @@ export function LogoUsage({ assets, rules = [], rulesHref }: { assets: AssetEntr
                 </>
               )}
             </dl>
-            {governing.length > 0 && (
-              <ul data-slot="logo-rules" className="flex flex-col gap-2 text-sm">
-                {governing.map((r) => (
-                  <li key={r.id} className="flex flex-wrap items-baseline gap-2">
-                    <StatusBadge status={r.status} />
-                    <a href={rulesHref ? `${rulesHref}#${r.id}` : `#${r.id}`} className="font-medium underline underline-offset-2">
-                      {r.title}
-                    </a>
-                    <span className="text-muted-foreground">{inline(r.statement)}</span>
-                  </li>
-                ))}
-              </ul>
-            )}
+            {own.length > 0 && <RuleList rules={own} rulesHref={rulesHref} />}
           </section>
         );
       })}
     </div>
   );
 }
+
+function RuleList({ rules, rulesHref, boxed }: { rules: RuleEntry[]; rulesHref?: string; boxed?: boolean }) {
+  return (
+    <ul
+      data-slot="logo-rules"
+      className={boxed ? "flex flex-col gap-3 rounded-lg border border-border bg-surface p-4 text-sm text-surface-foreground" : "flex flex-col gap-2 text-sm"}
+    >
+      {rules.map((r) => (
+        <li key={r.id} className="flex flex-wrap items-baseline gap-2">
+          <StatusBadge status={r.status} />
+          <a href={rulesHref ? `${rulesHref}#${r.id}` : `#${r.id}`} className={`${target} inline-flex items-center font-medium underline underline-offset-2`}>
+            {r.title}
+          </a>
+          <span className="text-muted-foreground">{inline(r.statement)}</span>
+        </li>
+      ))}
+    </ul>
+  );
+}

package/registry/pattern.tsx

@@ -8,6 +8,7 @@ import { slugOf } from "./lib/manifest";
 import type { ComponentsManifest, PatternEntry } from "./lib/manifest-types";
 import { StatusBadge } from "./lib/status";
 import { inline } from "./lib/text";
+import { cx, target } from "./lib/cx";
 
 /** A recurring screen composition: each composition live, with its code and the components it uses. */
 export function Pattern({
@@ -30,7 +31,7 @@ export function Pattern({
         {pattern.components.map((name) => {
           const c = known.get(name);
           return c ? (
-            <Link key={name} href={`${basePath}/components/${slugOf(c)}`} className="rounded-sm bg-muted px-1.5 py-0.5 font-mono text-xs hover:underline">
+            <Link key={name} href={`${basePath}/components/${slugOf(c)}`} className={cx(target, "inline-flex items-center rounded-sm bg-muted px-1.5 py-0.5 font-mono text-xs hover:underline")}>
               {name}
             </Link>
           ) : (
@@ -53,7 +54,7 @@ export function Pattern({
               {ex.description && <span className="text-muted-foreground">{inline(ex.description)}</span>}
               {ex.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={ex.code} label={ex.name} />
                   </div>

package/registry/playground.tsx

@@ -7,7 +7,7 @@ import { ToggleGroup } from "@base-ui/react/toggle-group";
 import { useId, useState } from "react";
 import { CodeView } from "./code-view";
 import { Boundary } from "./lib/boundary";
-import { cx } from "./lib/cx";
+import { cx, target } from "./lib/cx";
 import { toJSX } from "./lib/jsx";
 import { coerce, componentFor, Missing } from "./lib/lookup";
 import type { ComponentEntry, VariantAxis } from "./lib/manifest-types";
@@ -99,7 +99,7 @@ function AxisControl({ axis, value, onChange }: { axis: VariantAxis; value: stri
               key={o.name}
               value={o.name}
               title={o.description}
-              className="rounded-md border border-border px-2 py-1 font-mono text-xs hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring data-[pressed]:bg-primary data-[pressed]:text-primary-foreground"
+              className={cx(target, "rounded-md border border-border px-2 py-1 font-mono text-xs hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring data-[pressed]:bg-primary data-[pressed]:text-primary-foreground")}
             >
               {o.name}
             </Toggle>
@@ -116,7 +116,7 @@ function AxisControl({ axis, value, onChange }: { axis: VariantAxis; value: stri
       <Select.Root value={value} onValueChange={(v) => typeof v === "string" && onChange(v)}>
         <Select.Trigger
           aria-labelledby={id}
-          className="flex items-center justify-between rounded-md border border-border px-2 py-1 font-mono text-xs focus-visible:outline-2 focus-visible:outline-ring"
+          className={cx(target, "flex items-center justify-between rounded-md border border-border px-2 py-1 font-mono text-xs focus-visible:outline-2 focus-visible:outline-ring")}
         >
           <Select.Value />
           <Select.Icon aria-hidden>▾</Select.Icon>
@@ -129,7 +129,7 @@ function AxisControl({ axis, value, onChange }: { axis: VariantAxis; value: stri
                   <Select.Item
                     key={o.name}
                     value={o.name}
-                    className="cursor-default rounded-sm px-2 py-1 font-mono text-xs outline-none data-[highlighted]:bg-muted"
+                    className={cx(target, "flex cursor-default items-center rounded-sm px-2 py-1 font-mono text-xs outline-none data-[highlighted]:bg-muted")}
                   >
                     <Select.ItemText>{o.name}</Select.ItemText>
                   </Select.Item>
@@ -154,7 +154,8 @@ function FlagControl({ name, checked, onChange }: { name: string; checked: boole
         id={id}
         checked={checked}
         onCheckedChange={onChange}
-        className="relative h-5 w-9 shrink-0 rounded-full border border-border bg-canvas outline-offset-2 focus-visible:outline-2 focus-visible:outline-ring data-[checked]:border-primary data-[checked]:bg-primary"
+        // drawn small, pressed large: the hit area reaches 48px tall without the switch growing
+        className="relative h-5 w-9 shrink-0 rounded-full after:absolute after:-inset-3.5 after:content-[''] border border-border bg-canvas outline-offset-2 focus-visible:outline-2 focus-visible:outline-ring data-[checked]:border-primary data-[checked]:bg-primary"
       >
         <Switch.Thumb className="block size-3.5 translate-x-0.5 rounded-full bg-muted-foreground transition-transform data-[checked]:translate-x-[1.0625rem] data-[checked]:bg-primary-foreground motion-reduce:transition-none" />
       </Switch.Root>
@@ -173,7 +174,7 @@ function TextControl({ value, onChange }: { value: string; onChange: (v: string)
         id={id}
         value={value}
         onChange={(e) => onChange(e.target.value)}
-        className="rounded-md border border-border bg-canvas px-2 py-1 text-sm focus-visible:outline-2 focus-visible:outline-ring"
+        className={cx(target, "rounded-md border border-border bg-canvas px-2 py-1 text-sm focus-visible:outline-2 focus-visible:outline-ring")}
       />
     </div>
   );

package/registry/preview-frame.tsx

@@ -2,7 +2,7 @@
 
 import { useEffect, useState, type ReactNode } from "react";
 import { Boundary } from "./lib/boundary";
-import { cx } from "./lib/cx";
+import { cx, target } from "./lib/cx";
 import { compositionsFor, examplesFor, Missing, renderExample } from "./lib/lookup";
 import type { ComponentEntry, PatternEntry } from "./lib/manifest-types";
 
@@ -27,7 +27,7 @@ export function PreviewFrame({
   const [width, setWidth] = useState(widths[0]);
   const [theme, setTheme] = useState<Theme>("light");
   const url = `${src}${src.includes("?") ? "&" : "?"}theme=${theme}`;
-  const button = "rounded-md px-2 py-1 font-mono text-xs hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring";
+  const button = cx(target, "rounded-md px-2 py-1 font-mono text-xs hover:bg-muted focus-visible:outline-2 focus-visible:outline-ring");
 
   return (
     <figure data-slot="preview-frame" className="flex flex-col gap-2">
@@ -52,7 +52,7 @@ export function PreviewFrame({
           </a>
         </span>
       </figcaption>
-      <div className="overflow-x-auto rounded-lg border border-border bg-muted p-2">
+      <div className="overflow-x-auto rounded-lg border border-border bg-muted p-2" tabIndex={0} role="region" aria-label="Preview">
         <iframe
           title={`${title}, ${width}px wide, ${theme} mode`}
           src={url}