@astryxdesign/cli 0.6.3 → 0.6.4-canary.078fd25

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,28 +82,15 @@ 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 `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. Before building screens, read the two cascade layer sections of {@link generic:migration}.',
         },
         {
           type: 'prose',
-          text: 'Run `astryx docs theme` for the full theming guide.',
+          text: 'Run {@link generic:theme} for the full theming guide.',
         },
       ],
     },
@@ -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

@@ -73,7 +73,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 +128,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 />

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.',
         },
       ],
     },
@@ -33,8 +33,35 @@ export const docsDense = {
       section: 'Scaffold',
       title: 'Scaffold',
       content: [
-        // Shell
-        null,
+        {
+          type: 'prose',
+          text: 'pick shell, budget regions, choose nav, before content. steps: Shell, Navigation. rules for both:',
+        },
+        {
+          type: 'list',
+          items: [
+            'decide frame + region width budgets + fill-or-capped before content',
+            'state the reason for the nav choice, or inherit template pairing',
+            'raw px for structural widths; interior = tokens',
+          ],
+        },
+        {
+          type: 'list',
+          items: [
+            'build content-first, Card-wrapping each section',
+            'stretch prose/forms/lists across a wide region instead of capping with contentWidth',
+            'SideNav when the nav is really filters/controls, or must hold wide elements like breadcrumbs',
+            'TopNav when top-slot ownership is unclear, or hierarchy is deep or still growing',
+            'both bars when the ecosystem layer is thin',
+            'break template nav pairing without a reason',
+          ],
+        },
+      ],
+    },
+    {
+      section: 'Shell',
+      title: 'Shell',
+      content: [
         {
           type: 'prose',
           text: 'pick the shell + budget its regions before any content exists. structural widths are the one place raw px belongs; everything inside uses the scale.',
@@ -53,8 +80,12 @@ export const docsDense = {
           type: 'prose',
           text: 'verify: every region has a width budget + fill-or-capped + a container policy written down before any content.',
         },
-        // Navigation
-        null,
+      ],
+    },
+    {
+      section: 'Navigation',
+      title: 'Navigation',
+      content: [
         {
           type: 'prose',
           text: 'nav left open? default SideNav: it absorbs destinations you have not planned yet. app type + destination count are guiding indicators, not determining rules.',
@@ -71,37 +102,47 @@ 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.',
+        },
+      ],
+    },
+    {
+      section: 'Structure',
+      title: 'Structure',
+      content: [
+        {
+          type: 'prose',
+          text: 'rank content per region, pick the weakest container that groups it. steps: Type hierarchy, Card or rows, Headers and footers, Side panels. rules for all:',
         },
-        // Best practices
-        null,
         {
           type: 'list',
           items: [
-            'decide frame + region width budgets + fill-or-capped before content',
-            'state the reason for the nav choice, or inherit template pairing',
-            'raw px for structural widths; interior = tokens',
+            'one lead per region; rank via weight+color; one primary action',
+            'leave body copy at its defaults; demote via weight+color, not size',
+            'default Section; weakest container that reads as a group',
+            'collections = rows (Table/List), edge-to-edge with dividers',
+            'side panel on select; it yields width at narrow sizes',
           ],
         },
         {
           type: 'list',
           items: [
-            'build content-first, Card-wrapping each section',
-            'stretch prose/forms/lists across a wide region instead of capping with contentWidth',
-            'SideNav when the nav is really filters/controls, or must hold wide elements like breadcrumbs',
-            'TopNav when top-slot ownership is unclear, or hierarchy is deep or still growing',
-            'both bars when the ecosystem layer is thin',
-            'break template nav pairing without a reason',
+            'grey + shrink body copy, so a whole region reads as metadata',
+            'the disabled color for content; it fails contrast, it is for disabled controls',
+            'card soup: each record in its own Card',
+            'cards-in-cards, or full-width Cards as page structure',
+            'a header/footer rebuilt inside the body, where it scrolls away with the rows',
+            'flexbox soup instead of Grid/Layout/Section/FormLayout',
+            'two competing primary actions in one region',
+            'Badge as decoration; use StatusDot/Token for status',
           ],
         },
       ],
     },
     {
-      section: 'Structure',
-      title: 'Structure',
+      section: 'Type hierarchy',
+      title: 'Type hierarchy',
       content: [
-        // Type hierarchy
-        null,
         {
           type: 'prose',
           text: 'one lead per region, then rank with weight+color, not size. two text colors only: primary + secondary, nothing dimmer. body copy needs no props.',
@@ -120,8 +161,12 @@ export const docsDense = {
           type: 'prose',
           text: 'squint test: read lead, then support, then groups, in order. everything at once = raise contrast (weight/color), not borders and not smaller text.',
         },
-        // Containers
-        null,
+      ],
+    },
+    {
+      section: 'Card or rows',
+      title: 'Card or rows',
+      content: [
         {
           type: 'prose',
           text: 'weakest container that reads as a group, escalate only when it fails. weakest to strongest:',
@@ -140,8 +185,12 @@ export const docsDense = {
           type: 'prose',
           text: 'test: records -> rows (Table columnar, List single-line); self-contained widget or hard boundary -> Card; everything else -> Section.',
         },
-        // Headers and footers
-        null,
+      ],
+    },
+    {
+      section: 'Headers and footers',
+      title: 'Headers and footers',
+      content: [
         {
           type: 'prose',
           text: 'a region can pin a header/footer while its body scrolls. both are Layout slots, and padding set once on Layout reaches all three, so header/body/footer share one content line.',
@@ -160,8 +209,12 @@ export const docsDense = {
           type: 'prose',
           text: 'verify: scroll the body. header + footer stay put, dividers run full-bleed, all three still share one left content line.',
         },
-        // Side panels
-        null,
+      ],
+    },
+    {
+      section: 'Side panels',
+      title: 'Side panels',
+      content: [
         {
           type: 'prose',
           text: 'master-detail: select a row -> fixed-width side panel, no navigation away.',
@@ -179,41 +232,43 @@ export const docsDense = {
         null,
         {
           type: 'prose',
-          text: 'verify: at narrow widths the panel yields width instead of squeezing content (see Breakpoints), and only one element between the regions draws a border.',
+          text: 'verify: at narrow widths the panel yields width instead of squeezing content (see Responsive contract), and only one element between the regions draws a border.',
+        },
+      ],
+    },
+    {
+      section: 'Spacing',
+      title: 'Spacing',
+      content: [
+        {
+          type: 'prose',
+          text: 'one content line per region, then tune gaps + density. steps: Alignment, Rhythm, Density and size. rules for all:',
         },
-        // Best practices
-        null,
         {
           type: 'list',
           items: [
-            'one lead per region; rank via weight+color; one primary action',
-            'leave body copy at its defaults; demote via weight+color, not size',
-            'default Section; weakest container that reads as a group',
-            'collections = rows (Table/List), edge-to-edge with dividers',
-            'side panel on select; it yields width at narrow sizes',
+            'container owns padding; children zero margins',
+            'one content line: text on line, hover bleeds to edge',
+            'one padding token across region header/body/footer',
+            'contrast tight vs generous gaps',
+            'one control size per row; density by use frequency',
           ],
         },
         {
           type: 'list',
           items: [
-            'grey + shrink body copy, so a whole region reads as metadata',
-            'the disabled color for content; it fails contrast, it is for disabled controls',
-            'card soup: each record in its own Card',
-            'cards-in-cards, or full-width Cards as page structure',
-            'a header/footer rebuilt inside the body, where it scrolls away with the rows',
-            'flexbox soup instead of Grid/Layout/Section/FormLayout',
-            'two competing primary actions in one region',
-            'Badge as decoration; use StatusDot/Token for status',
+            'double padding (component past its heading); keep one inset owner',
+            'raw px for interior spacing; tokens only',
+            'one repeated gap everywhere',
+            'mixed control sizes in one row',
           ],
         },
       ],
     },
     {
-      section: 'Spacing',
-      title: 'Spacing',
+      section: 'Alignment',
+      title: 'Alignment',
       content: [
-        // Alignment
-        null,
         {
           type: 'prose',
           text: 'container owns padding + child gaps; children zero margins; interior spacing = token. one content line per region, hold the line not the padding: container_inset = content_line - component_intrinsic_inset.',
@@ -231,8 +286,12 @@ export const docsDense = {
           type: 'prose',
           text: 'verify: draw one vertical line down the left. every label touches it; only hover/selected backgrounds cross it.',
         },
-        // Rhythm
-        null,
+      ],
+    },
+    {
+      section: 'Rhythm',
+      title: 'Rhythm',
+      content: [
         {
           type: 'prose',
           text: 'grouping = contrast between tight and generous gaps, not one repeated value. same step everywhere = proximity does no work.',
@@ -250,8 +309,12 @@ export const docsDense = {
           type: 'prose',
           text: 'verify: borders removed, you can still name the groups from spacing alone. cannot = intervals too uniform. form fields excepted: FormLayout owns their spacing.',
         },
-        // Density and size
-        null,
+      ],
+    },
+    {
+      section: 'Density and size',
+      title: 'Density and size',
+      content: [
         {
           type: 'prose',
           text: 'density by use frequency; every control in a row shares one size so heights share a baseline.',
@@ -269,35 +332,38 @@ export const docsDense = {
           type: 'prose',
           text: 'verify: one size per row, paired with the density of the region it sits in.',
         },
-        // Best practices
-        null,
+      ],
+    },
+    {
+      section: 'Breakpoints',
+      title: 'Breakpoints',
+      content: [
+        {
+          type: 'prose',
+          text: 'decide what each region does as width changes. step: Responsive contract. rules:',
+        },
         {
           type: 'list',
           items: [
-            'container owns padding; children zero margins',
-            'one content line: text on line, hover bleeds to edge',
-            'one padding token across region header/body/footer',
-            'contrast tight vs generous gaps',
-            'one control size per row; density by use frequency',
+            'write the contract down for every region before calling the layout done',
+            'decide per region: revealed, resized, or swapped at each width',
+            'drop a region rather than let it fight for width it lacks',
           ],
         },
         {
           type: 'list',
           items: [
-            'double padding (component past its heading); keep one inset owner',
-            'raw px for interior spacing; tokens only',
-            'one repeated gap everywhere',
-            'mixed control sizes in one row',
+            '3 regions at a width where none has usable space',
+            'shrink every region uniformly instead of swapping/dropping one',
+            'a CSS breakpoint the contract comment never mentions',
           ],
         },
       ],
     },
     {
-      section: 'Breakpoints',
-      title: 'Breakpoints',
+      section: 'Responsive contract',
+      title: 'Responsive contract',
       content: [
-        // Responsive contract
-        null,
         {
           type: 'prose',
           text: 'lock what each region does as width changes; pair each contract line with the prop/hook that enforces it.',
@@ -316,24 +382,6 @@ export const docsDense = {
           type: 'prose',
           text: 'verify: every contract line names a mechanism, so the comment cannot drift from the behavior.',
         },
-        // Best practices
-        null,
-        {
-          type: 'list',
-          items: [
-            'write the contract down for every region before calling the layout done',
-            'decide per region: revealed, resized, or swapped at each width',
-            'drop a region rather than let it fight for width it lacks',
-          ],
-        },
-        {
-          type: 'list',
-          items: [
-            '3 regions at a width where none has usable space',
-            'shrink every region uniformly instead of swapping/dropping one',
-            'a CSS breakpoint the contract comment never mentions',
-          ],
-        },
       ],
     },
   ],