@astryxdesign/cli 0.1.4-canary.f00b844 → 0.1.4-canary.f0b9ca8

package/CHANGELOG.md

@@ -36,7 +36,7 @@ Thanks to everyone who contributed to this release:
 - Strict config + integration v1 schema (integrations, issuesUrl, hooks.postCodemod) and new @astryxdesign/cli/integration export.
 - File-based codemod API (createCodemod/createConfigCodemod) with the @astryxdesign/cli/codemod export and integration codemod discovery in upgrade.
 - component, template, and upgrade now print a one-line non-blocking warning when a configured integration has validation issues, pointing to validate-integration.
-- Add a Kanban Board page template: color-coded status columns, draggable task cards with priority tags, and board toolbar.
+- Add a Kanban Board page template: color-coded status columns, draggable task cards with priority tags, and board toolbar. Based on a design by @cg-hub18.
 - Add frame-first layout guidance: new `astryx docs layout` topic (shell choice, region budgets, app archetypes, cards-vs-rows policy, responsive contracts), layout rules in the generated agent cheat sheet, and layout anti-patterns in `docs principles`.
 - Add a v0.1.3 config codemod that migrates astryx.config layout.components to experimental.xle.components.
 - Add v0.1.0 codemods for migrating `declare module "@xds/core/..."` type augmentations and `.xds-*` / `[data-xds-theme]` / `@layer xds-theme` CSS surfaces to their `@astryxdesign`/`astryx-*` equivalents.
@@ -80,6 +80,7 @@ Thanks to everyone who contributed to this release:
 Thanks to everyone who contributed to this release:
 
 - @AKnassa
+- @cg-hub18
 - @ejhammond
 - @ernestt
 - @harshavardhan194

package/docs/getting-started.doc.mjs

@@ -69,6 +69,10 @@ export const docs = {
           type: 'prose',
           text: 'Available themes: @astryxdesign/theme-neutral (muted minimal, a good starting point), @astryxdesign/theme-butter, @astryxdesign/theme-chocolate, @astryxdesign/theme-gothic (dark-only), @astryxdesign/theme-matcha, @astryxdesign/theme-stone, and @astryxdesign/theme-y2k. See `npx astryx docs theme` for the full theming guide.',
         },
