@astryxdesign/cli 0.3.0-canary.ec85ba0 → 0.3.0-canary.f4607ea

package/api/theme/build/build.d.mts

@@ -21,13 +21,18 @@ export function importSpecifier(relDir: string, base: string): string;
  * `logger` (silent by default).
  *
  * @param {string} file - Theme file path, resolved against `cwd`.
- * @param {{out?: string, check?: boolean}} [options] - `out` overrides the output CSS path; `check` compares against on-disk outputs instead of writing.
+ * @param {{out?: string, check?: boolean, iconsSpecifier?: string}} [options] -
+ *   `out` overrides the output CSS path; `check` compares against on-disk outputs
+ *   instead of writing. `iconsSpecifier` overrides the icon registry import
+ *   specifier in the generated module (e.g. `./icons.mjs`); when omitted, the
+ *   specifier scraped from the theme source is emitted unchanged.
  * @param {{cwd?: string}} [ctx]
  * @returns {Promise<import('../theme.type.mjs').ThemeBuildResponse | import('../theme.type.mjs').ThemeBuildCheckResponse | null>}
  */
 export function themeBuild(file: string, options?: {
     out?: string;
     check?: boolean;
+    iconsSpecifier?: string;
 }, { cwd }?: {
     cwd?: string;
 }): Promise<import("../theme.type.mjs").ThemeBuildResponse | import("../theme.type.mjs").ThemeBuildCheckResponse | null>;

package/api/theme/build/build.mjs

@@ -726,13 +726,30 @@ function extractIconInfo(filePath) {
  * Generate a minimal JS module for a built theme.
  * Includes the theme name, marker, and re-exports the icon registry.
  * All styling is in the CSS file.
+ *
+ * The icon registry is imported rather than inlined because it holds React
+ * elements, which cannot be serialized. `extractIconInfo` lifts the specifier
+ * out of the TypeScript source, where an extensionless `./icons` is resolved by
+ * the TypeScript resolver — but the artifact here is ESM JavaScript, which
+ * requires a fully specified path. Only the caller knows what its own build
+ * will emit and under what name, so `iconsSpecifier` lets it say. When it is
+ * not given, the scraped specifier is emitted unchanged.
+ *
  * @param {any} themeDef
  * @param {{exportName: string, importPath: string} | null} iconInfo
+ * @param {string} [iconsSpecifier] - Overrides the scraped icon import specifier.
  * @returns {string}
  */
-function generateBuiltModule(themeDef, iconInfo) {
+function generateBuiltModule(themeDef, iconInfo, iconsSpecifier) {
+  // Preserve the historical generated bytes when no override is supplied.
+  // User-provided specifiers need string-literal encoding so quotes and
+  // backslashes cannot produce invalid JavaScript.
+  const renderedSpecifier =
+    iconsSpecifier === undefined
+      ? `'${iconInfo?.importPath}'`
+      : JSON.stringify(iconsSpecifier);
   const iconImport = iconInfo
-    ? `import { ${iconInfo.exportName} } from '${iconInfo.importPath}';\n`
+    ? `import { ${iconInfo.exportName} } from ${renderedSpecifier};\n`
     : '';
   const iconsField = iconInfo ? `  icons: ${iconInfo.exportName},` : '';
   const iconReExport = iconInfo ? `\nexport { ${iconInfo.exportName} };\n` : '';
@@ -970,7 +987,11 @@ function validatePrivateVars(themeDef) {
  * `logger` (silent by default).
  *
  * @param {string} file - Theme file path, resolved against `cwd`.
- * @param {{out?: string, check?: boolean}} [options] - `out` overrides the output CSS path; `check` compares against on-disk outputs instead of writing.
+ * @param {{out?: string, check?: boolean, iconsSpecifier?: string}} [options] -
+ *   `out` overrides the output CSS path; `check` compares against on-disk outputs
+ *   instead of writing. `iconsSpecifier` overrides the icon registry import
+ *   specifier in the generated module (e.g. `./icons.mjs`); when omitted, the
+ *   specifier scraped from the theme source is emitted unchanged.
  * @param {{cwd?: string}} [ctx]
  * @returns {Promise<import('../theme.type.mjs').ThemeBuildResponse | import('../theme.type.mjs').ThemeBuildCheckResponse | null>}
  */
@@ -1185,7 +1206,11 @@ export async function themeBuild(
     generatedHeader(sourceRelative, 'css', buildCommand, versions) + css;
   const jsContent =
     generatedHeader(sourceRelative, 'js', buildCommand, versions) +
-    generateBuiltModule(resolvedTheme || themeDef, iconInfo);
+    generateBuiltModule(
+      resolvedTheme || themeDef,
+      iconInfo,
+      options.iconsSpecifier,
+    );
   const dtsContent =
     generatedHeader(sourceRelative, 'ts', buildCommand, versions) +
     generateBuiltTypes(themeDef, iconInfo, variantsFileName);

package/api/theme/themeBuild.doc.mjs

@@ -19,11 +19,13 @@ export const doc = {
     "via @astryxdesign/core's shared generator (the single source of truth, so the build " +
     'emits the exact CSS the <Theme> runtime does), writes a scoped CSS file, a JS module ' +
     'that re-exports the built theme, and a .d.ts (plus an optional .variants.d.ts when the ' +
-    'theme adds custom prop values). With {check: true} it writes nothing and instead compares ' +
+    'theme adds custom prop values). When another build step emits the icon registry, ' +
+    '{iconsSpecifier} declares the fully specified module path for the generated JS import. ' +
+    'With {check: true} it writes nothing and instead compares ' +
     'each output against disk, returning the drift: the CI guard for committed, generated theme CSS.',
   importPath: '@astryxdesign/cli/api',
   signature:
-    'themeBuild(file: string, options?: {out?: string, check?: boolean}, ctx?: {cwd?: string}): Promise<ThemeBuildResponse | ThemeBuildCheckResponse | null>',
+    'themeBuild(file: string, options?: {out?: string, check?: boolean, iconsSpecifier?: string}, ctx?: {cwd?: string}): Promise<ThemeBuildResponse | ThemeBuildCheckResponse | null>',
   keywords: [
     'theme',
     'build',
@@ -54,6 +56,12 @@ export const doc = {
         'Compile in memory and compare each output against what is on disk instead of writing: the CI drift guard.',
       default: 'false',
     },
+    {
+      name: 'options.iconsSpecifier',
+      type: 'string',
+      description:
+        'Override the icon-registry import specifier in the generated JS module, for example ./icons.mjs. When omitted, the source specifier is preserved.',
+    },
     {
       name: 'ctx.cwd',
       type: 'string',
@@ -102,6 +110,10 @@ export const doc = {
       label: 'Check for drift (CI)',
       code: "const r = await themeBuild('src/themes/ocean.ts', {check: true});",
     },
+    {
+      label: 'Use a separately compiled icon registry',
+      code: "const r = await themeBuild('src/themes/ocean.ts', {iconsSpecifier: './icons.mjs'});",
+    },
   ],
   command: 'theme build',
   related: ['themeAdd', 'themeList', 'listThemes'],

package/assets/codemods/transforms/next/__tests__/next-codemods.test.mjs

@@ -0,0 +1,92 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Unit tests for the staged (next-release) codemods.
+ *
+ * Mirrors v0.3.0/__tests__/next-codemods.test.mjs, which covers the codemods
+ * after promotion. Keeping a copy here means a staged transform is tested from
+ * the day it is written rather than the day it is released.
+ */
+
+import {describe, expect, it} from 'vitest';
+import jscodeshift from 'jscodeshift';
+
+const j = jscodeshift.withParser('tsx');
+const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+
+async function apply(name, source) {
+  const {default: transform} = await import(`../${name}.mjs`);
+  return transform({source, path: 'test.tsx'}, api) ?? source;
+}
+
+const TRANSFORM = 'rename-dropdown-menu-radio-dot-target';
+
+describe('rename-dropdown-menu-radio-dot-target', () => {
+  it('renames the theme target key in a defineTheme components map', async () => {
+    const input = `import {defineTheme} from '@astryxdesign/core/theme';
+export const theme = defineTheme({
+  name: 'brand',
+  components: {
+    'dropdown-menu-radio-dot': {base: {backgroundColor: 'var(--color-accent)'}},
+  },
+});`;
+    const output = await apply(TRANSFORM, input);
+    expect(output).toContain("'radio-indicator-dot':");
+    // The old name survives only inside the TODO comment the rename attaches.
+    expect(output).not.toContain("'dropdown-menu-radio-dot':");
+  });
+
+  it('warns that the new target is app-wide, not menu-only', async () => {
+    const input = `const components = {
+  'dropdown-menu-radio-dot': {base: {width: '10px'}},
+};`;
+    const output = await apply(TRANSFORM, input);
+    // The rename cannot preserve scope — there is no menu-only dot element
+    // left — so the author has to decide, and must be told.
+    expect(output).toContain('TODO(astryx upgrade)');
+    expect(output).toContain('EVERY radio dot');
+  });
+
+  it('renames the rendered class inside a selector string', async () => {
+    const input = `const sel = '.astryx-dropdown-menu-radio-dot';
+const nested = '.astryx-dropdown-menu-radio .astryx-dropdown-menu-radio-dot';`;
+    const output = await apply(TRANSFORM, input);
+    expect(output).toContain("'.astryx-radio-indicator-dot'");
+    expect(output).toContain(
+      '.astryx-dropdown-menu-radio .astryx-radio-indicator-dot',
+    );
+  });
+
+  it('renames the class inside a template literal', async () => {
+    const input =
+      'const css = `.astryx-dropdown-menu-radio-dot { background: ${c}; }`;';
+    const output = await apply(TRANSFORM, input);
+    expect(output).toContain('.astryx-radio-indicator-dot {');
+    expect(output).not.toContain('astryx-dropdown-menu-radio-dot');
+  });
+
+  it('leaves the surviving dropdown-menu-radio target alone', async () => {
+    // Only the DOT target was removed; the circle still carries the
+    // menu-specific target, so a theme keyed on it must not be rewritten.
+    const input = `const components = {
+  'dropdown-menu-radio': {base: {borderWidth: '2px'}},
+};`;
+    const output = await apply(TRANSFORM, input);
+    expect(output).toContain("'dropdown-menu-radio'");
+    expect(output).not.toContain('radio-indicator');
+    expect(output).not.toContain('TODO(astryx upgrade)');
+  });
+
+  it('is a no-op on files that never mention the target', async () => {
+    const input = `const components = {button: {base: {fontWeight: '600'}}};`;
+    expect(await apply(TRANSFORM, input)).toBe(input);
+  });
+
+  it('is idempotent', async () => {
+    const input = `const components = {
+  'dropdown-menu-radio-dot': {base: {width: '10px'}},
+};`;
+    const once = await apply(TRANSFORM, input);
+    expect(await apply(TRANSFORM, once)).toBe(once);
+  });
+});

package/assets/codemods/transforms/next/index.mjs

@@ -7,4 +7,14 @@
  * this file into the resolved version folder.
  */
 
-export default [];
+import renameDropdownMenuRadioDotTarget, {
+  meta as renameDropdownMenuRadioDotTargetMeta,
+} from './rename-dropdown-menu-radio-dot-target.mjs';
+
+export default [
+  {
+    name: 'rename-dropdown-menu-radio-dot-target',
+    transform: renameDropdownMenuRadioDotTarget,
+    meta: renameDropdownMenuRadioDotTargetMeta,
+  },
+];

package/assets/codemods/transforms/next/rename-dropdown-menu-radio-dot-target.mjs

@@ -0,0 +1,152 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: rename the removed `dropdown-menu-radio-dot` theme target
+ *
+ * The menu radio's dot is no longer drawn by DropdownMenuRadioItem. That row
+ * now renders the shared radio indicator, so its dot is the indicator's dot and
+ * carries `radio-indicator-dot` (plus the legacy `radio-dot`) instead of the
+ * menu-specific `dropdown-menu-radio-dot`, which is gone.
+ *
+ * Runtime themes are not validated: a theme keyed on the old target keeps
+ * compiling and simply stops matching, with no error anywhere. That silence is
+ * why this rename needs a codemod rather than a changelog line.
+ *
+ * The rename is NOT scope-preserving, and that cannot be fixed here — there is
+ * no menu-only dot element left to address. `radio-indicator-dot` reaches every
+ * radio dot in the app, including RadioList's. So every rewritten site also
+ * gets a TODO comment (api.report is a stub; comments are the only warning
+ * channel) telling the author to check whether the rule was meant to be
+ * menu-only, and pointing at the containing-target route if it was.
+ */
+
+export const meta = {
+  title: 'Rename the removed dropdown-menu-radio-dot theme target',
+  description:
+    'Renames the `dropdown-menu-radio-dot` theme target (and the ' +
+    '`astryx-dropdown-menu-radio-dot` class it rendered) to ' +
+    '`radio-indicator-dot` / `astryx-radio-indicator-dot`. Menu radios draw ' +
+    'the shared radio indicator now, so the menu-specific dot target no ' +
+    'longer exists. The new target is app-wide rather than menu-only, so each ' +
+    'rewritten site gets a TODO comment to confirm that widening is intended.',
+  pr: '#4712',
+};
+
+const OLD_TARGET = 'dropdown-menu-radio-dot';
+const NEW_TARGET = 'radio-indicator-dot';
+const OLD_CLASS = `astryx-${OLD_TARGET}`;
+const NEW_CLASS = `astryx-${NEW_TARGET}`;
+
+const TODO_COMMENT =
+  ' TODO(astryx upgrade): `dropdown-menu-radio-dot` became `radio-indicator-dot`,' +
+  ' which styles EVERY radio dot, not just the ones in a menu. If this rule was' +
+  ' meant to be menu-only, scope it under the containing `dropdown-menu-radio`' +
+  ' target instead of this one. ';
+
+/**
+ * Rewrite one string value, or return null when it holds nothing to rename.
+ *
+ * Handles the target name on its own (a theme's `components` key) and the
+ * rendered class inside a larger string (a selector such as
+ * `.astryx-dropdown-menu-radio-dot`, or a className list).
+ *
+ * @param {string} value
+ * @returns {string | null}
+ */
+function renameIn(value) {
+  if (value === OLD_TARGET) {
+    return NEW_TARGET;
+  }
+  if (value.includes(OLD_CLASS)) {
+    return value.split(OLD_CLASS).join(NEW_CLASS);
+  }
+  return null;
+}
+
+/**
+ * @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file
+ * @param {import('../../../../authoring/codemod/type').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
+export default function transformer(file, api) {
+  // Cheap bail-out: most files in a consumer repo mention neither name.
+  if (!file.source.includes(OLD_TARGET)) {
+    return undefined;
+  }
+
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  /** Attach the widening warning once to the nearest statement-ish node. */
+  function attachTodo(/** @type {any} */ path) {
+    // The property (or its statement) reads better than the bare literal, and
+    // matches where a human would look for the note.
+    const host =
+      path.parent?.node?.type === 'ObjectProperty' ||
+      path.parent?.node?.type === 'Property'
+        ? path.parent.node
+        : path.node;
+    if (!host.comments) {
+      host.comments = [];
+    }
+    if (
+      host.comments.some((/** @type {any} */ c) => c.value === TODO_COMMENT)
+    ) {
+      return;
+    }
+    host.comments.push(j.commentBlock(TODO_COMMENT, true, false));
+  }
+
+  root
+    .find(j.StringLiteral)
+    .forEach((/** @type {any} */ path) => {
+      const renamed = renameIn(path.node.value);
+      if (renamed == null) {
+        return;
+      }
+      path.node.value = renamed;
+      attachTodo(path);
+      hasChanges = true;
+    });
+
+  // Older parsers surface string literals as `Literal`.
+  root.find(j.Literal).forEach((/** @type {any} */ path) => {
+    if (typeof path.node.value !== 'string') {
+      return;
+    }
+    const renamed = renameIn(path.node.value);
+    if (renamed == null) {
+      return;
+    }
+    path.node.value = renamed;
+    if (typeof path.node.raw === 'string') {
+      path.node.raw = path.node.raw
+        .split(OLD_TARGET)
+        .join(NEW_TARGET);
+    }
+    attachTodo(path);
+    hasChanges = true;
+  });
+
+  // Template literals carry the class in CSS strings: `.${OLD_CLASS} > span`.
+  root.find(j.TemplateElement).forEach((/** @type {any} */ path) => {
+    const cooked = path.node.value?.cooked;
+    if (typeof cooked !== 'string') {
+      return;
+    }
+    const renamed = renameIn(cooked);
+    if (renamed == null) {
+      return;
+    }
+    path.node.value.cooked = renamed;
+    path.node.value.raw = path.node.value.raw
+      .split(OLD_CLASS)
+      .join(NEW_CLASS)
+      .split(OLD_TARGET)
+      .join(NEW_TARGET);
+    hasChanges = true;
+  });
+
+  return hasChanges ? root.toSource({quote: 'single'}) : undefined;
+}

package/assets/docs/getting-started.doc.mjs

@@ -21,7 +21,7 @@ export const docs = {
           type: 'code',
           lang: 'text',
           label: 'Paste this into your AI',
-          code: 'Install @astryxdesign/core, @astryxdesign/theme-neutral, and @astryxdesign/cli in this project, then run `npx @astryxdesign/cli init` to set up agent docs. Read the generated files to learn the conventions.',
+          code: 'Install @astryxdesign/core, @stylexjs/stylex, @astryxdesign/theme-neutral, and @astryxdesign/cli in this project, then run `npx @astryxdesign/cli init` to set up agent docs. Read the generated files to learn the conventions.',
         },
       ],
     },
@@ -34,13 +34,13 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'Add the core package, a theme, and the CLI to your existing project.',
+          text: 'Add the core package and its `@stylexjs/stylex` peer dependency, plus a theme and the CLI.',
         },
         {
           type: 'code',
           lang: 'bash',
           label: 'Terminal',
-          code: `npm install @astryxdesign/core @astryxdesign/theme-neutral @astryxdesign/cli`,
+          code: `npm install @astryxdesign/core @stylexjs/stylex @astryxdesign/theme-neutral @astryxdesign/cli`,
         },
         {
           type: 'prose',

package/assets/templates/blocks/components/Stepper/StepperHorizontal.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'Stepper',
+  name: 'Stepper — Horizontal Progress',
+  displayName: 'Stepper — Horizontal Progress',
+  description:
+    'A horizontal separated stepper: each step owns a segment of the progress bar above its label. Filled segments track how far the flow has progressed.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Stepper'],
+};

package/assets/templates/blocks/components/Stepper/StepperHorizontal.tsx

@@ -0,0 +1,24 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Stepper, Step} from '@astryxdesign/lab';
+
+export default function StepperHorizontal() {
+  const [active, setActive] = useState(1);
+  return (
+    <div style={{width: '100%', maxWidth: 600}}>
+      <Stepper
+        activeStep={active}
+        orientation="horizontal"
+        onStepClick={setActive}>
+        <Step step={0} label="Workspace" />
+        <Step step={1} label="Team" />
+        <Step step={2} label="Integrations" />
+        <Step step={3} label="Import" />
+        <Step step={4} label="Launch" />
+      </Stepper>
+    </div>
+  );
+}

package/assets/templates/blocks/components/Stepper/StepperIndicatorModes.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'Stepper',
+  name: 'Stepper — Indicator Modes',
+  displayName: 'Stepper — Indicator Modes',
+  description:
+    'The indicator prop side by side: auto (check when done, ring when current, number ahead), always-number, and a custom icon per step.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Stepper', 'Text', 'Icon'],
+};

