@astryxdesign/cli 0.6.3-canary.ea2f048 → 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.3.0/__tests__/unwrap-authoring-factories.test.mjs

@@ -3,7 +3,8 @@
 import {describe, it, expect} from 'vitest';
 
 async function applyTransform(source, path = 'test.ts') {
-  const {default: transform} = await import('../unwrap-authoring-factories.mjs');
+  const {default: transform} =
+    await import('../unwrap-authoring-factories.mjs');
   const jscodeshift = (await import('jscodeshift')).default;
   const j = jscodeshift.withParser('tsx');
   const api = {jscodeshift: j, stats: () => {}, report: () => {}};
@@ -18,7 +19,7 @@ export default createConfig({integrations: ['@acme/widgets']});
 `;
     const output = await applyTransform(input);
     expect(output).not.toContain('createConfig');
-    expect(output).toContain("export default {");
+    expect(output).toContain('export default {');
     expect(output).toContain("integrations: ['@acme/widgets']");
     expect(output).not.toContain('type:');
   });
@@ -132,13 +133,34 @@ export default createComponentDoc();
     expect(output).toContain("type: 'component'");
   });
 
+  it('leaves same-named factories from unrelated packages unchanged', async () => {
+    const input = `import {createConfig} from '@acme/eslint';
+export default createConfig({strict: true});
+`;
+    expect(await applyTransform(input)).toBe(input);
+  });
+
+  it('keeps an unrelated same-named import when another factory is migrated', async () => {
+    const input = `import {createConfig as createLintConfig} from '@acme/eslint';
+import {createDoc} from '@astryxdesign/cli/doc';
+export const lintConfig = createLintConfig({strict: true});
+export const doc = createDoc({name: 'Theming', description: 'How theming works.'});
+`;
+    const output = await applyTransform(input);
+    expect(output).toContain(
+      "import {createConfig as createLintConfig} from '@acme/eslint'",
+    );
+    expect(output).toContain('createLintConfig({strict: true})');
+    expect(output).not.toContain('createDoc');
+    expect(output).toContain("type: 'generic'");
+  });
+
   it('is a no-op when no authoring factory is imported', async () => {
     const input = `import {Button} from '@astryxdesign/core';
 export default Button;
 `;
-    const {default: transform} = await import(
-      '../unwrap-authoring-factories.mjs'
-    );
+    const {default: transform} =
+      await import('../unwrap-authoring-factories.mjs');
     const jscodeshift = (await import('jscodeshift')).default;
     const j = jscodeshift.withParser('tsx');
     const api = {jscodeshift: j, stats: () => {}, report: () => {}};

package/assets/codemods/transforms/v0.3.0/unwrap-authoring-factories.mjs

@@ -5,8 +5,9 @@
  *
  * v0.3.0 removes the authoring factories. Authoring is now types + parsers: an
  * author writes a plain object and stamps its `type` directly. This transform
- * rewrites every factory call to the plain object the factory used to return,
- * then drops the now-dead factory imports:
+ * rewrites factory calls imported from the retired Astryx authoring entrypoints
+ * to the plain object the factory used to return, then drops the now-dead
+ * factory imports:
  *
  *   createConfig(o) / createIntegration(o)        -> o        (no discriminant)
  *   createComponentDoc(o)                         -> { ...o, type: 'component' }
@@ -25,8 +26,9 @@
  *
  * Import aliases are followed (`import {createDoc as mk}` → calls to `mk`), and
  * the factory specifiers are removed afterward (the whole import statement goes
- * if nothing else was imported from it). Run this BEFORE
- * `migrate-authoring-imports`, which repoints the surviving type imports.
+ * if nothing else was imported from it). Same-named imports from other packages
+ * remain untouched. Run this BEFORE `migrate-authoring-imports`, which repoints
+ * the surviving type imports.
  */
 
 export const meta = {
@@ -35,13 +37,24 @@ export const meta = {
     'Rewrites createConfig/createIntegration/createComponentDoc/' +
     'createFunctionDoc/createDoc/createPageTemplate/createBlockTemplate/' +
     'createCodemod/createConfigCodemod calls to the plain object they returned ' +
-    "(stamping the doc/template/codemod `type` discriminant), and removes the " +
+    '(stamping the doc/template/codemod `type` discriminant), and removes the ' +
     'now-dead factory imports. Authoring is types + parsers in v0.3.0 — there ' +
     'are no factories.',
   pr: '#4612',
   fileExtensions: ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'],
 };
 
+/** Legacy Astryx authoring entrypoints that exported the removed factories. */
+const AUTHORING_SOURCES = new Set([
+  '@astryxdesign/cli/config',
+  '@astryxdesign/cli/doc',
+  '@astryxdesign/cli/integration',
+  '@astryxdesign/cli/template',
+  '@astryxdesign/cli/codemod',
+  '@astryxdesign/core/authoring',
+  '@astryxdesign/core/config',
+]);
+
 /**
  * Factory name → the `type` discriminant it stamped, or `null` for the config /
  * integration factories, which were pure typed-identity (no discriminant).
@@ -108,6 +121,7 @@ export default function transformer(file, api) {
   /** @type {Map<string, string>} */
   const localToFactory = new Map();
   root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
+    if (!AUTHORING_SOURCES.has(path.node.source.value)) return;
     for (const spec of path.node.specifiers ?? []) {
       if (spec.type !== 'ImportSpecifier') continue;
       const importedName = spec.imported?.name;
@@ -163,6 +177,7 @@ export default function transformer(file, api) {
   // Drop the now-dead factory import specifiers; remove any import statement
   // left empty.
   root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
+    if (!AUTHORING_SOURCES.has(path.node.source.value)) return;
     const specs = path.node.specifiers ?? [];
     const kept = specs.filter(
       (/** @type {any} */ spec) =>

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/README.md

@@ -48,3 +48,12 @@ The material is usually good; the finding is placement, not quality. It goes in
 **Fits no row?** It is still not caller-facing. Default it to [Contributing](https://github.com/facebook/astryx/wiki/Contributing), or `CONTRIBUTING.md` when it is a step someone follows with the repo cloned. Never default it back to this directory.
 
 Worked example: a responsive-and-interaction readiness rubric is grading criteria → **Component-Audit-Rubric**, or **Component-Lifecycle** if it is a promotion gate.
+
+## Sections are read one at a time
+
+`astryx docs <topic> --index` lists a topic's sections, and readers then open
+one section by its key. A section's key is its `id`, or a key derived from its
+title when it has none. Give a section an `id` when its title may change, since
+readers and extensions link to the key. Two sections in one topic cannot share
+a key. Keep each section small enough to read on its own: `astryx doctor` fails
+any section over 32 KB.

package/assets/docs/authoring.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs authoring`: every authoring schema, one section each.
+ *
+ * Built from the self-docs colocated under packages/cli/authoring, so it cannot
+ * drift from the schemas it describes. `astryx doctor` names a self-doc this
+ * topic cannot reach.
+ */
+
+import {buildAuthoringTopic} from '../../foundation/discovery/authoring-self-docs.mjs';
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+export const docs = await buildAuthoringTopic();

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.',
         },
       ],
     },