@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4

package/api/upgrade/upgrade.doc.mjs

@@ -13,16 +13,19 @@ export const doc = {
   name: 'upgrade',
   namespace: 'cli/api',
   displayName: 'upgrade()',
-  summary:
-    'After bumping @astryxdesign/core, migrate project source with codemods and update copied compositions.',
+  summary: 'Run version migrations and reconcile copied compositions.',
   description:
-    'Runs the codemods between `from` and the installed Core version, then refreshes the ' +
-    'managed agent-docs block. Dry-run by default; `apply` writes changes only after the ' +
-    'selected codemods and hooks succeed. Config codemods run before astryx.config is ' +
-    'loaded, so they can repair an invalid config. Also updates copied compositions from ' +
-    'their install receipts: unchanged files are updated, non-overlapping edits are merged, ' +
-    'and conflicts are left untouched. `list` only lists codemods; `registry` only updates ' +
-    'copied compositions.',
+    'Migrates project source from a previous Astryx version to the currently ' +
+    'installed one by running the registered codemods, and compares the fully ' +
+    'rendered managed agent-docs block on every migration path, including ' +
+    'same-Core integration guidance changes; list and registry-only modes do not ' +
+    'run migration reconciliation. Dry-run previews without writing; `apply` ' +
+    'writes the prepared block only after selected codemods and hooks succeed. ' +
+    'Core codemods run before ' +
+    'the config is loaded so a config codemod can repair an otherwise-invalid ' +
+    'astryx.config. Copied compositions carry adjacent receipts with exact canonical and format-specific install bases; upgrade ' +
+    'compares those installed bases with the matching registry release, updates pristine ' +
+    'files, merges non-overlapping edits, and leaves conflicting originals untouched.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'upgrade(options?: UpgradeOptions, ctx?: {cwd?: string}): Promise<UpgradeListResponse | UpgradeRegistryResponse | UpgradeStatusResponse | UpgradeRunResponse>',
@@ -39,7 +42,7 @@ export const doc = {
       name: 'options.from',
       type: 'string',
       description:
-        'Version before the dependency bump; the target is the installed @astryxdesign/core (or legacy @xds/core). Required unless `list` or `registry` is set.',
+        'Version before the dependency bump. Required unless `list` or `registry` is set.',
     },
     {
       name: 'options.apply',
@@ -52,13 +55,11 @@ export const doc = {
       type: 'boolean',
       description:
         'Run codemods even when `from` is at/after the installed version.',
-      default: 'false',
     },
     {
       name: 'options.codemod',
       type: 'string',
-      description:
-        'Run only this codemod. Optional codemods run only when named here. Setting it also skips copied-composition reconciliation.',
+      description: 'Run a single named transform instead of the full set.',
     },
     {
       name: 'options.skipCodemod',
@@ -82,26 +83,23 @@ export const doc = {
       type: 'boolean',
       description:
         'Install jscodeshift when it is missing; otherwise a missing jscodeshift throws ERR_DEP_MISSING.',
-      default: 'false',
     },
     {
       name: 'options.registry',
       type: 'boolean',
       description:
-        'Only reconcile copied compositions from their install receipts; `from` is not required. Cannot be combined with `list`, `from`, `force`, `codemod`, `skipCodemod`, `integration` or `installDeps`.',
+        'Reconcile copied compositions from their install receipts without requiring `from`.',
       default: 'false',
     },
     {
       name: 'options.list',
       type: 'boolean',
       description: 'Return the available codemods instead of running any.',
-      default: 'false',
     },
     {
       name: 'ctx.cwd',
       type: 'string',
       description: 'Directory to run the upgrade in.',
-      default: 'process.cwd()',
     },
   ],
   returns: [
@@ -118,36 +116,36 @@ export const doc = {
     {
       type: 'upgrade.status',
       description:
-        'A short-circuit outcome (no codemods executed): `up_to_date` (`from` is at/after the installed target and no `force`), `no_codemods` (none apply to the range), or `config_fixable` (dry-run preview that a pending config codemod would repair an invalid astryx.config). up_to_date and no_codemods carry the agent-docs summary and, when receipts are found, the copied-composition summary; config_fixable carries configError, configCodemods, suggestedCommand, message, note, and the agent-docs summary.',
+        'A short-circuit outcome (no codemods executed): `up_to_date` (`from` is at/after the installed target and no `force`), `no_codemods` (none apply to the range), or `config_fixable` (dry-run preview that a pending config codemod would repair an invalid astryx.config). Each carries the agent-docs summary and, when found, the copied-composition registry summary.',
     },
     {
       type: 'upgrade.run',
       description:
-        'The terminal run receipt: from, to, codemods (count), integrations, agentDocs, agentDocsRefreshed, registryCompositions (when receipts are found), filesChanged, transformsApplied, modifiedFiles, protectedFiles, declinedCandidates, errors, and complete. When a protected file still requires a change, complete is false and errorCode is ERR_CODEMOD_PROTECTED; the CLI exits nonzero while preserving the structured receipt.',
+        'The terminal run receipt: from/to versions, codemod count, integrations processed, agent-docs and registry summaries, modifiedFiles, protectedFiles, declinedCandidates, and completion state. A protected required change returns complete: false with ERR_CODEMOD_PROTECTED; the CLI exits nonzero while preserving the structured receipt.',
     },
   ],
   throws: [
     {
       code: 'ERR_INVALID_ARGUMENT',
-      when: '`from` is missing (and neither `list` nor `registry` is set); `list` and `registry` are both set; `registry` is combined with `from`, `force`, `codemod`, `skipCodemod`, `integration` or `installDeps`; an `integration` specifier is invalid or not installed; or astryx.config fails to load or validate and no pending config codemod repairs it',
+      when: '`from` is missing (and neither `list` nor `registry` is set), or the project config fails strict validation and no pending config codemod can repair it',
     },
     {code: 'ERR_INVALID_VERSION', when: '`from` is not a valid semver string'},
     {code: 'ERR_PATH_TRAVERSAL', when: '`path` resolves outside cwd'},
     {
       code: 'ERR_VERSION_DETECT',
-      when: 'neither @astryxdesign/core nor legacy @xds/core is installed in cwd; with `registry`, only when copied-composition receipts exist and @astryxdesign/core is not installed',
+      when: 'the installed @astryxdesign/core version cannot be detected',
     },
     {
       code: 'ERR_DEP_MISSING',
-      when: 'jscodeshift is missing and `installDeps` is not set, or installing it failed',
+      when: 'jscodeshift is required but could not be installed',
     },
     {
       code: 'ERR_UNKNOWN_CODEMOD',
-      when: 'the version range has codemods but none remain selected: `codemod` names no codemod in the range, or `skipCodemod` excludes all of them',
+      when: 'a `codemod` name matches no registered codemod',
     },
     {
       code: 'ERR_CODEMOD_FAILED',
-      when: 'one or more codemods failed, or a post-codemod hook failed, and no protected file still needs a change (otherwise an upgrade.run receipt with complete: false is returned)',
+      when: 'one or more codemods failed, or a post-codemod hook failed',
     },
     {
       code: 'ERR_CODEMOD_PROTECTION_SOURCE',

package/api/upgrade/upgrade.type.mjs

@@ -119,11 +119,11 @@
  * @property {RegistryCompositionSummary} [data.registryCompositions]
  * @property {boolean} [data.complete] False when protected required changes remain.
  * @property {'ERR_CODEMOD_PROTECTED'} [data.errorCode] Stable incomplete-result code when complete is false.
- * @property {number} [data.filesChanged] Distinct files changed across core + integration codemods (apply mode). One file that four codemods each changed counts once.
+ * @property {number} [data.filesChanged] Total files changed across core + integration codemods (apply mode).
  * @property {string[]} [data.modifiedFiles] Project-relative files changed or previewed.
  * @property {ProtectedCodemodFile[]} [data.protectedFiles] Protected files that still require a codemod change after regeneration.
  * @property {Array<{file: string, location?: string, reason: string}>} [data.declinedCandidates] Candidates left unchanged because proof was insufficient.
- * @property {number} [data.transformsApplied] Total codemod changes. A code or config codemod counts once for each file it changed, so one file changed by four of them counts four times; a project codemod counts once, however many files it writes.
+ * @property {number} [data.transformsApplied] Total transforms that reported a change.
  * @property {Array<{file: string, codemod: string, error: string}>} [data.errors] Per-codemod errors, when any codemod failed.
  */
 

package/assets/codemods/__tests__/runner.test.mjs

@@ -46,9 +46,7 @@ describe('runCodemods — ordered dry-run state', () => {
       silent: true,
     });
 
-    // One file that two transforms changed is one file and two changes.
-    expect(preview.totalFilesChanged).toBe(1);
-    expect(preview.totalTransformsApplied).toBe(2);
+    expect(preview.totalFilesChanged).toBe(2);
     expect(preview.changedFiles).toEqual([
       path.join(srcDir, 'a.ts'),
       path.join(srcDir, 'a.ts'),

package/assets/codemods/integration-runner.mjs

@@ -67,6 +67,7 @@ export function runIntegrationCodemods(
   /** In-memory pipeline state keeps ordered dry-runs equivalent to apply. */
   const virtualContents = new Map(providedContents ?? []);
 
+  let totalFilesChanged = 0;
   let totalTransformsApplied = 0;
   /** @type {string[]} */
   const changedFiles = [];
@@ -114,6 +115,7 @@ export function runIntegrationCodemods(
       protection,
       contents: virtualContents,
     });
+    totalFilesChanged += r.filesChanged;
     totalTransformsApplied += r.filesChanged;
     changedFiles.push(...r.changedFiles);
     writtenFiles.push(...r.writtenFiles);
@@ -143,6 +145,7 @@ export function runIntegrationCodemods(
         protection,
         contents: virtualContents,
       });
+      totalFilesChanged += r.filesChanged;
       totalTransformsApplied += r.filesChanged;
       changedFiles.push(...r.changedFiles);
       writtenFiles.push(...r.writtenFiles);
@@ -151,9 +154,6 @@ export function runIntegrationCodemods(
     }
   }
 
-  // A file several codemods changed is one file; transforms count each change.
-  const totalFilesChanged = new Set(changedFiles).size;
-
   return {
     totalFilesChanged,
     totalTransformsApplied,

package/assets/codemods/runner.mjs

@@ -486,6 +486,7 @@ export async function runCodemods(
       (await import('jscodeshift')).default
     );
 
+  let totalFilesChanged = 0;
   let totalTransformsApplied = 0;
   let totalValidationBlocked = 0;
   /** @type {Array<{file: string, codemod: string, error: string}>} */
@@ -553,6 +554,7 @@ export async function runCodemods(
           protectionWriteCount = writtenFiles.length;
         }
         if (result.filesChanged > 0) {
+          totalFilesChanged += result.filesChanged;
           totalTransformsApplied += 1;
         }
         continue;
@@ -575,6 +577,7 @@ export async function runCodemods(
         changedFiles.push(...result.changedFiles);
         writtenFiles.push(...result.writtenFiles);
         if (result.filesChanged > 0) {
+          totalFilesChanged += result.filesChanged;
           totalTransformsApplied += result.filesChanged;
         }
         continue;
@@ -589,6 +592,7 @@ export async function runCodemods(
       protectedFiles.push(...result.protectedFiles);
       changedFiles.push(...result.changedFiles);
       writtenFiles.push(...result.writtenFiles);
+      totalFilesChanged += result.filesChanged;
       totalTransformsApplied += result.filesChanged;
       totalValidationBlocked += result.errors.filter(
         error =>
@@ -626,11 +630,6 @@ export async function runCodemods(
     );
   }
 
-  // A file several codemods changed is one file. `totalTransformsApplied` is
-  // unchanged: a code or config codemod counts each file it changed, and a
-  // project codemod counts once. The two answer different questions.
-  const totalFilesChanged = new Set(changedFiles).size;
-
   if (protectedFiles.length > 0) {
     const files = [...new Set(protectedFiles.map(item => item.file))];
     log.warn(

package/assets/docs/README.md

@@ -21,15 +21,13 @@ Someone building a product with Astryx. Their questions:
 ## Tells that you are writing for us instead
 
 - second person aimed at the wrong reader — "reviewers should…", "before promoting a component…", "attach evidence for…"
-- an internal rubric, readiness gate, audit checklist, or sign-off that the reader must satisfy for Astryx maintainers
+- **rubric, readiness, gate, audit, checklist, sign-off, promotion, evidence** as things the reader must produce
 - a table of things to verify rather than things to use
 - anything about lab → core, which is our lifecycle, not theirs
 - Storybook, Playwright, CI or the Simulator named as tools the reader runs
 
 One subtlety: a statement about the **system's behavior** is caller-facing even when it sounds like process. "A component's theme targets are stable once published" tells a caller what they can rely on; "reviewers must check that theme targets are stable" is ours. Same fact, different reader — **rewrite it rather than move it**.
 
-A public authoring-quality rubric is also caller-facing when it helps someone evaluate an artifact they create through Astryx. It must be complete and actionable from public inputs. It must not include Astryx's internal approval, promotion, evidence-publication, or CI process. A current system spec must assign the shipped guide as the rubric's owner.
-
 ## Where the rest goes
 
 The material is usually good; the finding is placement, not quality. It goes in the [wiki](https://github.com/facebook/astryx/wiki) — **as a section on the page that already covers it, not a new page.** The wiki is at nearly 60 pages, several of them overlapping, because every stray section got its own.
@@ -57,5 +55,5 @@ Worked example: a responsive-and-interaction readiness rubric is grading criteri
 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` warns on
+a key. Keep each section small enough to read on its own: `astryx doctor` fails
 any section over 32 KB.

package/assets/docs/browser-support.doc.mjs

@@ -73,7 +73,7 @@ export const docs = {
               'Baseline 2026: the tightest requirement.',
             ],
             [
-              '`Popover` API',
+              '[`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API',
               'Opens, stacks, and light-dismisses layered surfaces via the top layer.',
               'Baseline 2025.',
             ],
@@ -86,7 +86,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'The gap that matters is between Tier 1 and Tier 2: the `Popover` API and `light-dark()` reached wide availability well before anchor positioning. So in Tier 2 browsers, layered surfaces open and dismiss correctly; they just are not positioned. This is the one feature most consumers will need to reason about.',
+          text: 'The gap that matters is between Tier 1 and Tier 2: the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API and `light-dark()` reached wide availability well before anchor positioning. So in Tier 2 browsers, layered surfaces open and dismiss correctly; they just are not positioned. This is the one feature most consumers will need to reason about.',
         },
       ],
     },
@@ -95,24 +95,24 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Any component that opens a menu, popover, tooltip, or dropdown carries the browser requirement: it renders that surface in an overlay positioned against its trigger. That includes:',
+          text: 'The browser requirement is concentrated in the layered-surface components: anything that renders content in an overlay positioned against a trigger:',
         },
         {
           type: 'list',
           style: 'unordered',
           items: [
-            'Tooltip, HoverCard, and Popover, and any prop that shows one (such as the Button `tooltip`)',
-            'DropdownMenu, MoreMenu, and ContextMenu',
-            'Selector, MultiSelector, ComplexSelector, Typeahead, and PowerSearch (dropdown surfaces)',
-            'DateInput, DateRangeInput, and DateTimeInput (calendar popovers)',
+            'Tooltip',
+            'HoverCard',
+            'Popover',
+            'ContextMenu',
+            'Selector and MultiSelector (dropdown surfaces)',
             'Tokenizer (suggestion menu)',
-            'The overflow and flyout menus in Breadcrumbs, TabList, TopNav, and SideNav',
             'Carousel (anchored controls)',
           ],
         },
         {
           type: 'prose',
-          text: 'If your product opens no menus, popovers, tooltips, or dropdowns, it has no anchor-positioning requirement; it needs only `light-dark()` (Tier 2 and up) for correct theme colors. Page layout, typography, forms, buttons, cards, and tables work down to Tier 2 with no special handling.',
+          text: 'If your product does not use any of these, it has no anchor-positioning requirement at all; it needs only `light-dark()` (Tier 2 and up) for correct theme colors. Page layout, typography, forms, buttons, cards, tables, and navigation all work down to Tier 2 with no special handling.',
         },
       ],
     },
@@ -123,7 +123,7 @@ export const docs = {
           type: 'list',
           style: 'do',
           items: [
-            'Components never throw on missing platform APIs. Where a browser lacks the `Popover` API, layers fall back to plain visibility instead of crashing.',
+            'Components never throw on missing platform APIs. Where a browser lacks the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API, layers fall back to plain visibility instead of crashing.',
             'Tier 1 and Tier 2 are officially supported and tested.',
             'Non-layered components render correctly down to Tier 2.',
           ],
@@ -192,7 +192,7 @@ const hasLightDark = CSS.supports('color', 'light-dark(#000, #fff)');`,
         },
         {
           type: 'prose',
-          text: 'This is not an arbitrary window: Baseline − 2 is close to where anchor positioning stops being available while the `Popover` API and `light-dark()` still are, so the tier boundary tracks a real capability edge, not a guessed date. The version floors above are reviewed and advanced roughly once a year as new Baseline years land. Always feature-detect rather than hardcoding version numbers, so your app adapts automatically as the platform moves.',
+          text: 'This is not an arbitrary window: Baseline − 2 is close to where anchor positioning stops being available while the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API and `light-dark()` still are, so the tier boundary tracks a real capability edge, not a guessed date. The version floors above are reviewed and advanced roughly once a year as new Baseline years land. Always feature-detect rather than hardcoding version numbers, so your app adapts automatically as the platform moves.',
         },
       ],
     },

package/assets/docs/color.doc.mjs

@@ -22,8 +22,7 @@ export const docs = {
       ],
     },
     {
-      id: 'surface-colors',
-      title: 'Color Tokens',
+      title: 'Surface Colors',
   category: 'foundations',
       content: [
         {
@@ -38,14 +37,9 @@ export const docs = {
       ],
     },
     {
-      id: 'usage',
-      title: 'Use color tokens in StyleX',
+      title: 'Usage',
   category: 'foundations',
       content: [
-        {
-          type: 'prose',
-          text: 'Import the typed color tokens and use them in `stylex.create()`; they resolve to the active theme and color mode.',
-        },
         {
           type: 'code',
           lang: 'tsx',

package/assets/docs/elevation.doc.mjs

@@ -82,7 +82,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Configurable surfaces expose a single `elevation` prop instead of asking consumers to hand-write a box-shadow. It takes the graded enum `none | low | med | high`, narrowed per component to the steps that surface needs: Card, ClickableCard, SelectableCard, Button, IconButton, ButtonGroup, ToggleButton, and Banner expose the full scale, while ChatComposer exposes only `none | low`. `none` is a flat literal (`box-shadow: none`); the other levels map to the `--shadow-*` tokens above, so a surface stays theme-agnostic.',
+          text: 'Configurable surfaces expose a single `elevation` prop instead of asking consumers to hand-write a box-shadow. It takes the graded enum `none | low | med | high`, narrowed per component to the steps that surface needs: Card, ClickableCard, SelectableCard, Button, IconButton, ButtonGroup, and Banner expose the full scale, while ChatComposer exposes only `none | low`. `none` is a flat literal (`box-shadow: none`); the other levels map to the `--shadow-*` tokens above, so a surface stays theme-agnostic.',
         },
         {
           type: 'prose',
@@ -92,13 +92,11 @@ export const docs = {
           type: 'code',
           lang: 'tsx',
           label: 'Raising a surface with the elevation prop',
-          code: `import {Plus} from 'lucide-react';
-
-// Flat by default; raise only when the surface needs to float.
+          code: `// Flat by default; raise only when the surface needs to float.
 <Card elevation="low">Raised card</Card>
 
 // A floating action button.
-<IconButton icon={<Icon icon={Plus} />} label="New" variant="primary" elevation="med" />
+<IconButton icon={<Icon icon="add" />} label="New" variant="primary" elevation="med" />
 
 // Flatten the composer (defaults to 'low').
 <ChatComposer elevation="none" onSubmit={handleSubmit} />`,
@@ -121,7 +119,7 @@ export const docs = {
           type: 'code',
           lang: 'tsx',
           label: 'Applying elevation',
-          code: `import {shadowVars} from '@astryxdesign/core/theme/tokens.stylex';
+          code: `import {shadowVars} from '@astryxdesign/core';
 
 const styles = stylex.create({
   dropdown: {

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

@@ -8,7 +8,6 @@ export const docs = {
   category: 'guide',
   description:
     'Add the design system to your project and start building.',
-  keywords: ['quick start', 'setup', 'install'],
 
   sections: [
     {
@@ -82,11 +81,24 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'Run `astryx theme list` to see every theme.',
+          text: 'Available themes:',
+        },
+        {
+          type: 'list',
+          style: 'unordered',
+          items: [
+            '`@astryxdesign/theme-neutral`: muted and minimal; a good starting point',
+            '`@astryxdesign/theme-butter`: warm, golden tones with blue accents',
+            '`@astryxdesign/theme-chocolate`: rich chocolate and caramel tones',
+            '`@astryxdesign/theme-gothic`: dark-only theme with ink and noir influences',
+            '`@astryxdesign/theme-matcha`: earthy greens and botanical tones',
+            '`@astryxdesign/theme-stone`: warm neutrals inspired by sandstone',
+            '`@astryxdesign/theme-y2k`: playful early-2000s pop aesthetic',
+          ],
         },
         {
           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. Before building screens, read the two cascade layer sections of {@link generic:migration}.',
+          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',
@@ -123,7 +135,7 @@ export default function Page() {
       content: [
         {
           type: 'prose',
-          text: 'Astryx components support various styling solutions, from plain CSS and `className` to Tailwind and CSS-in-JS. See {@link generic:styling} for the full guide. Astryx also has a deep integration with [StyleX](https://stylexjs.com/), an atomic CSS-in-JS library: create styles with `stylex.create()` and pass them to components with the `xstyle` prop.',
+          text: 'Astryx components support various styling solutions, from plain CSS and `className` to Tailwind and CSS-in-JS. See the [styling docs](/docs/styling) for the full guide. Astryx also has a deep integration with [StyleX](https://stylexjs.com/), an atomic CSS-in-JS library: create styles with `stylex.create()` and pass them to components with the `xstyle` prop.',
         },
         {
           type: 'code',
@@ -155,7 +167,6 @@ const overrides = stylex.create({
             ['Next.js + Tailwind', 'Next.js + Tailwind bridge', '[apps/example-nextjs-tailwind](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-tailwind)'],
             ['Next.js Source', 'Next.js importing from source', '[apps/example-nextjs-source](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-source)'],
             ['Vite', 'Vite', '[apps/example-vite](https://github.com/facebook/astryx/tree/main/apps/example-vite)'],
-            ['Vite + Tailwind', 'Vite + Tailwind bridge', '[apps/example-vite-tailwind](https://github.com/facebook/astryx/tree/main/apps/example-vite-tailwind)'],
           ],
         },
         {

package/assets/docs/icons.doc.mjs

@@ -73,7 +73,7 @@ export const docs = {
 import { HeartIcon } from 'lucide-react';
 
 <Icon icon={PhotoIcon} size="lg" />
-<Icon icon={HeartIcon} color="error" />`,
+<Icon icon={HeartIcon} color="negative" />`,
         },
       ],
     },
@@ -128,7 +128,26 @@ export const brandTheme = defineTheme({
         },
         {
           type: 'prose',
-          text: 'Outside core, pass a fallback to `getExtendedIcon(key, fallback)` so the glyph renders with no theme.',
+          text: 'Ship the fallback in `defaultIcons` under the same key so the glyph still renders with no theme, or pass one to `getExtendedIcon(key, fallback)` when the icon lives outside core.',
+        },
+      ],
+    },
+    {
+      title: 'Adding New Icons',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'To add a new semantic icon name to the design system, only for a glyph the whole system shares; a component-owned one takes a namespaced key instead:',
+        },
+        {
+          type: 'list',
+          style: 'ordered',
+          items: [
+            'Add the name to IconName type in `packages/core/src/Icon/globalIconRegistry.tsx`',
+            'Add the default SVG to `packages/core/src/Icon/defaultIcons.tsx`',
+            'Add a row to the Available Names table in `packages/cli/assets/docs/icons.doc.mjs`',
+          ],
         },
       ],
     },

package/assets/docs/illustrations.doc.mjs

@@ -7,7 +7,6 @@ export const docs = {
   category: 'foundations',
   description:
     'Illustration guidelines for empty states, onboarding flows, and feature highlights.',
-  keywords: ['empty state'],
 
   sections: [
     {
@@ -60,17 +59,26 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'For an empty state, pass the illustration to the `icon` slot of `EmptyState`, which centers it above the title and description. Typical illustration sizes range from 120px for inline empty states to 240px for full-page onboarding screens. Always pair the illustration with a title and a description that says what to do next.',
+          text: 'Place illustrations inside Center with supporting text stacked below. Typical illustration sizes range from 120px for inline empty states to 240px for full-page onboarding screens. Always pair the illustration with a heading and optional body text to explain what the user should do next.',
         },
         {
           type: 'code',
           lang: 'tsx',
           label: 'Empty state with illustration',
-          code: `<EmptyState
-  icon={<img src="/illustrations/empty-search.svg" alt="" width={200} height={200} />}
-  title="No results found"
-  description="Try adjusting your search or filters."
-/>`,
+          code: `<Center>
+  <Stack direction="vertical" gap={3} hAlign="center">
+    <img
+      src="/illustrations/empty-search.svg"
+      alt="No results"
+      style={{ width: 200, height: 200 }}
+    />
+    <Heading level={3}>No results found</Heading>
+    <Text type="body" color="secondary">
+      Try adjusting your search or filters to find what you\u2019re
+      looking for.
+    </Text>
+  </Stack>
+</Center>`,
         },
       ],
     },

package/assets/docs/internationalization.doc.mjs

@@ -41,17 +41,15 @@ function App() {
           lang: 'tsx',
           label: 'Load an astryx locale catalog',
           code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
-import frFR from '@astryxdesign/core/locales/fr-FR.generated.js';
+import fr from '@astryxdesign/core/locales/fr.json';
 
-<InternationalizationProvider
-  locale="fr-FR"
-  messages={{'fr-FR': frFR}}>
+<InternationalizationProvider locale="fr" messages={{fr}}>
   <App />
 </InternationalizationProvider>;`,
         },
         {
           type: 'prose',
-          text: 'Astryx ships English and first-party translations for supported locales. Compact runtime modules from `@astryxdesign/core/locales/*.generated.js` contain only the messages apps need; the existing `@astryxdesign/core/locales/*.json` files retain translator context. Until a locale is available, apps can pass a local catalog in either shape. Missing keys fall back through the locale chain to English (for example, `pt-BR` walks to `pt`, then to shipped `en`).',
+          text: 'Astryx ships English today, with first-party translations for other locales on the roadmap. Until a locale is available from `@astryxdesign/core/locales/*`, apps can pass a local catalog with the same shape. See `@astryxdesign/core/locales/en.json` for the current key inventory. Missing keys fall back through the locale chain to English (for example, `pt-BR` walks to `pt`, then to shipped `en`).',
         },
         {
           type: 'prose',
@@ -292,7 +290,7 @@ export default function App() {
         },
         {
           type: 'prose',
-          text: '`Catalog` types the rich `{defaultMessage, description?}` authoring shape. `RuntimeCatalog` types the generated key-to-message string map. `ProviderMessagesByLocale` accepts either shape for the provider, while `MessagesByLocale` keeps the original rich-only context shape.',
+          text: '`Catalog` types a single locale file; `MessagesByLocale` types the map passed to `messages`. A catalog entry uses the same `{defaultMessage, description?}` shape as `@astryxdesign/core/locales/en.json`.',
         },
       ],
     },
@@ -309,7 +307,7 @@ export default function App() {
           lang: 'tsx',
           label: 'Turn on pseudo-localization',
           code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
-import pseudo from '@astryxdesign/core/locales/pseudo.generated.js';
+import pseudo from '@astryxdesign/core/locales/pseudo.json';
 
 <InternationalizationProvider locale="pseudo" messages={{pseudo}}>
   <App />