@supertype.ai/foundations 0.1.35 → 0.1.37

package/README.md

@@ -55,7 +55,15 @@ yarn add @supertype.ai/foundations
 # or: npm install @supertype.ai/foundations
 ```
 
-Peers are React 19+, Next 15+, `next-view-transitions` 0.3+ and `@base-ui/react` 1.4+.
+Peers are **Tailwind 4+**, React 19+, Next 15+, `next-view-transitions` 0.3+ and
+`@base-ui/react` 1.4+.
+
+**Tailwind v4 is required, not preferred.** `tokens.css` declares
+`@custom-variant` and `@theme inline`, and the `@source` line below is v4-only
+syntax; on v3 they are parse errors. If you are still on v3, run
+[`npx @tailwindcss/upgrade`](https://tailwindcss.com/docs/upgrade-guide) first —
+`foundations init` will tell you so rather than writing a block your build
+cannot parse.
 
 <details>
 <summary>Installing from a git tag instead</summary>
@@ -66,28 +74,52 @@ untagged git dependency resolves to a different commit on a fresh install.
 
 ```jsonc
 // package.json
-"@supertype.ai/foundations": "https://github.com/supertypeai/foundations.git#v0.1.35"
+"@supertype.ai/foundations": "https://github.com/supertypeai/foundations.git#v0.1.37"
 ```
 
 </details>
 
-### 2. Import the CSS, in this order
+### 2. Import the CSS
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@import "@supertype.ai/foundations";
+```
+
+That one line carries `tokens.css`, `theme.css`, `type.css` and `prose.css` in
+the order the cascade needs, and registers the package&rsquo;s own `@source` so
+Tailwind scans the components it ships. There is no path for you to work out and
+no order for you to keep: Tailwind v4 resolves `@source` relative to the file
+that declares it, so the package points at its own `dist/`, correctly, wherever
+it happens to be installed.
+
+Add `@import "@supertype.ai/foundations/shiki.css";` after it only if you render
+code fences.
+
+<details>
+<summary>Importing the parts separately</summary>
+
+The granular entry points are still exported and still supported, for the app
+that paints every colour role itself and wants `tokens.css` without `theme.css`.
+Taking them means owning the order and the scan path yourself:
 
 ```css
-/* app/global.css */
+/* app/globals.css */
 @import "tailwindcss";
 @import "@supertype.ai/foundations/tokens.css"; /* structural tokens + dark variant */
 @import "@supertype.ai/foundations/theme.css"; /* the house palette */
 @import "@supertype.ai/foundations/type.css"; /* the type ramp + font roles */
 @import "@supertype.ai/foundations/prose.css"; /* inline-code rule */
-@import "@supertype.ai/foundations/shiki.css"; /* only if you render code fences */
 
 @source '../node_modules/@supertype.ai/foundations/dist/**/*.js';
 ```
 
-**The `@source` line is required.** Tailwind does not scan `node_modules` by
-default, so without it the package&rsquo;s classes get purged and the
-components render without styles.
+**The `@source` line is required in this form.** Tailwind does not scan
+`node_modules` by default, so without it the package&rsquo;s classes get purged
+and the components render without styles. The path is relative to your CSS file,
+so it changes with your layout — and in a workspace, where the package hoists to
+the repo root, `../node_modules` is not where it lives.
 
 **`theme.css` is required.** `tokens.css` names the colour roles, and
 `theme.css` gives them values. Without it, the colour utilities cannot be
@@ -97,6 +129,8 @@ for marker highlights, and the `accordion-down` and `accordion-up` keyframes.
 Skip it only if you declare every role yourself; `foundations doctor` fails if
 neither path is true.
 
+</details>
+
 ### 3. Bind the fonts
 
 The package cannot load the typefaces for you. `next/font` runs in your app and

package/bin/foundations.mjs

@@ -22,7 +22,7 @@
  * that changes in the package changes here on the next release.
  */
 import { existsSync, lstatSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
-import { dirname, join, relative, resolve, sep } from "node:path";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const PKG_NAME = "@supertype.ai/foundations";
@@ -80,11 +80,19 @@ const readJson = (file) => {
   }
 };
 
+/**
+ * Directories that never hold an app's own source: dependencies, and the build
+ * output that mirrors it. Walking from the app root rather than a list of
+ * blessed directories means these have to be named, but naming what is not
+ * source is a much shorter and much more stable list than guessing what is.
+ */
+const NOT_SOURCE = new Set(["node_modules", "dist", "build", "out", "coverage", "public", "vendor", "target"]);
+
 /** Files under `dir` with one of `exts`, depth-limited and blind to build output. */
 const walk = (dir, exts, depth = 4, out = []) => {
   if (depth < 0 || !existsSync(dir)) return out;
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+    if (entry.name.startsWith(".") || NOT_SOURCE.has(entry.name)) continue;
     const full = join(dir, entry.name);
     if (entry.isDirectory()) walk(full, exts, depth - 1, out);
     else if (exts.some((ext) => entry.name.endsWith(ext))) out.push(full);
@@ -120,15 +128,94 @@ const findAppRoot = (from) => {
   }
 };
 
+/**
+ * `name` as Node would resolve it from `dir`: the first `node_modules` on the
+ * way up that actually holds it. A workspace hoists dependencies to the repo
+ * root, so the copy an app runs against is routinely nowhere near its own
+ * package.json, and assuming otherwise is how a check ends up reporting a
+ * missing peer that is installed and an `@source` path that points at nothing.
+ */
+const resolveDep = (dir, name) => {
+  const segments = name.split("/");
+  let at = resolve(dir);
+  for (;;) {
+    const candidate = join(at, "node_modules", ...segments);
+    if (existsSync(candidate)) return candidate;
+    const up = dirname(at);
+    if (up === at) return null;
+    at = up;
+  }
+};
+
+/**
+ * The installed Tailwind's major version, or null when it is not installed yet
+ * — which is the normal case for `npx … init` run before the first install, and
+ * not something to fail on.
+ *
+ * This is read from the installed package rather than inferred from which
+ * directives the app's CSS uses, because the two questions are genuinely
+ * separate: `@tailwind utilities;` is still legal in v4, and a v3 app being
+ * upgraded passes through states where its CSS and its lockfile disagree.
+ */
+const tailwindMajor = (appRoot) => {
+  const at = resolveDep(appRoot, "tailwindcss");
+  const meta = at ? readJson(join(at, "package.json")) : null;
+  return meta ? (versionParts(meta.version)?.[0] ?? null) : null;
+};
+
+/**
+ * The dialect a stylesheet is written in, for when the installed copy cannot
+ * answer — an app running `npx … init` before its first install. v4 imports the
+ * framework; v3 uses `@tailwind base`/`components`, which v4 removed.
+ * `@tailwind utilities` is deliberately not listed: it is still legal in v4, so
+ * it is not evidence of anything.
+ */
+const dialectOf = (css) => {
+  if (/@import\s+["']tailwindcss(?:\/[\w./-]+)?["']/.test(css)) return 4;
+  if (/@tailwind\s+(?:base|components)\b/.test(css)) return 3;
+  return null;
+};
+
+/**
+ * Which Tailwind this app is on, best evidence first: the installed copy, then
+ * the dialect of its entry stylesheet. Null when neither can say, which is a
+ * normal state and not a failure — a fresh app has no CSS and no install yet.
+ */
+const tailwindOf = (appRoot, cssFile) =>
+  tailwindMajor(appRoot) ?? (cssFile ? dialectOf(stripComments(read(cssFile) ?? "")) : null);
+
+/** Everything the style layer does is v4 syntax, so this is the one way out. */
+const TAILWIND_UPGRADE =
+  "Upgrade first: `npx @tailwindcss/upgrade` — https://tailwindcss.com/docs/upgrade-guide";
+
+/** Why v4 is not negotiable, said the same way wherever it comes up. */
+const TAILWIND_WHY =
+  "tokens.css declares @custom-variant and @theme inline, and the @source line is v4-only syntax.";
+
 /* -------------------------------------------------- what the package wants */
 
 /**
- * The CSS entry points, in the order they have to be imported: tokens, then
- * theme, then type. `exports` is already in that order, which is also the order
- * the README documents.
+ * The one import that carries the whole style layer. index.css registers the
+ * package's own `@source` and imports its own files in the one order the
+ * cascade accepts, so an app taking this single line cannot get the order, the
+ * path, or the completeness wrong — there is nothing left for it to get wrong.
+ */
+const BUNDLE = PKG_NAME;
+
+/** Either spelling: the bare specifier, or the file named outright. */
+const isBundle = (spec) => spec === PKG_NAME || spec === `${PKG_NAME}/index.css`;
+
+/**
+ * The granular entry points, in the order they have to be imported: tokens,
+ * then theme, then type. `exports` is already in that order, which is also the
+ * order the README documented before the bundle existed.
+ *
+ * They remain exported, and remain supported, for the app that paints every
+ * colour role itself and wants tokens.css without theme.css. index.css is not
+ * one of them: it is the whole, not a part.
  */
 const cssEntries = Object.keys(pkgJson.exports)
-  .filter((key) => key.endsWith(".css"))
+  .filter((key) => key.endsWith(".css") && key !== "./index.css")
   .map((key) => `${PKG_NAME}/${key.slice(2)}`);
 
 /** Only needed if the app renders code fences. */
@@ -164,11 +251,47 @@ const fontVars = (() => {
 
 /* -------------------------------------------------------- consumer probing */
 
-/** The CSS file that starts the cascade, i.e. the one importing Tailwind. */
+/** What Tailwind is processed from. v4 drops the preprocessors; v3 apps use them. */
+const STYLE_EXTS = [".css", ".pcss", ".postcss", ".scss"];
+
+/**
+ * A file that starts a Tailwind cascade, in either dialect: v4 pulls the
+ * framework in with `@import` (including the layered form, where the three
+ * layers are imported separately), v3 with `@tailwind`. Both name the same
+ * file — the one the app's styles begin at — so finding it does not depend on
+ * which version is installed, and must not, or an app on the wrong version
+ * gets told it has no stylesheet at all.
+ */
+const TAILWIND_ENTRY =
+  /@import\s+["']tailwindcss(?:\/[\w./-]+)?["']|@tailwind\s+(?:base|components|utilities)\b/;
+
+/** Conventional entry names, best first. Only ever used to break a tie. */
+const ENTRY_NAMES = ["globals", "global", "index", "main", "app", "styles", "tailwind"];
+
+/**
+ * The CSS file that starts the cascade. Searched from the app root rather than
+ * a list of blessed directories, because `app/`, `src/` and `styles/` are three
+ * of the places it lives and not the only three.
+ *
+ * More than one file can import Tailwind — an embed, a Storybook preview, an
+ * email template. The real entry is the shallowest, and among equals the one
+ * named the way the scaffolds name it.
+ */
 const findCssEntry = (appRoot) => {
-  const roots = ["app", "src", "styles"].map((d) => join(appRoot, d));
-  const files = roots.flatMap((dir) => walk(dir, [".css"]));
-  return files.find((file) => /@import\s+["']tailwindcss["']/.test(read(file) ?? "")) ?? null;
+  const candidates = walk(appRoot, STYLE_EXTS, 6).filter((file) =>
+    TAILWIND_ENTRY.test(stripComments(read(file) ?? "")),
+  );
+  const rank = (file) => {
+    const rel = relative(appRoot, file);
+    const at = ENTRY_NAMES.indexOf(basename(rel).replace(/\.[^.]+$/, ""));
+    return [rel.split(sep).length, at === -1 ? ENTRY_NAMES.length : at, rel];
+  };
+  return (
+    candidates
+      .map((file) => [rank(file), file])
+      .sort(([a], [b]) => (a[0] - b[0]) || (a[1] - b[1]) || (a[2] < b[2] ? -1 : 1))
+      .map(([, file]) => file)[0] ?? null
+  );
 };
 
 const LAYOUTS = ["app/layout.tsx", "src/app/layout.tsx", "app/layout.jsx", "src/app/layout.jsx"];
@@ -213,6 +336,13 @@ const stripComments = (css) => {
 /** `@import` targets in source order, so one parse gives presence and ordering. */
 const importsOf = (css) => [...css.matchAll(/@import\s+["']([^"']+)["']/g)].map((m) => m[1]);
 
+/**
+ * An import of the framework itself. v4's layered form names three files rather
+ * than one, and the block has to land after the last of them, so anywhere the
+ * code asks "is this Tailwind coming in here" has to accept both spellings.
+ */
+const isTailwindImport = (spec) => spec === "tailwindcss" || spec.startsWith("tailwindcss/");
+
 const sourceDirectives = (css) => [...css.matchAll(/@source\s+["']([^"']+)["']/g)].map((m) => m[1]);
 
 /** Consts assigned from a next/font call, so we can check how they are used. */
@@ -234,7 +364,11 @@ const fontConsts = (src) => {
 
 /** The @source line for this app, relative to the CSS file wherever yarn put us. */
 const sourceGlob = (appRoot, cssFile) => {
-  const installed = join(appRoot, "node_modules", ...PKG_NAME.split("/"));
+  // Where it actually is, which in a workspace is the repo root rather than
+  // this app. The conventional path is the fallback for an app that has not
+  // installed the package yet, where there is nothing to resolve.
+  const installed =
+    resolveDep(appRoot, PKG_NAME) ?? join(appRoot, "node_modules", ...PKG_NAME.split("/"));
   let path = relative(dirname(cssFile), join(installed, "dist"));
   path = path.split(sep).join("/");
   if (!path.startsWith(".")) path = `./${path}`;
@@ -255,7 +389,7 @@ const isGitSpec = (spec) =>
 const checkInstall = (appRoot) => {
   const out = [];
   const appPkg = readJson(join(appRoot, "package.json"));
-  const installed = join(appRoot, "node_modules", ...PKG_NAME.split("/"));
+  const installed = resolveDep(appRoot, PKG_NAME);
 
   const spec = appPkg?.dependencies?.[PKG_NAME] ?? appPkg?.devDependencies?.[PKG_NAME] ?? null;
 
@@ -298,7 +432,7 @@ const checkInstall = (appRoot) => {
     }
   }
 
-  if (existsSync(installed)) {
+  if (installed) {
     if (lstatSync(installed).isSymbolicLink()) {
       out.push(
         finding(
@@ -328,7 +462,8 @@ const checkInstall = (appRoot) => {
 
   for (const [peer, range] of Object.entries(pkgJson.peerDependencies ?? {})) {
     const soft = peer === "@base-ui/react"; // Only Accordion and Tabs need it.
-    const meta = readJson(join(appRoot, "node_modules", ...peer.split("/"), "package.json"));
+    const at = resolveDep(appRoot, peer);
+    const meta = at ? readJson(join(at, "package.json")) : null;
     if (!meta) {
       out.push(
         finding(
@@ -345,25 +480,80 @@ const checkInstall = (appRoot) => {
   return out;
 };
 
-const checkStyles = (appRoot) => {
+const checkStyles = (appRoot, major) => {
   const out = [];
   const cssFile = findCssEntry(appRoot);
   if (!cssFile) {
     out.push(
-      finding("error", "no CSS entry importing tailwindcss", "looked under app/, src/, styles/", "Create one (app/global.css), then run `foundations init`."),
+      finding(
+        "error",
+        "no CSS entry importing Tailwind",
+        `looked for a ${STYLE_EXTS.join(", ")} file under ${appRoot}`,
+        "Create one (app/globals.css), then run `foundations init`.",
+      ),
     );
     return out;
   }
 
   const css = stripComments(read(cssFile) ?? "");
   const rel = relative(appRoot, cssFile);
+
+  // Every check below reads a v4 cascade. Running them against a v3 stylesheet
+  // reports four separate failures that are all one cause, and buries it.
+  if (major !== null && major < 4) {
+    out.push(
+      finding(
+        "error",
+        `${rel} is a Tailwind v${major} stylesheet, and the package needs v4`,
+        TAILWIND_WHY,
+        TAILWIND_UPGRADE,
+      ),
+    );
+    return out;
+  }
   const order = importsOf(css);
+  const tailwindAt = order.reduce((at, spec, i) => (isTailwindImport(spec) ? i : at), -1);
+
+  // Applies to either shape, so it is asked before they diverge.
+  if (/@custom-variant\s+dark/.test(css)) {
+    out.push(
+      finding(
+        "warn",
+        "this app declares its own dark variant",
+        rel,
+        "tokens.css already binds dark: to the .dark class. With two declarations the later one wins, and nothing tells you which.",
+      ),
+    );
+  }
+
+  // The bundle carries the @source line and fixes the order inside the package,
+  // so the only thing an app can still get wrong is putting it before Tailwind.
+  const bundleAt = order.findIndex(isBundle);
+  if (bundleAt !== -1) {
+    out.push(
+      bundleAt < tailwindAt
+        ? finding(
+            "error",
+            `${BUNDLE} is imported before Tailwind`,
+            rel,
+            "It re-points variables Tailwind defines, so it has to come after.",
+          )
+        : finding("ok", "the style layer is complete", `${rel} → ${BUNDLE}`),
+    );
+    if (!order.some((spec) => OPTIONAL_CSS.has(spec))) {
+      out.push(
+        finding("info", `${[...OPTIONAL_CSS][0]} is not imported`, "only needed if you render code fences", "Add it when you add Shiki."),
+      );
+    }
+    return out;
+  }
+
   const seen = new Map(order.map((spec, i) => [spec, i]));
 
   const missing = [];
   /** Set when theme.css is absent but the app declares every role itself. */
   let selfPainted = false;
-  let last = seen.get("tailwindcss") ?? -1;
+  let last = tailwindAt;
   for (const entry of cssEntries) {
     const at = seen.get(entry);
     if (at === undefined) {
@@ -423,17 +613,6 @@ const checkStyles = (appRoot) => {
     out.push(finding("ok", "@source scans the package", ours));
   }
 
-  if (/@custom-variant\s+dark/.test(css)) {
-    out.push(
-      finding(
-        "warn",
-        "this app declares its own dark variant",
-        rel,
-        "tokens.css already binds dark: to the .dark class. With two declarations the later one wins, and nothing tells you which.",
-      ),
-    );
-  }
-
   const required = missing.filter(
     (entry) => !OPTIONAL_CSS.has(entry) && !(entry === PALETTE_CSS && selfPainted),
   );
@@ -500,8 +679,16 @@ const expandImports = (file, { includePackage }, seen = new Set()) => {
   if (seen.has(file)) return "";
   seen.add(file);
   return (read(file) ?? "").replace(/@import\s+["']([^"']+)["'];?/g, (_line, spec) => {
-    if (spec.startsWith(`${PKG_NAME}/`))
-      return includePackage ? (read(join(pkgRoot, "src", spec.slice(PKG_NAME.length + 1))) ?? "") : "";
+    // The bundle is ours too, and it pulls the rest in relatively — so it has to
+    // be followed rather than read. Reading it would yield four @import lines
+    // and no palette, and every role would measure as unpainted.
+    const ours = isBundle(spec)
+      ? "index.css"
+      : spec.startsWith(`${PKG_NAME}/`)
+        ? spec.slice(PKG_NAME.length + 1)
+        : null;
+    if (ours !== null)
+      return includePackage ? expandImports(join(pkgRoot, "src", ours), { includePackage }, seen) : "";
     if (spec.startsWith(".")) return expandImports(resolve(dirname(file), spec), { includePackage }, seen);
     return "";
   });
@@ -561,10 +748,14 @@ const serif = Average({ variable: "--font-average", weight: "400", subsets: ["la
 <html className={\`\${sans.variable} \${mono.variable} \${serif.variable} font-sans\`}>`;
 
 const doctor = async (appRoot) => {
+  // Asked once, because it decides what the rest of the report can mean.
+  const major = tailwindOf(appRoot, findCssEntry(appRoot));
   const install = checkInstall(appRoot);
-  const styles = checkStyles(appRoot);
+  const styles = checkStyles(appRoot, major);
   const fonts = checkFonts(appRoot);
-  const contrast = await checkContrast(appRoot);
+  // On v3 the cascade never assembles, so measuring the colours it did not
+  // produce would fill the report with failures that all have one cause.
+  const contrast = major !== null && major < 4 ? [] : await checkContrast(appRoot);
   const all = [...install, ...styles, ...fonts, ...contrast];
 
   console.log(`\n${bold(PKG_NAME)} ${dim(`doctor · ${appRoot}`)}`);
@@ -588,12 +779,27 @@ const doctor = async (appRoot) => {
 
 const init = (appRoot, { dryRun }) => {
   const cssFile = findCssEntry(appRoot);
+  const major = tailwindOf(appRoot, cssFile);
+
+  // Patching a v3 stylesheet would trade a working build for a pile of parse
+  // errors, so this stops at the diagnosis instead. Nothing is written.
+  if (major !== null && major < 4) {
+    console.log(`\n${paint(31, "✖")} this app is on ${bold(`Tailwind v${major}`)}, and the package needs v4.`);
+    if (cssFile) console.log(`  ${dim(`${relative(appRoot, cssFile)} is the entry, and it is in the v3 dialect.`)}`);
+    console.log(`  ${dim(TAILWIND_WHY)} ${dim("On v3 they are parse errors.")}`);
+    console.log(`\n  ${dim("→")} ${TAILWIND_UPGRADE}`);
+    console.log(`\nThen run ${bold("foundations init")} again.\n`);
+    return 1;
+  }
+
   if (!cssFile) {
-    console.log(`\nNo CSS entry importing tailwindcss under ${appRoot}.`);
-    console.log("Create app/global.css with:\n");
-    console.log(
-      ['@import "tailwindcss";', ...cssEntries.map((e) => `@import "${e}";`), "", `@source '../node_modules/${PKG_NAME}/dist/**/*.js';`].join("\n"),
-    );
+    // Named where the scaffolds actually put it, so the instruction matches the
+    // file the reader is about to create.
+    const target = existsSync(join(appRoot, "src/app")) ? "src/app/globals.css" : "app/globals.css";
+    console.log(`\nNo CSS entry importing Tailwind under ${appRoot}.`);
+    console.log(dim(`Looked for a ${STYLE_EXTS.join(", ")} file that imports it.`));
+    console.log(`\nCreate ${bold(target)} with:\n`);
+    console.log(`@import "tailwindcss";\n@import "${BUNDLE}";`);
     console.log();
     return 1;
   }
@@ -602,13 +808,52 @@ const init = (appRoot, { dryRun }) => {
   const live = stripComments(before);
   const rel = relative(appRoot, cssFile);
   const lines = before.split("\n");
+  const present = new Set(importsOf(live));
 
-  // Lift the package's own @import lines out, then lay them back down in the
-  // one order the cascade accepts. Lifting the whole LINE keeps a trailing
-  // comment attached to the import a consumer wrote it against, and makes a
-  // file that is merely out of order repairable rather than only diagnosable.
+  /** After Tailwind itself: everything the package ships re-points its variables. */
+  const anchorIn = (from) =>
+    from.reduce((at, line, i) => (importsOf(stripComments(line)).some(isTailwindImport) ? i : at), -1);
+
+  if ([...present].some(isBundle)) {
+    console.log(`\n${rel} already imports the style layer.`);
+  } else if (!cssEntries.some((entry) => present.has(entry))) {
+    // Nothing of ours in the file yet, so it gets the single import. There is
+    // no order to arrange and no @source to compute: the package does both.
+    const line = `@import "${BUNDLE}";`;
+    lines.splice(anchorIn(lines) + 1, 0, line);
+    if (dryRun) {
+      console.log(`\n${bold(rel)} ${dim("(dry run — nothing written)")}`);
+    } else {
+      writeFileSync(cssFile, lines.join("\n"));
+      console.log(`\n${paint(32, "✔")} patched ${bold(rel)}`);
+    }
+    console.log(`  ${paint(32, "+")} ${line}`);
+  } else {
+    legacy(appRoot, cssFile, { before, live, rel, lines, present, anchorIn, dryRun });
+  }
+
+  console.log(`\n${bold("Bind the fonts")} in your root layout. The package cannot load them for you:\n`);
+  console.log(fontSnippet());
+  console.log(`\n${bold("If you use a coding agent")}, point it at the API summary:\n`);
+  console.log(`  ${dim("# CLAUDE.md, AGENTS.md, or your agent's equivalent")}`);
+  console.log(`  @node_modules/${PKG_NAME}/llms.txt`);
+  console.log(`\nThen: ${bold("foundations doctor")}\n`);
+  return 0;
+};
+
+/**
+ * The old shape: the four entry points written out by the consumer, plus an
+ * `@source` line it had to path itself. Still supported, and still repaired —
+ * an app on it is not broken, and rewriting a file someone else wrote is not
+ * this command's call. `init` only offers the one-line form.
+ *
+ * Lift the package's own @import lines out, then lay them back down in the
+ * one order the cascade accepts. Lifting the whole LINE keeps a trailing
+ * comment attached to the import a consumer wrote it against, and makes a file
+ * that is merely out of order repairable rather than only diagnosable.
+ */
+const legacy = (appRoot, cssFile, { live, rel, lines, present, anchorIn, dryRun }) => {
   const existing = new Map();
-  const present = new Set(importsOf(live));
   const kept = lines.filter((line) => {
     const [spec] = importsOf(stripComments(line));
     // `present` keeps a commented-out import where it is instead of reviving it.
@@ -635,9 +880,7 @@ const init = (appRoot, { dryRun }) => {
   if (!added.length && !reordered && !needsSource) {
     console.log(`\n${rel} already imports the style layer, in order, and scans the package.`);
   } else {
-    // After Tailwind itself: the tokens re-point variables it defines.
-    const anchor = kept.reduce((at, line, i) => (/@import\s+["']tailwindcss["']/.test(line) ? i : at), -1);
-    kept.splice(anchor + 1, 0, ...block);
+    kept.splice(anchorIn(kept) + 1, 0, ...block);
 
     if (dryRun) {
       console.log(`\n${bold(rel)} ${dim("(dry run — nothing written)")}`);
@@ -652,18 +895,9 @@ const init = (appRoot, { dryRun }) => {
     if (reordered) console.log(`  ${dim("reordered: later files re-point variables the earlier ones define")}`);
   }
 
-  console.log(`\n${bold("Bind the fonts")} in your root layout. The package cannot load them for you:\n`);
-  console.log(fontSnippet());
-
-  // The package ships an llms.txt for whatever coding agent the app runs. It is
-  // only useful if the agent is pointed at it, and that is one line in a file
-  // this command should not edit on its own.
-  console.log(`\n${bold("If you use a coding agent")}, point it at the API summary:\n`);
-  console.log(`  ${dim("# CLAUDE.md, AGENTS.md, or your agent's equivalent")}`);
-  console.log(`  @node_modules/${PKG_NAME}/llms.txt`);
-
-  console.log(`\nThen: ${bold("foundations doctor")}\n`);
-  return 0;
+  console.log(
+    `\n${dim(`These ${cssEntries.filter((e) => !OPTIONAL_CSS.has(e)).length} lines and the @source can now be one: @import "${BUNDLE}";`)}`,
+  );
 };
 
 const usage = () => {
@@ -682,7 +916,9 @@ Options
 /* ------------------------------------------------------------------- entry */
 
 const args = process.argv.slice(2);
-const command = args.find((a) => !a.startsWith("--")) ?? "help";
+/** Flags that take a value, so the value is not mistaken for the command. */
+const VALUED = new Set(["--cwd"]);
+const command = args.find((a, i) => !a.startsWith("--") && !VALUED.has(args[i - 1])) ?? "help";
 const flag = (name) => args.includes(`--${name}`);
 const value = (name) => {
   const at = args.indexOf(`--${name}`);

package/dist/optical.d.ts

@@ -0,0 +1,73 @@
+/**
+ * How far a centred mark misses the letters, per rung of a type ramp.
+ *
+ * `items-center` centres boxes, and the box is the line box: leading, ascent and
+ * descent, only some of which the letters use. The mark beside a label therefore
+ * centres on the font's box rather than on the band of ink a reader sees, and
+ * whether those two agree is a property of the font, not of the design.
+ *
+ * The whole tool is one line of arithmetic, and the rounding is the reason it is
+ * worth shipping. Ratios alone give one constant tilt for a face, 0.0235em for
+ * Ubuntu Sans, which reads as every rung being equally out. Browsers quantise
+ * ascent, descent and cap height to whole pixels before they lay a line out, and
+ * rounded, that same face is half a pixel out at 11px, flat at 13px and half a
+ * pixel out again at 22px. The rendered pages agree, so the rounding is what
+ * separates a rung that needs the trim from one where it buys nothing.
+ *
+ * Build-time only, and only as good as the metrics handed to it. Verify cap
+ * height against the browser rather than a table: `next/font` ships 693 for
+ * Ubuntu Sans where canvas measures 727, and the wrong one flips the answer at
+ * every rung.
+ */
+/** A font's vertical metrics, in font units. The four numbers every metrics
+ *  table carries, `next/font`'s and capsize's alike. */
+export interface FontMetrics {
+    unitsPerEm: number;
+    ascent: number;
+    descent: number;
+    capHeight: number;
+}
+/** One step of a ramp: the name an app knows it by, and its size in px. */
+export interface TypeRung {
+    name: string;
+    fontSize: number;
+}
+export interface OpticalOffset extends TypeRung {
+    /** How far below the cap band's centre a centred mark sits, in px. Positive is
+     *  low, which is the direction rounding takes it. */
+    offset: number;
+    /** The same miss against the height of the letters it misses. Half a pixel is
+     *  a twelfth of an 11px cap band and a thirty-second of a 36px one, so this is
+     *  the number that says whether a reader sees it. */
+    share: number;
+    /** The rounded metrics the offset came out of, for a message worth reading. */
+    used: {
+        ascent: number;
+        descent: number;
+        capHeight: number;
+    };
+}
+/**
+ * The gap between the line box's centre and the cap band's, at one size.
+ *
+ * Half-leading cancels, so line height does not appear: a rung that is out stays
+ * out however loosely it is set, and no retune of the ramp's leading fixes it.
+ * Paint rounds the baseline a second time, in the same direction, so treat this
+ * as the floor of the error rather than the whole of it.
+ */
+export declare function capBandOffset(metrics: FontMetrics, fontSize: number): number;
+/**
+ * Every rung whose centred mark misses the letters by enough to see, worst first.
+ *
+ * A rung that comes back is one where an icon, a badge or a swatch set beside the
+ * text with `items-center` wants `CAP_TRIM` on the text to land on it. Most rungs
+ * of a ramp are half a pixel out, so the pixel is not the question: `tolerance` is
+ * a share of the cap band, and 0.05 is where a miss stops reading as a rounding
+ * artefact and starts reading as two things that do not line up. Raise it for a
+ * surface that only sets headlines, lower it to see the whole ramp.
+ */
+export declare function checkOptical(metrics: FontMetrics, rungs: readonly TypeRung[], { tolerance }?: {
+    tolerance?: number;
+}): OpticalOffset[];
+/** The failures as lines, on the model of `formatFailures` in contrast.ts. */
+export declare function formatOffsets(offsets: readonly OpticalOffset[]): string;

package/dist/optical.js

@@ -0,0 +1,68 @@
+/**
+ * How far a centred mark misses the letters, per rung of a type ramp.
+ *
+ * `items-center` centres boxes, and the box is the line box: leading, ascent and
+ * descent, only some of which the letters use. The mark beside a label therefore
+ * centres on the font's box rather than on the band of ink a reader sees, and
+ * whether those two agree is a property of the font, not of the design.
+ *
+ * The whole tool is one line of arithmetic, and the rounding is the reason it is
+ * worth shipping. Ratios alone give one constant tilt for a face, 0.0235em for
+ * Ubuntu Sans, which reads as every rung being equally out. Browsers quantise
+ * ascent, descent and cap height to whole pixels before they lay a line out, and
+ * rounded, that same face is half a pixel out at 11px, flat at 13px and half a
+ * pixel out again at 22px. The rendered pages agree, so the rounding is what
+ * separates a rung that needs the trim from one where it buys nothing.
+ *
+ * Build-time only, and only as good as the metrics handed to it. Verify cap
+ * height against the browser rather than a table: `next/font` ships 693 for
+ * Ubuntu Sans where canvas measures 727, and the wrong one flips the answer at
+ * every rung.
+ */
+const px = (value, fontSize, unitsPerEm) => Math.round((value * fontSize) / unitsPerEm);
+/**
+ * The gap between the line box's centre and the cap band's, at one size.
+ *
+ * Half-leading cancels, so line height does not appear: a rung that is out stays
+ * out however loosely it is set, and no retune of the ramp's leading fixes it.
+ * Paint rounds the baseline a second time, in the same direction, so treat this
+ * as the floor of the error rather than the whole of it.
+ */
+export function capBandOffset(metrics, fontSize) {
+    const ascent = px(metrics.ascent, fontSize, metrics.unitsPerEm);
+    const descent = px(metrics.descent, fontSize, metrics.unitsPerEm);
+    const capHeight = px(metrics.capHeight, fontSize, metrics.unitsPerEm);
+    return capHeight / 2 - (ascent - descent) / 2;
+}
+/**
+ * Every rung whose centred mark misses the letters by enough to see, worst first.
+ *
+ * A rung that comes back is one where an icon, a badge or a swatch set beside the
+ * text with `items-center` wants `CAP_TRIM` on the text to land on it. Most rungs
+ * of a ramp are half a pixel out, so the pixel is not the question: `tolerance` is
+ * a share of the cap band, and 0.05 is where a miss stops reading as a rounding
+ * artefact and starts reading as two things that do not line up. Raise it for a
+ * surface that only sets headlines, lower it to see the whole ramp.
+ */
+export function checkOptical(metrics, rungs, { tolerance = 0.05 } = {}) {
+    return rungs
+        .map((rung) => {
+        const used = {
+            ascent: px(metrics.ascent, rung.fontSize, metrics.unitsPerEm),
+            descent: px(metrics.descent, rung.fontSize, metrics.unitsPerEm),
+            capHeight: px(metrics.capHeight, rung.fontSize, metrics.unitsPerEm),
+        };
+        const offset = used.capHeight / 2 - (used.ascent - used.descent) / 2;
+        return { ...rung, offset, share: Math.abs(offset) / used.capHeight, used };
+    })
+        .filter((rung) => rung.share > tolerance)
+        .sort((a, b) => b.share - a.share);
+}
+/** The failures as lines, on the model of `formatFailures` in contrast.ts. */
+export function formatOffsets(offsets) {
+    return offsets
+        .map(({ name, fontSize, offset, used }) => `  ${name} (${fontSize}px)  mark sits ${Math.abs(offset)}px ${offset > 0 ? "below" : "above"} the cap band` +
+        `, ${Math.round((Math.abs(offset) / used.capHeight) * 100)}% of it` +
+        `  [ascent ${used.ascent}, descent ${used.descent}, cap ${used.capHeight}]`)
+        .join("\n");
+}

package/dist/typography/index.d.ts

@@ -2,3 +2,4 @@ export type { TypographyTag } from "./as.js";
 export * from "./header.js";
 export * from "./paragraph.js";
 export * from "./highlight.js";
+export * from "./trim.js";

package/dist/typography/index.js

@@ -1,3 +1,4 @@
 export * from "./header.js";
 export * from "./paragraph.js";
 export * from "./highlight.js";
+export * from "./trim.js";

package/dist/typography/trim.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The optical box: cap top to baseline, with the leading either side removed.
+ *
+ * A line box reserves room for the ascenders and descenders a string may not
+ * use, so `items-center` beside an icon centres that reservation rather than
+ * the letters. On an 11px uppercase label the mark next to it renders about a
+ * pixel low, which is a whole device pixel against an eight pixel cap band.
+ * Trimming makes the element as tall as its own ink, so the row centres what
+ * the reader actually sees.
+ *
+ * Two things follow. It goes on the text element, since `text-box` is not
+ * inherited and a row cannot hand it down. And it shortens that element, so a
+ * row of trimmed text needs a height floor of its own: without one, the card
+ * whose label carries no mark sits shorter than the three beside it and its
+ * figure rides high. Chrome and Safari trim, and a browser that does not know
+ * `text-box` keeps the untrimmed box, which is the behaviour of every consumer
+ * today.
+ *
+ * Never on a string that also clips. The bottom edge is the baseline, so
+ * descenders sit outside the box, and `truncate` or any other overflow hidden
+ * cuts the tails off every g and p in it.
+ *
+ * Uppercase is where it pays. A cap band fills half of an 11px line box and the
+ * mark beside it lands a whole device pixel low, where 13px mixed case measures
+ * the same trimmed or not: ascenders reach the top of the line box on their own,
+ * so there is little leading left to take.
+ */
+export declare const CAP_TRIM = "[text-box:trim-both_cap_alphabetic]";

package/dist/typography/trim.js

@@ -0,0 +1,28 @@
+/**
+ * The optical box: cap top to baseline, with the leading either side removed.
+ *
+ * A line box reserves room for the ascenders and descenders a string may not
+ * use, so `items-center` beside an icon centres that reservation rather than
+ * the letters. On an 11px uppercase label the mark next to it renders about a
+ * pixel low, which is a whole device pixel against an eight pixel cap band.
+ * Trimming makes the element as tall as its own ink, so the row centres what
+ * the reader actually sees.
+ *
+ * Two things follow. It goes on the text element, since `text-box` is not
+ * inherited and a row cannot hand it down. And it shortens that element, so a
+ * row of trimmed text needs a height floor of its own: without one, the card
+ * whose label carries no mark sits shorter than the three beside it and its
+ * figure rides high. Chrome and Safari trim, and a browser that does not know
+ * `text-box` keeps the untrimmed box, which is the behaviour of every consumer
+ * today.
+ *
+ * Never on a string that also clips. The bottom edge is the baseline, so
+ * descenders sit outside the box, and `truncate` or any other overflow hidden
+ * cuts the tails off every g and p in it.
+ *
+ * Uppercase is where it pays. A cap band fills half of an 11px line box and the
+ * mark beside it lands a whole device pixel low, where 13px mixed case measures
+ * the same trimmed or not: ascenders reach the top of the line box on their own,
+ * so there is little leading left to take.
+ */
+export const CAP_TRIM = "[text-box:trim-both_cap_alphabetic]";

package/llms.txt

@@ -67,6 +67,7 @@ silently. Full reference: https://github.com/supertypeai/foundations
 | an article whose body is prose or MDX | `EssayHeader` + `ReadingLayout` | `/essay` |
 | a post meta row (date, read time, tags) | `PostMetaRow` and friends | `/essay` |
 | a table of contents | `TableOfContents`, `ReadingRail` | `/essay` |
+| where a centred mark lands on a rung | `checkOptical` | `/optical` |
 | page metadata and JSON-LD | `createSeo` | `/seo` |
 | an OG image | `ogCard`, `OG_SIZE` | `/og` |
 | to merge classnames | `cn` | root |
@@ -75,13 +76,14 @@ silently. Full reference: https://github.com/supertypeai/foundations
 
 | import | exports |
 |---|---|
-| `@supertype.ai/foundations` | `cn`, `TypographyH1`, `TypographyH2`, `TypographyH3`, `TypographyH4`, `TypographyEyebrow`, `TypographyP`, `TypographyMuted`, `TypographyProse`, `TypographyList`, `TypographyProseList`, `TypographyCaption`, `TypographySmall`, `TypographyLabel`, `TypographyStat`, `TypographyInlineCode`, `TypographyLink`, `TypographyHighlight`, `headingClass`, `headingFace`, `eyebrowClass`, `toneClass`, `impliedTone`, `resolveLink`, `isExternalHref`. Types: `TypographyTag`, `ParagraphVariants`, `ListProps`, `CaptionVariants`, `LabelVariants`, `StatVariants`, `Tone`, `HighlightTone`, `LinkBehavior`, `ResolvedLink` |
+| `@supertype.ai/foundations` | `cn`, `TypographyH1`, `TypographyH2`, `TypographyH3`, `TypographyH4`, `TypographyEyebrow`, `TypographyP`, `TypographyMuted`, `TypographyProse`, `TypographyList`, `TypographyProseList`, `TypographyCaption`, `TypographySmall`, `TypographyLabel`, `TypographyStat`, `TypographyInlineCode`, `TypographyLink`, `TypographyHighlight`, `headingClass`, `headingFace`, `eyebrowClass`, `toneClass`, `impliedTone`, `resolveLink`, `isExternalHref`, `CAP_TRIM`. Types: `TypographyTag`, `ParagraphVariants`, `ListProps`, `CaptionVariants`, `LabelVariants`, `StatVariants`, `Tone`, `HighlightTone`, `LinkBehavior`, `ResolvedLink` |
 | `@supertype.ai/foundations/blocks` | `Anchor`, `Cards`, `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `Callout`, `Button`, `buttonVariants`, `Badge`, `badgeVariants`, `Steps`, `Step`, `Disclosure`, `DisclosureGroup`, `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`, `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`, `TabGroup`, `SEGMENT`, `Bulletin`, `Ribbon`, `EDITORIAL_INKS`, `Colophon`, `BuiltWithFoundations`, `FoundationsMark`, `FOUNDATIONS_URL`. Types: `ButtonLook`, `BadgeLook`, `TabItem`, `BulletinProps`, `BulletinPoint`, `RibbonHue`, `ColophonProps` |
 | `@supertype.ai/foundations/mdx` | `proseMdxComponents` |
 | `@supertype.ai/foundations/essay` | `createEssay`, `EssayHeader`, `EssayLayout`, `EssaySection`, `EssayPullQuote`, `EssayFigure`, `EssayMovements`, `EssayDocument`, `EssayColumns`, `EssayAside`, `EssayBody`, `ReadingLayout`, `TableOfContents`, `ReadingRail`, `ReadingProgressBar`, `Rail`, `RailLink`, `PostMetaRow`, `PostDate`, `ReadTime`, `TagPills`, `MetaDot`, `formatPostDate`, `extractHeadings`, `readingTime`, `createSlugger`, `useReadingProgress`, `useScrollSpy`. Types: `TocHeading`, `EssayDecorations`, `EssayIndexEntry`, `EssayDocSection`, `EssayMovement`, `PostDateFormat` |
 | `@supertype.ai/foundations/seo` | `createSeo`. Types: `SeoConfig`, `ArticleAuthor`, `ArticleOptions`, `PageMetadata` |
 | `@supertype.ai/foundations/og` | `ogCard`, `OG_SIZE`. Types: `OgCardOptions` |
 | `@supertype.ai/foundations/eslint` | `designRules` (every rule as one array, the one to spread), `designConfig` (the same set wrapped as a flat-config entry). The builders `colourRules`, `typographyRules`, `linkRules`, `themeOverrideRules`, `surfaceAsInkRules`, `renamedTokenRules` are exported too, though spreading them by hand is how a consumer ends up missing one. Types: `FlatConfigEntry`, `DesignRuleOptions`, `DesignConfigOptions`, `RestrictedSyntax`, `ColourOptions`, `TypographyOptions` |
+| `@supertype.ai/foundations/optical` | `capBandOffset` (the gap between a line box's centre and its cap band's, at one size), `checkOptical` (every rung of a ramp whose centred mark misses the letters, worst first), `formatOffsets`. Types: `FontMetrics`, `TypeRung`, `OpticalOffset`. Build-time only |
 | `@supertype.ai/foundations/rehype` | `rehypeProseCode`, `proseCodeOptions`, `PROSE_LANGS`, `PROSE_THEMES`. Build-time only, must not resolve React |
 | `@supertype.ai/foundations/contrast` | `checkLegibility` (inks at 4.5:1), `checkSignals` (fills at 3:1 — status hues, the categorical earth hues and the six chart series alike — tinted inks at 4.5:1, `--subtle-foreground` at the 3:1 it is documented for, labels against their own fill: the tone rows are read off `TONE` and each cut is resolved along its `var()` fallback chain, so an app that declares `--brand` without `--brand-foreground` is measured on the label the cascade really reaches for rather than skipped), `checkHairlines` (`--border` and `--input` at 1.4:1 on `--background` and `--card`, `--sidebar-border` on `--sidebar`: a rule is exempt from the ink and mark bars, but it still has to read as the same weight in both themes), `resolveTokens`, `formatFailures`, `specificity`, `parseColor`, `luminance`, `contrast` (WCAG ratio), `lc` (APCA lightness contrast: polarity-aware, for checking that an ink ramp is perceptually ordered rather than merely ordered by ratio), `tokenCuts` (which cuts a token ships: fill, the label printed on it, the hue as words, the taxonomy `checkSignals` measures against). Types: `Rgb`, `Theme`, `LegibilityFailure`, `TokenCuts`. Build-time only |
 
@@ -103,6 +105,16 @@ silently. Full reference: https://github.com/supertypeai/foundations
   trigger. It exists so `target`/`rel` are never written at a call site; `external`
   is for a same-origin path that is not a route, which the router would prefetch.
 - `Tone` is the one semantic colour vocabulary, shared by `Button`, `Badge`, `Callout`, `TypographyLink` and `TabsList`: `"muted" | "primary" | "secondary" | "brand" | "success" | "warn" | "destructive"`, defaulting to `muted` everywhere except a solid `Button`. Seven tones, seven tokens, one to one, which is the bar for adding one. Four names map onto others: `neutral` and `foreground` are `muted`, the word the rest of the package uses; `accent` is `--primary`'s hover tint, so a washed `primary` renders the same thing; `info` is covered by the `success | warn | destructive` triad. `brand` falls back to `--primary` in an app that defines no `--brand`.
+- **`CAP_TRIM` centres a mark on the letters.** `items-center` centres line
+  boxes, and a line box reserves room for ascenders and descenders the string may
+  not use, so an (i) or a badge beside an uppercase micro-label renders about a
+  pixel low. Put `CAP_TRIM` on the text element, never on the row, because
+  `text-box` is not inherited. It shortens the element, so give the row a height
+  floor from whatever sits beside it: a trimmed label with no mark next to it
+  makes a shorter row than its neighbours and the figure under it rides high.
+  Never put it on a string that clips: the box ends at the baseline, so `truncate`
+  cuts the tail off every descender. Which rungs need it is computed rather than
+  eyeballed: `checkOptical` from `/optical` reads a face's metrics and names them.
 - **Ink is handed down by whatever paints.** `toneClass(tone)` is a palette and sets no ink. A surface that fills adds `INK_ON_FILL`; a tinted one adds `INK_ON_CARD`, `INK_ON_POPOVER` or `INK_ON_SIDEBAR`, and one the package does not name spreads `inkOnSurfaceStyle(token)` into `style` rather than building a class. Both declare `--ink` and `--ink-muted`, which every type primitive reads, falling back to the page. Paint a background without them and a nested `TypographyLabel` prints `--foreground` on your fill, which measures 2.34:1 on `--primary`. On a hue fill `--ink-muted` equals `--ink`: a filled control has one ink, and wanting a second rung means wanting a tinted surface.
 - `Button`: `variant?: "solid" | "soft" | "outline" | "ghost" | "link"` (default `solid`), `tone?: Tone` (defaults to `primary` on a solid button and `muted` on every other variant — filling a button in is how a page says this is the action), `size?: "xs" | "sm" | "md" | "lg" | "xl"` (default `md`), `icon?: boolean` for a square glyph box, `pill?: boolean` for full-round corners, `href` to make it a link, `render` for an element that is neither a button nor a link. Variant is how much ink it spends and tone is what the ink means, on separate axes, so a quiet delete is `variant="ghost" tone="destructive"`.
 - `Badge`: `variant?: "solid" | "soft" | "outline" | "ghost"` (default `solid`), `tone?: Tone`, `size?: "xs" | "sm"` (default `sm`), `pill?: boolean`, `href` for a badge that leads somewhere. Same axes and same spellings as `Button`, minus `link`, which belongs to things you click. `warning` and `supertype` were `tone="warn"` and `tone="brand"` under invented names.
@@ -187,14 +199,16 @@ Code samples and commit messages stay conventional. This is about prose.
 - `<TypographyMuted tone="default">`: a type error. Use `TypographyP`.
 - Binding fonts with `font.className` instead of `font.variable`. The className
   form sets `font-family` on the element and leaves the roles unresolved.
-- Omitting `@source '../node_modules/@supertype.ai/foundations/dist/**/*.js'` from
-  the CSS entry. Tailwind then purges every class the package ships.
-- Omitting `@import "@supertype.ai/foundations/theme.css"`. `tokens.css` names the
-  colour roles but holds no values, so the whole palette resolves to nothing.
+- Writing the style layer out by hand. `@import "@supertype.ai/foundations";` after
+  `@import "tailwindcss";` is the whole of it: it carries tokens, theme, type and
+  prose in order and registers the package's own `@source`. Split into the granular
+  imports, an app owns the order, the palette and the scan path — and a wrong
+  `@source` path purges every class the package ships, silently.
 - Using `Accordion` for a static FAQ. `Disclosure` runs on the browser alone.
 - Adding a second `@custom-variant dark`. `tokens.css` already binds it.
 
-Run `npx foundations doctor` in the app to check the last four.
+Run `npx foundations doctor` in the app to check the font binding, the style layer
+and the dark variant.
 
 ## Surfaces
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supertype.ai/foundations",
-  "version": "0.1.35",
+  "version": "0.1.37",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -38,9 +38,11 @@
   },
   "exports": {
     ".": {
+      "style": "./src/index.css",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./index.css": "./src/index.css",
     "./blocks": {
       "types": "./dist/blocks/index.d.ts",
       "default": "./dist/blocks/index.js"
@@ -66,6 +68,10 @@
       "require": "./dist/cjs/eslint.js",
       "default": "./dist/eslint.js"
     },
+    "./optical": {
+      "types": "./dist/optical.d.ts",
+      "default": "./dist/optical.js"
+    },
     "./rehype": {
       "types": "./dist/rehype.d.ts",
       "default": "./dist/rehype.js"
@@ -109,7 +115,8 @@
     "@base-ui/react": ">=1.4",
     "next": ">=15",
     "next-view-transitions": ">=0.3",
-    "react": ">=19"
+    "react": ">=19",
+    "tailwindcss": ">=4"
   },
   "devDependencies": {
     "@base-ui/react": "^1.4.1",

package/src/index.css

@@ -0,0 +1,37 @@
+/* The whole style layer, in one import.
+ *
+ * An app used to write these four imports itself, in this order, plus an
+ * `@source` line pointing back into node_modules — and every part of that was
+ * something to get wrong. The order is a cascade, so a file out of place
+ * re-points variables an earlier one defines. The `@source` path is relative to
+ * the app's CSS file, so it moved with the app's layout and broke outright in a
+ * workspace, where the package hoists to the repo root: Tailwind then scanned
+ * nothing, purged every class this package ships, and rendered the components
+ * unstyled with no error anywhere.
+ *
+ * None of it was ever the app's business. Tailwind v4 resolves `@source`
+ * relative to the file that declares it, so the package can register its own
+ * content — and then the order, the path and the completeness are all decided
+ * here, where they are the same for everyone.
+ *
+ *   @import "tailwindcss";
+ *   @import "@supertype.ai/foundations";
+ *
+ * shiki.css is deliberately not here: an app that renders no code fences should
+ * not pay for it. Import it separately when you add Shiki.
+ *
+ * The granular entry points remain exported, for the one app in a hundred that
+ * paints every colour role itself and wants tokens.css without theme.css.
+ */
+@import "./tokens.css";
+@import "./theme.css";
+@import "./type.css";
+@import "./prose.css";
+
+/* Relative to this file, so it is right wherever the package is installed.
+ *
+ * Narrowed to `.js` rather than pointing at the directory: Tailwind reads every
+ * source file as plain text, so scanning all of dist/ hands it the prose in the
+ * .d.ts doc comments and it emits rules for words that happen to look like
+ * classes. `check-candidates.mjs` guards the same boundary from the other side. */
+@source "../dist/**/*.js";