@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db52d98

package/assets/codemods/transforms/next/__tests__/migrate-theme-catalog-to-descriptors.test.mjs

@@ -0,0 +1,220 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import manifest from '../index.mjs';
+import migrate from '../migrate-theme-catalog-to-descriptors.mjs';
+import {runCodemods} from '../../../runner.mjs';
+import {discoverThemeDirectory} from '../../../../../foundation/discovery/theme-discovery.mjs';
+
+let root;
+
+beforeEach(() => {
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-theme-catalog-'));
+});
+
+afterEach(() => {
+  fs.rmSync(root, {recursive: true, force: true});
+});
+
+/** A catalog entry exactly as `astryx integration add theme <slug>` wrote it in 0.6. */
+function entry(slug, overrides = {}) {
+  const identifier = slug.replace(/-([a-z0-9])/gu, (_, c) => c.toUpperCase());
+  const displayName = slug
+    .split('-')
+    .map(part => part[0].toUpperCase() + part.slice(1))
+    .join(' ');
+  return {
+    slug,
+    displayName,
+    description: `${displayName} theme.`,
+    maintained: true,
+    entry: `${identifier}Theme.ts`,
+    exportName: `${identifier}Theme`,
+    files: [`${identifier}Theme.ts`],
+    ...overrides,
+  };
+}
+
+/** @param {ReturnType<typeof entry>[]} themes */
+function writeKit(themes, {sources = true} = {}) {
+  fs.writeFileSync(
+    path.join(root, 'package.json'),
+    '{"name":"@acme/kit","version":"1.0.0"}\n',
+  );
+  fs.writeFileSync(
+    path.join(root, 'astryx.integration.mjs'),
+    "export default {themes: './themes'};\n",
+  );
+  for (const theme of themes) {
+    const source = path.join(root, 'themes', theme.slug, theme.entry);
+    fs.mkdirSync(path.dirname(source), {recursive: true});
+    if (sources) {
+      fs.writeFileSync(
+        source,
+        `import {defineTheme} from '@astryxdesign/core/theme';\n\nexport const ${theme.exportName} = defineTheme({\n  name: '${theme.slug}',\n});\n`,
+      );
+    }
+  }
+  fs.mkdirSync(path.join(root, 'themes'), {recursive: true});
+  fs.writeFileSync(
+    path.join(root, 'themes', 'manifest.json'),
+    `${JSON.stringify({version: 1, themes}, null, 2)}\n`,
+  );
+}
+
+const catalog = () => path.join(root, 'themes', 'manifest.json');
+
+/** @param {boolean} apply @param {string} [srcPath] */
+const run = (apply, srcPath = root) =>
+  runCodemods([{version: 'next', transforms: manifest}], {
+    apply,
+    path: srcPath,
+    codemod: undefined,
+    silent: true,
+    root,
+  });
+
+describe('migrate-theme-catalog-to-descriptors', () => {
+  it('is staged for the next release as a project codemod', () => {
+    expect(manifest.map(t => [t.name, t.meta.codemodType])).toEqual([
+      ['migrate-theme-catalog-to-descriptors', 'project'],
+      ['migrate-native-picker-to-presentation', undefined],
+    ]);
+  });
+
+  it('writes one typed descriptor per catalog theme and removes the catalog', async () => {
+    writeKit([
+      entry('ocean'),
+      entry('deep-sea', {
+        displayName: "Deep 'Sea'",
+        description: 'Line one\nline two \\ done.',
+        maintained: false,
+      }),
+    ]);
+
+    const result = await run(true);
+
+    expect(result).toMatchObject({errors: [], totalFilesChanged: 3});
+    expect(fs.existsSync(catalog())).toBe(false);
+    expect(
+      fs.readFileSync(
+        path.join(root, 'themes/ocean/oceanTheme.doc.mjs'),
+        'utf-8',
+      ),
+    ).toBe(
+      "/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */\nexport default {\n  type: 'theme',\n  name: 'ocean',\n  displayName: 'Ocean',\n  description: 'Ocean theme.',\n  maintained: true,\n};\n",
+    );
+    const themes = discoverThemeDirectory(
+      path.join(root, 'themes'),
+      '@acme/kit',
+    );
+    expect(
+      themes.map(({slug, displayName, description, maintained}) => ({
+        slug,
+        displayName,
+        description,
+        maintained,
+      })),
+    ).toEqual([
+      {
+        slug: 'deep-sea',
+        displayName: "Deep 'Sea'",
+        description: 'Line one\nline two \\ done.',
+        maintained: false,
+      },
+      {
+        slug: 'ocean',
+        displayName: 'Ocean',
+        description: 'Ocean theme.',
+        maintained: true,
+      },
+    ]);
+  });
+
+  it('previews without writing, even with no source folder', async () => {
+    writeKit([entry('ocean')]);
+    // A staged code codemod (migrate-native-picker-to-presentation) requires
+    // the source folder to exist; an empty one exercises the same preview.
+    fs.mkdirSync(path.join(root, 'src'), {recursive: true});
+
+    const result = await run(false, path.join(root, 'src'));
+
+    expect(result).toMatchObject({
+      errors: [],
+      totalFilesChanged: 2,
+      writtenFiles: [],
+    });
+    expect(fs.existsSync(catalog())).toBe(true);
+    expect(
+      fs.existsSync(path.join(root, 'themes/ocean/oceanTheme.doc.mjs')),
+    ).toBe(false);
+  });
+
+  it('keeps a descriptor that already exists and still removes the catalog', async () => {
+    writeKit([entry('ocean'), entry('reef')]);
+    const kept = path.join(root, 'themes/ocean/oceanTheme.doc.mjs');
+    fs.writeFileSync(
+      kept,
+      "export default {type: 'theme', name: 'ocean', displayName: 'Mine', description: '', maintained: true};\n",
+    );
+
+    const result = await run(true);
+
+    expect(result.errors).toEqual([]);
+    expect(fs.readFileSync(kept, 'utf-8')).toContain("displayName: 'Mine'");
+    expect(
+      fs.existsSync(path.join(root, 'themes/reef/reefTheme.doc.mjs')),
+    ).toBe(true);
+    expect(fs.existsSync(catalog())).toBe(false);
+  });
+
+  it('changes nothing and names each entry that cannot convert', async () => {
+    writeKit([
+      entry('ocean'),
+      entry('sea', {exportName: 'oceanBlue'}),
+      entry('nested', {
+        entry: 'src/nestedTheme.ts',
+        files: ['src/nestedTheme.ts'],
+      }),
+    ]);
+    fs.rmSync(path.join(root, 'themes/ocean/oceanTheme.ts'));
+    const before = fs.readFileSync(catalog(), 'utf-8');
+
+    const result = await run(true);
+
+    expect(result.errors.map(e => [e.file, e.error])).toEqual([
+      ['themes/ocean', 'holds no oceanTheme.ts for theme "ocean".'],
+      [
+        'themes/manifest.json',
+        'theme "sea" exports "oceanBlue" from seaTheme.ts; a descriptor takes the export name from the file name, so rename the export or the file to match.',
+      ],
+      [
+        'themes/manifest.json',
+        'theme "nested" has entry "src/nestedTheme.ts"; a descriptor sits beside a .ts, .tsx, .mjs, or .js source directly in themes/nested/.',
+      ],
+    ]);
+    expect(fs.readFileSync(catalog(), 'utf-8')).toBe(before);
+    expect(fs.existsSync(path.join(root, 'themes/sea/seaTheme.doc.mjs'))).toBe(
+      false,
+    );
+  });
+
+  it('leaves a package with no catalog to convert alone', async () => {
+    const empty = {writes: [], deletes: [], problems: []};
+    await expect(migrate(root)).resolves.toEqual(empty);
+    fs.writeFileSync(
+      path.join(root, 'astryx.integration.mjs'),
+      'export default {};\n',
+    );
+    await expect(migrate(root)).resolves.toEqual(empty);
+    fs.writeFileSync(
+      path.join(root, 'astryx.integration.mjs'),
+      "export default {themes: './themes'};\n",
+    );
+    fs.mkdirSync(path.join(root, 'themes'));
+    await expect(migrate(root)).resolves.toEqual(empty);
+  });
+});

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

@@ -7,4 +7,22 @@
  * this file into the resolved version folder.
  */
 
-export default [];
+import migrateThemeCatalogToDescriptors, {
+  meta as migrateThemeCatalogToDescriptorsMeta,
+} from './migrate-theme-catalog-to-descriptors.mjs';
+import migrateNativePickerToPresentation, {
+  meta as migrateNativePickerToPresentationMeta,
+} from './migrate-native-picker-to-presentation.mjs';
+
+export default [
+  {
+    name: 'migrate-theme-catalog-to-descriptors',
+    transform: migrateThemeCatalogToDescriptors,
+    meta: migrateThemeCatalogToDescriptorsMeta,
+  },
+  {
+    name: 'migrate-native-picker-to-presentation',
+    transform: migrateNativePickerToPresentation,
+    meta: migrateNativePickerToPresentationMeta,
+  },
+];

package/assets/codemods/transforms/next/migrate-native-picker-to-presentation.mjs

@@ -0,0 +1,148 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: migrate nativePicker to presentation on date/time inputs
+ *
+ * `spec:AST-043` FR3 mapping, applied only to static literals written
+ * directly on imported `DateInput`, `DateTimeInput`, and `TimeInput`
+ * elements: the prop is renamed to `presentation` and its value mapped.
+ * When the element already sets `presentation`, the deprecated prop is
+ * removed (presentation wins, FR4). Dynamic values are left unchanged —
+ * the deprecated prop keeps working, so an unmigrated callsite is still
+ * correct, and guessing at an expression's values would not be.
+ */
+
+import {transformProp} from '../../transform-prop.mjs';
+
+export const meta = {
+  title: 'Migrate nativePicker to presentation',
+  description:
+    'Renames `nativePicker` to `presentation` on DateInput, DateTimeInput, ' +
+    'and TimeInput, mapping touch→adaptive-native, always→native, and ' +
+    'never→adaptive-bottom-sheet (text-input for TimeInput). Dynamic ' +
+    'values are left for manual migration; the deprecated prop still works.',
+};
+
+const CORE_IMPORT_RE = /^@(astryxdesign|xds)\/core(?:\/|$)/;
+
+const COMPONENT_PROPS = new Map([
+  ['DateInput', new Set(['nativePicker'])],
+  ['DateTimeInput', new Set(['nativePicker'])],
+  ['TimeInput', new Set(['nativePicker'])],
+]);
+
+/** @param {string} component @param {string} value */
+function mapValue(component, value) {
+  switch (value) {
+    case 'touch':
+      return 'adaptive-native';
+    case 'always':
+      return 'native';
+    case 'never':
+      return component === 'TimeInput' ? 'text-input' : 'adaptive-bottom-sheet';
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Collect the string-literal leaves of a value expression without mutating
+ * anything. Returns false for any dynamic or non-string node.
+ * @param {any} node
+ * @param {any[]} leaves
+ * @returns {boolean}
+ */
+function collectStaticLeaves(node, leaves) {
+  if (!node) return false;
+  if (
+    node.type === 'TSAsExpression' ||
+    node.type === 'TSSatisfiesExpression' ||
+    node.type === 'TypeCastExpression' ||
+    node.type === 'ParenthesizedExpression'
+  ) {
+    return collectStaticLeaves(node.expression, leaves);
+  }
+  if (node.type === 'ConditionalExpression') {
+    return (
+      collectStaticLeaves(node.consequent, leaves) &&
+      collectStaticLeaves(node.alternate, leaves)
+    );
+  }
+  if (
+    (node.type !== 'StringLiteral' && node.type !== 'Literal') ||
+    typeof node.value !== 'string'
+  ) {
+    return false;
+  }
+  leaves.push(node);
+  return true;
+}
+
+/**
+ * Map every leaf, or none of them: a mixed static/dynamic conditional must
+ * stay byte-identical, never half-migrated.
+ * @param {any} node
+ * @param {string} component
+ */
+function mapStaticValue(node, component) {
+  /** @type {any[]} */
+  const leaves = [];
+  if (!collectStaticLeaves(node, leaves)) return false;
+  if (leaves.some(leaf => mapValue(component, leaf.value) === undefined)) {
+    return false;
+  }
+  for (const leaf of leaves) {
+    leaf.value = mapValue(component, leaf.value);
+    if (leaf.raw) leaf.raw = undefined;
+  }
+  return true;
+}
+
+/**
+ * @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file
+ * @param {import('../../../../authoring/codemod/type').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
+export default function transformer(file, api) {
+  if (!file.source.includes('nativePicker')) return undefined;
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  transformProp(
+    root,
+    j,
+    {
+      matchesImport: source => CORE_IMPORT_RE.test(source),
+      components: COMPONENT_PROPS,
+    },
+    (propPath, {component}) => {
+      const opening = propPath.parent?.node;
+      const attributes = opening?.attributes ?? [];
+      const hasPresentation = attributes.some(
+        (/** @type {any} */ attribute) =>
+          attribute.type === 'JSXAttribute' &&
+          attribute.name?.name === 'presentation',
+      );
+      const prop = propPath.node;
+      if (hasPresentation) {
+        // FR4: presentation wins; drop the deprecated prop.
+        opening.attributes = attributes.filter(
+          (/** @type {any} */ attribute) => attribute !== prop,
+        );
+        hasChanges = true;
+        return;
+      }
+      const value =
+        prop.value?.type === 'JSXExpressionContainer'
+          ? prop.value.expression
+          : prop.value;
+      if (!mapStaticValue(value, component)) return;
+      prop.name.name = 'presentation';
+      hasChanges = true;
+    },
+  );
+
+  if (!hasChanges) return undefined;
+  return root.toSource({quote: 'single'});
+}

package/assets/codemods/transforms/next/migrate-theme-catalog-to-descriptors.mjs

@@ -0,0 +1,141 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Give each integration theme a typed descriptor instead of the
+ *   `manifest.json` theme catalog.
+ *
+ * Astryx 0.6 scaffolded integration themes into one catalog,
+ * `<themes root>/manifest.json`. Each theme now carries a strongly typed
+ * same-stem `.doc.mjs` descriptor, and a themes root that still holds the
+ * catalog is refused. This project codemod reads the package's integration
+ * manifest, plans one descriptor per catalog entry beside that theme's source,
+ * and removes the catalog. When any entry cannot convert, it plans nothing and
+ * names the entry, so the package is never left half converted.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {loadManifestObject} from '../../../../foundation/integrations/integrations.mjs';
+import {findLocalIntegrationManifestOrNull} from '../../../../foundation/integrations/manifest-writer.mjs';
+import {themeDescriptorSource} from '../../../../foundation/integrations/theme-descriptor.mjs';
+
+export const meta = {
+  title:
+    'Give each integration theme a typed descriptor instead of the manifest.json catalog',
+  description:
+    'Writes <name>Theme.doc.mjs beside each theme the catalog lists, then removes the catalog.',
+  codemodType: 'project',
+};
+
+const SLUG = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
+const SOURCE = /\.(?:ts|tsx|mjs|js)$/u;
+
+/**
+ * @param {string} root the package directory
+ * @returns {Promise<import('../../runner.mjs').ProjectCodemodPlan>}
+ */
+export default async function migrateThemeCatalogToDescriptors(root) {
+  /** @type {import('../../runner.mjs').ProjectCodemodPlan} */
+  const plan = {writes: [], deletes: [], problems: []};
+  /** @param {string} file @returns {string} */
+  const rel = file => path.relative(root, file).split(path.sep).join('/');
+  /** @param {string} file @param {string} message */
+  const problem = (file, message) => plan.problems.push({file, message});
+
+  const manifestFile = findLocalIntegrationManifestOrNull(root);
+  if (!manifestFile) return plan;
+  const manifest = await loadManifestObject(
+    manifestFile,
+    `Integration manifest ${path.basename(manifestFile)}`,
+    {fresh: true},
+  );
+  if (typeof manifest.themes !== 'string') return plan;
+  const themesRoot = path.resolve(root, manifest.themes);
+  const fromRoot = path.relative(root, themesRoot);
+  if (fromRoot.startsWith('..') || path.isAbsolute(fromRoot)) return plan;
+  const catalogFile = path.join(themesRoot, 'manifest.json');
+  if (!fs.existsSync(catalogFile)) return plan;
+  const catalogPath = rel(catalogFile);
+
+  let catalog;
+  try {
+    catalog = JSON.parse(fs.readFileSync(catalogFile, 'utf-8'));
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    problem(catalogPath, `is not valid JSON (${reason}).`);
+    return plan;
+  }
+  if (
+    !catalog ||
+    typeof catalog !== 'object' ||
+    catalog.version !== 1 ||
+    !Array.isArray(catalog.themes)
+  ) {
+    problem(catalogPath, 'is not a version 1 theme catalog.');
+    return plan;
+  }
+
+  for (const [index, entry] of catalog.themes.entries()) {
+    const slug = entry?.slug;
+    if (typeof slug !== 'string' || !SLUG.test(slug)) {
+      problem(
+        catalogPath,
+        `themes[${index}] has no lowercase kebab-case slug; fix the entry or add that theme's descriptor by hand.`,
+      );
+      continue;
+    }
+    const themeDir = path.join(themesRoot, slug);
+    const source = entry.entry;
+    if (
+      typeof source !== 'string' ||
+      !SOURCE.test(source) ||
+      source !== path.basename(source)
+    ) {
+      problem(
+        catalogPath,
+        `theme "${slug}" has entry ${JSON.stringify(source)}; a descriptor sits beside a .ts, .tsx, .mjs, or .js source directly in ${rel(themeDir)}/.`,
+      );
+      continue;
+    }
+    const stem = source.replace(SOURCE, '');
+    if (entry.exportName !== stem) {
+      problem(
+        catalogPath,
+        `theme "${slug}" exports ${JSON.stringify(entry.exportName)} from ${source}; a descriptor takes the export name from the file name, so rename the export or the file to match.`,
+      );
+      continue;
+    }
+    if (typeof entry.displayName !== 'string' || !entry.displayName.trim()) {
+      problem(catalogPath, `theme "${slug}" has no displayName.`);
+      continue;
+    }
+    if (typeof entry.description !== 'string') {
+      problem(catalogPath, `theme "${slug}" has no description string.`);
+      continue;
+    }
+    if (typeof entry.maintained !== 'boolean') {
+      problem(catalogPath, `theme "${slug}" has no maintained flag.`);
+      continue;
+    }
+    if (!fs.existsSync(path.join(themeDir, source))) {
+      problem(rel(themeDir), `holds no ${source} for theme "${slug}".`);
+      continue;
+    }
+    const descriptor = path.join(themeDir, `${stem}.doc.mjs`);
+    if (fs.existsSync(descriptor)) continue;
+    plan.writes.push({
+      path: descriptor,
+      contents: themeDescriptorSource({
+        type: 'theme',
+        name: slug,
+        displayName: entry.displayName,
+        description: entry.description,
+        maintained: entry.maintained,
+      }),
+    });
+  }
+  if (plan.problems.length > 0)
+    return {writes: [], deletes: [], problems: plan.problems};
+  plan.deletes.push(catalogFile);
+  return plan;
+}

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/layout.doc.dense.mjs

@@ -25,7 +25,7 @@ export const docsDense = {
         },
         {
           type: 'prose',
-          text: 'decides layout, not component APIs. npx astryx build "<idea>" = closest template for your app type. npx astryx component <Name> = props.',
+          text: 'decides layout, not component APIs. npx astryx build "<idea>" = the template to start from for your app type. npx astryx component <Name> = props.',
         },
       ],
     },
@@ -71,7 +71,7 @@ export const docsDense = {
         null,
         {
           type: 'prose',
-          text: 'verify: you can state the reason in one sentence, and it still holds if the nav doubles. npx astryx build "<idea>" names the closest template, --skeleton shows the pairing wired up.',
+          text: 'verify: you can state the reason in one sentence, and it still holds if the nav doubles. npx astryx build "<idea>" names the template to start from; scaffold it and the pairing is wired up.',
         },
         // Best practices
         null,

package/assets/docs/layout.doc.mjs

@@ -106,7 +106,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'Verify: you can state the reason in one sentence, and the choice still holds if the nav doubles in size. `npx astryx build "<idea>"` names the closest template, and its `--skeleton` shows the pairing already wired up.',
+          text: 'Verify: you can state the reason in one sentence, and the choice still holds if the nav doubles in size. `npx astryx build "<idea>"` names the template to start from; scaffold it and the pairing is already wired up.',
         },
 
         {type: 'heading', level: 3, text: 'Best practices'},

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}.',
         },
       ],
     },
@@ -150,7 +150,7 @@ const styles = stylex.create({
       content: [
         {
           type: 'prose',
-          text: 'The Tailwind v4 bridge at `@astryxdesign/core/tailwind-theme.css` maps Tailwind theme variables to system CSS variables with `@theme inline`, so utility classes like `text-primary`, `bg-surface`, `border-border`, `rounded-lg`, and `shadow-md` stay in sync with the active theme.',
+          text: 'The Tailwind v4 bridge at `@astryxdesign/core/tailwind-theme.css` maps Tailwind theme variables to system CSS variables with `@theme reference inline`, so utility classes like `text-primary`, `bg-surface`, `border-border`, `rounded-lg`, and `shadow-md` stay in sync with the active theme without emitting competing runtime declarations.',
         },
         {
           type: 'code',
@@ -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.',
           ],
         },