@texturehq/edges 1.33.2 → 1.34.1

package/dist/theme.css

@@ -3,10 +3,11 @@
  *
  * This file imports all theme layers in the correct order:
  * 1. Design tokens (from @texturehq/edges-tokens)
- * 2. Legacy aliases (backward compat for old variable names)
- * 3. Animation features
- * 4. Computed values (derived from tokens)
- * 5. Utility classes
+ * 2. Typography role utilities (from @texturehq/edges-tokens)
+ * 3. Legacy aliases (backward compat for old variable names)
+ * 4. Animation features
+ * 5. Computed values (derived from tokens)
+ * 6. Utility classes
  */
 
 /* Layer 1: Design Tokens
@@ -15,9 +16,20 @@
 @import "@texturehq/edges-tokens/css/light";
 @import "@texturehq/edges-tokens/css/dark";
 
+/* Typography role utilities
+   Generated from edges-tokens so full Edges consumers get the same lightweight
+   role classes marketing consumers can import directly. */
+@import "@texturehq/edges-tokens/css/typography";
+
+/* Prose: editorial composition wrapper for long-form content. Pairs with
+   the <Prose> component exported from this package. */
+@import "@texturehq/edges-tokens/css/prose";
+
 /* Layer 1b: Legacy Aliases
    Backward-compat aliases from old variable names (--action-brand-background,
-   --feedback-*, --skeleton-*, etc.) to new ones. Remove after migration. */
+   --feedback-*, --skeleton-*, and deprecated font color names) to new ones.
+   Font colors should use text-primary/text-secondary/text-inverse/text-disabled;
+   remove this import after the broader compatibility migration. */
 @import "@texturehq/edges-tokens/css/legacy";
 
 /* Layer 1b2: Legacy Bridge
@@ -25,8 +37,9 @@
    Remove once utility classes are updated to reference --color-* directly. */
 @import "./styles/legacy-bridge.css";
 
