@robomous/ui-core 0.1.1 → 0.2.0

package/{shadcn → src/components}/tabs.tsx

@@ -1,8 +1,8 @@
-import * as React from "react"
-import { cva, type VariantProps } from "class-variance-authority"
-import { Tabs as TabsPrimitive } from "radix-ui"
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { Tabs as TabsPrimitive } from "radix-ui";
 
-import { cn } from "@/lib/cn"
+import { cn } from "cn";
 
 function Tabs({
   className,
@@ -13,13 +13,10 @@ function Tabs({
     <TabsPrimitive.Root
       data-slot="tabs"
       data-orientation={orientation}
-      className={cn(
-        "group/tabs flex gap-2 data-horizontal:flex-col",
-        className
-      )}
+      className={cn("group/tabs flex gap-2 data-horizontal:flex-col", className)}
       {...props}
     />
-  )
+  );
 }
 
 const tabsListVariants = cva(
@@ -34,15 +31,14 @@ const tabsListVariants = cva(
     defaultVariants: {
       variant: "default",
     },
-  }
-)
+  },
+);
 
 function TabsList({
   className,
   variant = "default",
   ...props
-}: React.ComponentProps<typeof TabsPrimitive.List> &
-  VariantProps<typeof tabsListVariants>) {
+}: React.ComponentProps<typeof TabsPrimitive.List> & VariantProps<typeof tabsListVariants>) {
   return (
     <TabsPrimitive.List
       data-slot="tabs-list"
@@ -50,13 +46,10 @@ function TabsList({
       className={cn(tabsListVariants({ variant }), className)}
       {...props}
     />
-  )
+  );
 }
 
-function TabsTrigger({
-  className,
-  ...props
-}: React.ComponentProps<typeof TabsPrimitive.Trigger>) {
+function TabsTrigger({ className, ...props }: React.ComponentProps<typeof TabsPrimitive.Trigger>) {
   return (
     <TabsPrimitive.Trigger
       data-slot="tabs-trigger"
@@ -65,24 +58,21 @@ function TabsTrigger({
         "group-data-[variant=line]/tabs-list:bg-transparent group-data-[variant=line]/tabs-list:data-active:bg-transparent dark:group-data-[variant=line]/tabs-list:data-active:border-transparent dark:group-data-[variant=line]/tabs-list:data-active:bg-transparent",
         "data-active:bg-background data-active:text-foreground dark:data-active:border-input dark:data-active:bg-input/30 dark:data-active:text-foreground",
         "after:absolute after:bg-foreground after:opacity-0 after:transition-opacity group-data-horizontal/tabs:after:inset-x-0 group-data-horizontal/tabs:after:bottom-[-5px] group-data-horizontal/tabs:after:h-0.5 group-data-vertical/tabs:after:inset-y-0 group-data-vertical/tabs:after:-right-1 group-data-vertical/tabs:after:w-0.5 group-data-[variant=line]/tabs-list:data-active:after:opacity-100",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
-function TabsContent({
-  className,
-  ...props
-}: React.ComponentProps<typeof TabsPrimitive.Content>) {
+function TabsContent({ className, ...props }: React.ComponentProps<typeof TabsPrimitive.Content>) {
   return (
     <TabsPrimitive.Content
       data-slot="tabs-content"
       className={cn("flex-1 text-sm outline-none", className)}
       {...props}
     />
-  )
+  );
 }
 
-export { Tabs, TabsList, TabsTrigger, TabsContent, tabsListVariants }
+export { Tabs, TabsList, TabsTrigger, TabsContent, tabsListVariants };

package/{shadcn → src/components}/textarea.tsx

@@ -1,6 +1,6 @@
-import * as React from "react"
+import * as React from "react";
 
-import { cn } from "@/lib/cn"
+import { cn } from "cn";
 
 function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
   return (
@@ -8,11 +8,11 @@ function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
       data-slot="textarea"
       className={cn(
         "flex field-sizing-content min-h-16 w-full rounded-lg border border-input bg-transparent px-2.5 py-2 text-base transition-colors outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:bg-input/50 disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 md:text-sm dark:bg-input/30 dark:disabled:bg-input/80 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40",
-        className
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
-export { Textarea }
+export { Textarea };

package/{shadcn → src/components}/tooltip.tsx

@@ -1,9 +1,9 @@
-"use client"
+"use client";
 
-import * as React from "react"
-import { Tooltip as TooltipPrimitive } from "radix-ui"
+import * as React from "react";
+import { Tooltip as TooltipPrimitive } from "radix-ui";
 
-import { cn } from "@/lib/cn"
+import { cn } from "cn";
 
 function TooltipProvider({
   delayDuration = 0,
@@ -15,19 +15,15 @@ function TooltipProvider({
       delayDuration={delayDuration}
       {...props}
     />
-  )
+  );
 }
 
-function Tooltip({
-  ...props
-}: React.ComponentProps<typeof TooltipPrimitive.Root>) {
-  return <TooltipPrimitive.Root data-slot="tooltip" {...props} />
+function Tooltip({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Root>) {
+  return <TooltipPrimitive.Root data-slot="tooltip" {...props} />;
 }
 
-function TooltipTrigger({
-  ...props
-}: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
-  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />
+function TooltipTrigger({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
+  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />;
 }
 
 function TooltipContent({
@@ -43,7 +39,7 @@ function TooltipContent({
         sideOffset={sideOffset}
         className={cn(
           "z-50 inline-flex w-fit max-w-xs origin-(--radix-tooltip-content-transform-origin) items-center gap-1.5 rounded-md bg-foreground px-3 py-1.5 text-xs text-background has-data-[slot=kbd]:pr-1.5 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:rounded-sm data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
-          className
+          className,
         )}
         {...props}
       >
@@ -51,7 +47,7 @@ function TooltipContent({
         <TooltipPrimitive.Arrow className="z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground" />
       </TooltipPrimitive.Content>
     </TooltipPrimitive.Portal>
-  )
+  );
 }
 
-export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger }
+export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger };

package/src/gates/design.test.ts

@@ -0,0 +1,188 @@
+// @vitest-environment node
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { expect, test } from "vitest";
+
+import { competingStatusPaletteIn, statusPaletteIn } from "./index.js";
+
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+const read = (rel: string) => readFileSync(path.join(REPO, rel), "utf8");
+
+const SOURCE = /\.(?:ts|tsx|css)$/;
+
+/**
+ * Assembles a Tailwind utility fixture (e.g. "bg-emerald-500") from its
+ * prefix and family/shade at runtime. This file scans its own package (it
+ * lives under `src/`), so a fixture spelled out contiguously would trip the
+ * very gates below on itself — the same reason `HEX` and
+ * `RETIRED_ICON_PACKAGE` are built from fragments in the sibling gate files.
+ */
+const cls = (prefix: string, familyAndShade: string) => `${prefix}-${familyAndShade}`;
+
+/** Every tracked package file matching `SOURCE`. */
+function packageSources(): string[] {
+  const listed = spawnSync("git", ["ls-files", "-z", "src"], { cwd: REPO, encoding: "utf8" });
+  expect(listed.status, `git ls-files failed: ${listed.stderr}`).toBe(0);
+  return listed.stdout.split("\0").filter((name) => SOURCE.test(name));
+}
+
+const FOUNDATION_BADGE = ["success", "warning", "info", "quiet"];
+
+/** The class string of one variant line in a cva source. */
+function variantClasses(source: string, key: string): string {
+  const m = source.match(new RegExp(String.raw`^\s*"?${key}"?:\s*\n?\s*"([^"]*)"`, "m"));
+  expect(m, `no variant ${key}`).toBeTruthy();
+  return m![1];
+}
+
+const BADGE = "src/components/badge.tsx";
+
+test("Badge's status vocabulary is exactly the four owned names", () => {
+  const source = read("src/components/badge.tsx");
+  for (const name of FOUNDATION_BADGE) {
+    expect(source.includes(`${name}:`), `badge.tsx is missing the ${name} variant`).toBeTruthy();
+  }
+});
+
+test("a status Badge paints a soft surface and readable ink, never a coloured stroke", () => {
+  const src = read(BADGE);
+  const stroke = /\bborder-(?:emerald|amber|sky|success|warning|destructive|primary)\b/;
+  for (const k of [...FOUNDATION_BADGE, "destructive"]) {
+    expect(variantClasses(src, k), `${k} adds a coloured border`).not.toMatch(stroke);
+  }
+  expect(variantClasses(src, "success")).toMatch(/\bbg-emerald-500\/10\b/);
+  expect(variantClasses(src, "success")).toMatch(/\btext-emerald-700\b/);
+  expect(variantClasses(src, "warning")).toMatch(/\bbg-amber-500\/10\b/);
+  expect(variantClasses(src, "warning")).toMatch(/\btext-amber-700\b/);
+  expect(variantClasses(src, "info")).toMatch(/\bbg-sky-500\/10\b/);
+  expect(variantClasses(src, "info")).toMatch(/\btext-sky-700\b/);
+  expect(variantClasses(src, "quiet")).toMatch(/\bbg-muted\b/);
+  expect(variantClasses(src, "quiet")).toMatch(/\btext-muted-foreground\b/);
+  // Official destructive stays on the semantic token, never red-*.
+  expect(variantClasses(src, "destructive")).toMatch(/\bbg-destructive\/10\b/);
+  expect(src).not.toMatch(/\b(?:bg|text)-red-\d/);
+});
+
+test("statusPaletteIn finds the emerald/amber/sky family, and not a token or a comment", () => {
+  expect(statusPaletteIn("a.tsx", `  className="${cls("bg", "emerald-500/10")}"`)).toEqual([
+    `a.tsx:1: className="${cls("bg", "emerald-500/10")}"`,
+  ]);
+  expect(
+    statusPaletteIn(
+      "b.tsx",
+      `  className="${cls("border", "amber-400")} dark:${cls("border", "amber-300")}"`,
+    ),
+  ).toEqual([
+    `b.tsx:1: className="${cls("border", "amber-400")} dark:${cls("border", "amber-300")}"`,
+  ]);
+  expect(statusPaletteIn("c.tsx", `  className="${cls("ring", "sky-500")}"`)).toEqual([
+    `c.tsx:1: className="${cls("ring", "sky-500")}"`,
+  ]);
+  expect(statusPaletteIn("d.tsx", `  className="${cls("shadow", "emerald-500/20")}"`)).toEqual([
+    `d.tsx:1: className="${cls("shadow", "emerald-500/20")}"`,
+  ]);
+  // A token, not the palette.
+  expect(statusPaletteIn("e.tsx", `  className="bg-primary text-primary-foreground"`)).toEqual([]);
+  // The family name without a shade is not yet a colour.
+  expect(statusPaletteIn("f.tsx", `  className="bg-emerald"`)).toEqual([]);
+  // A comment recalling the palette states history, not a usage.
+  expect(
+    statusPaletteIn("g.tsx", `  // never ${cls("bg", "emerald-500")} outside statusTone`),
+  ).toEqual([]);
+});
+
+test("competingStatusPaletteIn finds a rival colour family, and not the status palette itself", () => {
+  expect(competingStatusPaletteIn("a.tsx", `  className="${cls("bg", "green-500")}"`)).toEqual([
+    `a.tsx:1: className="${cls("bg", "green-500")}"`,
+  ]);
+  expect(competingStatusPaletteIn("b.tsx", `  className="${cls("text", "yellow-700")}"`)).toEqual([
+    `b.tsx:1: className="${cls("text", "yellow-700")}"`,
+  ]);
+  expect(competingStatusPaletteIn("c.tsx", `  className="${cls("border", "blue-400")}"`)).toEqual([
+    `c.tsx:1: className="${cls("border", "blue-400")}"`,
+  ]);
+  expect(competingStatusPaletteIn("d.tsx", `  className="${cls("bg", "emerald-500")}"`)).toEqual(
+    [],
+  );
+  expect(
+    competingStatusPaletteIn("e.tsx", `  // never ${cls("bg", "red-500")} for a destructive state`),
+  ).toEqual([]);
+});
+
+test("the status palette lives in exactly Badge and statusTone, nowhere else", () => {
+  const ALLOWED_PALETTE_FILES = [
+    "src/components/badge.tsx",
+    "src/theme/statusTone.ts",
+    "src/theme/statusTone.test.ts",
+  ];
+  const tracked = packageSources();
+  expect(
+    tracked.length > 0,
+    "the scan found no package sources, so it proves nothing",
+  ).toBeTruthy();
+
+  const offenders = tracked
+    .filter((file) => !ALLOWED_PALETTE_FILES.includes(file))
+    .flatMap((file) => statusPaletteIn(file, readFileSync(path.join(REPO, file), "utf8")));
+  expect(
+    offenders,
+    "the status palette has exactly one home outside Badge and statusTone — read the tone from " +
+      `src/theme/statusTone.ts instead:\n${offenders.join("\n")}`,
+  ).toEqual([]);
+});
+
+test("no competing colour family stands in for the status palette anywhere in the package", () => {
+  const tracked = packageSources();
+  expect(
+    tracked.length > 0,
+    "the scan found no package sources, so it proves nothing",
+  ).toBeTruthy();
+
+  const offenders = tracked.flatMap((file) =>
+    competingStatusPaletteIn(file, readFileSync(path.join(REPO, file), "utf8")),
+  );
+  expect(
+    offenders,
+    `a competing colour family stands in for the status palette:\n${offenders.join("\n")}`,
+  ).toEqual([]);
+});
+
+/**
+ * Every component module is part of the public surface.
+ *
+ * `src/index.ts` lists its exports one by one rather than re-exporting a
+ * directory, which is what keeps the promise auditable — and is also what lets
+ * a finished component sit in `src/components/` for months without ever
+ * reaching a consumer. `separator.tsx` did exactly that: written, imported by
+ * `field.tsx`, never exported, and nothing noticed because every other check
+ * here reads the files rather than the surface.
+ *
+ * A module that is deliberately internal has no home in `src/components/`; move
+ * it beside its one caller instead, and this gate stops asking about it.
+ */
+test("src/index.ts exports every component module in src/components", () => {
+  const listed = spawnSync("git", ["ls-files", "-z", "src/components"], {
+    cwd: REPO,
+    encoding: "utf8",
+  });
+  expect(listed.status, `git ls-files failed: ${listed.stderr}`).toBe(0);
+
+  const modules = listed.stdout
+    .split("\0")
+    .filter((name) => name.endsWith(".tsx") && !name.includes(".test."))
+    .map((name) => path.basename(name, ".tsx"));
+  expect(
+    modules.length > 0,
+    "no component modules were found, so this proves nothing",
+  ).toBeTruthy();
+
+  const surface = read("src/index.ts");
+  const missing = modules.filter((name) => !surface.includes(`from "./components/${name}.js"`));
+  expect(
+    missing,
+    "these components exist but no consumer can import them — add an export to src/index.ts, " +
+      `or move the module next to its only caller:\n${missing.join("\n")}`,
+  ).toEqual([]);
+});

package/src/gates/index.test.ts

@@ -0,0 +1,11 @@
+// @vitest-environment node
+import { execFileSync } from "node:child_process";
+import { expect, test } from "vitest";
+
+test("foundationTokenNames resolves the stylesheet from the built package", () => {
+  const script = `import("./dist/gates/index.js").then((m) => { const n = m.foundationTokenNames(); if (!n.includes("background")) { throw new Error("missing token: " + n.join(",")); } console.log("ok"); });`;
+  const out = execFileSync(process.execPath, ["--input-type=module", "-e", script], {
+    encoding: "utf8",
+  });
+  expect(out.trim()).toBe("ok");
+});

package/src/gates/index.ts

@@ -0,0 +1,165 @@
+/**
+ * @robomous/ui-core/gates — the pure helpers and token facts that keep the
+ * design system honest, published so every consumer repo can run the same
+ * gates over its own sources with its own extensions registry.
+ *
+ * Eight exports: four scanners over one file's text, three readers for a
+ * stylesheet's blocks and declarations, and the token names read off the
+ * stylesheet that ships. DESIGN.md names the rule each one holds.
+ */
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PKG = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+const COMMENT = /^\s*(?:\/\/|\/\*|\*|#)/;
+
+// ---- status palette discipline ----
+
+/**
+ * The status palette's one Tailwind family: emerald/amber/sky, across every
+ * prefix that can carry a colour. `Badge` and `statusTone.ts` are its one
+ * home — see `statusTone.ts`'s own docstring — so a third place naming the
+ * family is a fork of the palette, not a use of it.
+ */
+const STATUS_PALETTE =
+  /\b(?:bg|text|border|ring|fill|stroke|from|to|via|outline|decoration|shadow)-(?:emerald|amber|sky)-\d/;
+
+/** Every `file:line` in `text` painting with the status palette, outside a comment. */
+export function statusPaletteIn(file: string, text: string): string[] {
+  return text
+    .split("\n")
+    .map((line, index) => ({ line, at: index + 1 }))
+    .filter(({ line }) => !COMMENT.test(line) && STATUS_PALETTE.test(line))
+    .map(({ line, at }) => `${file}:${at}: ${line.trim()}`);
+}
+
+/**
+ * A colour family that competes with the status palette for the same job —
+ * "a warning", "a success" — and so could stand in for it undetected. Unlike
+ * the palette itself these have no allowed home anywhere in a consumer.
+ */
+const COMPETING_PALETTE = /\b(?:bg|text|border)-(?:green|lime|teal|yellow|orange|blue|cyan|red)-\d/;
+
+/** Every `file:line` in `text` reaching for a colour family that competes with the status palette. */
+export function competingStatusPaletteIn(file: string, text: string): string[] {
+  return text
+    .split("\n")
+    .map((line, index) => ({ line, at: index + 1 }))
+    .filter(({ line }) => !COMMENT.test(line) && COMPETING_PALETTE.test(line))
+    .map(({ line, at }) => `${file}:${at}: ${line.trim()}`);
+}
+
+// ---- colour discipline (from tests/scripts/design_tokens.test.mjs) ----
+
+/**
+ * A Tailwind arbitrary value whose content is a colour.
+ *
+ * Assembled from fragments so this file does not match itself. The `-` before
+ * the bracket is what makes it a *utility* rather than an array index or a
+ * TypeScript tuple type.
+ */
+const HEX = ["#", "[0-9a-fA-F]{3,8}"].join("");
+const LITERAL = String.raw`(?:${HEX}|rgba?\(|hsla?\(|oklch\()`;
+// A raw colour right inside the bracket…
+const ARBITRARY_COLOUR = new RegExp(String.raw`-\[\s*(?:${LITERAL}|var\(\s*--)`);
+// The one colour-mix the preset writes mixes tokens only:
+// `color-mix(in_oklch,var(--secondary),var(--foreground)_5%)`. Any other
+// argument shape — a literal, a named colour, a bare number — is a colour.
+const TOKEN_MIX = String.raw`color-mix\(in_[a-z0-9-]+(?:,var\(--[a-z0-9-]+\)(?:_\d+(?:\.\d+)?%)?)+\)`;
+const BRACKET_MIX = new RegExp(String.raw`-\[\s*color-mix\([^\]]*\]`);
+const ALLOWED_MIX = new RegExp(String.raw`-\[\s*${TOKEN_MIX}\]`);
+
+/** Every `file:line` in `text` that puts a colour inside a Tailwind class. */
+export function colouredClassesIn(file: string, text: string): string[] {
+  return text
+    .split("\n")
+    .map((line, index) => ({ line, at: index + 1 }))
+    .filter(
+      ({ line }) =>
+        !COMMENT.test(line) &&
+        (ARBITRARY_COLOUR.test(line) || (BRACKET_MIX.test(line) && !ALLOWED_MIX.test(line))),
+    )
+    .map(({ line, at }) => `${file}:${at}: ${line.trim()}`);
+}
+
+/**
+ * `DESIGN.md` "Where the brand is": the brand is identity, not a functional-UI
+ * colour — the wordmark and the styleguide swatch that shows it off, nothing
+ * a person acts on. This is not a headcount: the gate does not exist to hold
+ * a count of sites, it exists so brand can never migrate onto a control (a
+ * button, a progress fill, anything with a function) instead of staying the
+ * one place it is allowed to just be seen. A pure function over one file's
+ * text, so the gate is provable with fabricated input, and `COMMENT` keeps
+ * the styles.css line that *states* the rule from counting as a usage of it.
+ */
+const BRAND_UTILITY = /\b(?:bg|text|border|ring|fill|stroke)-brand\b/;
+
+/** Every line in `text` that paints with the brand colour. */
+export function brandUsagesIn(
+  file: string,
+  text: string,
+): { file: string; at: number; text: string }[] {
+  return text
+    .split("\n")
+    .map((line, index) => ({ line, at: index + 1 }))
+    .filter(({ line }) => !COMMENT.test(line) && BRAND_UTILITY.test(line))
+    .map(({ line, at }) => ({ file, at, text: line.trim() }));
+}
+
+// ---- stylesheet parsing (from src/theme/tokens.test.ts, translated TS→JS) ----
+
+/** Whitespace is presentation; a value that wraps is the same value — used internally by `rawDeclarations`. */
+function normalize(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * The `{ … }` body belonging to the block whose header (e.g. `:root {` or
+ * `.dark {`) appears first in the file, matched by brace depth rather than by
+ * the next `\n}` so a nested `calc(...)` or `color-mix(...)` cannot fool it.
+ */
+export function blockBody(css: string, header: string): string {
+  const headerAt = css.indexOf(header);
+  if (headerAt === -1) throw new Error(`stylesheet has no ${JSON.stringify(header)} block`);
+  const braceAt = css.indexOf("{", headerAt);
+  let depth = 1;
+  let i = braceAt + 1;
+  while (depth > 0 && i < css.length) {
+    if (css[i] === "{") depth++;
+    else if (css[i] === "}") depth--;
+    i++;
+  }
+  return css.slice(braceAt + 1, i - 1);
+}
+
+/** Every `--name: value;` declaration in a block, keyed WITH the leading `--`. */
+export function rawDeclarations(block: string): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const match of block.matchAll(/(--[\w-]+):\s*([^;]+);/g)) {
+    map.set(match[1], normalize(match[2]));
+  }
+  return map;
+}
+
+/** The same, keyed WITHOUT the leading `--` — the shape `LIGHT_THEME` uses. */
+export function declarations(block: string): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const [name, value] of rawDeclarations(block)) {
+    map.set(name.slice(2), value);
+  }
+  return map;
+}
+
+// ---- foundation facts ----
+
+/**
+ * The foundation token names, read off the shipped stylesheet's `:root` so
+ * they can never drift from what actually runs. `radius` is a geometry
+ * setting, not a colour token, and is excluded — it matches LIGHT_THEME's keys.
+ */
+export function foundationTokenNames(): string[] {
+  const css = readFileSync(path.join(PKG, "src/theme/styles.css"), "utf8");
+  return [...declarations(blockBody(css, ":root {")).keys()].filter((n) => n !== "radius");
+}