+        {
+          type: 'prose',
+          text: 'These stylesheets are cascade-layered: the reset loads in @layer reset and component styles in @layer astryx-base. If your project has existing global CSS, a legacy reset, or Tailwind, declare the layer order explicitly and assign every stylesheet to a layer deliberately: unlayered styles and later layers both override astryx-base regardless of specificity. See the Cascade Layer Safety section in `npx astryx docs migration` before building screens.',
+        },
       ],
     },
     {

package/docs/migration.doc.mjs

@@ -33,6 +33,7 @@ export const docs = {
             'Install the design system and run init so the project has package scripts, theme CSS, and agent docs.',
             'Wrap the app root with Theme and choose the initial light, dark, or system mode behavior.',
             'Make Tailwind and design system CSS layer order explicit before replacing components.',
+            'Render the foundation smoke test page and confirm primitives keep their padding before migrating any surface.',
             'Move the persistent frame first: AppShell, TopNav, SideNav, page content, and mobile navigation.',
             'Replace shared primitives: Button, IconButton, TextInput, NumberInput, Switch, CheckboxInput, RadioList, Selector, Tabs, Dialog, AlertDialog, Banner, Toast, Badge, Card, Table, and ListItem.',
             'Replace global workflows: command palette, settings popover, theme toggle, search, filters, create flows, and destructive confirmation dialogs.',
@@ -125,6 +126,139 @@ export function AppRoot({children}: {children: React.ReactNode}) {
 @import "@astryxdesign/core/tailwind-theme.css";
 @import "tailwindcss/utilities.css" layer(utilities);`,
         },
+        {
+          type: 'prose',
+          text: 'On Tailwind v3 there is no preflight.css to import, so wrap the @tailwind base directive in a named layer instead. Keep utilities unlayered so existing app utility classes still win everywhere.',
+        },
+        {
+          type: 'code',
+          lang: 'css',
+          label: 'Tailwind v3 coexistence',
+          code: `@layer reset, tw-preflight, astryx-base, astryx-theme;
+
+@import "@astryxdesign/core/reset.css";
+@import "@astryxdesign/core/astryx.css";
+@import "@astryxdesign/theme-neutral/theme.css";
+
+@layer tw-preflight {
+  @tailwind base; /* layered: astryx-theme now wins over preflight */
+}
+@tailwind components;
+@tailwind utilities; /* unlayered: legacy utility classes keep winning */`,
+        },
+      ],
+    },
+    {
+      title: 'Cascade Layer Safety',
+      content: [
+        {
+          type: 'prose',
+          text: 'In a stylesheet with no layers at all, a zero-specificity reset like `* { padding: 0 }` loses to any class selector, so most developers treat resets as harmless. Layers change the rules twice: unlayered styles beat every named layer, and a later layer beats an earlier one, both regardless of specificity. The same reset therefore wins against every component style either by staying unlayered or by landing in a layer declared after astryx-base. Same CSS, opposite outcome, and no error or warning when it happens.',
+        },
+        {
+          type: 'prose',
+          text: 'This is the most common way an adoption breaks, through one of two @import mechanisms. A top-level @import without the layer() keyword keeps the legacy reset unlayered, where it overrides every design system layer. And an @import nested inside a file that was itself imported into a layer inherits that surrounding layer, so a reset can silently land in a consumer layer above astryx-base. Either way the fix is the same: import the legacy reset into the lowest layer explicitly.',
+        },
+        {
+          type: 'code',
+          lang: 'css',
+          label: 'Legacy reset, explicitly layered',
+          code: `/* was: @import "./legacy-reset.css";  (unlayered: beats every layer) */
+@import "./legacy-reset.css" layer(reset);`,
+        },
+        {
+          type: 'prose',
+          text: 'Audit the layers around the design system with this checklist before building screens.',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            'Declare the canonical @layer order once, before any @import. With webpack-based bundlers (including Next.js) the order declaration must live in its own CSS file imported first, such as layers.css, because webpack hoists @import content above the inline CSS that follows it.',
+            'Audit every pre-existing global or reset stylesheet and assign each one to a layer deliberately. Top-level imports without layer() stay unlayered and beat every layer; imports nested inside a layered file inherit that layer.',
+            'Remove or demote the app legacy reset. The design system ships its own :where() reset in the lowest layer, so any app reset belongs in that same reset layer and never in a layer above astryx-base.',
+            'Layer Tailwind preflight. On Tailwind v4, import preflight.css with layer(base). On Tailwind v3, wrap the @tailwind base directive in a named layer (see the snippet in Theme and CSS Setup). Unlayered preflight overrides theme CSS silently.',
+            'Set moduleResolution to bundler or node16 and newer so subpath imports like @astryxdesign/core/reset.css resolve.',
+            'Theme with defineTheme and the accent family API instead of hand-writing individual color tokens. Derived tokens like --color-on-accent are generated from the accent scale automatically; hand-writing only --color-accent leaves --color-on-accent at its stale white default with no contrast guarantee against the new accent.',
+            'Run the foundation smoke test below and view a few components in both light and dark mode before migrating any route.',
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'One more mental model shift: a className or utility class you write on a component still reaches the DOM either way, but whether it overrides the component is a layer question, not a source order question. Keep app utilities in the utilities layer so they keep winning.',
+        },
+      ],
+    },
+    {
+      title: 'Foundation Smoke Test',
+      content: [
+        {
+          type: 'prose',
+          text: 'A broken layer order fails silently and identically on every page, so catch it before feature work instead of after N migrated screens. Render one throwaway page with a few primitives as the first migration step.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Foundation check page',
+          code: `import {useState} from 'react';
+import {Button} from '@astryxdesign/core/Button';
+import {Card} from '@astryxdesign/core/Card';
+import {Table} from '@astryxdesign/core/Table';
+import {TextInput} from '@astryxdesign/core/TextInput';
+import {VStack} from '@astryxdesign/core/VStack';
+
+export default function FoundationCheck() {
+  const [email, setEmail] = useState('');
+
+  return (
+    <div data-foundation-check>
+      <VStack gap={4}>
+        <Button label="Primary action" variant="primary" />
+        <TextInput
+          label="Email"
+          placeholder="you@example.com"
+          value={email}
+          onChange={setEmail}
+        />
+        <Card>One card with default padding</Card>
+        <Table
+          data={[{name: 'Foundation', status: 'ok'}]}
+          columns={[
+            {key: 'name', header: 'Name'},
+            {key: 'status', header: 'Status'},
+          ]}
+        />
+      </VStack>
+    </div>
+  );
+}`,
+        },
+        {
+          type: 'prose',
+          text: 'If the button renders with visible padding, a filled primary background, and the input and card have borders and internal spacing, the foundation is sound. For an assertion that can run in any test runner or a dev-only effect, check that a primitive keeps non-zero padding:',
+        },
+        {
+          type: 'code',
+          lang: 'ts',
+          label: 'Foundation assertion',
+          code: `const button = document.querySelector<HTMLButtonElement>(
+  '[data-foundation-check] button',
+);
+if (!button) {
+  throw new Error('Foundation check page did not render a button.');
+}
+if (getComputedStyle(button).paddingInline === '0px') {
+  throw new Error(
+    'Foundation broken: an unlayered reset or a later cascade layer is ' +
+      'overriding component styles. Check that no app reset sits outside ' +
+      'the reset layer.',
+  );
+}`,
+        },
+        {
+          type: 'prose',
+          text: 'When this fails, the fix is almost always in the layer order: find the stylesheet that zeroes padding, and move it into the reset layer or delete it.',
+        },
       ],
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.4-canary.f00b844",
+  "version": "0.1.4-canary.f0b9ca8",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -75,12 +75,16 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "0.1.4-canary.f00b844",
-    "@astryxdesign/lab": "0.1.4-canary.f00b844",
-    "@astryxdesign/theme-neutral": "0.1.4-canary.f00b844",
-    "gpt-tokenizer": "^2.0.0"
+    "@astryxdesign/charts": "0.1.4-canary.f0b9ca8",
+    "@astryxdesign/core": "0.1.4-canary.f0b9ca8",
+    "@astryxdesign/lab": "0.1.4-canary.f0b9ca8",
+    "@astryxdesign/theme-neutral": "0.1.4-canary.f0b9ca8",
+    "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
+    "@astryxdesign/charts": {
+      "optional": true
+    },
     "@astryxdesign/core": {
       "optional": true
     },
@@ -92,10 +96,11 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/core": "0.1.4-canary.f00b844",
-    "@astryxdesign/lab": "0.1.4-canary.f00b844",
-    "@astryxdesign/theme-neutral": "0.1.4-canary.f00b844",
-    "gpt-tokenizer": "^2.0.0"
+    "@astryxdesign/charts": "0.1.4-canary.f0b9ca8",
+    "@astryxdesign/core": "0.1.4-canary.f0b9ca8",
+    "@astryxdesign/lab": "0.1.4-canary.f0b9ca8",
+    "@astryxdesign/theme-neutral": "0.1.4-canary.f0b9ca8",
+    "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {
     "astryx": "node bin/astryx.mjs",

package/src/api/doctor.mjs

@@ -115,10 +115,21 @@ function findThemePackages(cwd) {
     return found;
   }
   for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
     if (!entry.name.startsWith('theme-')) continue;
+    const dir = path.join(scopeDir, entry.name);
+    // pnpm installs packages as symlinks into node_modules/.pnpm, and a
+    // symlink dirent reports isDirectory() as false — stat the target instead.
+    let isDir = entry.isDirectory();
+    if (!isDir && entry.isSymbolicLink()) {
+      try {
+        isDir = fs.statSync(dir).isDirectory();
+      } catch {
+        isDir = false;
+      }
+    }
+    if (!isDir) continue;
     const name = `@astryxdesign/${entry.name}`;
-    found.push({name, version: pkgVersion(path.join(scopeDir, entry.name))});
+    found.push({name, version: pkgVersion(dir)});
   }
   return found;
 }

package/src/codemods/__tests__/runner.test.mjs

@@ -99,5 +99,43 @@ describe('runCodemods — unified config codemod path', () => {
     expect(fs.readFileSync(path.join(srcDir, 'a.ts'), 'utf-8')).toContain(
       'const bar = 1',
     );
+    // writtenFiles must be returned (consumed by upgrade.mjs to run the
+    // post-codemod formatting/lint hooks). Regression guard: it was previously
+    // built internally but omitted from the return object, so hooks received an
+    // empty file list and silently skipped, leaving codemod output unformatted.
+    expect(result.writtenFiles).toEqual([path.join(srcDir, 'a.ts')]);
+  });
+
+  it('returns writtenFiles for every changed file (post-codemod hook input)', async () => {
+    const srcDir = path.join(tmpDir, 'src');
+    fs.mkdirSync(srcDir);
+    fs.writeFileSync(path.join(srcDir, 'a.ts'), 'const foo = 1;\n');
+    fs.writeFileSync(path.join(srcDir, 'b.ts'), 'const foo = 2;\n');
+    fs.writeFileSync(path.join(srcDir, 'c.ts'), 'const untouched = 3;\n');
+
+    const versionManifests = [
+      {
+        version: '0.1.3',
+        transforms: [
+          {
+            name: 'synthetic-code-codemod',
+            meta: {title: 'Synthetic code codemod'},
+            transform: file => file.source.replace(/foo/g, 'bar'),
+          },
+        ],
+      },
+    ];
+
+    const result = await runCodemods(versionManifests, {
+      apply: true,
+      path: './src',
+      silent: true,
+    });
+
+    expect(result.totalFilesChanged).toBe(2);
+    // Only the two files that actually changed are reported (not c.ts).
+    expect([...result.writtenFiles].sort()).toEqual(
+      [path.join(srcDir, 'a.ts'), path.join(srcDir, 'b.ts')].sort(),
+    );
   });
 });

package/src/codemods/runner.mjs

@@ -178,6 +178,7 @@ function toUnifiedEntry(transformEntry, version) {
  * @param {string|undefined} options.codemod - Run only this specific transform
  * @param {Set<string>} [options.skipCodemods] - Transform names to exclude
  * @param {boolean} [options.silent] - Suppress all human-facing output (for --json)
+ * @returns {{totalFilesChanged: number, totalTransformsApplied: number, totalValidationBlocked: number, writtenFiles: string[], errors: Array, skippedOptional: Array}}
  */
 export async function runCodemods(
   versionManifests,
@@ -405,6 +406,7 @@ export async function runCodemods(
     totalFilesChanged,
     totalTransformsApplied,
     totalValidationBlocked,
+    writtenFiles,
     errors,
     skippedOptional,
   };

package/src/commands/agent-docs.mjs

@@ -9,11 +9,12 @@
  * - Claude Code: CLAUDE.md (root) or .claude/CLAUDE.md
  * - Cursor: .cursorrules
  * - Codex/generic: AGENTS.md
+ * - Hermes Agent: .hermes.md or HERMES.md (existing), else AGENTS.md
  *
  * Auto-detect: discovers existing files and updates them in place.
  * Default (no existing files): creates .claude/CLAUDE.md.
  *
- * --agent <tool>: target a specific tool preset (claude, cursor, codex, all)
+ * --agent <tool>: target a specific tool preset (claude, cursor, codex, hermes, all)
  * --agent-docs-path <path>: explicit file path(s)
  */
 
@@ -46,6 +47,7 @@ const AGENT_PRESETS = {
   claude: [CLAUDE_MD, CLAUDE_DIR_MD],
   cursor: ['.cursorrules', AGENTS_MD],
   codex: [AGENTS_MD],
+  hermes: ['.hermes.md', 'HERMES.md', AGENTS_MD],
 };
 
 /**
@@ -64,7 +66,7 @@ export function discoverAgentDocs(targetDir) {
  * Searches for existing files first, falls back to default creation path.
  *
  * @param {string} targetDir
- * @param {string} agent - Preset name: 'claude', 'cursor', 'codex', 'all'
+ * @param {string} agent - Preset name: 'claude', 'cursor', 'codex', 'hermes', 'all'
  * @returns {{inject: string[], create: string[]}} Files to inject into vs create fresh
  */
 export function resolveAgentPaths(targetDir, agent) {
@@ -386,7 +388,7 @@ export function removeAgentDocs(targetDir) {
  * @param {object} [options]
  * @param {boolean} [options.zh]
  * @param {string} [options.lang]
- * @param {string} [options.agent] - Tool preset: 'claude', 'cursor', 'codex', 'all'
+ * @param {string} [options.agent] - Tool preset: 'claude', 'cursor', 'codex', 'hermes', 'all'
  * @param {string[]} [options.paths] - Explicit paths (overrides agent/auto-detect)
  * @param {boolean} [options.onlyReplace] - Only update files that already have Astryx markers (for upgrades)
  * @returns {string[]} List of files written
@@ -468,14 +470,14 @@ export function installAgentDocs(targetDir, {zh = false, lang, agent, paths, onl
   return written;
 }
 
-const VALID_AGENTS = ['claude', 'cursor', 'codex', 'all'];
+const VALID_AGENTS = ['claude', 'cursor', 'codex', 'hermes', 'all'];
 
 export function registerAgentDocs(program) {
   program
     .command('agent-docs')
     .description('Install/update the component index for AI coding agents')
     .option('--remove', 'Remove the design system section from all agent doc files')
-    .option('--agent <tool>', 'Target tool: claude, cursor, codex, all')
+    .option('--agent <tool>', 'Target tool: claude, cursor, codex, hermes, all')
     .option('--agent-docs-path <path...>', 'Explicit file path(s) to write to')
     .action(options => {
       const targetDir = process.cwd();

package/src/commands/agent-docs.test.mjs

@@ -449,6 +449,17 @@ describe('installAgentDocs', () => {
     expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(true);
   });
 
+  it('respects --agent hermes preset: creates AGENTS.md', () => {
+    setupCorePackage(tmpDir);
+
+    const written = installAgentDocs(tmpDir, {agent: 'hermes'});
+
+    expect(written).toEqual(['AGENTS.md']);
+    const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
+    expect(content).toContain('<!-- ASTRYX:START -->');
+    expect(fs.existsSync(path.join(tmpDir, '.claude'))).toBe(false);
+  });
+
   it('respects explicit --paths', () => {
     setupCorePackage(tmpDir);
 
@@ -548,4 +559,26 @@ describe('resolveAgentPaths', () => {
     expect(result.create).toContain('AGENTS.md');
     expect(result.create).toContain('.claude/CLAUDE.md');
   });
+
+  it('hermes preset creates AGENTS.md when nothing exists', () => {
+    const result = resolveAgentPaths(tmpDir, 'hermes');
+    expect(result).toEqual({inject: [], create: ['AGENTS.md']});
+  });
+
+  it('hermes preset finds existing .hermes.md', () => {
+    fs.writeFileSync(path.join(tmpDir, '.hermes.md'), '');
+    const result = resolveAgentPaths(tmpDir, 'hermes');
+    expect(result).toEqual({inject: ['.hermes.md'], create: []});
+  });
+
+  it('hermes preset finds existing HERMES.md when no .hermes.md', () => {
+    fs.writeFileSync(path.join(tmpDir, 'HERMES.md'), '');
+    const result = resolveAgentPaths(tmpDir, 'hermes');
+    expect(result).toEqual({inject: ['HERMES.md'], create: []});
+  });
+
+  it('claude preset still creates .claude/CLAUDE.md when nothing exists (hermes is additive)', () => {
+    const result = resolveAgentPaths(tmpDir, 'claude');
+    expect(result).toEqual({inject: [], create: ['.claude/CLAUDE.md']});
+  });
 });

package/src/commands/build-theme.mjs

@@ -175,14 +175,85 @@ async function getKnownValues(componentName) {
   return _knownValuesCache.get(componentName);
 }
 
+/**
+ * Resolve `@astryxdesign/core`'s package root relative to the CLI package. Core
+ * and the CLI ship as siblings (`@astryxdesign/core`, `@astryxdesign/cli`), so
+ * `../../../core` from `src/commands/` reaches core whether installed from npm
+ * or run inside the monorepo. Returns null if it can't be found.
+ */
+function resolveCoreRoot() {
+  const cliDir = path.dirname(fileURLToPath(import.meta.url));
+  const coreRoot = path.resolve(cliDir, '../../../core');
+  return fs.existsSync(coreRoot) ? coreRoot : null;
+}
+
+/**
+ * Read the type declarations `@astryxdesign/core/<Component>` exposes so we can
+ * check whether a given augmentation-target interface actually exists before
+ * generating a module augmentation against it.
+ *
+ * Reads the shipped `dist/<Component>/index.d.ts` (what a consumer's TypeScript
+ * actually sees), falling back to the `src/<Component>/index.ts` in the
+ * monorepo. Returns the file contents, or '' if nothing is found.
+ */
+const _componentDeclCache = new Map();
+function readComponentDeclarations(pascalName) {
+  if (_componentDeclCache.has(pascalName)) {
+    return _componentDeclCache.get(pascalName);
+  }
+  let contents = '';
+  const coreRoot = resolveCoreRoot();
+  if (coreRoot) {
+    const candidates = [
+      path.join(coreRoot, 'dist', pascalName, 'index.d.ts'),
+      path.join(coreRoot, 'src', pascalName, 'index.ts'),
+    ];
+    for (const file of candidates) {
+      try {
+        if (fs.existsSync(file)) {
+          contents = fs.readFileSync(file, 'utf-8');
+          break;
+        }
+      } catch {
+        // ignore and try the next candidate
+      }
+    }
+  }
+  _componentDeclCache.set(pascalName, contents);
+  return contents;
+}
+
+/**
+ * Determine whether `@astryxdesign/core/<Component>` exports an interface named
+ * `interfaceName` that can be augmented via module augmentation.
+ *
+ * Only interfaces are extension points — closed literal-union types (e.g.
+ * `HeadingType`, `ButtonSize`) are NOT augmentable, so a generated augmentation
+ * against them is dead code. We check that the name is exported (directly or
+ * re-exported) as a type/interface.
+ */
+function componentHasAugmentableInterface(pascalName, interfaceName) {
+  const decl = readComponentDeclarations(pascalName);
+  if (!decl) return false;
+  // Word-boundary match so `ButtonVariantMap` doesn't match `XButtonVariantMap`.
+  const re = new RegExp(`\\b${interfaceName}\\b`);
+  return re.test(decl);
+}
+
 /**
  * Generate TypeScript declaration content with module augmentation for custom
  * component prop values found in the theme's `components` keys. Reads known
  * values from doc files to filter out base prop values.
  *
- * Interface naming convention: Astryx + PascalCase(component) + PascalCase(prop) + Map
- *   banner + status → XDSBannerStatusMap
- *   button + variant → XDSButtonVariantMap
+ * Interface naming convention: PascalCase(component) + PascalCase(prop) + Map
+ *   banner + status → BannerStatusMap
+ *   button + variant → ButtonVariantMap
+ *
+ * An augmentation is only emitted when `@astryxdesign/core/<Component>` actually
+ * exports a matching interface. Props backed by closed literal-union types
+ * (e.g. Button `size`, Heading `type`/`level`) have no augmentation point, so
+ * generating a `declare module` block for them would be dead code — those are
+ * skipped.
  *
  * @param {object} themeDef - Theme definition (resolved by defineTheme)
  * @returns {Promise<string|null>} TypeScript declaration content, or null if no augmentations needed
@@ -234,7 +305,14 @@ async function generateVariantDeclarationsAsync(themeDef) {
       const pascal = toPascalCase(component);
       const propPascal = prop.charAt(0).toUpperCase() + prop.slice(1);
       const modulePath = `@astryxdesign/core/${pascal}`;
-      const interfaceName = `XDS${pascal}${propPascal}Map`;
+      const interfaceName = `${pascal}${propPascal}Map`;
+
+      // Only augment interfaces that actually exist as an extension point in
+      // core. Props backed by closed literal-union types (e.g. Button `size`,
+      // Heading `type`/`level`) have no `*Map` interface — a `declare module`
+      // block against a non-existent interface just creates a new, unused
+      // interface and never extends the component's prop union, so skip it.
+      if (!componentHasAugmentableInterface(pascal, interfaceName)) continue;
 
       sections.push(`declare module '${modulePath}' {`);
       sections.push(`  interface ${interfaceName} {`);
@@ -247,6 +325,13 @@ async function generateVariantDeclarationsAsync(themeDef) {
     }
   }
 
+  // If every custom value targeted a non-augmentable prop, there's nothing to
+  // emit beyond the header — return null so no `.variants.d.ts` is written.
+  const hasEmittedAugmentation = sections.some(line =>
+    line.startsWith('declare module'),
+  );
+  if (!hasEmittedAugmentation) return null;
+
   return sections.join('\n');
 }
 
@@ -433,13 +518,21 @@ ${iconReExport}`;
 /**
  * Generate TypeScript declarations for a built theme module.
  */
-function generateBuiltTypes(themeDef, iconInfo) {
+function generateBuiltTypes(themeDef, iconInfo, variantsFileName) {
   const iconType = iconInfo
     ? `import type { IconRegistry } from '@astryxdesign/core/Icon';
 export declare const ${iconInfo.exportName}: IconRegistry;
 `
     : '';
-  return `import type { DefinedTheme } from '@astryxdesign/core/theme';
+  // Pull in the generated custom-variant augmentations so that importing the
+  // theme's types also loads the module augmentations (otherwise the
+  // `.variants.d.ts` is emitted but never referenced, and the custom variants
+  // never widen the component prop unions for consumers).
+  const variantsRef = variantsFileName
+    ? `/// <reference path="./${variantsFileName}" />
+`
+    : '';
+  return `${variantsRef}import type { DefinedTheme } from '@astryxdesign/core/theme';
 ${iconType}export declare const ${toIdentifier(themeDef.name)}Theme: DefinedTheme;
 `;
 }
@@ -894,19 +987,23 @@ export function registerTheme(program) {
 
       const iconInfo = extractIconInfo(filePath);
 
-      // Generate all file contents in memory first.
-      const cssContent = generatedHeader(sourceRelative, 'css', buildCommand) + css;
-      const jsContent = generatedHeader(sourceRelative, 'js', buildCommand) + generateBuiltModule(resolvedTheme || themeDef, iconInfo);
-      const dtsContent = generatedHeader(sourceRelative, 'ts', buildCommand) + generateBuiltTypes(themeDef, iconInfo);
-
-      // Type augmentation .d.ts if theme has custom prop values
+      // Type augmentation .d.ts if theme has custom prop values. Computed
+      // before the main .d.ts so the latter can reference it (see below).
       const augmentationSource = resolvedTheme || themeDef;
       const variantDecl = await generateVariantDeclarationsAsync(augmentationSource);
-      const variantDtsPath = variantDecl ? path.join(outDir, `${baseName}.variants.d.ts`) : null;
+      const variantsFileName = variantDecl ? `${baseName}.variants.d.ts` : null;
+      const variantDtsPath = variantDecl ? path.join(outDir, variantsFileName) : null;
       const variantContent = variantDecl
         ? generatedHeader(sourceRelative, 'ts', buildCommand) + variantDecl
         : null;
 
+      // Generate all file contents in memory first. The main .d.ts references
+      // the variants file (when present) via a triple-slash directive so
+      // importing the theme also loads the custom-variant augmentations.
+      const cssContent = generatedHeader(sourceRelative, 'css', buildCommand) + css;
+      const jsContent = generatedHeader(sourceRelative, 'js', buildCommand) + generateBuiltModule(resolvedTheme || themeDef, iconInfo);
+      const dtsContent = generatedHeader(sourceRelative, 'ts', buildCommand) + generateBuiltTypes(themeDef, iconInfo, variantsFileName);
+
       // Atomic-ish write: stage every file as `<dest>.tmp`, then rename
       // each into place. If any stage step fails we clean up partials and
       // exit; if a rename fails mid-way we still have the originals (or