@astryxdesign/cli 0.1.7 → 0.1.8-canary.07362a9

package/docs/elevation.doc.mjs

@@ -36,10 +36,85 @@ export const docs = {
         },
       ],
     },
+    {
+      title: 'Choosing a level',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'Pick the level by how far the surface sits from the page, not by how much shadow you want. Elevation encodes stacking order: a higher level means the surface is layered over more of the UI. Use exactly one level per surface, and only raise a surface above `none` when it actually sits above other content.',
+        },
+        {
+          type: 'table',
+          headers: ['Level', 'When to use', 'Examples'],
+          rows: [
+            [
+              'none',
+              'The component is flat and embedded in the surface — it is part of the page, not layered above it. This is the default for every surface except ChatComposer.',
+              'A Card in a grid, an inline Banner, a standard Button',
+            ],
+            [
+              'low',
+              'The component is in the normal page flow but should read as distinct from the background. Use for emphasis or to separate the component from the surface behind it — the component still sits on the page, it is not floating over other content.',
+              'A raised Card that needs emphasis, a ChatComposer',
+            ],
+            [
+              'med',
+              'The component sits over other content on the same page — it floats above nearby elements but not the whole screen.',
+              'A Popover, a floating Banner, a floating action Button',
+            ],
+            [
+              'high',
+              'The component is placed over the entire UI — it is the topmost layer and typically has a backdrop or takes focus from everything else.',
+              'A modal Dialog, a full-screen overlay surface',
+            ],
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'If two surfaces overlap, the one on top takes the higher level. If a surface does not overlap anything, it is `none` or `low` — never `med` or `high`.',
+        },
+      ],
+    },
+    {
+      title: 'The elevation prop',
+  category: 'foundations',
+      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.',
+        },
+        {
+          type: 'prose',
+          text: 'Prop defaults preserve current appearance: every surface defaults to `none` except ChatComposer, which defaults to `low` to keep its raised look. Set `elevation="none"` to flatten it — the flat composer draws a border with the same rest / hover / focus treatment as a text input.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Raising a surface with the elevation prop',
+          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="add" />} label="New" variant="primary" elevation="med" />
+
+// Flatten the composer (defaults to 'low').
+<ChatComposer elevation="none" onSubmit={handleSubmit} />`,
+        },
+        {
+          type: 'prose',
+          text: 'Always float — no prop: intrinsic overlays (Dialog, Popover, Tooltip, Toast, HoverCard, DropdownMenu, and the components that compose them) bake their elevation in and never expose the prop. Flow content (inputs, Text, layout) is never elevated; input fields use inset rings, which are a separate concept from elevation.',
+        },
+      ],
+    },
     {
       title: 'Usage',
   category: 'foundations',
       content: [
+        {
+          type: 'prose',
+          text: 'When building a custom surface, read elevation from the token scale rather than a hand-rolled shadow — the same tokens the elevation prop resolves to.',
+        },
         {
           type: 'code',
           lang: 'tsx',
@@ -68,7 +143,8 @@ const styles = stylex.create({
           type: 'list',
           style: 'do',
           items: [
-            'Match elevation to interaction context: low for tooltips, med for dropdowns, high for dialogs.',
+            'Reach for the `elevation` prop on a configurable surface before writing any custom shadow.',
+            'Choose the level by how far the surface sits from the page: `none` when flat/embedded, `low` when in-flow but distinct, `med` when over page content, `high` when over the whole UI. See "Choosing a level".',
             'Use inset shadows for input focus/selection states; they compose better than outlines.',
           ],
         },
@@ -76,6 +152,8 @@ const styles = stylex.create({
           type: 'list',
           style: 'dont',
           items: [
+            'Hand-write a `box-shadow` in app code — set the `elevation` prop or read `shadowVars` instead.',
+            'Raise a surface that does not sit above other content — a non-overlapping surface is `none` or `low`, never `med` or `high`.',
             'Stack multiple elevation levels on the same element.',
             'Use elevation shadows for decorative borders. Use --color-border tokens instead.',
           ],

package/docs/getting-started.doc.mjs

@@ -21,7 +21,7 @@ export const docs = {
           type: 'code',
           lang: 'text',
           label: 'Paste this into your AI',
-          code: 'Install @astryxdesign/core, @astryxdesign/theme-neutral, and @astryxdesign/cli in this project. Run `npx astryx init` to set up agent docs. Read the generated files to learn the conventions.',
+          code: 'Install @astryxdesign/core, @astryxdesign/theme-neutral, and @astryxdesign/cli in this project, then run `npx @astryxdesign/cli init` to set up agent docs. Read the generated files to learn the conventions.',
         },
       ],
     },
@@ -40,7 +40,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'Then run the init wizard to set up AI agent docs, pick a starter template, and learn about theming.',
+          text: "Then run `astryx init` to install the AI agent cheat sheet (AGENTS.md/CLAUDE.md). It's non-interactive — no prompts — so it's safe for AI agents, CI, and scripts. Add `--all` for pointers to the theme and page-building workflows.",
         },
         {
           type: 'code',
@@ -67,11 +67,11 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'Available themes: @astryxdesign/theme-neutral (muted minimal, a good starting point), @astryxdesign/theme-butter, @astryxdesign/theme-chocolate, @astryxdesign/theme-gothic (dark-only), @astryxdesign/theme-matcha, @astryxdesign/theme-stone, and @astryxdesign/theme-y2k. See `npx astryx docs theme` for the full theming guide.',
+          text: 'Available themes: @astryxdesign/theme-neutral (muted minimal, a good starting point), @astryxdesign/theme-butter, @astryxdesign/theme-chocolate, @astryxdesign/theme-gothic (dark-only), @astryxdesign/theme-matcha, @astryxdesign/theme-stone, and @astryxdesign/theme-y2k. See `astryx docs theme` for the full theming guide.',
         },
         {
           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 `npx 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 `astryx docs migration` before building screens.',
         },
       ],
     },
@@ -172,11 +172,11 @@ pnpm dev`,
           type: 'code',
           lang: 'bash',
           label: 'Terminal',
-          code: `npx astryx component          # list all components
-npx astryx component Button   # props, usage, theming for Button
-npx astryx docs               # list all doc topics
-npx astryx template --list    # available page templates
-npx astryx docs tokens        # spacing, color, radius reference`,
+          code: `astryx component          # list all components
+astryx component Button   # props, usage, theming for Button
+astryx docs               # list all doc topics
+astryx template --list    # available page templates
+astryx docs tokens        # spacing, color, radius reference`,
         },
       ],
     },

package/docs/internationalization.doc.mjs

@@ -7,7 +7,7 @@ export const docs = {
   title: 'Internationalization',
   category: 'guide',
   description:
-    'Localize astryx component strings, provide translation catalogs, override default text, coexist with your own i18n library, swap languages at runtime, and test translations with the pseudo locale.',
+    'Set the active locale for astryx components, load locale catalogs, coexist with your own i18n library, swap languages at runtime, and test translations with the pseudo locale.',
 
   sections: [
     {
@@ -16,13 +16,13 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Internationalization ships with `@astryxdesign/core`. There is nothing to install. Wrap your app in `<InternationalizationProvider>` and set a `locale`, and astryx components pick up localized strings automatically.',
+          text: 'Internationalization ships with `@astryxdesign/core`. There is nothing to install. Wrap your app in `<InternationalizationProvider>` and set the active `locale`; astryx components pick up localized strings from that provider.',
         },
         {
           type: 'code',
           lang: 'tsx',
           label: 'Wrap your app',
-          code: `import {InternationalizationProvider} from '@astryxdesign/core';
+          code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
 
 function App() {
   return (
@@ -32,53 +32,56 @@ function App() {
   );
 }`,
         },
+        {
+          type: 'prose',
+          text: 'The provider always has the built-in English catalog. Pass additional catalogs through `messages` when you enable another locale.',
+        },
         {
           type: 'code',
           lang: 'tsx',
-          label: 'Read strings inside a component',
-          code: `import {useTranslator} from '@astryxdesign/core';
+          label: 'Load an astryx locale catalog',
+          code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
+import fr from '@astryxdesign/core/locales/fr.json';
 
-function SaveButton() {
-  const t = useTranslator();
-  return <button>{t('@myapp.actions.save')}</button>;
-}`,
+<InternationalizationProvider locale="fr" messages={{fr}}>
+  <App />
+</InternationalizationProvider>;`,
         },
         {
           type: 'prose',
-          text: 'The hook is available to consumer components too, but using it is entirely optional: many teams keep their app strings on their existing i18n library (react-intl, i18next, next-intl, LinguiJS) and only use `useTranslator` when reading astryx keys. If you do route your own strings through it, we recommend namespacing them (`@myapp.*` or your npm scope) to keep them separated from `@astryx.*`, but this is a convention, not a requirement; the resolver treats every key as an opaque string.',
+          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',
-          text: "Astryx ships translations only for English today. First-party translations for other locales are on the roadmap; track https://github.com/facebook/astryx/issues/3641. In the meantime, if you want astryx UI translated into another locale, you can ship your own catalog through the `messages` prop (covered in the next section). If you're using `useTranslator` for your own strings, you'll want to ship your own catalog either way, since astryx only carries the fallback for `@astryx.*` keys, not the ones you author.",
+          text: 'Locale catalogs only affect astryx strings. Your app can continue using its own i18n system for product copy.',
         },
       ],
     },
     {
-      title: 'Providing locale catalogs',
+      title: 'Runtime language swap',
       category: 'guide',
       content: [
         {
           type: 'prose',
-          text: 'Astryx bundles only the English catalog today. To render in any other locale, provide a translation catalog through the `messages` prop and set `locale` accordingly. This matches how MUI, Ant Design, and AG Grid work: the consumer app supplies the catalogs it actually needs so unused translations stay out of the bundle.',
+          text: 'Re-render `<InternationalizationProvider>` with a new `locale` prop and every astryx string updates live. No reload, no separate API call.',
         },
         {
           type: 'code',
           lang: 'tsx',
-          label: 'Add French',
-          code: `import {InternationalizationProvider} from '@astryxdesign/core';
-import fr from './locales/astryx/fr.json';
+          label: 'Toggle between locales',
+          code: `const [locale, setLocale] = useState<'en' | 'fr'>('en');
 
-<InternationalizationProvider locale="fr" messages={{fr}}>
+<InternationalizationProvider locale={locale} messages={{fr}}>
+  <Button
+    label={locale === 'en' ? 'Français' : 'English'}
+    onClick={() => setLocale(l => (l === 'en' ? 'fr' : 'en'))}
+  />
   <App />
 </InternationalizationProvider>;`,
         },
         {
           type: 'prose',
-          text: "See `@astryxdesign/core/locales/en.json` for the full inventory of keys to translate. Copy it as the starting point: every key you translate replaces the English default; anything you omit falls back through the locale chain to English (e.g. `pt-BR` walks to `pt` then to shipped `en`), so a partial translation renders as a mix rather than empty text or raw key names.",
-        },
-        {
-          type: 'prose',
-          text: 'A community-maintained set of astryx translations is on the roadmap but not shipped yet. For now, consumer apps that ship in multiple languages own their astryx catalogs alongside their app catalogs. Contributions to a first-party set are welcome; track discussion at https://github.com/facebook/astryx/issues/3641.',
+          text: "Persisting the user's choice (localStorage, cookie, URL segment, account setting) is up to the consumer. Astryx reads whatever `locale` you pass in.",
         },
       ],
     },
@@ -119,7 +122,7 @@ import fr from './locales/astryx/fr.json';
           type: 'code',
           lang: 'tsx',
           label: 'Astryx + react-intl side by side',
-          code: `import {InternationalizationProvider} from '@astryxdesign/core';
+          code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
 import {Selector} from '@astryxdesign/core/Selector';
 import {Button} from '@astryxdesign/core/Button';
 import {FormattedMessage, IntlProvider, useIntl} from 'react-intl';
@@ -169,35 +172,56 @@ export default function App() {
         },
         {
           type: 'prose',
-          text: "Single-catalog usage (where an external i18n runtime like react-intl or i18next resolves both your app strings AND astryx's strings through one provider) is on the roadmap via a `Translator` adapter. Track https://github.com/facebook/astryx/issues/4029. For now, run the two providers side by side as shown above.",
+          text: "Single-catalog usage (where an external i18n runtime like react-intl or i18next resolves both your app strings AND astryx's strings through one provider) is on the roadmap via a `Translator` adapter. Track [facebook/astryx#4029](https://github.com/facebook/astryx/issues/4029). For now, run the two providers side by side as shown above.",
         },
       ],
     },
     {
-      title: 'Runtime language swap',
+      title: 'Using astryx as your i18n library',
       category: 'guide',
       content: [
         {
           type: 'prose',
-          text: 'Re-render `<InternationalizationProvider>` with a new `locale` prop and every astryx string updates live. No reload, no separate API call.',
+          text: "For production apps with substantial localization needs, we recommend a dedicated i18n library such as react-intl, i18next, next-intl, or LinguiJS. If your app is small or you do not want another runtime, you can resolve your own strings through astryx too. Keep app keys in a separate namespace from `@astryx.*`, and include your own `en` catalog because astryx's built-in English fallback only contains astryx component strings.",
         },
         {
           type: 'code',
           lang: 'tsx',
-          label: 'Toggle between locales',
-          code: `const [locale, setLocale] = useState<'en' | 'fr'>('en');
+          label: 'Translate app strings with astryx',
+          code: `import {Button} from '@astryxdesign/core/Button';
+import {
+  InternationalizationProvider,
+  useTranslator,
+  type Catalog,
+  type MessagesByLocale,
+} from '@astryxdesign/core/i18n';
 
-<InternationalizationProvider locale={locale} messages={{fr}}>
-  <Button
-    label={locale === 'en' ? 'Français' : 'English'}
-    onClick={() => setLocale(l => (l === 'en' ? 'fr' : 'en'))}
-  />
-  <App />
-</InternationalizationProvider>;`,
+const en: Catalog = {
+  '@myapp.actions.save': {defaultMessage: 'Save'},
+};
+
+const fr: Catalog = {
+  '@myapp.actions.save': {defaultMessage: 'Enregistrer'},
+};
+
+const messages: MessagesByLocale = {en, fr};
+
+function SaveButton() {
+  const t = useTranslator();
+  return <Button label={t('@myapp.actions.save')} />;
+}
+
+export default function App() {
+  return (
+    <InternationalizationProvider locale="fr" messages={messages}>
+      <SaveButton />
+    </InternationalizationProvider>
+  );
+}`,
         },
         {
           type: 'prose',
-          text: "Persisting the user's choice (localStorage, cookie, URL segment, account setting) is up to the consumer. Astryx reads whatever `locale` you pass in.",
+          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`.',
         },
       ],
     },
@@ -207,36 +231,58 @@ export default function App() {
       content: [
         {
           type: 'prose',
-          text: 'Astryx generates a `pseudo` locale that wraps every string in `⟦…⟧` and replaces letters with accented look-alikes. Switching to it in development instantly reveals any astryx string that isn\'t going through the translator, plus any layout that breaks under longer text.',
+          text: 'Astryx generates a `pseudo` locale that wraps every string in `⟦…⟧` and replaces letters with accented look-alikes. Switch to it in development to catch hardcoded astryx strings and layout issues caused by longer text.',
         },
         {
           type: 'code',
           lang: 'tsx',
           label: 'Turn on pseudo-localization',
-          code: `import pseudo from '@astryxdesign/core/locales/pseudo.json';
+          code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
+import pseudo from '@astryxdesign/core/locales/pseudo.json';
 
 <InternationalizationProvider locale="pseudo" messages={{pseudo}}>
   <App />
 </InternationalizationProvider>;`,
         },
-        {
-          type: 'prose',
-          text: 'Any bare English text you still see on screen is a hardcoded string that needs to be routed through `useTranslator`.',
-        },
-        {
-          type: 'prose',
-          text: "Pseudoloc also has a subtle caveat worth knowing: the pseudo catalog is complete (astryx generates it from every shipped key), so a component using an astryx-shipped key will always render its pseudo version. Your handwritten translation catalogs, on the other hand, only cover the keys you translated; anything missing falls back to English. That means \"looks perfect in pseudo\" is not the same guarantee as \"looks perfect in French.\" Check each real locale by hand for coverage gaps.",
-        },
       ],
     },
     {
       title: 'For contributors',
       category: 'guide',
       content: [
+        {
+          type: 'heading',
+          level: 3,
+          text: 'Developers',
+        },
+        {
+          type: 'prose',
+          text: 'Astryx component authors read strings with `useTranslator()` rather than hardcoding user-facing text.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Read an astryx string',
+          code: `import {useTranslator} from '@astryxdesign/core/i18n';
+
+function SaveButton() {
+  const t = useTranslator();
+  return <button>{t('@astryx.actions.save')}</button>;
+}`,
+        },
         {
           type: 'prose',
           text: "Astryx's own strings live in `packages/core/locales/en.json`. New user-facing strings must go through `useTranslator`; this is enforced by the `@astryx/no-hardcoded-i18n-string` ESLint rule. See the AI contribution guide for the alias-and-resolve pattern used when adding new keys.",
         },
+        {
+          type: 'heading',
+          level: 3,
+          text: 'Translators',
+        },
+        {
+          type: 'prose',
+          text: 'Crowdin is the preferred way to contribute — [join a language](https://crowdin.com/project/astryx), translate strings in the web UI, and your work syncs back to the repo without opening a PR. Direct PRs against `packages/core/locales/*.json` also work if you prefer that flow.',
+        },
       ],
     },
   ],

package/docs/migration.doc.mjs

@@ -54,18 +54,18 @@ export const docs = {
           type: 'code',
           lang: 'bash',
           label: 'Migration-oriented CLI pass',
-          code: `npx astryx docs migration
-npx astryx docs theme
-npx astryx docs styling
-npx astryx template --list --type block
-npx astryx template AppShellTopNavWithSideNav --skeleton
-npx astryx template PopoverSettingsPanel --skeleton
-npx astryx component AppShell
-npx astryx component SideNav
-npx astryx component TopNav
-npx astryx component CommandPalette
-npx astryx component Button
-npx astryx component TextInput`,
+          code: `astryx docs migration
+astryx docs theme
+astryx docs styling
+astryx template --list --type block
+astryx template AppShellTopNavWithSideNav --skeleton
+astryx template PopoverSettingsPanel --skeleton
+astryx component AppShell
+astryx component SideNav
+astryx component TopNav
+astryx component CommandPalette
+astryx component Button
+astryx component TextInput`,
         },
         {
           type: 'prose',
@@ -75,8 +75,8 @@ npx astryx component TextInput`,
           type: 'code',
           lang: 'bash',
           label: 'Dense and JSON modes',
-          code: `npx astryx docs migration --dense
-npx astryx component Button --json`,
+          code: `astryx docs migration --dense
+astryx component Button --json`,
         },
       ],
     },
@@ -371,10 +371,10 @@ if (getComputedStyle(button).paddingInline === '0px') {
           code: `We are migrating this existing Tailwind/shadcn app to Astryx incrementally.
 
 First run:
-- npx astryx docs migration --dense
-- npx astryx docs theme --dense
-- npx astryx docs styling --dense
-- npx astryx template AppShellTopNavWithSideNav --skeleton
+- astryx docs migration --dense
+- astryx docs theme --dense
+- astryx docs styling --dense
+- astryx template AppShellTopNavWithSideNav --skeleton
 
 Then migrate one route or shell surface at a time. Keep business logic and routing intact. Replace shadcn/Radix/Tailwind primitives with Astryx components, remove hardcoded colors, verify light and dark mode, and take screenshots before moving to the next surface.`,
         },

package/docs/principles.doc.dense.mjs

@@ -9,6 +9,6 @@ export const docsDense = {
     { section: 'Rules', title: 'Rules', content: [{ type: 'list', items: ['use components', 'frame-first layout: shell + region budgets before content (astryx docs layout)', 'dense data = rows (Table, List/Item) not Cards; Card = widgets/galleries/settings groups', 'StyleX or Tailwind for styling', 'semantic tokens only', 'CSS vars for colors', 'controlled form inputs', 'useLinkComponent() for navigation'] }] },
     { section: 'Styling Approach', title: 'Styling', content: [{ type: 'prose', text: 'xstyle prop for component overrides. StyleX or Tailwind for layout. See astryx docs styling.' }] },
     { section: 'Anti-Patterns', title: 'Anti-Patterns', content: [{ type: 'list', items: ['no inline styles on raw elements', 'no hardcoded colors — use tokens or Tailwind semantic classes', 'no hardcoded spacing', 'no hardcoded <a> — use useLinkComponent()', 'no Card-wrapped list items — frame first, rows for dense data (astryx docs layout)', 'no decorative Badge — StatusDot/Token for status', 'read docs before inventing props'] }] },
-    { section: 'Design Tokens', title: 'Tokens', content: [{ type: 'prose', text: 'run npx astryx docs tokens for full reference' }] },
+    { section: 'Design Tokens', title: 'Tokens', content: [{ type: 'prose', text: 'run astryx docs tokens for full reference' }] },
   ],
 };

package/docs/principles.doc.mjs

@@ -39,10 +39,10 @@ export const docs = {
           style: 'ordered',
           items: [
             'Use components for everything they cover',
-            'Layout is frame-first: pick the shell and budget regions before writing content (see \`npx astryx docs layout\`)',
+            'Layout is frame-first: pick the shell and budget regions before writing content (see \`astryx docs 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 \`npx astryx docs styling\`)',
-            'Semantic tokens, not hardcoded values (see \`npx astryx docs tokens\`)',
+            'StyleX or Tailwind for custom styling; both are first-class (see \`astryx docs styling\`)',
+            'Semantic tokens, not hardcoded values (see \`astryx docs 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 \`npx astryx docs styling\` for the complete guide with examples.',
+          text: 'See \`astryx docs 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 \`npx astryx docs layout\`)',
+            'Wrapping every list item or page section in a Card. Decide the frame first; dense data renders as rows (see \`astryx docs 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 \`npx 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 \`astryx docs tokens\` for the full reference with all values.',
         },
       ],
     },

package/docs/principles.doc.zh.mjs

@@ -9,6 +9,6 @@ export const docsZh = {
     { section: 'Rules', title: '规则', content: [{ type: 'list', items: ['所有支持的场景都使用 XDS 组件', '布局采用框架优先：先选定外壳并规划区域尺寸，再编写内容（见 astryx docs layout）', '密集数据使用行（Table、List/Item）通栏渲染；Card 用于小部件、画廊和设置分组', '使用 StyleX 或 Tailwind 进行样式设置', '使用语义化令牌，不使用硬编码值', '使用 CSS 变量设置颜色，不使用十六进制值', '表单输入为受控组件（value + onChange）', '使用 useLinkComponent() 进行导航'] }] },
     { section: 'Styling Approach', title: '样式方法', content: [{ type: 'prose', text: '组件覆盖使用 xstyle 属性。布局使用 StyleX 或 Tailwind。详见 astryx docs styling。' }] },
     { section: 'Anti-Patterns', title: '反模式', content: [{ type: 'list', items: ['不要在原始元素上使用内联样式', '不要硬编码颜色 — 使用令牌或 Tailwind 语义类', '不要硬编码间距', '不要硬编码 <a> 元素 — 使用 useLinkComponent()', '不要把每个列表项都包在 Card 里 — 先定框架，密集数据用行渲染（见 astryx docs layout）', '不要把 Badge 当装饰 — 状态请使用 StatusDot 或 Token', '不要自创属性。先阅读组件文档'] }] },
-    { section: 'Design Tokens', title: '设计令牌', content: [{ type: 'prose', text: '运行 npx astryx docs tokens 查看完整参考' }] },
+    { section: 'Design Tokens', title: '设计令牌', content: [{ type: 'prose', text: '运行 astryx docs tokens 查看完整参考' }] },
   ],
 };

package/docs/styling-libraries.doc.mjs

@@ -24,7 +24,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'For available token names and values, run `npx astryx docs tokens`. Focused references are also available with `npx astryx docs color`, `npx astryx docs spacing`, `npx astryx docs shape`, `npx astryx docs typography`, `npx astryx docs elevation`, and `npx astryx docs motion`.',
+          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`.',
         },
       ],
     },
@@ -452,10 +452,10 @@ function RevenueChart({data}: {data: Array<{x: string; y: number}>}) {
           type: 'list',
           style: 'ordered',
           items: [
-            'Import the reset/base CSS and a theme CSS file early enough for first paint. For production SSR, prefer built themes from `npx astryx theme build` or published `/built` theme imports plus `theme.css`.',
+            '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 `npx 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 `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 token resolver APIs only for non-CSS APIs that need resolved values.',
           ],
         },

package/docs/styling.doc.mjs

@@ -30,7 +30,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'All approaches resolve to the same design tokens, so theming and dark mode work regardless of which you choose. For external styling libraries, run `npx astryx docs styling-libraries`; it covers Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, Sass, and `useTheme()` for non-CSS processing.',
+          text: 'All approaches resolve to the same design tokens, so theming and dark mode work regardless of which you choose. For external styling libraries, run `astryx docs styling-libraries`; it covers Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, Sass, and `useTheme()` for non-CSS processing.',
         },
       ],
     },
@@ -118,7 +118,7 @@ const overrides = stylex.create({
         },
         {
           type: 'prose',
-          text: 'The bridge is pure CSS with zero JS. Theme changes (dark mode, custom themes) apply automatically because the utilities reference the same CSS custom properties that components use. This is the paved Tailwind path; for other styling libraries that follow the same aliasing pattern, run `npx astryx docs styling-libraries`.',
+          text: 'The bridge is pure CSS with zero JS. Theme changes (dark mode, custom themes) apply automatically because the utilities reference the same CSS custom properties that components use. This is the paved Tailwind path; for other styling libraries that follow the same aliasing pattern, run `astryx docs styling-libraries`.',
         },
       ],
     },