package/assets/templates/blocks/components/Stepper/StepperIndicatorModes.tsx

@@ -0,0 +1,68 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Stepper, Step} from '@astryxdesign/lab';
+import {Text} from '@astryxdesign/core/Text';
+import {Icon} from '@astryxdesign/core/Icon';
+
+export default function StepperIndicatorModes() {
+  const [active, setActive] = useState(2);
+  return (
+    <div style={{display: 'flex', gap: 48, flexWrap: 'wrap'}}>
+      <div style={{maxWidth: 220}}>
+        <Text type="label">Auto</Text>
+        <Stepper
+          activeStep={active}
+          orientation="vertical"
+          onStepClick={setActive}>
+          <Step step={0} label="Account" />
+          <Step step={1} label="Profile" />
+          <Step step={2} label="Settings" />
+          <Step step={3} label="Review" />
+        </Stepper>
+      </div>
+      <div style={{maxWidth: 220}}>
+        <Text type="label">Number</Text>
+        <Stepper
+          activeStep={active}
+          orientation="vertical"
+          onStepClick={setActive}>
+          <Step step={0} label="Account" indicator="number" />
+          <Step step={1} label="Profile" indicator="number" />
+          <Step step={2} label="Settings" indicator="number" />
+          <Step step={3} label="Review" indicator="number" />
+        </Stepper>
+      </div>
+      <div style={{maxWidth: 220}}>
+        <Text type="label">Custom icon</Text>
+        <Stepper
+          activeStep={active}
+          orientation="vertical"
+          onStepClick={setActive}>
+          <Step
+            step={0}
+            label="Account"
+            icon={<Icon icon="info" size="sm" />}
+          />
+          <Step
+            step={1}
+            label="Profile"
+            icon={<Icon icon="search" size="sm" />}
+          />
+          <Step
+            step={2}
+            label="Settings"
+            icon={<Icon icon="wrench" size="sm" />}
+          />
+          <Step
+            step={3}
+            label="Review"
+            icon={<Icon icon="check" size="sm" />}
+          />
+        </Stepper>
+      </div>
+    </div>
+  );
+}

package/assets/templates/blocks/components/Stepper/StepperMultiStepForm.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'Stepper',
+  name: 'Stepper — Multi-Step Form',
+  displayName: 'Stepper — Multi-Step Form',
+  description:
+    'A vertical stepper driving a multi-step form. Each step renders its own fields in the content slot for the active step, with Back/Continue buttons advancing activeStep.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Stepper', 'TextInput', 'Button', 'Text'],
+};

package/assets/templates/blocks/components/Stepper/StepperMultiStepForm.tsx

@@ -0,0 +1,92 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Stepper, Step} from '@astryxdesign/lab';
+import {TextInput} from '@astryxdesign/core/TextInput';
+import {Button} from '@astryxdesign/core/Button';
+import {Text} from '@astryxdesign/core/Text';
+
+export default function StepperMultiStepForm() {
+  const [active, setActive] = useState(0);
+  return (
+    <div style={{width: '100%', maxWidth: 480}}>
+      <Stepper
+        activeStep={active}
+        orientation="vertical"
+        onStepClick={setActive}>
+        <Step step={0} label="Project details" indicator="number">
+          {active === 0 && (
+            <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
+              <TextInput
+                label="Project name"
+                placeholder="My awesome project"
+                value=""
+              />
+              <TextInput
+                label="Repository URL"
+                placeholder="https://github.com/..."
+                value=""
+              />
+              <div>
+                <Button
+                  label="Continue"
+                  variant="primary"
+                  onClick={() => setActive(1)}
+                />
+              </div>
+            </div>
+          )}
+        </Step>
+        <Step step={1} label="Environment" indicator="number">
+          {active === 1 && (
+            <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
+              <TextInput label="Node version" placeholder="20" value="" />
+              <TextInput
+                label="Build command"
+                placeholder="npm run build"
+                value=""
+              />
+              <div style={{display: 'flex', gap: 8}}>
+                <Button
+                  label="Back"
+                  variant="secondary"
+                  onClick={() => setActive(0)}
+                />
+                <Button
+                  label="Continue"
+                  variant="primary"
+                  onClick={() => setActive(2)}
+                />
+              </div>
+            </div>
+          )}
+        </Step>
+        <Step step={2} label="Deploy" indicator="number">
+          {active === 2 && (
+            <div style={{display: 'flex', flexDirection: 'column', gap: 12}}>
+              <Text type="body">
+                Ready to deploy. This creates a production build and pushes to
+                your configured hosting.
+              </Text>
+              <div style={{display: 'flex', gap: 8}}>
+                <Button
+                  label="Back"
+                  variant="secondary"
+                  onClick={() => setActive(1)}
+                />
+                <Button
+                  label="Deploy now"
+                  variant="primary"
+                  onClick={() => setActive(3)}
+                />
+              </div>
+            </div>
+          )}
+        </Step>
+        <Step step={3} label="Done" indicator="number" />
+      </Stepper>
+    </div>
+  );
+}

package/assets/templates/blocks/components/Stepper/StepperOnTrackVertical.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'Stepper',
+  name: 'Stepper — On-Track Vertical',
+  displayName: 'Stepper — On-Track Vertical',
+  description:
+    'The on-track layout in vertical orientation: indicators sit inline on a continuous connector rail, with each label and description beside its node.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Stepper'],
+};

package/assets/templates/blocks/components/Stepper/StepperOnTrackVertical.tsx

@@ -0,0 +1,41 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Stepper, Step} from '@astryxdesign/lab';
+
+export default function StepperOnTrackVertical() {
+  const [active, setActive] = useState(2);
+  return (
+    <div style={{width: '100%', maxWidth: 400}}>
+      <Stepper
+        activeStep={active}
+        orientation="vertical"
+        indicatorPosition="on-track"
+        onStepClick={setActive}>
+        <Step
+          step={0}
+          label="Create workspace"
+          description="Name and configure your workspace"
+        />
+        <Step
+          step={1}
+          label="Invite team members"
+          description="Add collaborators by email"
+        />
+        <Step
+          step={2}
+          label="Set up integrations"
+          description="Connect Slack, GitHub, Jira"
+        />
+        <Step
+          step={3}
+          label="Import data"
+          description="Bring in existing projects"
+        />
+        <Step step={4} label="Launch" description="Go live with your team" />
+      </Stepper>
+    </div>
+  );
+}

package/assets/templates/blocks/components/Stepper/StepperShowcase.doc.mjs

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'Stepper',
+  name: 'Stepper — Checkout Progress',
+  displayName: 'Stepper — Checkout Progress',
+  description:
+    'A horizontal on-track stepper for a checkout flow: numbered nodes sit on a continuous connector, with completed and current steps filled. Click any step to jump.',
+  isReady: true,
+  isShowcase: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Stepper'],
+};

package/assets/templates/blocks/components/Stepper/StepperShowcase.tsx

@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Stepper, Step} from '@astryxdesign/lab';
+
+export default function StepperShowcase() {
+  const [active, setActive] = useState(2);
+  return (
+    <div style={{width: '100%', maxWidth: 640}}>
+      <Stepper
+        activeStep={active}
+        orientation="horizontal"
+        indicatorPosition="on-track"
+        onStepClick={setActive}>
+        <Step step={0} label="Cart" indicator="number" />
+        <Step step={1} label="Shipping" indicator="number" />
+        <Step step={2} label="Payment" indicator="number" />
+        <Step step={3} label="Review" indicator="number" />
+        <Step step={4} label="Confirm" indicator="number" />
+      </Stepper>
+    </div>
+  );
+}

package/assets/templates/blocks/components/Stepper/StepperStatus.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'Stepper',
+  name: 'Stepper — Validation Status',
+  displayName: 'Stepper — Validation Status',
+  description:
+    'Semantic status per step in a verification flow: success shows a green check, error a red glyph, accent the in-progress step. Status sets the indicator color and glyph only, never the connector, and is announced to assistive tech as text.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Stepper'],
+};

package/assets/templates/blocks/components/Stepper/StepperStatus.tsx

@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Stepper, Step} from '@astryxdesign/lab';
+
+export default function StepperStatus() {
+  const [active, setActive] = useState(3);
+  return (
+    <div style={{width: '100%', maxWidth: 400}}>
+      <Stepper
+        activeStep={active}
+        orientation="vertical"
+        onStepClick={setActive}>
+        <Step
+          step={0}
+          label="Email verified"
+          description="you@example.com"
+          status="success"
+        />
+        <Step
+          step={1}
+          label="Phone verified"
+          description="+1 (555) 012-3456"
+          status="success"
+        />
+        <Step
+          step={2}
+          label="Identity document"
+          description="Passport upload failed"
+          status="error"
+        />
+        <Step
+          step={3}
+          label="Address verification"
+          description="Pending review"
+          status="accent"
+        />
+        <Step
+          step={4}
+          label="Background check"
+          isOptional
+          description="Skipped"
+        />
+        <Step step={5} label="Account activated" />
+      </Stepper>
+    </div>
+  );
+}

package/assets/templates/blocks/components/Stepper/StepperVerticalOnboarding.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'Stepper',
+  name: 'Stepper — Vertical Onboarding',
+  displayName: 'Stepper — Vertical Onboarding',
+  description:
+    'A vertical stepper for an onboarding flow, with a label and description per step. The auto indicator shows a check for completed steps, a ring for the current step, and a number for upcoming ones.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Stepper'],
+};

package/assets/templates/blocks/components/Stepper/StepperVerticalOnboarding.tsx

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {Stepper, Step} from '@astryxdesign/lab';
+
+export default function StepperVerticalOnboarding() {
+  const [active, setActive] = useState(2);
+  return (
+    <div style={{width: '100%', maxWidth: 400}}>
+      <Stepper
+        activeStep={active}
+        orientation="vertical"
+        onStepClick={setActive}>
+        <Step
+          step={0}
+          label="Create workspace"
+          description="Name and configure your workspace"
+        />
+        <Step
+          step={1}
+          label="Invite team members"
+          description="Add collaborators by email"
+        />
+        <Step
+          step={2}
+          label="Set up integrations"
+          description="Connect Slack, GitHub, Jira"
+        />
+        <Step
+          step={3}
+          label="Import data"
+          description="Bring in existing projects"
+        />
+        <Step step={4} label="Launch" description="Go live with your team" />
+      </Stepper>
+    </div>
+  );
+}

package/assets/templates/blocks/components/TextArea/TextAreaStates.tsx

