@astryxdesign/cli 0.1.4-canary.d5cbae3 → 0.1.4-canary.d7c9a39

package/docs/styling.doc.mjs

@@ -344,7 +344,7 @@ const styles = stylex.create({
       content: [
         {
           type: 'prose',
-          text: 'Astryx components ship pre-compiled, so consuming the published package needs no StyleX setup. But `astryx swizzle <Component>` copies the raw StyleX *source* into your app, and StyleX source requires a build-time StyleX compiler to produce atomic CSS. Without one the component compiles but renders completely unstyled — no error, no warning. If a swizzled component looks unstyled, a missing StyleX compiler is almost always why. The same applies if you author your own StyleX with `stylex.create()`.',
+          text: 'Astryx components ship pre-compiled, so consuming the published package needs no StyleX setup. But `astryx swizzle <Component>` copies the raw StyleX *source* into your app, and StyleX source requires a build-time StyleX compiler to produce atomic CSS. Without one the component compiles but renders completely unstyled: no error, no warning. If a swizzled component looks unstyled, a missing StyleX compiler is almost always why. The same applies if you author your own StyleX with `stylex.create()`.',
         },
         {
           type: 'table',
@@ -353,12 +353,12 @@ const styles = stylex.create({
             ['Webpack', '@stylexjs/webpack-plugin'],
             ['Vite / Rollup', '@stylexjs/rollup-plugin (or a community Vite plugin)'],
             ['Babel (any bundler)', '@stylexjs/babel-plugin + @stylexjs/postcss-plugin'],
-            ['Next.js (App Router, SWC)', 'An SWC-based transform — see the Next.js note below'],
+            ['Next.js (App Router, SWC)', 'An SWC-based transform; see the Next.js note below'],
           ],
         },
         {
           type: 'prose',
-          text: 'Next.js (App Router) is the sharp edge. StyleX\u2019s canonical compiler is a Babel plugin, but introducing a Babel config in Next.js disables the SWC compiler, which in turn breaks SWC-dependent features like `next/font`. So the "obvious" Babel setup is actively incompatible with a standard Next 15 App Router app.',
+          text: 'Next.js (App Router) is the sharp edge. StyleX\'s canonical compiler is a Babel plugin, but introducing a Babel config in Next.js disables the SWC compiler, which in turn breaks SWC-dependent features like `next/font`. So the "obvious" Babel setup is actively incompatible with a standard Next 15 App Router app.',
         },
         {
           type: 'prose',
@@ -367,7 +367,7 @@ const styles = stylex.create({
         {
           type: 'code',
           lang: 'js',
-          label: 'next.config.mjs — SWC-based StyleX transform (keeps next/font working)',
+          label: 'next.config.mjs: SWC-based StyleX transform (keeps next/font working)',
           code: `import stylexPlugin from '@stylexswc/nextjs-plugin';
 
 export default stylexPlugin({
@@ -385,8 +385,8 @@ export default stylexPlugin({
           style: 'unordered',
           items: [
             'Symptom of a missing compiler: swizzled component renders with no styles, but no build or runtime error.',
-            'Do NOT add @stylexjs/babel-plugin to a Next.js App Router app — it disables SWC and breaks next/font.',
-            'Pure theming (defineTheme + astryx theme build) needs NO StyleX compiler — only swizzled/authored StyleX source does.',
+            'Do NOT add @stylexjs/babel-plugin to a Next.js App Router app; it disables SWC and breaks next/font.',
+            'Pure theming (defineTheme + astryx theme build) needs NO StyleX compiler; only swizzled/authored StyleX source does.',
           ],
         },
       ],

package/docs/working-with-ai.doc.mjs

@@ -125,7 +125,7 @@ If you don't know all three, run \`npx astryx init --features agents\` to genera
           lang: 'json',
           label: 'package.json',
           code: `"scripts": {
-  "xds": "node node_modules/@astryxdesign/cli/bin/astryx.mjs"
+  "astryx": "node node_modules/@astryxdesign/cli/bin/astryx.mjs"
 }`,
         },
         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.4-canary.d5cbae3",
+  "version": "0.1.4-canary.d7c9a39",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -68,17 +68,17 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@clack/prompts": "^1.5.1",
+    "@clack/prompts": "^1.7.0",
     "commander": "^12.1.0",
     "jiti": "^2.7.0",
     "jscodeshift": "^17.3.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.1.4-canary.d5cbae3",
-    "@astryxdesign/core": "0.1.4-canary.d5cbae3",
-    "@astryxdesign/lab": "0.1.4-canary.d5cbae3",
-    "@astryxdesign/theme-neutral": "0.1.4-canary.d5cbae3",
+    "@astryxdesign/charts": "0.1.4-canary.d7c9a39",
+    "@astryxdesign/core": "0.1.4-canary.d7c9a39",
+    "@astryxdesign/lab": "0.1.4-canary.d7c9a39",
+    "@astryxdesign/theme-neutral": "0.1.4-canary.d7c9a39",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -96,10 +96,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.1.4-canary.d5cbae3",
-    "@astryxdesign/core": "0.1.4-canary.d5cbae3",
-    "@astryxdesign/lab": "0.1.4-canary.d5cbae3",
-    "@astryxdesign/theme-neutral": "0.1.4-canary.d5cbae3",
+    "@astryxdesign/charts": "0.1.4-canary.d7c9a39",
+    "@astryxdesign/core": "0.1.4-canary.d7c9a39",
+    "@astryxdesign/lab": "0.1.4-canary.d7c9a39",
+    "@astryxdesign/theme-neutral": "0.1.4-canary.d7c9a39",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {

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

@@ -19,6 +19,7 @@ describe('registry', () => {
         '0.1.0',
         '0.1.2',
         '0.1.3',
+        '0.1.5',
       ]);
     });
   });

package/src/codemods/registry.mjs

@@ -20,6 +20,7 @@ const registry = new Map([
   ['0.1.0', () => import('./transforms/v0.1.0/index.mjs')],
   ['0.1.2', () => import('./transforms/v0.1.2/index.mjs')],
   ['0.1.3', () => import('./transforms/v0.1.3/index.mjs')],
+  ['0.1.5', () => import('./transforms/v0.1.5/index.mjs')],
 ]);
 
 // Re-export from the shared utility so registry callers and other consumers

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

@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source) {
+  const {default: transform} =
+    await import('../rename-switch-label-spacing-default-to-hug.mjs');
+  const jscodeshift = (await import('jscodeshift')).default;
+  const j = jscodeshift.withParser('tsx');
+  const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+  const file = {source, path: 'test.tsx'};
+  const result = transform(file, api);
+  return result ?? source;
+}
+
+describe('rename-switch-label-spacing-default-to-hug', () => {
+  it('renames Switch labelSpacing="default" to labelSpacing="hug"', async () => {
+    const input = `<Switch label="Notify" value={on} labelSpacing="default" />`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'hug'");
+    expect(output).not.toContain('default');
+  });
+
+  it("renames expression-container labelSpacing={'default'}", async () => {
+    const input = `<Switch label="Notify" value={on} labelSpacing={'default'} />`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'hug'");
+    expect(output).not.toContain("'default'");
+  });
+
+  it('renames default inside a ternary labelSpacing expression', async () => {
+    const input = `<Switch label="Notify" value={on} labelSpacing={isRow ? 'spread' : 'default'} />`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'hug'");
+    expect(output).toContain("'spread'");
+    expect(output).not.toContain("'default'");
+  });
+
+  it('does not change labelSpacing="spread"', async () => {
+    const input = `<Switch label="Notify" value={on} labelSpacing="spread" />`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('does not touch labelSpacing="default" on non-Switch components', async () => {
+    const input = `<LegacyToggle labelSpacing="default" />`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('does not touch other props with a "default" value on Switch', async () => {
+    const input = `<Switch label="Notify" value={on} data-variant="default" />`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('does not touch unrelated "default" string literals', async () => {
+    const input = `const theme = {mode: 'default', label: 'Default Mode'};`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('renames object labelSpacing prop in files importing Switch', async () => {
+    const input = `import {Switch} from '@astryxdesign/core/Switch';
+const cfg = {labelSpacing: 'default'};`;
+    const output = await applyTransform(input);
+    expect(output).toContain("labelSpacing: 'hug'");
+    expect(output).not.toContain("'default'");
+  });
+
+  it("renames labelSpacing: 'default' as const in files importing Switch", async () => {
+    const input = `import {Switch} from '@astryxdesign/core/Switch';
+const ROWS = [{labelSpacing: 'default' as const, label: 'Adjacent'}];`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'hug' as const");
+    expect(output).not.toContain("'default'");
+  });
+
+  it('does not rename object labelSpacing prop when Switch is not imported', async () => {
+    const input = `const cfg = {labelSpacing: 'default'};`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('renames Storybook argTypes options in files importing Switch', async () => {
+    const input = `import {Switch} from '@astryxdesign/core/Switch';
+const meta = {argTypes: {labelSpacing: {control: 'select', options: ['default', 'spread']}}};`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'hug'");
+    expect(output).toContain("'spread'");
+    expect(output).not.toContain("'default'");
+  });
+});

package/src/codemods/transforms/v0.1.5/index.mjs

@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file v0.1.5 transform manifest
+ *
+ * Lists all codemods for the v0.1.5 release in the order they should run.
+ */
+
+import renameSwitchLabelSpacingDefaultToHug, {
+  meta as renameSwitchLabelSpacingDefaultToHugMeta,
+} from './rename-switch-label-spacing-default-to-hug.mjs';
+
+export default [
+  {
+    name: 'rename-switch-label-spacing-default-to-hug',
+    transform: renameSwitchLabelSpacingDefaultToHug,
+    meta: renameSwitchLabelSpacingDefaultToHugMeta,
+  },
+];

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/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

@@ -939,8 +939,15 @@ export function registerTheme(program) {
         if (component.length > 0) {
           const componentInner = component.join('\n\n');
           const componentScope = `@scope (${scopeSelector}) to (${scopeTo}) {\n${componentInner}\n}`;
+          // light-dark() needs a color-scheme declaration in this bundle, but a
+          // bare `:root { color-scheme: light dark }` outranks reset.css's
+          // `html[data-theme]` mapping (astryx-theme layer comes after reset),
+          // silently defeating `<Theme mode>` forcing on <html>. Mirror the
+          // attribute-keyed mapping so the declaration follows the active mode.
           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}`,

package/src/commands/build-theme.variants.test.mjs

@@ -28,20 +28,10 @@ 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 REPO_ROOT = path.resolve(__dirname, '../../../..');
-const CORE_THEME_ENTRY = path.join(
-  REPO_ROOT,
-  'packages/core/dist/theme/index.js',
-);
-// The fix reads core's shipped component declarations to decide whether an
-// interface is augmentable; those .d.ts files come from the same core build.
-const CORE_BUTTON_DTS = path.join(
-  REPO_ROOT,
-  'packages/core/dist/Button/index.d.ts',
-);
 
 function runCli(args, cwd) {
   try {
@@ -68,14 +58,13 @@ function writeTheme(dir, contents) {
   return file;
 }
 
+// Build core through the shared lock helper — this suite previously ran its
+// own unguarded `if (!exists) pnpm -F core build`, and when Vitest scheduled
+// it alongside the other build-theme suites on a fresh checkout, the
+// concurrent builds collided on packages/core/dist (core's build starts by
+// wiping dist), nondeterministically breaking whichever suite was mid-read.
 beforeAll(() => {
-  if (!fs.existsSync(CORE_THEME_ENTRY) || !fs.existsSync(CORE_BUTTON_DTS)) {
-    execFileSync('pnpm', ['-F', '@astryxdesign/core', 'build'], {
-      cwd: REPO_ROOT,
-      stdio: 'pipe',
-      timeout: 180_000,
-    });
-  }
+  ensureCoreBuilt();
 }, 200_000);
 
 let tmpDir;

package/templates/blocks/components/Collapsible/CollapsibleWithoutCard.tsx

@@ -2,34 +2,36 @@
 
 'use client';
 
-import {Collapsible} from '@astryxdesign/core/Collapsible';
+import {Collapsible, CollapsibleGroup} from '@astryxdesign/core/Collapsible';
 import {Divider} from '@astryxdesign/core/Divider';
 import {Text} from '@astryxdesign/core/Text';
 import {VStack} from '@astryxdesign/core/Layout';
 
 export default function CollapsibleWithoutCard() {
   return (
-    <VStack gap={3} style={{width: '100%', maxWidth: 400}}>
-      <Collapsible trigger="Deployment Details">
-        <Text type="body">
-          Last deployed on April 18, 2026 at 3:42 PM by Sarah Chen. Build
-          duration was 2m 14s with zero warnings.
-        </Text>
-      </Collapsible>
-      <Divider />
-      <Collapsible trigger="Environment Variables" defaultIsOpen={false}>
-        <Text type="body">
-          12 variables configured. Last updated March 30, 2026. All secrets are
-          encrypted at rest with AES-256.
-        </Text>
-      </Collapsible>
-      <Divider />
-      <Collapsible trigger="Build Logs" defaultIsOpen={false}>
-        <Text type="body">
-          Build completed successfully. 847 modules compiled, 0 errors, 0
-          warnings. Bundle size: 142 KB gzipped.
-        </Text>
-      </Collapsible>
-    </VStack>
+    <CollapsibleGroup type="single" defaultValue="deployment">
+      <VStack gap={3} style={{width: '100%', maxWidth: 400}}>
+        <Collapsible trigger="Deployment Details" value="deployment">
+          <Text type="body">
+            Last deployed on April 18, 2026 at 3:42 PM by Sarah Chen. Build
+            duration was 2m 14s with zero warnings.
+          </Text>
+        </Collapsible>
+        <Divider />
+        <Collapsible trigger="Environment Variables" value="environment">
+          <Text type="body">
+            12 variables configured. Last updated March 30, 2026. All secrets
+            are encrypted at rest with AES-256.
+          </Text>
+        </Collapsible>
+        <Divider />
+        <Collapsible trigger="Build Logs" value="logs">
+          <Text type="body">
+            Build completed successfully. 847 modules compiled, 0 errors, 0
+            warnings. Bundle size: 142 KB gzipped.
+          </Text>
+        </Collapsible>
+      </VStack>
+    </CollapsibleGroup>
   );
 }

package/templates/pages/classic-gallery/page.tsx

@@ -110,7 +110,7 @@ export default function ClassicGalleryTemplate() {
 
   return (
     <Layout
-      height="auto"
+      height="fill"
       content={
         <LayoutContent padding={0}>
           <Center axis="horizontal">

package/templates/pages/dashboard/page.tsx

@@ -729,7 +729,7 @@ function TableCard<T extends {id: string}>({
 export default function DashboardTemplate() {
   return (
     <Layout
-      height="auto"
+      height="fill"
       content={
         <LayoutContent padding={6}>
           <VStack gap={6}>

package/templates/pages/documentation/page.tsx

@@ -209,7 +209,7 @@ const COMPONENT_CATEGORIES = [
 export default function DocumentationOverviewPage() {
   return (
     <Layout
-      height="auto"
+      height="fill"
       contentWidth={1200}
       content={
         <LayoutContent padding={8}>

package/templates/pages/incident-console/template.doc.mjs

@@ -6,7 +6,7 @@ export const doc = {
   name: 'Incident Console',
   displayName: 'Incident Console',
   description:
-    'On-call incident response console: grouped dense incident rows with severity dots, PowerSearch filtering, status segmented control, and a resizable inspector panel with metadata and timeline. Frame-first tracker archetype — rows, not cards.',
+    'On-call incident response console: grouped dense incident rows with severity dots, PowerSearch filtering, status segmented control, and a resizable inspector panel with metadata and timeline. Frame-first tracker archetype: rows, not cards.',
   isReady: false,
   category: 'Tools - Incident Console',
 };

package/templates/pages/messaging-shell/template.doc.mjs

@@ -6,7 +6,7 @@ export const doc = {
   name: 'Messaging Shell',
   displayName: 'Messaging Shell',
   description:
-    'Slack-style messaging shell with a four-column frame (workspace rail, channel sidebar, message stream, thread panel) built on the Chat component family — dense rows, zero cards.',
+    'Slack-style messaging shell with a four-column frame (workspace rail, channel sidebar, message stream, thread panel) built on the Chat component family: dense rows, zero cards.',
   isReady: false,
   category: 'Shell - Messaging',
 };

package/templates/pages/mixed-gallery/page.tsx

@@ -112,7 +112,7 @@ function GalleryCard({
 export default function MixedGalleryTemplate() {
   return (
     <Layout
-      height="auto"
+      height="fill"
       contentWidth={1400}
       content={
         <LayoutContent padding={6}>

package/templates/pages/payment-form/page.tsx

@@ -153,10 +153,6 @@ const fmt = (n: number) => `$${n.toFixed(2)}`;
 // :root by `@astryxdesign/core/astryx.css`). No StyleX compiler required.
 
 const fullWidth: CSSProperties = {width: '100%'};
-// LayoutContent clips overflow by default, which traps position:sticky
-// children (the sticky order summary). With height="auto" the page scrolls
-// at the window, so let overflow be visible here so sticky can pin.
-const visibleOverflow: CSSProperties = {overflow: 'visible'};
 // Form column flex-basis so the two checkout columns share width evenly.
 const formColBasis: CSSProperties = {flexBasis: 0};
 // Space the Order Summary content below its collapsible trigger title.
@@ -266,9 +262,9 @@ export default function PaymentFormPage() {
 
   return (
     <Layout
-      height="auto"
+      height="fill"
       content={
-        <LayoutContent padding={0} style={visibleOverflow}>
+        <LayoutContent padding={0}>
           <Center axis="horizontal">
             <Section
               variant="transparent"

package/templates/pages/product-detail/page.tsx

@@ -3,12 +3,7 @@
 'use client';
 
 import {useState} from 'react';
-import {
-  VStack,
-  HStack,
-  Layout,
-  LayoutContent,
-} from '@astryxdesign/core/Layout';
+import {VStack, HStack, Layout, LayoutContent} from '@astryxdesign/core/Layout';
 import {Center} from '@astryxdesign/core/Center';
 import {Grid} from '@astryxdesign/core/Grid';
 import {Text, Heading} from '@astryxdesign/core/Text';
@@ -203,10 +198,7 @@ function ProductInfo() {
       <VStack gap={2}>
         <Text type="label">Finish</Text>
         <VStack hAlign="start">
-          <SegmentedControl
-            value={finish}
-            onChange={setFinish}
-            label="Finish">
+          <SegmentedControl value={finish} onChange={setFinish} label="Finish">
             {FINISHES.map(f => (
               <SegmentedControlItem
                 key={f.value}
@@ -286,7 +278,7 @@ export default function ProductDetailTemplate() {
 
   return (
     <Layout
-      height="auto"
+      height="fill"
       contentWidth={1200}
       content={
         <LayoutContent padding={6}>

package/templates/pages/product-gallery/page.tsx

@@ -119,7 +119,7 @@ function ProductCard({product}: {product: Product}) {
 export default function ProductGalleryTemplate() {
   return (
     <Layout
-      height="auto"
+      height="fill"
       contentWidth={1200}
       content={
         <LayoutContent padding={6}>

package/templates/pages/settings/page.tsx

@@ -70,7 +70,7 @@ export default function SettingsTemplate() {
 
   return (
     <Layout
-      height="auto"
+      height="fill"
       contentWidth={1440}
       header={
         <LayoutHeader hasDivider>

package/templates/pages/side-gallery/page.tsx

@@ -101,7 +101,7 @@ function ImageGrid() {
 export default function SideGalleryTemplate() {
   return (
     <Layout
-      height="auto"
+      height="fill"
       contentWidth={1400}
       content={
         <LayoutContent padding={6}>

package/templates/pages/table-page/page.tsx

@@ -389,7 +389,7 @@ export default function TablePageTemplate() {
 
   return (
     <Layout
-      height="auto"
+      height="fill"
       header={
         <LayoutHeader hasDivider>
           <HStack gap={2} vAlign="center">

package/templates/pages/table-page-chart/page.tsx

@@ -513,7 +513,7 @@ const columns: TableColumn<OrderRow>[] = [
 export default function TablePageChartTemplate() {
   return (
     <Layout
-      height="auto"
+      height="fill"
       header={
         <LayoutHeader hasDivider>
           <HStack gap={2} vAlign="center">

package/templates/pages/table-page-heatmap-status/page.tsx

@@ -430,7 +430,7 @@ function OutageHeatmap() {
 export default function TablePageHeatmapStatusTemplate() {
   return (
     <Layout
-      height="auto"
+      height="fill"
       header={
         <LayoutHeader hasDivider>
           <HStack gap={2} vAlign="center">

package/templates/pages/table-page-shoe-store-heatmap/page.tsx

@@ -867,7 +867,7 @@ const columns: TableColumn<OrderRow>[] = [
 export default function TablePageShoeStoreHeatmapTemplate() {
   return (
     <Layout
-      height="auto"
+      height="fill"
       header={
         <LayoutHeader hasDivider>
           <HStack gap={2} vAlign="center">