@astryxdesign/cli 0.1.4 → 0.1.5-canary.76e6697

package/src/codemods/transforms/v0.1.5/rename-switch-label-spacing-default-to-hug.mjs

@@ -0,0 +1,140 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: Rename Switch labelSpacing "default" to "hug"
+ * @see https://github.com/facebook/astryx/issues/2889
+ *
+ * The `labelSpacing="default"` value is renamed to `labelSpacing="hug"` so
+ * the name describes the behavior (label and switch hug each other), matching
+ * the behavioral register of the sibling `spread` value and the existing
+ * `hug`/`fill` layout vocabulary on TabList and SegmentedControl. The old
+ * `default` value keeps working as a deprecated alias, so this codemod is a
+ * cleanup, not a build fix.
+ *
+ * Transforms (scoped to Switch):
+ * - <Switch labelSpacing="default" />            → <Switch labelSpacing="hug" />
+ * - <Switch labelSpacing={'default'} />          → <Switch labelSpacing={'hug'} />
+ * - <Switch labelSpacing={cond ? 'default' : x}> → <Switch labelSpacing={cond ? 'hug' : x}>
+ * - Storybook argTypes: labelSpacing: { options: [..., 'default', ...] }
+ *     → replaces 'default' with 'hug' (files importing Switch)
+ * - Object properties: { labelSpacing: 'default' } / { labelSpacing: 'default' as const }
+ *     → { labelSpacing: 'hug' } (files importing Switch)
+ *
+ * The transform deliberately does NOT touch bare `'default'` strings that are
+ * not a `labelSpacing` value (an extremely common string otherwise), so it is
+ * safe to run across an entire codebase.
+ */
+
+export const meta = {
+  title: 'Rename Switch labelSpacing "default" to "hug"',
+  description:
+    'Renames the `labelSpacing="default"` value to `labelSpacing="hug"` on ' +
+    'Switch. The old value keeps working as a deprecated alias. Also updates ' +
+    'Storybook labelSpacing argTypes options and object-literal `labelSpacing` ' +
+    'props in files that import Switch.',
+  pr: '#2889',
+};
+
+const OLD_VALUE = 'default';
+const NEW_VALUE = 'hug';
+
+/** Prop whose value is being renamed. */
+const TARGET_PROP = 'labelSpacing';
+
+/** Components whose `labelSpacing` prop accepts a SwitchLabelSpacing value. */
+const TARGET_COMPONENTS = new Set(['Switch']);
+
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  /** Rewrite a string-literal node when it equals the old value. */
+  function renameStringLiteral(node) {
+    if (!node) return false;
+    if (
+      (node.type === 'StringLiteral' || node.type === 'Literal') &&
+      node.value === OLD_VALUE
+    ) {
+      node.value = NEW_VALUE;
+      if (node.raw) node.raw = `'${NEW_VALUE}'`;
+      return true;
+    }
+    return false;
+  }
+
+  /** Recursively rewrite the old value inside ternary/logical expressions. */
+  function renameInExpression(node) {
+    if (!node) return false;
+    let changed = false;
+    if (node.type === 'StringLiteral' || node.type === 'Literal') {
+      changed = renameStringLiteral(node) || changed;
+    } else if (node.type === 'ConditionalExpression') {
+      changed = renameInExpression(node.consequent) || changed;
+      changed = renameInExpression(node.alternate) || changed;
+    } else if (node.type === 'LogicalExpression') {
+      changed = renameInExpression(node.left) || changed;
+      changed = renameInExpression(node.right) || changed;
+    } else if (node.type === 'TSAsExpression') {
+      // `'default' as const` → rewrite the inner expression
+      changed = renameInExpression(node.expression) || changed;
+    }
+    return changed;
+  }
+
+  // --- 1. JSX attribute: labelSpacing="default" / labelSpacing={'default'} on Switch ---
+  root.find(j.JSXOpeningElement).forEach(path => {
+    const name = path.node.name;
+    const componentName = name.type === 'JSXIdentifier' ? name.name : null;
+    if (!componentName || !TARGET_COMPONENTS.has(componentName)) return;
+
+    path.node.attributes.forEach(attr => {
+      if (attr.type !== 'JSXAttribute') return;
+      if (!attr.name || attr.name.name !== TARGET_PROP) return;
+
+      const value = attr.value;
+      if (!value) return;
+
+      if (value.type === 'StringLiteral' || value.type === 'Literal') {
+        if (renameStringLiteral(value)) hasChanges = true;
+      } else if (value.type === 'JSXExpressionContainer') {
+        if (renameInExpression(value.expression)) hasChanges = true;
+      }
+    });
+  });
+
+  // Object-property / argTypes transforms only run in files that use a target
+  // component — keeps unrelated `{ labelSpacing: 'default' }` strings safe.
+  const importsTarget =
+    root
+      .find(j.ImportSpecifier)
+      .filter(p => TARGET_COMPONENTS.has(p.node.imported?.name))
+      .size() > 0;
+
+  if (importsTarget) {
+    const PropertyType = j.ObjectProperty ?? j.Property;
+
+    // --- 2. Object property: { labelSpacing: 'default' } / 'default' as const ---
+    root.find(PropertyType, {key: {name: TARGET_PROP}}).forEach(path => {
+      if (renameInExpression(path.node.value)) hasChanges = true;
+    });
+
+    // --- 3. Storybook argTypes: labelSpacing: { options: [..., 'default', ...] } ---
+    root.find(PropertyType, {key: {name: TARGET_PROP}}).forEach(path => {
+      const value = path.node.value;
+      if (!value || value.type !== 'ObjectExpression') return;
+
+      const optionsProp = value.properties.find(
+        p => p.key && (p.key.name === 'options' || p.key.value === 'options'),
+      );
+      if (optionsProp && optionsProp.value.type === 'ArrayExpression') {
+        optionsProp.value.elements.forEach(el => {
+          if (renameStringLiteral(el)) hasChanges = true;
+        });
+      }
+    });
+  }
+
+  if (!hasChanges) return undefined;
+  return root.toSource({quote: 'single'});
+}

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)
  */
 