@@ -263,7 +263,7 @@ const overrides = stylex.create({
         },
         {
           type: 'prose',
-          text: 'For systematic theming, use defineTheme component overrides instead of raw CSS selectors. defineTheme keeps the higher-level `prop:value` API (`variant:primary`, `size:sm`) and handles selector generation for you. Run `npx astryx docs theme` for the full theming guide.',
+          text: 'For systematic theming, use defineTheme component overrides instead of raw CSS selectors. defineTheme keeps the higher-level `prop:value` API (`variant:primary`, `size:sm`) and handles selector generation for you. Run `astryx docs theme` for the full theming guide.',
         },
       ],
     },
@@ -334,7 +334,7 @@ const styles = stylex.create({
         },
         {
           type: 'prose',
-          text: 'See `npx astryx docs tokens` for the full token reference (all spacing, color, radius, shadow, and typography tokens with values). See `npx astryx docs theme` for how to override tokens via defineTheme.',
+          text: 'See `astryx docs tokens` for the full token reference (all spacing, color, radius, shadow, and typography tokens with values). See `astryx docs theme` for how to override tokens via defineTheme.',
         },
       ],
     },

package/docs/theme.doc.dense.mjs

@@ -10,9 +10,9 @@ export const docsDense = {
     { section: 'Theme Props', title: 'Props', content: [null] },
     { section: 'Creating a Custom Theme', title: 'Custom Theme', content: [{ type: 'prose', text: 'CLI wizard or manual defineTheme. only override tokens that differ.' }, null] },
     { section: 'defineTheme', title: 'defineTheme', content: [{ type: 'prose', text: 'scale configs (color, typography, radius, motion) + explicit token overrides + component overrides. color derives full palette from accent hex via HCT.' }, null, null] },
-    { section: 'Component Style Overrides', title: 'Component Overrides', content: [{ type: 'prose', text: 'components field uses semantic component keys + style keys (base, variant:value, stateName), not raw selectors. for external CSS, prefer data-* selectors from `astryx docs styling`. write standard CSS (borderRadius, padding) — pipeline expands to internal vars. public vars (--button-press-scale etc) set directly. private vars (--_*) cannot be set — use CSS properties. run `npx astryx component <Name>` for details.' }, null, null, null, null] },
+    { section: 'Component Style Overrides', title: 'Component Overrides', content: [{ type: 'prose', text: 'components field uses semantic component keys + style keys (base, variant:value, stateName), not raw selectors. for external CSS, prefer data-* selectors from `astryx docs styling`. write standard CSS (borderRadius, padding) — pipeline expands to internal vars. public vars (--button-press-scale etc) set directly. private vars (--_*) cannot be set — use CSS properties. run `astryx component <Name>` for details.' }, null, null, null, null] },
     { section: 'Custom Variants', title: 'Custom Variants', content: [{ type: 'prose', text: 'any unknown prop:value in components becomes a new variant. astryx theme build generates TS augmentations. works on any extensible prop axis (variant, status, etc).' }, null, null, null, null] },
-    { section: 'Building Themes for Production', title: 'Build for Production', content: [{ type: 'prose', text: 'npx astryx theme build compiles defineTheme to static CSS. outputs .css + .js (__built:true) + .d.ts.' }, null, null, null, null] },
+    { section: 'Building Themes for Production', title: 'Build for Production', content: [{ type: 'prose', text: 'astryx theme build compiles defineTheme to static CSS. outputs .css + .js (__built:true) + .d.ts.' }, null, null, null, null] },
     { section: 'Runtime vs Built Themes', title: 'Runtime vs Built', content: [{ type: 'prose', text: 'runtime: useInsertionEffect injects styles client-side. built: static CSS on first paint. USE /built + theme.css FOR SSR.' }, null, null, null] },
     { section: 'Light/Dark Mode', title: 'Light/Dark', content: [{ type: 'prose', text: 'light-dark() in token values via [light, dark] tuples. mode=system follows OS.' }, null, null] },
     { section: 'Nesting Themes', title: 'Nesting', content: [{ type: 'prose', text: 'wrap sections in separate <Theme> providers' }, null] },