-/* Layer 1c: Responsive Typography
-   Overrides font-size tokens with responsive values (smaller on mobile, larger on desktop) */
+/* Layer 1c: Legacy Responsive Typography Compatibility
+   Deprecated compatibility layer for primitive Tailwind size utilities.
+   Semantic typography roles now own responsive behavior at the token layer. */
 @import "./styles/responsive-typography.css";
 
 /* Layer 1d: Light Theme Override

package/dist/typography.css

@@ -0,0 +1,150 @@
+/**
+ * Typography utilities — @texturehq/edges-tokens
+ * Generated by Style Dictionary. DO NOT EDIT.
+ *
+ * Import after @texturehq/edges-tokens/css/light so the referenced
+ * --text-* and --font-family-* custom properties are defined.
+ */
+
+.text-agent {
+  font: var(--text-agent);
+  letter-spacing: var(--text-agent-letter-spacing);
+  font-optical-sizing: auto;
+}
+
+.text-body-lg {
+  font: var(--text-body-lg);
+  letter-spacing: var(--text-body-lg-letter-spacing);
+}
+
+.text-body-md {
+  font: var(--text-body-md);
+  letter-spacing: var(--text-body-md-letter-spacing);
+}
+
+.text-body-sm {
+  font: var(--text-body-sm);
+  letter-spacing: var(--text-body-sm-letter-spacing);
+}
+
+.text-code {
+  font: var(--text-code);
+  letter-spacing: var(--text-code-letter-spacing);
+  font-variant-numeric: tabular-nums;
+}
+
+.text-display-lg {
+  font: var(--text-display-lg);
+  letter-spacing: var(--text-display-lg-letter-spacing);
+}
+
+.text-display-md {
+  font: var(--text-display-md);
+  letter-spacing: var(--text-display-md-letter-spacing);
+}
+
+.text-display-sm {
+  font: var(--text-display-sm);
+  letter-spacing: var(--text-display-sm-letter-spacing);
+}
+
+.text-display-xl {
+  font: var(--text-display-xl);
+  letter-spacing: var(--text-display-xl-letter-spacing);
+}
+
+.text-heading-lg {
+  font: var(--text-heading-lg);
+  letter-spacing: var(--text-heading-lg-letter-spacing);
+}
+
+.text-heading-md {
+  font: var(--text-heading-md);
+  letter-spacing: var(--text-heading-md-letter-spacing);
+}
+
+.text-heading-sm {
+  font: var(--text-heading-sm);
+  letter-spacing: var(--text-heading-sm-letter-spacing);
+}
+
+.text-heading-xl {
+  font: var(--text-heading-xl);
+  letter-spacing: var(--text-heading-xl-letter-spacing);
+}
+
+.text-label-lg {
+  font: var(--text-label-lg);
+  letter-spacing: var(--text-label-lg-letter-spacing);
+}
+
+.text-label-md {
+  font: var(--text-label-md);
+  letter-spacing: var(--text-label-md-letter-spacing);
+}
+
+.text-label-sm {
+  font: var(--text-label-sm);
+  letter-spacing: var(--text-label-sm-letter-spacing);
+}
+
+/* Semantic text color utilities. Pair with role utilities above. */
+.text-text-body {
+  color: var(--color-text-body);
+}
+
+.text-text-caption {
+  color: var(--color-text-caption);
+}
+
+.text-text-disabled {
+  color: var(--color-text-disabled);
+}
+
+.text-text-heading {
+  color: var(--color-text-heading);
+}
+
+.text-text-inverse {
+  color: var(--color-text-inverse);
+}
+
+.text-text-label {
+  color: var(--color-text-label);
+}
+
+.text-text-link-default {
+  color: var(--color-text-link-default);
+}
+
+.text-text-link-hover {
+  color: var(--color-text-link-hover);
+}
+
+.text-text-muted {
+  color: var(--color-text-muted);
+}
+
+.text-text-onBrand {
+  color: var(--color-text-onBrand);
+}
+
+.text-text-onPrimary {
+  color: var(--color-text-onPrimary);
+}
+
+.text-text-placeholder {
+  color: var(--color-text-placeholder);
+}
+
+.text-text-primary {
+  color: var(--color-text-primary);
+}
+
+.text-text-secondary {
+  color: var(--color-text-secondary);
+}
+
+.text-text-subtle {
+  color: var(--color-text-subtle);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@texturehq/edges",
-  "version": "1.33.2",
+  "version": "1.34.1",
   "author": "Nicholas Brown <nick@texturehq.com>",
   "description": "A shared component library for Texture",
   "type": "module",
@@ -39,23 +39,21 @@
     "./dist/styles.css": "./dist/styles.css",
     "./theme.css": "./dist/theme.css",
     "./dist/theme.css": "./dist/theme.css",
-    "./responsive-typography.css": "./dist/styles/responsive-typography.css"
+    "./responsive-typography.css": "./dist/styles/responsive-typography.css",
+    "./typography.css": "./dist/typography.css",
+    "./prose.css": "./dist/prose.css"
   },
   "scripts": {
-    "dev": "yarn watch",
+    "dev": "yarn build:pre && yarn watch",
     "watch": "tsup --watch",
-    "build": "yarn tokens:build && tsup && yarn build:post",
-    "build:post": "postcss src/styles.css -o dist/styles.css && node scripts/copy-assets.js",
-    "tokens:build": "node style-dictionary.config.mjs && node scripts/generate-viz-runtime.js",
-    "tokens:build:tailwind": "node style-dictionary.config.mjs",
-    "tokens:watch": "nodemon --watch tokens --ext json --exec 'yarn tokens:build'",
-    "tokens:watch:tailwind": "nodemon --watch tokens --ext json --exec 'yarn tokens:build:tailwind'",
-    "tokens:validate": "node scripts/validate-tokens.js",
+    "build": "yarn build:pre && tsup && yarn build:post",
+    "build:pre": "node scripts/generate-color-utilities.mjs",
+    "build:post": "node scripts/copy-assets.js",
     "build:yalc": "yarn build && npx yalc publish && npx yalc push",
     "dev:yalc": "yarn build && npx yalc publish && npx yalc push && echo 'Package updated! Run in target project: yarn install && yarn dev'",
     "dev:yalc:force": "yarn build && npx yalc publish && npx yalc push && echo 'Package updated! Run in target project: rm -rf .vite && yarn cache clean && yarn dev --force'",
     "clean": "rm -rf dist",
-    "lint": "biome check src/",
+    "lint": "biome check src/ && yarn lint:action-variants",
     "lint:quiet": "biome check --reporter=github src/",
     "lint:fix": "biome check --write src/",
     "typecheck": "tsc --noEmit -p tsconfig.prod.json",
@@ -66,7 +64,9 @@
     "test:coverage": "vitest run --coverage",
     "test:ui": "vitest --ui",
     "storybook": "VITE_MAPBOX_ACCESS_TOKEN=pk.eyJ1IjoidmljdG9yLXRleHR1cmUiLCJhIjoiY2x1cXM5dnVqMDFvYTJrcWszbnZmdGo4cCJ9.uEu0gqmITLtBMKEVW0aFtA storybook dev -p ${STORYBOOK_PORT:-6010} --no-open",
-    "build-storybook": "storybook build"
+    "build-storybook": "storybook build",
+    "lint:font-colors": "node scripts/check-legacy-font-colors.mjs",
+    "lint:action-variants": "node scripts/check-legacy-action-variants.mjs"
   },
   "peerDependencies": {
     "@hookform/resolvers": "^3.x || ^5.x",
@@ -93,7 +93,7 @@
     "@dnd-kit/utilities": "^3.2.2",
     "@phosphor-icons/react": "^2.1.7",
     "@tanstack/react-virtual": "^3.13.12",
-    "@texturehq/edges-tokens": "^0.3.0",
+    "@texturehq/edges-tokens": "^0.4.3",
     "@tiptap/core": "^3.4.5",
     "@tiptap/extension-link": "^3.4.5",
     "@tiptap/pm": "^3.4.5",
@@ -169,7 +169,6 @@
     "react-dom": "19.2.0",
     "react-hook-form": "^7.53.0",
     "storybook": "^8.6.14",
-    "style-dictionary": "^5.0.4",
     "tailwindcss": "^4.1.14",
     "tsup": "^8.0.2",
     "typescript": "~5.9.2",

package/scripts/check-legacy-action-variants.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const root = process.cwd();
+const scanRoots = ["src/components", "src/form", "src/docs", "templates", "README.md"];
+const ignoredParts = new Set(["node_modules", "dist", "generated"]);
+const extensions = new Set([".ts", ".tsx", ".md", ".mdx"]);
+
+const legacyPropPatterns = [
+  /\b(?:Button|TextLink|Chip|Badge|Checkbox|Switch|RadioGroup|RadioCard|Tabs|ToggleButton|SegmentedControl|ChipInputField|TextAreaWithChips|DeviceMetaDisplay|SiteMetaDisplay|ContactMetaDisplay)\b[^\n>]*variant=[{]?\s*["'](?:default|brand)["']/,
+  /chipVariant=[{]?\s*["'](?:default|brand)["']/,
+  /linkVariant=[{]?\s*["'](?:default|brand)["']/,
+  /\b(?:Button|TextLink|Chip|Badge|Checkbox|Switch|RadioGroup|RadioCard|Tabs|ToggleButton|SegmentedControl|ChipInputField|TextAreaWithChips|DeviceMetaDisplay|SiteMetaDisplay|ContactMetaDisplay)\b[^\n]*(?:variant|chipVariant|linkVariant):\s*["'](?:default|brand)["']/,
+];
+
+const legacyClassPatterns = [];
+
+const allowlistedFiles = new Set([
+  // Compatibility aliases intentionally remain in the primitives while consumers migrate.
+  "src/components/Button/Button.test.tsx",
+  "src/components/Chip/Chip.test.tsx",
+  "src/components/TextLink/TextLink.tsx",
+  "src/components/Button/Button.tsx",
+  "src/components/Chip/Chip.tsx",
+  "src/components/Badge/Badge.tsx",
+  "src/components/Checkbox/Checkbox.tsx",
+  "src/components/Switch/Switch.tsx",
+  "src/components/RadioGroup/RadioGroup.tsx",
+  "src/components/RadioCard/RadioCard.tsx",
+  "src/components/Tabs/Tabs.tsx",
+  "src/components/ToggleButton/ToggleButton.tsx",
+  "src/components/SegmentedControl/SegmentedControl.tsx",
+  "src/components/ChipInputField/ChipInputField.tsx",
+  "src/components/TextAreaWithChips/TextAreaWithChips.tsx",
+  "src/components/TextAreaWithChips/ChipTextArea.tsx",
+  "src/components/DeviceMetaDisplay/DeviceMetaDisplay.tsx",
+  "src/components/SiteMetaDisplay/SiteMetaDisplay.tsx",
+  "src/components/ContactMetaDisplay/ContactMetaDisplay.tsx",
+  "src/components/DataTable/cells/TextCell.tsx",
+  "src/components/DataTable/cells/SiteMetaCell.tsx",
+  "src/components/DataTable/cells/ContactMetaCell.tsx",
+  "src/components/DataTable/cells/DeviceMetaCell.tsx",
+  "src/components/DataTable/cells/cellUtils.tsx",
+]);
+
+function hasSupportedExtension(path) {
+  if (path.endsWith("README.md")) return true;
+  return [...extensions].some((extension) => path.endsWith(extension));
+}
+
+function walk(path, files = []) {
+  const rel = relative(root, path);
+  if (rel.split("/").some((part) => ignoredParts.has(part))) return files;
+
+  const stat = statSync(path);
+  if (stat.isDirectory()) {
+    for (const entry of readdirSync(path)) walk(join(path, entry), files);
+    return files;
+  }
+
+  if (stat.isFile() && hasSupportedExtension(path)) files.push(path);
+  return files;
+}
+
+const violations = [];
+for (const scanRoot of scanRoots) {
+  const path = join(root, scanRoot);
+  if (!existsSync(path)) continue;
+
+  for (const file of walk(path)) {
+    const rel = relative(root, file);
+    if (allowlistedFiles.has(rel)) continue;
+
+    const contents = readFileSync(file, "utf8");
+    const lines = contents.split(/\r?\n/);
+    lines.forEach((line, index) => {
+      if (legacyPropPatterns.some((pattern) => pattern.test(line))) {
+        violations.push(`${rel}:${index + 1}: legacy default/brand variant prop`);
+      }
+      if (legacyClassPatterns.some((pattern) => pattern.test(line))) {
+        violations.push(`${rel}:${index + 1}: legacy action brand/default styling class`);
+      }
+    });
+  }
+}
+
+if (violations.length > 0) {
+  console.error(
+    "Legacy action variant vocabulary found. Use primary/secondary APIs and action-primary/action-secondary tokens instead.\n"
+  );
+  console.error(violations.join("\n"));
+  process.exit(1);
+}
+
+console.log("No legacy action variant vocabulary found.");

package/scripts/check-legacy-font-colors.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const root = process.cwd();
+const scanRoots = ["src/components", "src/form", "src/docs", "src/utils", "templates", "README.md"];
+const ignoredParts = new Set(["node_modules", "dist", "generated"]);
+
+const deprecatedPatterns = [
+  "text-text-heading",
+  "text-text-body",
+  "text-text-muted",
+  "text-text-caption",
+  "text-text-placeholder",
+  "text-text-onPrimary",
+  "text-text-onBrand",
+  "text-textFaint",
+  "--color-text-heading",
+  "--color-text-body",
+  "--color-text-muted",
+  "--color-text-caption",
+  "--color-text-placeholder",
+  "--color-text-onPrimary",
+  "--color-text-onBrand",
+  "--color-text-label",
+  "--theme-text-label",
+  "fill-text-body",
+  "fill-text-muted",
+  "fill-text-caption",
+  "fill-text-heading",
+  "bg-text-caption",
+  "bg-text-muted",
+  "bg-text-heading",
+  "border-text-heading",
+  "hover:bg-text-body",
+];
+
+const extensions = new Set([".ts", ".tsx", ".css", ".md", ".mdx"]);
+const allowlistedFiles = new Set([
+  "src/styles/theme-light-override.css",
+  "theme.css",
+]);
+
+function hasSupportedExtension(path) {
+  if (path.endsWith("README.md")) return true;
+  return [...extensions].some((extension) => path.endsWith(extension));
+}
+
+function walk(path, files = []) {
+  const rel = relative(root, path);
+  if (rel.split("/").some((part) => ignoredParts.has(part))) return files;
+
+  const stat = statSync(path);
+  if (stat.isDirectory()) {
+    for (const entry of readdirSync(path)) {
+      walk(join(path, entry), files);
+    }
+    return files;
+  }
+
+  if (stat.isFile() && hasSupportedExtension(path)) {
+    files.push(path);
+  }
+  return files;
+}
+
+const violations = [];
+for (const scanRoot of scanRoots) {
+  const path = join(root, scanRoot);
+  for (const file of walk(path)) {
+    const rel = relative(root, file);
+    if (allowlistedFiles.has(rel)) continue;
+
+    const contents = readFileSync(file, "utf8");
+    const lines = contents.split(/\r?\n/);
+    lines.forEach((line, index) => {
+      for (const pattern of deprecatedPatterns) {
+        if (line.includes(pattern)) {
+          violations.push(`${rel}:${index + 1}: ${pattern}`);
+        }
+      }
+    });
+  }
+}
+
+if (violations.length > 0) {
+  console.error("Deprecated font color tokens found. Use text-primary/text-secondary/text-inverse/text-disabled instead.\n");
+  console.error(violations.join("\n"));
+  process.exit(1);
+}
+
+console.log("No deprecated font color tokens found.");

package/scripts/copy-assets.js

@@ -9,6 +9,18 @@ try {
   fs.copyFileSync("src/theme.css", "dist/theme.css");
   console.log("✅ Theme CSS copied to dist");
 
+  // Expose generated typography utilities as @texturehq/edges/typography.css.
+  // @texturehq/edges/theme.css already imports them for full Edges consumers,
+  // while this standalone file gives lighter consumers the same role classes.
+  fs.copyFileSync("../edges-tokens/dist/typography.css", "dist/typography.css");
+  console.log("✅ Typography utilities copied to dist");
+
+  // Expose the editorial Prose CSS as @texturehq/edges/prose.css for
+  // lightweight consumers. Full Edges consumers already get it bundled via
+  // @texturehq/edges/styles.css → theme.css.
+  fs.copyFileSync("../edges-tokens/dist/prose.css", "dist/prose.css");
+  console.log("✅ Prose CSS copied to dist");
+
   // Copy style layer files to dist
   const styleFiles = [
     "src/styles/animations.css",

package/scripts/generate-color-utilities.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+
+/**
+ * Generates `src/styles/generated-color-utilities.css` — a single
+ * `@source inline(...)` block that guarantees every color token in
+ * `@texturehq/edges-tokens` has its appropriate Tailwind utility class
+ * shipped in the compiled `dist/styles.css`.
+ *
+ * Without this, Tailwind v4's content-scan would only emit utilities
+ * for the subset of color tokens actually referenced in `packages/edges/src`,
+ * leaving consumers of the prebuilt CSS (apps that don't run Tailwind
+ * themselves) unable to use the rest of the token set — even though the
+ * underlying CSS variables are present in the shipped theme.
+ *
+ * Token name → utility mapping (by prefix):
+ *   text-*                  → text-{token}
+ *   border-*                → border-{token}
+ *   background-*            → bg-{token}
+ *   input-background-*      → bg-{token}
+ *   scrim-*, skeleton-*     → bg-{token}
+ *   feedback-*-background   → bg-{token}
+ *   feedback-*-border       → border-{token}
+ *   feedback-*-text         → text-{token}
+ *   state-*-border          → border-{token}
+ *   state-*-text            → text-{token}
+ *   state-*-data            → (skipped — consumed via CSS var directly)
+ *   state-* (other)         → bg-{token} + text-{token}
+ *   action-*-text           → text-{token}
+ *   action-*-hover          → bg-{token}
+ *   action-* (other)        → bg-{token} + text-{token}
+ *   map-*-border            → border-{token}
+ *   map-*                   → bg-{token}
+ *   viz-*                   → bg-{token} + text-{token}
+ *   color primitives (gray-/iris-/ocean-/etc., black/white/graphite/ink/linen/paper)
+ *                           → bg-, text-, border- (all three)
+ *
+ * Token names that don't match any rule above are skipped with a warning so
+ * a maintainer can decide whether to extend the mapping.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(__dirname, "..");
+
+const TOKENS_PATH = path.resolve(PKG_ROOT, "../edges-tokens/dist/tokens.json");
+const OUTPUT_PATH = path.resolve(PKG_ROOT, "src/generated/color-utilities.css");
+
+const PRIMITIVES = new Set(["black", "white", "graphite", "ink", "linen", "paper"]);
+const PALETTE_PREFIXES = ["gray-", "iris-", "moss-", "ocean-", "rose-", "honey-", "canary-", "plum-"];
+const SEMANTIC_BASE_NAMES = new Set([
+  "error-light",
+  "error-base",
+  "error-dark",
+  "warning-light",
+  "warning-base",
+  "warning-dark",
+  "success-light",
+  "success-base",
+  "success-dark",
+  "info-light",
+  "info-base",
+  "info-dark",
+]);
+
+function classify(token) {
+  if (token === "paper-border") return ["border"];
+  if (token.startsWith("text-")) return ["text"];
+  if (token.startsWith("border-")) return ["border"];
+  if (token.startsWith("background-")) return ["bg"];
+  if (token.startsWith("input-background-")) return ["bg"];
+  if (token.startsWith("scrim-") || token.startsWith("skeleton-")) return ["bg"];
+
+  if (token.startsWith("feedback-")) {
+    if (token.endsWith("-background")) return ["bg"];
+    if (token.endsWith("-border")) return ["border"];
+    if (token.endsWith("-text")) return ["text"];
+    return null;
+  }
+
+  if (token.startsWith("state-")) {
+    if (token.endsWith("-border")) return ["border"];
+    if (token.endsWith("-text")) return ["text"];
+    if (token.endsWith("-data")) return [];
+    return ["bg", "text"];
+  }
+
+  if (token.startsWith("action-")) {
+    if (token.endsWith("-text")) return ["text"];
+    if (token.endsWith("-hover")) return ["bg"];
+    return ["bg", "text"];
+  }
+
+  if (token.startsWith("map-")) {
+    if (token.endsWith("-border")) return ["border"];
+    return ["bg"];
+  }
+
+  if (token.startsWith("viz-")) return ["bg", "text"];
+
+  if (PRIMITIVES.has(token)) return ["bg", "text", "border"];
+  if (PALETTE_PREFIXES.some((p) => token.startsWith(p))) return ["bg", "text", "border"];
+  if (SEMANTIC_BASE_NAMES.has(token)) return ["bg", "text", "border"];
+
+  return null;
+}
+
+const tokensRaw = JSON.parse(fs.readFileSync(TOKENS_PATH, "utf8"));
+const colorTokens = Object.keys(tokensRaw)
+  .filter((k) => k.startsWith("color-"))
+  .map((k) => k.slice("color-".length))
+  .sort();
+
+const classes = new Set();
+const unmatched = [];
+
+for (const token of colorTokens) {
+  const prefixes = classify(token);
+  if (prefixes === null) {
+    unmatched.push(token);
+    continue;
+  }
+  for (const prefix of prefixes) {
+    classes.add(`${prefix}-${token}`);
+  }
+}
+
+const sorted = Array.from(classes).sort();
+
+const banner = `/**
+ * GENERATED FILE — DO NOT EDIT BY HAND.
+ *
+ * Source:    scripts/generate-color-utilities.mjs
+ * Inputs:    ../edges-tokens/dist/tokens.json
+ * Tokens:    ${colorTokens.length} color tokens → ${sorted.length} utility classes
+ *
+ * Forces Tailwind to ship a utility for every color token in the design
+ * system, regardless of whether it's referenced in this package's source.
+ * Apps that consume the prebuilt dist/styles.css get the full token set.
+ *
+ * To regenerate: \`yarn build\` (runs this script as build:pre, before tsup).
+ */
+`;
+
+const sourceBlock = `@source inline("${sorted.join(" ")}");\n`;
+
+fs.mkdirSync(path.dirname(OUTPUT_PATH), { recursive: true });
+fs.writeFileSync(OUTPUT_PATH, `${banner}\n${sourceBlock}`);
+
+console.log(`✅ Wrote ${sorted.length} color utilities to ${path.relative(PKG_ROOT, OUTPUT_PATH)}`);
+
+if (unmatched.length > 0) {
+  console.error("");
+  console.error(`❌ ${unmatched.length} color tokens did not match any classification rule:`);
+  for (const t of unmatched) console.error(`   - color-${t}`);
+  console.error("");
+  console.error("   Every color token must map to at least one utility (or be explicitly");
+  console.error("   skipped by returning []). Extend the rules in classify() in");
+  console.error("   scripts/generate-color-utilities.mjs so this PR's contract holds.");
+  process.exit(1);
+}

package/templates/claude-rules/.claude

@@ -20,13 +20,13 @@ The theme is imported via CSS:
 ## Usage Guidelines
 
 - **Use semantic classes over arbitrary values**
-- Prefer: `bg-brand-primary`, `text-text-body`, `p-md`, `rounded-lg`
+- Prefer: `bg-brand-primary`, `text-text-primary`, `text-text-secondary`, `p-md`, `rounded-lg`
 - Avoid: `bg-[#444ae1]`, `text-[#333333]`, `p-[1rem]`, `rounded-[0.5rem]`
 
 ## Naming Conventions
 
 - Brand colors: `brand-primary`, `brand-light`, `brand-dark`
-- Text colors: `text-body`, `text-heading`, `text-muted`, `text-caption`
+- Text colors: `text-primary`, `text-secondary`, `text-inverse`, `text-disabled` (legacy aliases: `text-body`, `text-heading`, `text-muted`, `text-caption`)
 - Background colors: `background-body`, `background-surface`, `background-muted`
 - Border colors: `border-default`, `border-focus`, `border-muted`
 - Action colors: `action-primary`, `action-secondary`, `action-destructive`
@@ -39,9 +39,9 @@ The theme is imported via CSS:
 
 ```html
 <!-- ✅ Good - Uses semantic classes -->
-<div class="bg-brand-primary text-text-on-primary p-md rounded-lg shadow-md">
-  <h2 class="text-text-heading text-lg font-medium">Title</h2>
-  <p class="text-text-body text-base">Content</p>
+<div class="bg-brand-primary text-text-inverse p-md rounded-lg shadow-md">
+  <h2 class="text-text-primary text-lg font-medium">Title</h2>
+  <p class="text-text-primary text-base">Content</p>
 </div>
 
 <!-- ❌ Avoid - Uses arbitrary values -->