@@ -29,7 +30,8 @@ import {ERROR_CODES} from '../lib/error-codes.mjs';
 
 const AGENTS_MD = 'AGENTS.md';
 const CLAUDE_MD = 'CLAUDE.md';
-const CLAUDE_DIR_MD = path.join('.claude', 'CLAUDE.md');
+const CLAUDE_DIR_MD = '.claude/CLAUDE.md'; // cross-platform literal
+
 
 const MARKER_START = '<!-- ASTRYX:START -->';
 const MARKER_END = '<!-- ASTRYX:END -->';
@@ -45,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],
 };
 
 /**
@@ -63,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) {
@@ -385,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
@@ -467,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.color-scheme.test.mjs

@@ -0,0 +1,153 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Regression test for the `color-scheme` declaration `astryx theme build`
+ * emits alongside `light-dark()` token output (see #3658).
+ *
+ * `astryx theme build` injects a `color-scheme` declaration into
+ * `@layer astryx-theme` whenever the generated CSS contains `light-dark()`,
+ * so LightningCSS/browsers can resolve it. That declaration must mirror
+ * reset.css's own `html[data-theme]` -> `color-scheme` mapping (a bare
+ * `:root { color-scheme: light dark; }` alone permanently pins the page to
+ * "light dark", defeating `<Theme mode="light|dark">` forcing regardless of
+ * `@layer astryx-theme` being declared after `@layer reset` in layer order):
+ *
+ *   :root { color-scheme: light dark; }
+ *   html[data-theme="light"] { color-scheme: light; }
+ *   html[data-theme="dark"] { color-scheme: dark; }
+ *
+ * Themes that never use `light-dark()` have no `color-scheme` ambiguity to
+ * resolve, so none of the three rules should be emitted for them.
+ *
+ * Building `astryx theme build` requires a compiled @astryxdesign/core (there is no in-CLI
+ * fallback generator), so this suite builds core once in beforeAll via the
+ * shared ensureCoreBuilt() helper — which serializes concurrent Vitest workers
+ * behind a lock — to stay self-sufficient regardless of CI job ordering.
+ */
+
+import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {fileURLToPath} from 'node:url';
+import {ensureCoreBuilt} from './ensure-core-built.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
+
+const COLOR_SCHEME_ROOT_DECL = ':root { color-scheme: light dark; }';
+const COLOR_SCHEME_LIGHT_DECL = 'html[data-theme="light"] { color-scheme: light; }';
+const COLOR_SCHEME_DARK_DECL = 'html[data-theme="dark"] { color-scheme: dark; }';
+
+function runCli(args, cwd) {
+  try {
+    const out = execFileSync('node', [CLI_BIN, ...args], {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: {...process.env, FORCE_COLOR: '0'},
+    });
+    return {code: 0, stdout: out, stderr: ''};
+  } catch (e) {
+    return {
+      code: e.status ?? 1,
+      stdout: e.stdout?.toString() ?? '',
+      stderr: e.stderr?.toString() ?? '',
+    };
+  }
+}
+
+function writeTheme(dir, name, tokens) {
+  fs.mkdirSync(dir, {recursive: true});
+  // The CLI writes <basename>.css next to the source file, so use the
+  // theme name as the filename for unambiguous fixtures.
+  const file = path.join(dir, `${name}.mjs`);
+  fs.writeFileSync(
+    file,
+    `export default { name: ${JSON.stringify(name)}, tokens: ${JSON.stringify(tokens)} };\n`,
+  );
+  return file;
+}
+
+// `astryx theme build` imports the compiled @astryxdesign/core/theme entry. Build core
+// once if it isn't already present so the suite works in any CI job.
+beforeAll(() => {
+  ensureCoreBuilt();
+}, 200_000);
+
+let tmpDir;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-build-theme-color-scheme-'));
+});
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('theme build color-scheme output', () => {
+  it('emits the mode-aware color-scheme rules in @layer astryx-theme for a light-dark() theme', () => {
+    const project = path.join(tmpDir, 'project');
+    const themesDir = path.join(project, 'themes');
+    // A raw light-dark() token value is what triggers the color-scheme
+    // injection in build-theme.mjs (it checks the generated CSS for the
+    // literal substring). `defineTheme.test.ts` already covers the separate
+    // [light, dark] tuple -> light-dark() conversion; this fixture writes
+    // the string directly so this test stays focused on the CLI's own
+    // color-scheme decision, not on that conversion.
+    const themeFile = writeTheme(themesDir, 'with-light-dark', {
+      '--color-accent': 'light-dark(#0077B6, #48CAE4)',
+    });
+
+    const result = runCli(
+      ['theme', 'build', path.relative(project, themeFile)],
+      project,
+    );
+
+    expect(result.code).toBe(0);
+
+    const cssPath = path.join(themesDir, 'with-light-dark.css');
+    expect(fs.existsSync(cssPath)).toBe(true);
+    const css = fs.readFileSync(cssPath, 'utf-8');
+
+    expect(css).toContain('light-dark(#0077B6, #48CAE4)');
+
+    // All 3 rules must be present...
+    expect(css).toContain(COLOR_SCHEME_ROOT_DECL);
+    expect(css).toContain(COLOR_SCHEME_LIGHT_DECL);
+    expect(css).toContain(COLOR_SCHEME_DARK_DECL);
+
+    // ...and specifically inside @layer astryx-theme, not @layer reset (the
+    // declaration must sit alongside the light-dark() token/component output
+    // it resolves, not the zero-specificity prose defaults).
+    const themeLayerStart = css.indexOf('@layer astryx-theme');
+    expect(themeLayerStart).toBeGreaterThanOrEqual(0);
+    const themeLayerBody = css.slice(themeLayerStart);
+    expect(themeLayerBody).toContain(COLOR_SCHEME_ROOT_DECL);
+    expect(themeLayerBody).toContain(COLOR_SCHEME_LIGHT_DECL);
+    expect(themeLayerBody).toContain(COLOR_SCHEME_DARK_DECL);
+  });
+
+  it('omits all color-scheme rules for a theme with no light-dark() tokens', () => {
+    const project = path.join(tmpDir, 'project');
+    const themesDir = path.join(project, 'themes');
+    const themeFile = writeTheme(themesDir, 'no-light-dark', {
+      '--color-accent': '#0077B6',
+    });
+
+    const result = runCli(
+      ['theme', 'build', path.relative(project, themeFile)],
+      project,
+    );
+
+    expect(result.code).toBe(0);
+
+    const cssPath = path.join(themesDir, 'no-light-dark.css');
+    expect(fs.existsSync(cssPath)).toBe(true);
+    const css = fs.readFileSync(cssPath, 'utf-8');
+
+    expect(css).not.toContain('light-dark(');
+    expect(css).not.toContain(COLOR_SCHEME_ROOT_DECL);
+    expect(css).not.toContain(COLOR_SCHEME_LIGHT_DECL);
+    expect(css).not.toContain(COLOR_SCHEME_DARK_DECL);
+  });
+});

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;
 `;
 }
@@ -846,8 +939,9 @@ export function registerTheme(program) {
         if (component.length > 0) {
           const componentInner = component.join('\n\n');
           const componentScope = `@scope (${scopeSelector}) to (${scopeTo}) {\n${componentInner}\n}`;
+          // #3658: also emit attribute-specific rules so <Theme mode> can override color-scheme
           const colorSchemeDecl = componentScope.includes('light-dark(')
-            ? '  :root { color-scheme: light dark; }\n\n'
+            ? '  :root { color-scheme: light dark; }\n  html[data-theme="light"] { color-scheme: light; }\n  html[data-theme="dark"] { color-scheme: dark; }\n\n'
             : '';
           cssParts.push(
             `@layer astryx-theme {\n${colorSchemeDecl}${componentScope}\n}`,
@@ -894,19 +988,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