@astryxdesign/cli 0.1.6 → 0.1.7-canary.04cd8f7

package/docs/layout.doc.dense.mjs

@@ -7,6 +7,7 @@ export const docsDense = {
     'frame-first app layout: shell choice, region budgets, cards vs rows',
   sections: [
     {
+      section: 'Frame First',
       title: 'Frame First',
       content: [
         {
@@ -26,6 +27,7 @@ export const docsDense = {
       ],
     },
     {
+      section: 'App Archetypes',
       title: 'App Archetypes',
       content: [
         {
@@ -40,6 +42,7 @@ export const docsDense = {
       ],
     },
     {
+      section: 'Cards vs Rows',
       title: 'Cards vs Rows',
       content: [
         {
@@ -67,6 +70,7 @@ export const docsDense = {
       ],
     },
     {
+      section: 'Panels and Inspectors',
       title: 'Panels and Inspectors',
       content: [
         {
@@ -77,6 +81,7 @@ export const docsDense = {
       ],
     },
     {
+      section: 'Responsive Contract',
       title: 'Responsive Contract',
       content: [
         {

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

@@ -5,10 +5,10 @@
 export const docsDense = {
   description: 'core design principles + rules for the design system',
   sections: [
-    { title: 'Philosophy', content: [{ type: 'list', items: ['components over primitives', 'semantic tokens over hardcoded values', 'theme-agnostic code', 'open internals'] }] },
-    { 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'] }] },
-    { title: 'Styling', content: [{ type: 'prose', text: 'xstyle prop for component overrides. StyleX or Tailwind for layout. See astryx docs styling.' }] },
-    { 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'] }] },
-    { title: 'Tokens', content: [{ type: 'prose', text: 'run npx astryx docs tokens for full reference' }] },
+    { section: 'Design Philosophy', title: 'Philosophy', content: [{ type: 'list', items: ['components over primitives', 'semantic tokens over hardcoded values', 'theme-agnostic code', 'open internals'] }] },
+    { 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 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

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

@@ -5,17 +5,17 @@
 export const docsDense = {
   description: 'Theme provider, custom themes, light/dark, component overrides',
   sections: [
-    { title: 'Quick Start', content: [null, null, null, null, { type: 'prose', text: 'default import = runtime injection. /built import = pre-compiled CSS (pair with theme.css).' }] },
-    { title: 'Themes', content: [null, null, { type: 'prose', text: 'published: neutral (start here), butter, chocolate, gothic (dark-only), matcha, stone, y2k. @astryxdesign/theme-{name} = source (runtime). @astryxdesign/theme-{name}/built = optimized (+ theme.css).' }] },
-    { title: 'Props', content: [null] },
-    { title: 'Custom Theme', content: [{ type: 'prose', text: 'CLI wizard or manual defineTheme. only override tokens that differ.' }, null] },
-    { 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] },
-    { 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] },
-    { 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] },
-    { 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] },
-    { 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] },
-    { title: 'Light/Dark', content: [{ type: 'prose', text: 'light-dark() in token values via [light, dark] tuples. mode=system follows OS.' }, null, null] },
-    { title: 'Nesting', content: [{ type: 'prose', text: 'wrap sections in separate <Theme> providers' }, null] },
-    { title: 'useTheme', content: [null, { type: 'prose', text: 'read-only. manage state at app level.' }] },
+    { section: 'Quick Start', title: 'Quick Start', content: [null, null, null, null, { type: 'prose', text: 'default import = runtime injection. /built import = pre-compiled CSS (pair with theme.css).' }] },
+    { section: 'Available Themes', title: 'Themes', content: [null, null, { type: 'prose', text: 'published: neutral (start here), butter, chocolate, gothic (dark-only), matcha, stone, y2k. @astryxdesign/theme-{name} = source (runtime). @astryxdesign/theme-{name}/built = optimized (+ theme.css).' }] },
+    { 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 `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: '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] },
+    { section: 'useTheme Hook', title: 'useTheme', content: [null, { type: 'prose', text: 'read-only. manage state at app level.' }] },
   ],
 };

package/docs/theme.doc.mjs

@@ -148,7 +148,7 @@ function App() {
           type: 'code',
           lang: 'bash',
           label: 'Scaffold with CLI',
-          code: 'npx astryx theme',
+          code: 'astryx theme',
         },
       ],
     },
@@ -287,7 +287,7 @@ const brandTheme = defineTheme({
         },
         {
           type: 'prose',
-          text: 'Run `npx astryx component <Name>` to see a component\'s theming targets, public CSS variables, and which standard CSS properties are supported.',
+          text: 'Run `astryx component <Name>` to see a component\'s theming targets, public CSS variables, and which standard CSS properties are supported.',
         },
         {
           type: 'list',
@@ -361,13 +361,13 @@ const brandTheme = defineTheme({
       content: [
         {
           type: 'prose',
-          text: '`npx astryx theme build` compiles a defineTheme file into production-ready artifacts. Recommended for SSR apps (Next.js, Remix) where styles must be present on first paint.',
+          text: '`astryx theme build` compiles a defineTheme file into production-ready artifacts. Recommended for SSR apps (Next.js, Remix) where styles must be present on first paint.',
         },
         {
           type: 'code',
           lang: 'bash',
           label: 'Build a theme',
-          code: 'npx astryx theme build ./src/themes/ocean.ts',
+          code: 'astryx theme build ./src/themes/ocean.ts',
         },
         {
           type: 'prose',
@@ -432,7 +432,7 @@ import './themes/ocean.css';
             [
               'Import (custom theme)',
               'defineTheme() directly',
-              "Built .js + .css from `npx astryx theme build`",
+              "Built .js + .css from `astryx theme build`",
             ],
             [
               'How it works',
@@ -462,7 +462,7 @@ import './themes/ocean.css';
           items: [
             'Use the /built subpath + theme.css for production SSR apps.',
             'Use runtime themes during development for fast iteration.',
-            'Run `npx astryx theme build` for custom themes to get the built artifacts.',
+            'Run `astryx theme build` for custom themes to get the built artifacts.',
           ],
         },
         {
@@ -610,7 +610,7 @@ function ChartConfig() {
         },
         {
           type: 'prose',
-          text: 'See `npx astryx docs styling-libraries` for styling-library interop and `npx astryx docs tokens` for the full token reference.',
+          text: 'See `astryx docs styling-libraries` for styling-library interop and `astryx docs tokens` for the full token reference.',
         },
       ],
     },

package/docs/theme.doc.zh.mjs

@@ -5,15 +5,15 @@
 export const docsZh = {
   description: 'Theme 提供者、自定义主题、亮/暗模式和组件样式覆盖。',
   sections: [
-    { title: '快速开始', content: [null, null, null, null, { type: 'prose', text: '默认导入使用运行时样式注入。/built 导入使用预编译 CSS（需配合 theme.css）。' }] },
-    { title: '可用主题', content: [null, null, { type: 'prose', text: '已发布主题：neutral（推荐起点）、butter、chocolate、gothic（仅暗色）、matcha、stone、y2k。@astryxdesign/theme-{name} = 源码版（运行时注入）。@astryxdesign/theme-{name}/built = 优化版（配合 theme.css）。' }] },
-    { title: 'Theme 属性', content: [null] },
-    { title: '创建自定义主题', content: [{ type: 'prose', text: '使用 CLI 向导（推荐）或手动 defineTheme。只覆盖与默认值不同的令牌。' }, null] },
-    { title: 'defineTheme', content: [{ type: 'prose', text: '支持比例配置（typography、radius、motion）+ 显式令牌覆盖 + 组件覆盖。' }, null, null] },
-    { title: '生产构建', content: [{ type: 'prose', text: 'npx astryx theme build 将 defineTheme 编译为静态 CSS。输出 .css + .js（__built:true）+ .d.ts。' }, null, null, null, null] },
-    { title: '运行时 vs 构建', content: [{ type: 'prose', text: '运行时：useInsertionEffect 在客户端注入样式。构建：静态 CSS 在首次渲染时就存在。SSR 应用请使用 /built + theme.css。' }, null, null, null] },
-    { title: '亮/暗模式', content: [{ type: 'prose', text: "令牌值使用 [light, dark] 元组实现自动模式切换。Theme 上 mode='system'（默认）跟随系统偏好。" }, null, null] },
-    { title: '嵌套主题', content: [{ type: 'prose', text: '将不同部分包裹在独立的 <Theme> 提供者中。' }, null] },
-    { title: 'useTheme 钩子', content: [null, { type: 'prose', text: '这是只读的。要更改主题/模式，在应用层管理状态并传递给 <Theme>。' }] },
+    { section: 'Quick Start', title: '快速开始', content: [null, null, null, null, { type: 'prose', text: '默认导入使用运行时样式注入。/built 导入使用预编译 CSS（需配合 theme.css）。' }] },
+    { section: 'Available Themes', title: '可用主题', content: [null, null, { type: 'prose', text: '已发布主题：neutral（推荐起点）、butter、chocolate、gothic（仅暗色）、matcha、stone、y2k。@astryxdesign/theme-{name} = 源码版（运行时注入）。@astryxdesign/theme-{name}/built = 优化版（配合 theme.css）。' }] },
+    { section: 'Theme Props', title: 'Theme 属性', content: [null] },
+    { section: 'Creating a Custom Theme', title: '创建自定义主题', content: [{ type: 'prose', text: '使用 CLI 向导（推荐）或手动 defineTheme。只覆盖与默认值不同的令牌。' }, null] },
+    { section: 'defineTheme', title: 'defineTheme', content: [{ type: 'prose', text: '支持比例配置（typography、radius、motion）+ 显式令牌覆盖 + 组件覆盖。' }, null, null] },
+    { section: 'Building Themes for Production', title: '生产构建', content: [{ type: 'prose', text: 'astryx theme build 将 defineTheme 编译为静态 CSS。输出 .css + .js（__built:true）+ .d.ts。' }, null, null, null, null] },
+    { section: 'Runtime vs Built Themes', title: '运行时 vs 构建', content: [{ type: 'prose', text: '运行时：useInsertionEffect 在客户端注入样式。构建：静态 CSS 在首次渲染时就存在。SSR 应用请使用 /built + theme.css。' }, null, null, null] },
+    { section: 'Light/Dark Mode', title: '亮/暗模式', content: [{ type: 'prose', text: "令牌值使用 [light, dark] 元组实现自动模式切换。Theme 上 mode='system'（默认）跟随系统偏好。" }, null, null] },
+    { section: 'Nesting Themes', title: '嵌套主题', content: [{ type: 'prose', text: '将不同部分包裹在独立的 <Theme> 提供者中。' }, null] },
+    { section: 'useTheme Hook', title: 'useTheme 钩子', content: [null, { type: 'prose', text: '这是只读的。要更改主题/模式，在应用层管理状态并传递给 <Theme>。' }] },
   ],
 };

package/docs/tokens.doc.dense.mjs

@@ -5,12 +5,11 @@
 export const docsDense = {
   description: 'spacing/color/radius/type/shadow token ref',
   sections: [
-    { title: 'Spacing', content: [{ type: 'prose', text: 'defined in tokens.stylex.ts. gap props use space0-space12.' }, null] },
-    { title: 'Size', content: [{ type: 'prose', text: 'control heights for buttons/inputs/selectors.' }, null] },
-    { title: 'Color', content: [{ type: 'prose', text: 'semantic colors, support light-dark() auto switching.' }, null, null, null] },
-    { title: 'Radius', content: [null] },
-    { title: 'Elevation', content: [null] },
-    { title: 'Typography', content: [null, null, null, null] },
-    { title: 'StyleX Usage', content: [null, null] },
+    { section: 'Color Tokens', title: 'Color', content: [{ type: 'prose', text: 'semantic colors, support light-dark() auto switching.' }, null, null, null] },
+    { section: 'Spacing Tokens', title: 'Spacing', content: [{ type: 'prose', text: 'defined in tokens.stylex.ts. gap props use space0-space12.' }, null] },
+    { section: 'Size Tokens', title: 'Size', content: [{ type: 'prose', text: 'control heights for buttons/inputs/selectors.' }, null] },
+    { section: 'Radius Tokens', title: 'Radius', content: [null] },
+    { section: 'Shadow Tokens', title: 'Elevation', content: [null] },
+    { section: 'Usage in StyleX', title: 'StyleX Usage', content: [null, null] },
   ],
 };

package/docs/tokens.doc.mjs

@@ -1068,7 +1068,7 @@ export const docs = {
         },
         {
           "type": "prose",
-          "text": "See `npx astryx docs styling` for how to apply tokens via xstyle, className, and compound component patterns. See `npx astryx docs theme` for overriding tokens with defineTheme."
+          "text": "See `astryx docs styling` for how to apply tokens via xstyle, className, and compound component patterns. See `astryx docs theme` for overriding tokens with defineTheme."
         }
       ]
     }

package/docs/tokens.doc.zh.mjs

@@ -5,12 +5,11 @@
 export const docsZh = {
   description: '间距、颜色、圆角、排版和阴影设计令牌参考。',
   sections: [
-    { title: '间距令牌', content: [{ type: 'prose', text: '所有设计令牌定义在 packages/core/src/theme/tokens.stylex.ts 中。组件的 gap 属性使用 space0-space12 映射到这些令牌。' }, null] },
-    { title: '尺寸令牌', content: [{ type: 'prose', text: '控制按钮、输入框和选择器的一致高度。' }, null] },
-    { title: '颜色令牌', content: [{ type: 'prose', text: '语义化颜色，支持 light-dark() 自动切换模式。' }, null, null, null] },
-    { title: '圆角令牌', content: [null] },
-    { title: '阴影令牌', content: [null] },
-    { title: '排版令牌', content: [null, null, null, null] },
-    { title: 'StyleX 用法', content: [null, null] },
+    { section: 'Color Tokens', title: '颜色令牌', content: [{ type: 'prose', text: '语义化颜色，支持 light-dark() 自动切换模式。' }, null, null, null] },
+    { section: 'Spacing Tokens', title: '间距令牌', content: [{ type: 'prose', text: '所有设计令牌定义在 packages/core/src/theme/tokens.stylex.ts 中。组件的 gap 属性使用 space0-space12 映射到这些令牌。' }, null] },
+    { section: 'Size Tokens', title: '尺寸令牌', content: [{ type: 'prose', text: '控制按钮、输入框和选择器的一致高度。' }, null] },
+    { section: 'Radius Tokens', title: '圆角令牌', content: [null] },
+    { section: 'Shadow Tokens', title: '阴影令牌', content: [null] },
+    { section: 'Usage in StyleX', title: 'StyleX 用法', content: [null, null] },
   ],
 };

package/docs/working-with-ai.doc.mjs

@@ -34,7 +34,7 @@ export const docs = {
           type: 'code',
           lang: 'text',
           label: 'Paste this into your AI',
-          code: 'Install @astryxdesign/cli and run `npx astryx init --features agents` to set up your Astryx context. Read the generated file.',
+          code: 'Install @astryxdesign/cli and run `npx @astryxdesign/cli init --features agents` to set up your Astryx context. Read the generated file.',
         },
         {
           type: 'prose',
@@ -48,9 +48,9 @@ export const docs = {
           type: 'code',
           lang: 'bash',
           label: 'Manual options',
-          code: `npx astryx init --features agents --agent claude    # CLAUDE.md
-npx astryx init --features agents --agent cursor    # .cursorrules
-npx astryx init --features agents --agent codex     # AGENTS.md (Copilot, Codex, etc.)`,
+          code: `npx @astryxdesign/cli init --features agents --agent claude    # CLAUDE.md
+npx @astryxdesign/cli init --features agents --agent cursor    # .cursorrules
+npx @astryxdesign/cli init --features agents --agent codex     # AGENTS.md (Copilot, Codex, etc.)`,
         },
       ],
     },
@@ -65,9 +65,9 @@ npx astryx init --features agents --agent codex     # AGENTS.md (Copilot, Codex,
           type: 'list',
           style: 'ordered',
           items: [
-            '`npx astryx template --list`: find a related page pattern to use as reference',
-            '`npx astryx template <name> --skeleton`: study the layout structure',
-            '`npx astryx component <Name>`: read props and examples for every component used',
+            '`astryx template --list`: find a related page pattern to use as reference',
+            '`astryx template <name> --skeleton`: study the layout structure',
+            '`astryx component <Name>`: read props and examples for every component used',
           ],
         },
         {
@@ -88,7 +88,7 @@ npx astryx init --features agents --agent codex     # AGENTS.md (Copilot, Codex,
           lang: 'bash',
           label: 'Install as a Cursor user rule',
           code: `mkdir -p ~/.cursor/rules
-npx astryx init --features agents --agent-docs-path ~/.cursor/rules/xds.mdc`,
+npx @astryxdesign/cli init --features agents --agent-docs-path ~/.cursor/rules/xds.mdc`,
         },
       ],
     },
@@ -109,12 +109,12 @@ npx astryx init --features agents --agent-docs-path ~/.cursor/rules/xds.mdc`,
 2. How do you make an Dialog non-dismissible?
 3. What prop does Selector use for its items?
 
-If you don't know all three, run \`npx astryx init --features agents\` to generate agent docs, then read the generated file.`,
+If you don't know all three, run \`npx @astryxdesign/cli init --features agents\` to generate agent docs, then read the generated file.`,
         },
       ],
     },
     {
-      title: 'The npx astryx Pattern',
+      title: 'The astryx Pattern',
       content: [
         {
           type: 'prose',
@@ -130,16 +130,16 @@ If you don't know all three, run \`npx astryx init --features agents\` to genera
         },
         {
           type: 'prose',
-          text: 'With this alias, agents use `npx astryx component --list` instead of guessing the binary path. The `--` separator is standard npm convention for passing flags to scripts.',
+          text: 'With this alias, agents use `astryx component --list` instead of guessing the binary path. The `--` separator is standard npm convention for passing flags to scripts.',
         },
         {
           type: 'code',
           lang: 'bash',
           label: 'Reliable CLI invocation',
-          code: `npx astryx component --list
-npx astryx component Dialog --dense
-npx astryx docs styling --dense
-npx astryx docs tokens --dense`,
+          code: `astryx component --list
+astryx component Dialog --dense
+astryx docs styling --dense
+astryx docs tokens --dense`,
         },
       ],
     },
@@ -154,9 +154,9 @@ npx astryx docs tokens --dense`,
           type: 'code',
           lang: 'bash',
           label: 'Dense output for pasting into AI conversations',
-          code: `npx astryx component Dialog --dense
-npx astryx docs styling --dense
-npx astryx docs tokens --dense`,
+          code: `astryx component Dialog --dense
+astryx docs styling --dense
+astryx docs tokens --dense`,
         },
       ],
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.6",
+  "version": "0.1.7-canary.04cd8f7",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -47,6 +47,10 @@
       "types": "./src/types/integration.d.ts",
       "import": "./src/integration.mjs"
     },
+    "./doc": {
+      "types": "./src/types/doc.d.ts",
+      "import": "./src/doc.mjs"
+    },
     "./template": {
       "types": "./src/types/template-api.d.ts",
       "import": "./src/template.mjs"
@@ -68,17 +72,16 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@clack/prompts": "^1.7.0",
     "commander": "^12.1.0",
     "jiti": "^2.7.0",
     "jscodeshift": "^17.3.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "*",
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-neutral": "*",
+    "@astryxdesign/charts": "0.1.7-canary.04cd8f7",
+    "@astryxdesign/core": "0.1.7-canary.04cd8f7",
+    "@astryxdesign/lab": "0.1.7-canary.04cd8f7",
+    "@astryxdesign/theme-neutral": "0.1.7-canary.04cd8f7",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -96,10 +99,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "*",
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-neutral": "*",
+    "@astryxdesign/charts": "0.1.7-canary.04cd8f7",
+    "@astryxdesign/core": "0.1.7-canary.04cd8f7",
+    "@astryxdesign/lab": "0.1.7-canary.04cd8f7",
+    "@astryxdesign/theme-neutral": "0.1.7-canary.04cd8f7",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {