@astryxdesign/cli 0.6.3-canary.ebaebc4 → 0.6.3-canary.ee13359

package/assets/codemods/transforms/v0.1.8/rename-avatar-size-scale.mjs

@@ -4,46 +4,23 @@
  * @file Codemod: Rename Avatar named sizes to Icon's abbreviated scale
  * @see https://github.com/facebook/astryx/issues/2672
  *
- * As of v0.1.8, Avatar and AvatarGroup use the same abbreviated size scale as
- * Icon (`xsm`/`sm`/`md`/`lg`/`xl`) instead of full words. Pixel values are
- * unchanged — only the names move:
- *
- *   tiny (20px)   → xsm
- *   xsmall (24px) → sm
- *   small (36px)  → md   ← also the new default (was `small`)
- *   medium (48px) → lg
- *   large (128px) → xl
- *
- * The default size shifts from `small` to `md`, but that is the SAME 36px, so
- * call sites that relied on the default need no change.
- *
- * ## Precision
- *
- * `small`, `medium`, and `large` are common English words that appear as
- * unrelated string/type literals (priorities, statuses, breakpoints, …). To
- * avoid corrupting those, the three AMBIGUOUS names are renamed ONLY in a
- * precise context: a `size` JSX attribute on a component that resolves to an
- * Avatar/AvatarGroup import (alias-aware).
- *
- * `tiny` and `xsmall` are unique to Avatar's scale, so they are additionally
- * renamed in context-blind positions (object properties keyed `size`/`*Size`,
- * Storybook `options` arrays, and size-typed union literals) within files that
- * import Avatar/AvatarGroup.
+ * This transform is deliberately limited to static literals written directly
+ * in the `size` prop of an imported Avatar or AvatarGroup JSX element. It does
+ * not infer through variables, helpers, objects, types, Storybook metadata, or
+ * wrappers: missing an indirect migration is safer than rewriting another
+ * component's size vocabulary.
  */
 
+import {transformProp} from '../../transform-prop.mjs';
+
 export const meta = {
   title: 'Rename Avatar named sizes tiny/xsmall/small/medium/large → xsm/sm/md/lg/xl',
   description:
-    'Avatar and AvatarGroup adopt Icon\'s abbreviated size scale ' +
-    '(xsm/sm/md/lg/xl). Pixel values are unchanged; the default moves from ' +
-    '`small` to `md` (both 36px). The ambiguous names small/medium/large are ' +
-    'only renamed on Avatar/AvatarGroup `size` JSX attributes; the unique ' +
-    'names tiny/xsmall are also renamed in size-keyed props, Storybook ' +
-    'options, and union types in files importing Avatar/AvatarGroup.',
+    'Renames static sizes written directly on imported Avatar and AvatarGroup ' +
+    'JSX elements. Indirect values are left unchanged for manual migration.',
   pr: '#2672',
 };
 
-/** Import sources that provide the Astryx Avatar/AvatarGroup components. */
 const IMPORT_SOURCES = new Set([
   '@astryxdesign/core',
   '@astryxdesign/core/Avatar',
@@ -53,10 +30,11 @@ const IMPORT_SOURCES = new Set([
   '@xds/core/AvatarGroup',
 ]);
 
-/** Component names whose `size` prop is renamed. */
-const TARGET_IMPORTED_NAMES = new Set(['Avatar', 'AvatarGroup']);
+const COMPONENT_PROPS = new Map([
+  ['Avatar', new Set(['size'])],
+  ['AvatarGroup', new Set(['size'])],
+]);
 
-/** Old → new size-name mapping. */
 const RENAMES = new Map([
   ['tiny', 'xsm'],
   ['xsmall', 'sm'],
@@ -65,46 +43,38 @@ const RENAMES = new Map([
   ['large', 'xl'],
 ]);
 
-/**
- * Ambiguous names — common words that must ONLY be renamed in a precise
- * context. `tiny`/`xsmall` are omitted because they are unique to Avatar's
- * scale; their presence in a collection proves it is an Avatar size enum.
- */
-const AMBIGUOUS = new Set(['small', 'medium', 'large']);
-
-/** Names that appear only in Avatar's scale — safe signals of Avatar sizing. */
-const UNIQUE = new Set(['tiny', 'xsmall']);
-
-/**
- * Rename a string-literal node if its value is an old size name.
- * Unwraps `'small' as const`. In non-precise contexts, ambiguous names are
- * skipped. Returns true when a rename occurred.
- */
-function renameValue(/** @type {any} */ node, {precise = false} = {}) {
-  if (!node) return false;
-  const target = node.type === 'TSAsExpression' ? node.expression : node;
-  const isString =
-    target.type === 'StringLiteral' || target.type === 'Literal';
-  if (!isString || typeof target.value !== 'string') return false;
-  const replacement = RENAMES.get(target.value);
-  if (!replacement) return false;
-  if (!precise && AMBIGUOUS.has(target.value)) return false;
-  target.value = replacement;
-  if (target.raw) target.raw = undefined;
-  return true;
+/** @param {string} name */
+function canonicalComponentName(name) {
+  return name.startsWith('XDS') ? name.slice(3) : name;
 }
 
-/** Extract a plain string value from a literal-ish node, or null. */
-function literalString(/** @type {any} */ node) {
-  const target = node?.type === 'TSAsExpression' ? node.expression : node;
+/** @param {any} node @returns {boolean} */
+function renameStaticValue(node) {
+  if (!node) return false;
   if (
-    target &&
-    (target.type === 'StringLiteral' || target.type === 'Literal') &&
-    typeof target.value === 'string'
+    node.type === 'TSAsExpression' ||
+    node.type === 'TSSatisfiesExpression' ||
+    node.type === 'TypeCastExpression' ||
+    node.type === 'ParenthesizedExpression'
   ) {
-    return target.value;
+    return renameStaticValue(node.expression);
   }
-  return null;
+  if (node.type === 'ConditionalExpression') {
+    const consequentChanged = renameStaticValue(node.consequent);
+    const alternateChanged = renameStaticValue(node.alternate);
+    return consequentChanged || alternateChanged;
+  }
+  if (
+    (node.type !== 'StringLiteral' && node.type !== 'Literal') ||
+    typeof node.value !== 'string'
+  ) {
+    return false;
+  }
+  const replacement = RENAMES.get(node.value);
+  if (!replacement) return false;
+  node.value = replacement;
+  if (node.raw) node.raw = undefined;
+  return true;
 }
 
 /**
@@ -117,122 +87,23 @@ export default function transformer(file, api) {
   const root = j(file.source);
   let hasChanges = false;
 
-  // Track alias-aware local names for the target components.
-  const targetLocals = new Set();
-  root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
-    if (!IMPORT_SOURCES.has(path.node.source.value)) return;
-    for (const spec of path.node.specifiers ?? []) {
-      if (
-        spec.type === 'ImportSpecifier' &&
-        TARGET_IMPORTED_NAMES.has(spec.imported.name)
-      ) {
-        targetLocals.add(spec.local.name);
-      }
-    }
-  });
-
-  if (targetLocals.size === 0) return undefined;
-
-  function renameArrayElements(/** @type {any} */ node) {
-    let arr = node;
-    if (arr.type === 'TSAsExpression') arr = arr.expression;
-    if (arr.type !== 'ArrayExpression') return;
-    // If the array contains a name unique to Avatar's scale (tiny/xsmall), the
-    // whole collection is unambiguously the Avatar size enum, so it is safe to
-    // rename the ambiguous members too. Otherwise stay conservative.
-    const precise = arr.elements.some((/** @type {any} */ el) => UNIQUE.has(literalString(el)));
-    for (const el of arr.elements) {
-      if (renameValue(el, {precise})) hasChanges = true;
-    }
-  }
-
-  // 1. `size` JSX attributes on target components — PRECISE (component known),
-  //    so all five names, including the ambiguous ones, are renamed here.
-  root.find(j.JSXOpeningElement).forEach((/** @type {any} */ path) => {
-    const name = path.node.name;
-    const componentName = name.type === 'JSXIdentifier' ? name.name : null;
-    if (!componentName || !targetLocals.has(componentName)) return;
-
-    for (const attr of path.node.attributes) {
-      if (attr.type !== 'JSXAttribute' || attr.name?.name !== 'size') continue;
-      const value = attr.value;
-
-      // size="small"
-      if (renameValue(value, {precise: true})) {
-        hasChanges = true;
-        continue;
-      }
-      if (
-        value &&
-        value.type === 'JSXExpressionContainer' &&
-        value.expression
-      ) {
-        // size={'small'}
-        if (renameValue(value.expression, {precise: true})) {
-          hasChanges = true;
-          continue;
-        }
-        // size={cond ? 'small' : 'large'}
-        if (value.expression.type === 'ConditionalExpression') {
-          if (renameValue(value.expression.consequent, {precise: true}))
-            hasChanges = true;
-          if (renameValue(value.expression.alternate, {precise: true}))
-            hasChanges = true;
-        }
-      }
-    }
-  });
-
-  // 2. Object properties keyed `size` (or `*Size`) + Storybook `options`
-  //    arrays — NON-PRECISE (the component isn't known here), so only the
-  //    unique names tiny/xsmall are renamed.
-  const PropertyType = j.ObjectProperty ?? j.Property;
-  root.find(PropertyType).forEach((/** @type {any} */ path) => {
-    const key = path.node.key;
-    const keyName =
-      key.type === 'Identifier'
-        ? key.name
-        : key.type === 'StringLiteral' || key.type === 'Literal'
-          ? key.value
-          : null;
-    if (typeof keyName !== 'string') return;
-
-    const lower = keyName.toLowerCase();
-    if (lower !== 'size' && !lower.endsWith('size')) return;
-
-    const value = path.node.value;
-    // size: 'tiny'
-    if (renameValue(value)) {
-      hasChanges = true;
-      return;
-    }
-    // size: { control: 'select', options: ['tiny', ...] }
-    if (value.type === 'ObjectExpression') {
-      const optionsProp = value.properties.find(
-        (/** @type {any} */ p) => p.key && (p.key.name === 'options' || p.key.value === 'options'),
-      );
-      if (optionsProp) renameArrayElements(optionsProp.value);
-    }
-    // size: ['tiny', 'xsmall', ...]
-    renameArrayElements(value);
-  });
-
-  // 3. Union-type literals — NON-PRECISE, so only the unique names tiny/xsmall
-  //    are renamed. This avoids corrupting unrelated unions that happen to use
-  //    common words like 'medium' (e.g. a priority or breakpoint type) in a
-  //    file that also imports Avatar.
-  root.find(j.TSLiteralType).forEach((/** @type {any} */ path) => {
-    if (renameValue(path.node.literal)) hasChanges = true;
-  });
-
-  // 4. Standalone array literals whose members are exactly the Avatar size
-  //    scale (identified by the presence of a unique name like tiny/xsmall) —
-  //    e.g. `(['tiny', 'xsmall', 'small', 'medium', 'large'] as const).map(...)`
-  //    used to render every size. The unique name proves the whole array is the
-  //    Avatar enum, so its ambiguous members can be renamed safely.
-  root.find(j.ArrayExpression).forEach((/** @type {any} */ path) => {
-    renameArrayElements(path.node);
-  });
+  transformProp(
+    root,
+    j,
+    {
+      matchesImport: source => IMPORT_SOURCES.has(source),
+      components: COMPONENT_PROPS,
+      normalizeComponentName: canonicalComponentName,
+    },
+    propPath => {
+      const prop = propPath.node;
+      const value =
+        prop.value?.type === 'JSXExpressionContainer'
+          ? prop.value.expression
+          : prop.value;
+      if (renameStaticValue(value)) hasChanges = true;
+    },
+  );
 
   if (!hasChanges) return undefined;
   return root.toSource({quote: 'single'});

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

@@ -220,4 +220,51 @@ function wrapper(useResizable) {
     const output = await apply('rename-resizable-pixel-bounds', input);
     expect(output).toBe(input);
   });
+
+  it('renames bounds when useResizable comes from a namespace import', async () => {
+    const input = `import * as Astryx from '@astryxdesign/core';
+const region = Astryx.useResizable({defaultSize: 240, minSizePx: 120, maxSizePx: 480});`;
+    const output = await apply('rename-resizable-pixel-bounds', input);
+    expect(output).toContain('minSize: 120');
+    expect(output).toContain('maxSize: 480');
+    expect(output).not.toContain('minSizePx');
+    expect(output).not.toContain('maxSizePx');
+  });
+
+  it('leaves a namespace that does not come from Astryx alone', async () => {
+    const input = `import * as Other from 'other-resizable';
+const region = Other.useResizable({minSizePx: 120});`;
+    const output = await apply('rename-resizable-pixel-bounds', input);
+    expect(output).toContain('minSizePx: 120');
+  });
+
+  it('does not rewrite a parameter that shadows the namespace import', async () => {
+    const input = `import * as Astryx from '@astryxdesign/core';
+function build(Astryx) {
+  return Astryx.useResizable({minSizePx: 120});
+}`;
+    const output = await apply('rename-resizable-pixel-bounds', input);
+    expect(output).toContain('minSizePx: 120');
+  });
+
+  it.each([
+    ['as const', '{defaultSize: 240, minSizePx: 120} as const'],
+    ['satisfies', '{defaultSize: 240, minSizePx: 120} satisfies object'],
+  ])('renames a static configuration wrapped in %s', async (_label, config) => {
+    const input = `import {useResizable} from '@astryxdesign/core/Resizable';
+const region = useResizable(${config});`;
+    const output = await apply('rename-resizable-pixel-bounds', input);
+    expect(output).toContain('minSize: 120');
+    expect(output).not.toContain('minSizePx');
+  });
+
+  it('renames wrapped multi-region configurations', async () => {
+    const input = `import {useResizable} from '@astryxdesign/core';
+const regions = useResizable({regions: {
+  nav: {defaultSize: 240, minSizePx: 120} as const,
+} as const});`;
+    const output = await apply('rename-resizable-pixel-bounds', input);
+    expect(output).toContain('minSize: 120');
+    expect(output).not.toContain('minSizePx');
+  });
 });

package/assets/codemods/transforms/v0.6.0/rename-resizable-pixel-bounds.mjs

@@ -8,6 +8,9 @@
  * released conflict rule (the unified property wins when both are present).
  * A spread or computed property can change precedence invisibly, so dynamic
  * objects stay unchanged and receive a manual-migration TODO instead.
+ * Named and namespace imports both count, and a type-only wrapper (`as`,
+ * `satisfies`, a non-null assertion, parentheses) does not make a
+ * configuration dynamic.
  */
 
 export const meta = {
@@ -33,6 +36,26 @@ const MANUAL_MIGRATION_COMMENT =
   'or computed property. Rename minSizePx/maxSizePx to minSize/maxSize ' +
   'manually without changing property precedence. ';
 
+const TYPE_WRAPPERS = new Set([
+  'TSAsExpression',
+  'TSSatisfiesExpression',
+  'TSTypeAssertion',
+  'TSNonNullExpression',
+  'ParenthesizedExpression',
+]);
+
+/**
+ * The expression under type-only wrappers such as `{...} as const`.
+ * @param {any} node
+ */
+function unwrap(node) {
+  let current = node;
+  while (current && TYPE_WRAPPERS.has(current.type)) {
+    current = current.expression;
+  }
+  return current;
+}
+
 /** @param {any} property */
 function staticPropertyName(property) {
   if (property.computed) return null;
@@ -128,6 +151,8 @@ export default function transformer(file, api) {
   const root = j(file.source);
   /** @type {Map<string, any>} */
   const bindings = new Map();
+  /** @type {Map<string, any>} */
+  const namespaces = new Map();
 
   root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
     if (!IMPORT_SOURCES.has(path.node.source.value)) return;
@@ -138,17 +163,40 @@ export default function transformer(file, api) {
       ) {
         const local = specifier.local?.name ?? 'useResizable';
         bindings.set(local, path.scope.lookup(local) ?? path.scope);
+      } else if (specifier.type === 'ImportNamespaceSpecifier') {
+        const local = specifier.local.name;
+        namespaces.set(local, path.scope.lookup(local) ?? path.scope);
       }
     }
   });
-  if (bindings.size === 0) return undefined;
+  if (bindings.size === 0 && namespaces.size === 0) return undefined;
+
+  /**
+   * @param {any} callee
+   * @param {any} scope
+   */
+  const isUseResizable = (callee, scope) => {
+    if (callee.type === 'Identifier') {
+      return (
+        bindings.has(callee.name) &&
+        scope.lookup(callee.name) === bindings.get(callee.name)
+      );
+    }
+    return (
+      callee.type === 'MemberExpression' &&
+      !callee.computed &&
+      callee.object.type === 'Identifier' &&
+      callee.property.type === 'Identifier' &&
+      callee.property.name === 'useResizable' &&
+      namespaces.has(callee.object.name) &&
+      scope.lookup(callee.object.name) === namespaces.get(callee.object.name)
+    );
+  };
 
   let changed = false;
   root.find(j.CallExpression).forEach((/** @type {any} */ path) => {
-    const callee = path.node.callee;
-    if (callee.type !== 'Identifier' || !bindings.has(callee.name)) return;
-    if (path.scope.lookup(callee.name) !== bindings.get(callee.name)) return;
-    const config = path.node.arguments[0];
+    if (!isUseResizable(path.node.callee, path.scope)) return;
+    const config = unwrap(path.node.arguments[0]);
     if (config?.type !== 'ObjectExpression') return;
 
     changed = migrateObject(j, config) || changed;
@@ -158,13 +206,12 @@ export default function transformer(file, api) {
         staticPropertyName(property) === 'regions',
     );
     if (!regions || !('value' in regions)) return;
-    const regionsObject = regions.value;
+    const regionsObject = unwrap(regions.value);
     if (regionsObject?.type !== 'ObjectExpression') return;
     for (const region of regionsObject.properties) {
-      if (!('value' in region) || region.value?.type !== 'ObjectExpression') {
-        continue;
-      }
-      changed = migrateObject(j, region.value) || changed;
+      const regionConfig = 'value' in region ? unwrap(region.value) : null;
+      if (regionConfig?.type !== 'ObjectExpression') continue;
+      changed = migrateObject(j, regionConfig) || changed;
     }
   });
 

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

@@ -98,11 +98,11 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'These stylesheets are cascade-layered: the reset loads in @layer reset and component styles in @layer astryx-base. If your project has existing global CSS, a legacy reset, or Tailwind, declare the layer order explicitly and assign every stylesheet to a layer deliberately: unlayered styles and later layers both override astryx-base regardless of specificity. See the Cascade Layer Safety section in `astryx docs migration` before building screens.',
+          text: 'These stylesheets are cascade-layered: the reset loads in @layer reset and component styles in @layer astryx-base. If your project has existing global CSS, a legacy reset, or Tailwind, declare the layer order explicitly and assign every stylesheet to a layer deliberately: unlayered styles and later layers both override astryx-base regardless of specificity. See the Cascade Layer Safety section in {@link generic:migration} before building screens.',
         },
         {
           type: 'prose',
-          text: 'Run `astryx docs theme` for the full theming guide.',
+          text: 'Run {@link generic:theme} for the full theming guide.',
         },
       ],
     },

package/assets/docs/principles.doc.mjs

@@ -39,10 +39,10 @@ export const docs = {
           style: 'ordered',
           items: [
             'Use components for everything they cover',
-            'Page layout is frame-first: pick the shell and budget regions before writing content (see \`astryx docs layout\`)',
+            'Page layout is frame-first: pick the shell and budget regions before writing content (see {@link generic:layout})',
             'Dense data renders as rows (Table, List/Item), edge-to-edge with dividers; Card is for widgets, galleries, and settings groups',
-            'StyleX or Tailwind for custom styling; both are first-class (see \`astryx docs styling\`)',
-            'Semantic tokens, not hardcoded values (see \`astryx docs tokens\`)',
+            'StyleX or Tailwind for custom styling; both are first-class (see {@link generic:styling})',
+            'Semantic tokens, not hardcoded values (see {@link generic:tokens})',
             'CSS custom properties for colors, not hex values',
             'Form inputs are controlled (value + onChange)',
             'Use useLinkComponent() for navigation so consumers can plug in their framework router via LinkProvider',
@@ -60,7 +60,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'See \`astryx docs styling\` for the complete guide with examples.',
+          text: 'See {@link generic:styling} for the complete guide with examples.',
         },
       ],
     },
@@ -76,7 +76,7 @@ export const docs = {
             'Hardcoded colors (#fff). Use var(--color-*) or Tailwind semantic classes (text-primary, bg-surface)',
             'Hardcoded spacing (16px). Use spacing tokens or Tailwind spacing utilities',
             'Hardcoded <a> elements. Use useLinkComponent() so consumers can swap in their framework router via LinkProvider',
-            'Wrapping every list item or page section in a Card. Decide the frame first; dense data renders as rows (see \`astryx docs layout\`)',
+            'Wrapping every list item or page section in a Card. Decide the frame first; dense data renders as rows (see {@link generic:layout})',
             'Badge as decoration. Reserve Badge for counts and enumerated states; use StatusDot or Token for status',
             'Inventing props. Read component docs first',
           ],
@@ -89,7 +89,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'The design system provides semantic design tokens for spacing, color, radius, shadow, typography, and size. Tokens adapt to the active theme and color mode. Run \`astryx docs tokens\` for the full reference with all values.',
+          text: 'The design system provides semantic design tokens for spacing, color, radius, shadow, typography, and size. Tokens adapt to the active theme and color mode. Run {@link generic:tokens} for the full reference with all values.',
         },
       ],
     },

package/assets/docs/styling-libraries.doc.mjs

@@ -24,7 +24,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'For available token names and values, run `astryx docs tokens`. Focused references are also available with `astryx docs color`, `astryx docs spacing`, `astryx docs shape`, `astryx docs typography`, `astryx docs elevation`, and `astryx docs motion`.',
+          text: 'For available token names and values, run {@link generic:tokens}. Focused references are also available with {@link generic:color}, {@link generic:spacing}, {@link generic:shape}, {@link generic:typography}, {@link generic:elevation}, and {@link generic:motion}.',
         },
       ],
     },
@@ -455,7 +455,7 @@ function RevenueChart({data}: {data: Array<{x: string; y: number}>}) {
             'Import the reset/base CSS and a theme CSS file early enough for first paint. For production SSR, prefer built themes from `astryx theme build` or published `/built` theme imports plus `theme.css`.',
             'Choose one owner for color mode. Theme uses `data-theme="light|dark"` and `color-scheme` to resolve `light-dark()` tokens.',
             'Map the external library\'s semantic layer to system variables by intent, not by exact naming. For example, MUI `background.paper` maps to `--color-background-surface`.',
-            'Use `astryx docs tokens` and focused token docs when building mappings. Keep mappings small at first: text, surface/body/card/popover, border, accent, status, spacing, radius, typography, shadow.',
+            'Use {@link generic:tokens} and focused token docs when building mappings. Keep mappings small at first: text, surface/body/card/popover, border, accent, status, spacing, radius, typography, shadow.',
             'Use token resolver APIs only for non-CSS APIs that need resolved values.',
           ],
         },

package/assets/docs/styling.doc.mjs

@@ -30,7 +30,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'All approaches resolve to the same design tokens, so theming and dark mode work regardless of which you choose. For external styling libraries, run `astryx docs styling-libraries`; it covers Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, Sass, and `useTheme()` for non-CSS processing.',
+          text: 'All approaches resolve to the same design tokens, so theming and dark mode work regardless of which you choose. For external styling libraries, run {@link generic:styling-libraries}; it covers Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, Sass, and `useTheme()` for non-CSS processing.',
         },
       ],
     },
@@ -118,7 +118,7 @@ const overrides = stylex.create({
         },
         {
           type: 'prose',
-          text: 'The bridge is pure CSS with zero JS. Theme changes (dark mode, custom themes) apply automatically because the utilities reference the same CSS custom properties that components use. This is the paved Tailwind path; for other styling libraries that follow the same aliasing pattern, run `astryx docs styling-libraries`.',
+          text: 'The bridge is pure CSS with zero JS. Theme changes (dark mode, custom themes) apply automatically because the utilities reference the same CSS custom properties that components use. This is the paved Tailwind path; for other styling libraries that follow the same aliasing pattern, run {@link generic:styling-libraries}.',
         },
       ],
     },
@@ -263,7 +263,7 @@ const overrides = stylex.create({
         },
         {
           type: 'prose',
-          text: 'For systematic theming, use defineTheme component overrides instead of raw CSS selectors. defineTheme keeps the higher-level `prop:value` API (`variant:primary`, `size:sm`) and handles selector generation for you. Run `astryx docs theme` for the full theming guide.',
+          text: 'For systematic theming, use defineTheme component overrides instead of raw CSS selectors. defineTheme keeps the higher-level `prop:value` API (`variant:primary`, `size:sm`) and handles selector generation for you. Run {@link generic:theme} for the full theming guide.',
         },
       ],
     },
@@ -338,7 +338,7 @@ const styles = stylex.create({
         },
         {
           type: 'prose',
-          text: 'See `astryx docs tokens` for the full token reference (all spacing, color, radius, shadow, and typography tokens with values). See `astryx docs theme` for how to override tokens via defineTheme.',
+          text: 'See {@link generic:tokens} for the full token reference (all spacing, color, radius, shadow, and typography tokens with values). See {@link generic:theme} for how to override tokens via defineTheme.',
         },
       ],
     },

package/assets/docs/theme.doc.mjs

@@ -152,7 +152,7 @@ function App() {
         },
         {
           type: 'prose',
-          text: 'The copy is editable project source, not a reference back into node_modules. Every file named by the theme catalog comes with it, including nested token or palette modules. A second add refuses to overwrite those files unless you pass `--overwrite`.',
+          text: 'The copy is editable project source, not a reference back into node_modules. The complete theme directory comes with it, including its typed `.doc.mjs`, nested token and palette modules, and receipts. A second add refuses to overwrite those files unless you pass `--overwrite`.',
         },
       ],
     },
@@ -391,7 +391,7 @@ const brandTheme = defineTheme({
       content: [
         {
           type: 'prose',
-          text: 'The `components` field in defineTheme uses semantic component keys and style keys, not raw CSS selectors. Use `base` for all instances, `variant:value` or `stateName` for specific props/states, and let the theme pipeline choose the underlying selector. For raw external CSS escape hatches, prefer the data-attribute selector surface documented in `astryx docs styling`.',
+          text: 'The `components` field in defineTheme uses semantic component keys and style keys, not raw CSS selectors. Use `base` for all instances, `variant:value` or `stateName` for specific props/states, and let the theme pipeline choose the underlying selector. For raw external CSS escape hatches, prefer the data-attribute selector surface documented in {@link generic:styling}.',
         },
         {
           type: 'code',
@@ -572,7 +572,7 @@ import './themes/ocean.css';
         },
         {
           type: 'prose',
-          text: "The build also warns when the theme names font families it does not load (webfonts like Fraunces) and prints the `<link>`/`@font-face` to add. The built CSS only sets font-family, so loading the font files stays the app's job. See `astryx docs typography` for the full recipe.",
+          text: "The build also warns when the theme names font families it does not load (webfonts like Fraunces) and prints the `<link>`/`@font-face` to add. The built CSS only sets font-family, so loading the font files stays the app's job. See {@link generic:typography} for the full recipe.",
         },
       ],
     },
@@ -811,7 +811,7 @@ function ChartConfig() {
         },
         {
           type: 'prose',
-          text: 'See `astryx docs styling-libraries` for styling-library interop and `astryx docs tokens` for the full token reference.',
+          text: 'See {@link generic:styling-libraries} for styling-library interop and {@link generic:tokens} for the full token reference.',
         },
       ],
     },

package/assets/docs/tokens.doc.mjs

@@ -1102,7 +1102,7 @@ export const docs = {
         },
         {
           "type": "prose",
-          "text": "See `astryx docs styling` for how to apply tokens via xstyle, className, and compound component patterns. See `astryx docs theme` for overriding tokens with defineTheme."
+          "text": "See {@link generic:styling} for how to apply tokens via xstyle, className, and compound component patterns. See {@link generic:theme} for overriding tokens with defineTheme."
         }
       ]
     }

package/assets/docs/tree/api.doc.mjs

@@ -0,0 +1,30 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/api`: the programmatic API of `@astryxdesign/cli/api`.
+ *
+ * Adopts each function, schema, and enum doc whose `namespace` is `cli/api`,
+ * one generated level per kind: `cli/api/functions`, `cli/api/schemas`, and
+ * `cli/api/enums`.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'api',
+  title: 'API',
+  summary:
+    'The programmatic API: functions, the JSON output envelope, error codes, and response types.',
+  keywords: ['api', 'functions', 'schemas', 'enums', 'json'],
+  placement: {parent: 'namespace:cli', slot: 'reference', order: 20},
+  slots: {
+    kinds: {title: 'Reference', accepts: {kinds: ['namespace']}},
+  },
+  adopts: [
+    {
+      source: {group: 'cli/api', kinds: ['function', 'schema', 'enum']},
+      into: 'kinds',
+      groupBy: 'kind',
+    },
+  ],
+};