@@ -20,7 +20,7 @@ export default function TextAreaStates() {
       />
       <TextArea
         label="Disabled field"
-        value="This field is read-only and cannot be edited."
+        value="This field is disabled and cannot be edited."
         onChange={() => {}}
         isDisabled
       />

package/authoring/doctypes/base/type.ts

@@ -260,6 +260,8 @@ export interface ComponentSlotElement {
  * { property: 'padding', vars: ['--_card-padding'] },
  * ```
  */
+// SYNC: apps/docsite/scripts/generate-data.mjs (interface DerivedVar) — see the
+// note on ComponentThemingTarget below.
 export interface ComponentThemingDerivedVar {
   /** The standard CSS property name (camelCase) that theme authors write.
    *  e.g. `'borderRadius'`, `'padding'`, `'paddingBlock'` */
@@ -291,6 +293,10 @@ export interface ComponentThemingDerivedVar {
  * {className: 'astryx-card'}
  * ```
  */
+// SYNC: When adding a field here, add it to the docsite's generated-registry
+// copy too — apps/docsite/scripts/generate-data.mjs (interface ThemingTarget).
+// `next build` type-checks the emitted componentRegistry.ts against that copy,
+// so a field present in a .doc.mjs but missing there fails the docsite build.
 export interface ComponentThemingTarget {
   /** The stable CSS class name rendered by the component.
    *  Always starts with `astryx-`.

package/clients/cli/commands/build-theme.icons-specifier.test.mjs

@@ -0,0 +1,225 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Regression tests for `astryx theme build --icons-specifier`.
+ *
+ * The generated module imports the icon registry rather than inlining it,
+ * because the registry holds React elements. `extractIconInfo` lifts that
+ * specifier out of the TypeScript source, where an extensionless `./icons` is
+ * resolved by the TypeScript resolver — but the artifact is ESM JavaScript,
+ * which requires a fully specified path, so Node cannot load it. See #4620.
+ *
+ * Only the caller knows what its own build emits and under what name (the same
+ * source compiled by tsup lands at `icons.mjs` in a package with no `"type"`
+ * field and at `icons.js` in one with `"type": "module"`), so the specifier is
+ * declared rather than inferred. Absent the flag, output is byte-for-byte what
+ * it was before, which keeps the default no-`--out` flow — where the neighbour
+ * is an uncompiled `icons.tsx` that only a bundler can resolve — working.
+ */
+
+import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {ensureCoreBuilt} from './ensure-core-built.mjs';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+/**
+ * The emitted icon import, or null. Reads the statement rather than the whole
+ * file: the `@generated` header quotes the source filename and a usage example,
+ * so a substring search over the file matches comment text too.
+ */
+function iconImportLine(generated) {
+  const match = generated.match(/^import .*$/m);
+  return match ? match[0] : null;
+}
+
+/** A theme whose registry arrives via a relative import, plus that module. */
+function writeThemeWithIcons(dir, name) {
+  fs.mkdirSync(dir, {recursive: true});
+  fs.writeFileSync(
+    path.join(dir, 'icons.mjs'),
+    'export const testIcons = {};\n',
+  );
+  const file = path.join(dir, `${name}.mjs`);
+  fs.writeFileSync(
+    file,
+    `import {testIcons} from './icons';\n` +
+      `export default {\n` +
+      `  name: ${JSON.stringify(name)},\n` +
+      `  icons: testIcons,\n` +
+      `  tokens: {'--color-bg': '#fff'},\n` +
+      `};\n`,
+  );
+  return file;
+}
+
+beforeAll(() => {
+  ensureCoreBuilt();
+}, 200_000);
+
+let tmpDir;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-icons-specifier-'));
+});
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('theme build --icons-specifier', () => {
+  it('emits the declared specifier', async () => {
+    const project = path.join(tmpDir, 'project');
+    const themeFile = writeThemeWithIcons(project, 'declared');
+
+    const result = await runCli(
+      [
+        'theme',
+        'build',
+        path.relative(project, themeFile),
+        '--icons-specifier',
+        './icons.mjs',
+      ],
+      project,
+    );
+    expect(result.code).toBe(0);
+
+    const generated = fs.readFileSync(
+      path.join(project, 'declared.js'),
+      'utf8',
+    );
+    expect(iconImportLine(generated)).toBe(
+      'import { testIcons } from "./icons.mjs";',
+    );
+  });
+
+  it('accepts a specifier the generator could never have inferred', async () => {
+    const project = path.join(tmpDir, 'project');
+    const themeFile = writeThemeWithIcons(project, 'custom');
+
+    const result = await runCli(
+      [
+        'theme',
+        'build',
+        path.relative(project, themeFile),
+        '--icons-specifier',
+        '../build/registry/icons.js',
+      ],
+      project,
+    );
+    expect(result.code).toBe(0);
+
+    const generated = fs.readFileSync(path.join(project, 'custom.js'), 'utf8');
+    expect(iconImportLine(generated)).toBe(
+      'import { testIcons } from "../build/registry/icons.js";',
+    );
+  });
+
+  it('encodes the declared specifier as a valid JavaScript string', async () => {
+    const project = path.join(tmpDir, 'project');
+    const themeFile = writeThemeWithIcons(project, 'encoded');
+
+    const result = await runCli(
+      [
+        'theme',
+        'build',
+        path.relative(project, themeFile),
+        '--icons-specifier',
+        "./icon's.mjs",
+      ],
+      project,
+    );
+    expect(result.code).toBe(0);
+
+    const generated = fs.readFileSync(path.join(project, 'encoded.js'), 'utf8');
+    expect(iconImportLine(generated)).toBe(
+      'import { testIcons } from "./icon\'s.mjs";',
+    );
+  });
+
+  it('combines with the current --check flow', async () => {
+    const project = path.join(tmpDir, 'project');
+    const themeFile = writeThemeWithIcons(project, 'checked');
+    const relativeTheme = path.relative(project, themeFile);
+
+    const built = await runCli(
+      [
+        'theme',
+        'build',
+        relativeTheme,
+        '--icons-specifier',
+        './icons.mjs',
+      ],
+      project,
+    );
+    expect(built.code).toBe(0);
+
+    const withoutSpecifier = await runCli(
+      ['theme', 'build', relativeTheme, '--check'],
+      project,
+    );
+    expect(withoutSpecifier.code).toBe(1);
+
+    const withSpecifier = await runCli(
+      [
+        'theme',
+        'build',
+        relativeTheme,
+        '--check',
+        '--icons-specifier',
+        './icons.mjs',
+      ],
+      project,
+    );
+    expect(withSpecifier.code).toBe(0);
+  });
+
+  it('leaves the scraped specifier untouched when the flag is absent', async () => {
+    const project = path.join(tmpDir, 'project');
+    const themeFile = writeThemeWithIcons(project, 'untouched');
+
+    const result = await runCli(
+      ['theme', 'build', path.relative(project, themeFile)],
+      project,
+    );
+    expect(result.code).toBe(0);
+
+    // The pre-flag behaviour, preserved: no extension is invented. In this
+    // layout the neighbour is a source file only a bundler can resolve, so
+    // adding one would break a build that works today.
+    const generated = fs.readFileSync(
+      path.join(project, 'untouched.js'),
+      'utf8',
+    );
+    expect(iconImportLine(generated)).toBe(
+      "import { testIcons } from './icons';",
+    );
+  });
+
+  it('is inert for a theme with no icons field', async () => {
+    const project = path.join(tmpDir, 'project');
+    fs.mkdirSync(project, {recursive: true});
+    const themeFile = path.join(project, 'plain.mjs');
+    fs.writeFileSync(
+      themeFile,
+      `export default {name: 'plain', tokens: {'--color-bg': '#fff'}};\n`,
+    );
+
+    const result = await runCli(
+      [
+        'theme',
+        'build',
+        path.relative(project, themeFile),
+        '--icons-specifier',
+        './icons.mjs',
+      ],
+      project,
+    );
+    expect(result.code).toBe(0);
+
+    // No icons field means no import to rewrite, so the flag has nothing to act
+    // on and must not introduce one.
+    const generated = fs.readFileSync(path.join(project, 'plain.js'), 'utf8');
+    expect(iconImportLine(generated)).toBeNull();
+    expect(generated).not.toContain('icons:');
+  });
+});

package/clients/cli/commands/build-theme.mjs

@@ -57,13 +57,15 @@ function resolveCliBin() {
  * Resolves with the child's exit code; never rejects.
  *
  * @param {string} file - The theme file argument, as the user passed it.
- * @param {{out?: string}} options - Parsed command options (only `out` is forwarded).
+ * @param {{out?: string, iconsSpecifier?: string}} options - Parsed command
+ *   options that affect generated output.
  * @returns {Promise<number>}
  */
 function runThemeBuildOnceChild(file, options) {
   const cliBin = resolveCliBin();
   const args = [cliBin, 'theme', 'build', file];
   if (options.out) args.push('--out', options.out);
+  if (options.iconsSpecifier) args.push('--icons-specifier', options.iconsSpecifier);
   return new Promise((/** @type {(code: number) => void} */ resolve) => {
     const child = spawn(process.execPath, args, {
       stdio: 'inherit',
@@ -83,7 +85,7 @@ function runThemeBuildOnceChild(file, options) {
  *
  * @param {string} file - The theme file argument, as the user passed it.
  * @param {string} filePath - Absolute path to the theme file.
- * @param {{out?: string}} options - Parsed command options.
+ * @param {{out?: string, iconsSpecifier?: string}} options - Parsed command options.
  * @returns {Promise<void>} Resolves when the watcher is stopped (Ctrl-C).
  */
 async function runThemeBuildWatch(file, filePath, options) {
@@ -204,7 +206,7 @@ export function registerTheme(program) {
     fn: themeBuildFn,
     action: async (
       /** @type {string} */ file,
-      /** @type {{out?: string, watch?: boolean, check?: boolean}} */ options,
+      /** @type {{out?: string, watch?: boolean, check?: boolean, iconsSpecifier?: string}} */ options,
     ) => {
       const filePath = path.resolve(process.cwd(), file);
       const json = program.opts().json || false;
@@ -247,7 +249,11 @@ export function registerTheme(program) {
       try {
         const result = await themeBuild(
           file,
-          {out: options.out, check: options.check},
+          {
+            out: options.out,
+            check: options.check,
+            iconsSpecifier: options.iconsSpecifier,
+          },
           {cwd: process.cwd()},
         );
         if (json && result) jsonOut(result);

package/clients/cli/commands/theme-build.doc.mjs

@@ -18,11 +18,19 @@ export const doc = {
   description:
     'Compiles a file that calls defineTheme() into a scoped CSS file, a JS module, and ' +
     'type declarations: the exact CSS the <Theme> runtime emits. With --check it writes ' +
-    'nothing and instead reports whether the committed outputs have drifted from source.',
+    'nothing and instead reports whether the committed outputs have drifted from source. ' +
+    'When a separate build step emits the icon registry, --icons-specifier declares the ' +
+    'fully specified module path that the generated JS should import.',
   fn: 'themeBuild',
   args: [{name: 'file', param: 'file', required: true}],
   options: [
     {flag: '-o, --out <path>', param: 'options.out', description: 'Output CSS file path'},
+    {
+      flag: '--icons-specifier <specifier>',
+      param: 'options.iconsSpecifier',
+      description:
+        'Override the icon-registry import in the generated JS module (for example, ./icons.mjs)',
+    },
     {
       flag: '-w, --watch',
       description: 'Rebuild automatically when the theme file changes (Ctrl-C to stop)',
@@ -43,6 +51,10 @@ export const doc = {
       label: 'Check for drift (CI)',
       cli: 'astryx theme build ./src/themes/ocean.ts --check',
     },
+    {
+      label: 'Build against a separately compiled icon registry',
+      cli: 'astryx theme build ./src/themes/ocean.ts --icons-specifier ./icons.mjs',
+    },
   ],
   exitCodes: [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.3.0-canary.ec85ba0",
+  "version": "0.3.0-canary.f4607ea",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -84,10 +84,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.3.0-canary.ec85ba0",
-    "@astryxdesign/core": "0.3.0-canary.ec85ba0",
-    "@astryxdesign/lab": "0.3.0-canary.ec85ba0",
-    "@astryxdesign/theme-neutral": "0.3.0-canary.ec85ba0",
+    "@astryxdesign/charts": "0.3.0-canary.f4607ea",
+    "@astryxdesign/core": "0.3.0-canary.f4607ea",
+    "@astryxdesign/lab": "0.3.0-canary.f4607ea",
+    "@astryxdesign/theme-neutral": "0.3.0-canary.f4607ea",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -105,10 +105,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.3.0-canary.ec85ba0",
-    "@astryxdesign/core": "0.3.0-canary.ec85ba0",
-    "@astryxdesign/lab": "0.3.0-canary.ec85ba0",
-    "@astryxdesign/theme-neutral": "0.3.0-canary.ec85ba0",
+    "@astryxdesign/charts": "0.3.0-canary.f4607ea",
+    "@astryxdesign/core": "0.3.0-canary.f4607ea",
+    "@astryxdesign/lab": "0.3.0-canary.f4607ea",
+    "@astryxdesign/theme-neutral": "0.3.0-canary.f4607ea",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {