@astryxdesign/cli 0.6.4 → 0.6.5-canary.00f1ed9

package/api/upgrade/upgrade.type.mjs

@@ -116,14 +116,15 @@
  * @property {string[]} data.integrations Integration packages processed in this upgrade (by name/spec).
  * @property {boolean} data.agentDocsRefreshed
  * @property {AgentDocsSummary} data.agentDocs
+ * @property {boolean} data.sourcePathFound Whether the resolved source directory (`path`, default `./src`) exists. False means no source file was read, so a zero `filesChanged` says nothing about the project being migrated.
  * @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] Total files changed across core + integration codemods (apply mode).
+ * @property {number} [data.filesChanged] Distinct files changed across core + integration codemods (apply mode). One file that four codemods each changed counts once.
  * @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 transforms that reported a change.
+ * @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 {Array<{file: string, codemod: string, error: string}>} [data.errors] Per-codemod errors, when any codemod failed.
  */
 

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

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

package/assets/codemods/file-count.test.mjs

@@ -0,0 +1,163 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `filesChanged` counts FILES, not (codemod, file) pairs.
+ *
+ * One source file that four codemods each changed was reported as four files
+ * changed — the total was incremented once per transform per file, so it
+ * equalled `transformsApplied` in every run and the documented meaning of the
+ * field ("Total files changed") was never true. The two numbers answer
+ * different questions and both are in the receipt.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import jscodeshift from 'jscodeshift';
+import {runCodemods} from './runner.mjs';
+import {runIntegrationCodemods} from './integration-runner.mjs';
+
+let dir;
+
+beforeEach(() => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-file-count-'));
+});
+afterEach(() => fs.rmSync(dir, {recursive: true, force: true}));
+
+/** A transform that rewrites one distinctive token, so several can stack. */
+const renaming = (from, to) => (file) =>
+  file.source.includes(from) ? file.source.split(from).join(to) : null;
+
+/** @param {string} name @param {string[]} contents */
+function writeSources(...contents) {
+  return contents.map((content, i) => {
+    const file = path.join(dir, `file${i}.ts`);
+    fs.writeFileSync(file, content);
+    return file;
+  });
+}
+
+describe('core codemod runner — filesChanged counts files', () => {
+  it('reports 1 file for one file changed by four codemods', async () => {
+    writeSources('const a = ONE + TWO + THREE + FOUR;\n');
+
+    const result = await runCodemods(
+      [
+        {
+          version: '0.0.2',
+          transforms: [
+            {name: 'one', transform: renaming('ONE', '1'), meta: {title: 'one'}},
+            {name: 'two', transform: renaming('TWO', '2'), meta: {title: 'two'}},
+            {name: 'three', transform: renaming('THREE', '3'), meta: {title: 'three'}},
+            {name: 'four', transform: renaming('FOUR', '4'), meta: {title: 'four'}},
+          ],
+        },
+      ],
+      {apply: true, path: dir, root: dir, codemod: undefined, skipCodemods: new Set(), silent: true},
+    );
+
+    expect(result.totalTransformsApplied).toBe(4);
+    expect(result.totalFilesChanged).toBe(1);
+    expect(new Set(result.changedFiles).size).toBe(1);
+  });
+
+  it('still counts two files as two', async () => {
+    writeSources('const a = ONE;\n', 'const b = ONE;\n');
+
+    const result = await runCodemods(
+      [
+        {
+          version: '0.0.2',
+          transforms: [
+            {name: 'one', transform: renaming('ONE', '1'), meta: {title: 'one'}},
+          ],
+        },
+      ],
+      {apply: true, path: dir, root: dir, codemod: undefined, skipCodemods: new Set(), silent: true},
+    );
+
+    expect(result.totalTransformsApplied).toBe(2);
+    expect(result.totalFilesChanged).toBe(2);
+  });
+
+  it('reports 0 when nothing matched', async () => {
+    writeSources('const a = 1;\n');
+
+    const result = await runCodemods(
+      [
+        {
+          version: '0.0.2',
+          transforms: [
+            {name: 'one', transform: renaming('ONE', '1'), meta: {title: 'one'}},
+          ],
+        },
+      ],
+      {apply: true, path: dir, root: dir, codemod: undefined, skipCodemods: new Set(), silent: true},
+    );
+
+    expect(result.totalFilesChanged).toBe(0);
+    expect(result.totalTransformsApplied).toBe(0);
+  });
+});
+
+describe('integration codemod runner — filesChanged counts files', () => {
+  it('reports 1 file for one file changed by three integration codemods', () => {
+    writeSources('const a = ONE + TWO + THREE;\n');
+
+    const entry = (id, from, to) => ({
+      id,
+      package: '@acme/widgets',
+      type: 'code',
+      codemod: {title: id, transform: renaming(from, to)},
+    });
+
+    const result = runIntegrationCodemods(
+      [
+        {
+          version: '1.0.0',
+          codemods: [
+            entry('one', 'ONE', '1'),
+            entry('two', 'TWO', '2'),
+            entry('three', 'THREE', '3'),
+          ],
+        },
+      ],
+      {apply: true, path: dir, root: dir, skipCodemods: new Set(), jscodeshift, silent: true},
+    );
+
+    expect(result.totalTransformsApplied).toBe(3);
+    expect(result.totalFilesChanged).toBe(1);
+    expect(new Set(result.changedFiles).size).toBe(1);
+  });
+});
+
+describe('core codemod runner — a project codemod', () => {
+  it('counts every file it writes, and one change', async () => {
+    const result = await runCodemods(
+      [
+        {
+          version: '0.0.2',
+          transforms: [
+            {
+              name: 'project-plan',
+              meta: {title: 'project plan', codemodType: 'project'},
+              transform: async root => ({
+                writes: [
+                  {path: path.join(root, 'a.ts'), contents: 'a\n'},
+                  {path: path.join(root, 'b.ts'), contents: 'b\n'},
+                ],
+                deletes: [],
+                problems: [],
+              }),
+            },
+          ],
+        },
+      ],
+      {apply: true, path: dir, root: dir, codemod: undefined, skipCodemods: new Set(), silent: true},
+    );
+
+    expect(result.totalFilesChanged).toBe(2);
+    expect(result.totalTransformsApplied).toBe(1);
+  });
+});

package/assets/codemods/integration-runner.mjs

@@ -67,7 +67,6 @@ 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 = [];
@@ -115,7 +114,6 @@ export function runIntegrationCodemods(
       protection,
       contents: virtualContents,
     });
-    totalFilesChanged += r.filesChanged;
     totalTransformsApplied += r.filesChanged;
     changedFiles.push(...r.changedFiles);
     writtenFiles.push(...r.writtenFiles);
@@ -145,7 +143,6 @@ export function runIntegrationCodemods(
         protection,
         contents: virtualContents,
       });
-      totalFilesChanged += r.filesChanged;
       totalTransformsApplied += r.filesChanged;
       changedFiles.push(...r.changedFiles);
       writtenFiles.push(...r.writtenFiles);
@@ -154,6 +151,9 @@ 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,7 +486,6 @@ 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}>} */
@@ -554,7 +553,6 @@ export async function runCodemods(
           protectionWriteCount = writtenFiles.length;
         }
         if (result.filesChanged > 0) {
-          totalFilesChanged += result.filesChanged;
           totalTransformsApplied += 1;
         }
         continue;
@@ -577,7 +575,6 @@ export async function runCodemods(
         changedFiles.push(...result.changedFiles);
         writtenFiles.push(...result.writtenFiles);
         if (result.filesChanged > 0) {
-          totalFilesChanged += result.filesChanged;
           totalTransformsApplied += result.filesChanged;
         }
         continue;
@@ -592,7 +589,6 @@ 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 =>
@@ -630,6 +626,11 @@ 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,13 +21,15 @@ 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…"
-- **rubric, readiness, gate, audit, checklist, sign-off, promotion, evidence** as things the reader must produce
+- an internal rubric, readiness gate, audit checklist, or sign-off that the reader must satisfy for Astryx maintainers
 - 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.
@@ -55,5 +57,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` fails
+a key. Keep each section small enough to read on its own: `astryx doctor` warns on
 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`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API',
+              '`Popover` 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`](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.',
+          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.',
         },
       ],
     },
@@ -95,24 +95,24 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'The browser requirement is concentrated in the layered-surface components: anything that renders content in an overlay positioned against a trigger:',
+          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:',
         },
         {
           type: 'list',
           style: 'unordered',
           items: [
-            'Tooltip',
-            'HoverCard',
-            'Popover',
-            'ContextMenu',
-            'Selector and MultiSelector (dropdown surfaces)',
+            '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)',
             'Tokenizer (suggestion menu)',
+            'The overflow and flyout menus in Breadcrumbs, TabList, TopNav, and SideNav',
             'Carousel (anchored controls)',
           ],
         },
         {
           type: 'prose',
-          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.',
+          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.',
         },
       ],
     },
@@ -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`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API, layers fall back to plain visibility instead of crashing.',
+            'Components never throw on missing platform APIs. Where a browser lacks the `Popover` 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`](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.',
+          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.',
         },
       ],
     },

package/assets/docs/color.doc.mjs

@@ -22,7 +22,8 @@ export const docs = {
       ],
     },
     {
-      title: 'Surface Colors',
+      id: 'surface-colors',
+      title: 'Color Tokens',
   category: 'foundations',
       content: [
         {
@@ -37,9 +38,14 @@ export const docs = {
       ],
     },
     {
-      title: 'Usage',
+      id: 'usage',
+      title: 'Use color tokens in StyleX',
   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, 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, 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.',
         },
         {
           type: 'prose',
@@ -92,11 +92,13 @@ export const docs = {
           type: 'code',
           lang: 'tsx',
           label: 'Raising a surface with the elevation prop',
-          code: `// Flat by default; raise only when the surface needs to float.
+          code: `import {Plus} from 'lucide-react';
+
+// 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="add" />} label="New" variant="primary" elevation="med" />
+<IconButton icon={<Icon icon={Plus} />} label="New" variant="primary" elevation="med" />
 
 // Flatten the composer (defaults to 'low').
 <ChatComposer elevation="none" onSubmit={handleSubmit} />`,
@@ -119,7 +121,7 @@ export const docs = {
           type: 'code',
           lang: 'tsx',
           label: 'Applying elevation',
-          code: `import {shadowVars} from '@astryxdesign/core';
+          code: `import {shadowVars} from '@astryxdesign/core/theme/tokens.stylex';
 
 const styles = stylex.create({
   dropdown: {

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

@@ -8,6 +8,7 @@ export const docs = {
   category: 'guide',
   description:
     'Add the design system to your project and start building.',
+  keywords: ['quick start', 'setup', 'install'],
 
   sections: [
     {
@@ -81,24 +82,11 @@ export const docs = {
         },
         {
           type: 'prose',
-          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',
-          ],
+          text: 'Run `astryx theme list` to see every theme.',
         },
         {
           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 {@link generic: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. Before building screens, read the two cascade layer sections of {@link generic:migration}.',
         },
         {
           type: 'prose',
@@ -135,7 +123,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 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.',
+          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.',
         },
         {
           type: 'code',
@@ -167,6 +155,7 @@ 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

@@ -42,6 +42,7 @@ export const docs = {
             ['menu', 'Hamburger menu, navigation toggle'],
             ['moreHorizontal', 'Overflow menu, additional actions'],
             ['search', 'Search inputs, find'],
+            ['upload', 'Upload files or content'],
             ['arrowUp', 'Sort ascending, move up'],
             ['arrowDown', 'Sort descending, move down'],
             ['arrowsUpDown', 'Sortable column indicator'],
@@ -73,7 +74,7 @@ export const docs = {
 import { HeartIcon } from 'lucide-react';
 
 <Icon icon={PhotoIcon} size="lg" />
-<Icon icon={HeartIcon} color="negative" />`,
+<Icon icon={HeartIcon} color="error" />`,
         },
       ],
     },
@@ -128,26 +129,7 @@ export const brandTheme = defineTheme({
         },
         {
           type: 'prose',
-          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`',
-          ],
+          text: 'Outside core, pass a fallback to `getExtendedIcon(key, fallback)` so the glyph renders with no theme.',
         },
       ],
     },

package/assets/docs/illustrations.doc.mjs

@@ -7,6 +7,7 @@ export const docs = {
   category: 'foundations',
   description:
     'Illustration guidelines for empty states, onboarding flows, and feature highlights.',
+  keywords: ['empty state'],
 
   sections: [
     {
@@ -59,26 +60,17 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          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.',
+          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.',
         },
         {
           type: 'code',
           lang: 'tsx',
           label: 'Empty state with illustration',
-          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>`,
+          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."
+/>`,
         },
       ],
     },

package/assets/docs/internationalization.doc.mjs

@@ -41,15 +41,17 @@ function App() {
           lang: 'tsx',
           label: 'Load an astryx locale catalog',
           code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
-import fr from '@astryxdesign/core/locales/fr.json';
+import frFR from '@astryxdesign/core/locales/fr-FR.generated.js';
 
-<InternationalizationProvider locale="fr" messages={{fr}}>
+<InternationalizationProvider
+  locale="fr-FR"
+  messages={{'fr-FR': frFR}}>
   <App />
 </InternationalizationProvider>;`,
         },
         {
           type: 'prose',
-          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`).',
+          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`).',
         },
         {
           type: 'prose',
@@ -290,7 +292,7 @@ export default function App() {
         },
         {
           type: 'prose',
-          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`.',
+          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.',
         },
       ],
     },
@@ -307,7 +309,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.json';
+import pseudo from '@astryxdesign/core/locales/pseudo.generated.js';
 
 <InternationalizationProvider locale="pseudo" messages={{pseudo}}>
   <App />