@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

package/assets/docs/theme.doc.mjs

@@ -11,7 +11,8 @@ export const docs = {
 
   sections: [
     {
-      title: 'Quick Start',
+      id: 'quick-start',
+      title: 'Wrap your app in a theme',
       category: 'guide',
       content: [
         {
@@ -76,7 +77,7 @@ function App() {
             [
               'Neutral',
               "import {neutralTheme} from '@astryxdesign/theme-neutral'",
-              'Muted, minimal aesthetic with system fonts. A good starting point.',
+              'Muted, minimal aesthetic with Figtree typography. A good starting point.',
             ],
             [
               'Butter',
@@ -96,7 +97,7 @@ function App() {
             [
               'Matcha',
               "import {matchaTheme} from '@astryxdesign/theme-matcha'",
-              'Earthy green theme with Figtree typography.',
+              'Earthy greens; DM Sans + Playwrite US Trad type.',
             ],
             [
               'Stone',
@@ -121,22 +122,13 @@ function App() {
       category: 'guide',
       content: [
         {
-          type: 'table',
-          headers: ['Prop', 'Type', 'Default', 'Description'],
-          rows: [
-            ['theme', 'DefinedTheme', '-', 'Theme object (required)'],
-            [
-              'mode',
-              "'system' | 'light' | 'dark'",
-              "'system'",
-              'Color mode. system follows OS preference.',
-            ],
-            ['children', 'ReactNode', '-', 'App content'],
-          ],
+          type: 'prose',
+          text: "`<Theme>` takes `theme` (required), `mode` (`'system'` by default, or `'light'`/`'dark'`), and `children`. For every prop, run `astryx component Theme`.",
         },
       ],
     },
     {
+      id: 'integration-themes',
       title: 'Using a Theme from an Integration',
       category: 'guide',
       content: [
@@ -152,12 +144,13 @@ function App() {
         },
         {
           type: 'prose',
-          text: 'The copy is editable project source, not a reference back into node_modules. Every file named by the theme catalog comes with it, including nested token or palette modules. A second add refuses to overwrite those files unless you pass `--overwrite`.',
+          text: 'The copy is editable project source, not a reference back into node_modules. The complete theme directory comes with it, including its typed `.doc.mjs`, nested token and palette modules, and receipts. A second add refuses to overwrite those files unless you pass `--overwrite`.',
         },
       ],
     },
     {
-      title: 'Creating a Custom Theme',
+      id: 'creating-a-custom-theme',
+      title: 'Custom themes',
       category: 'guide',
       content: [
         {
@@ -365,11 +358,18 @@ const brandTheme = defineTheme({
         },
         {
           type: 'prose',
-          text: '`widthBreakpoints` are fixed named start points. Defaults are 640 / 768 / 1024 / 1280 / 1536 CSS pixels. `from` includes its point; `below` excludes it. Breakpoint configuration alone emits no CSS.',
+          text: '`widthBreakpoints` are fixed named start points. Defaults are 640 / 768 / 1024 / 1280 / 1536 CSS pixels. `from` includes its point; `below` excludes it. Breakpoint configuration alone emits no CSS. For how matching rules combine and what a rule may write, see Adaptation order and validation.',
         },
+      ],
+    },
+    {
+      id: 'adaptation-rules',
+      title: 'Adaptation order and validation',
+      category: 'guide',
+      content: [
         {
           type: 'prose',
-          text: '**Precedence follows rule order.** Root theme values apply first, then every matching rule in declaration order. A later rule may deliberately restore a root value. `onDark` and `onLight` media-surface overrides apply after adaptations and win on the same leaf.',
+          text: 'Precedence follows rule order. Root theme values apply first, then every matching rule in declaration order. A later rule may deliberately restore a root value. `onDark` and `onLight` media-surface overrides apply after adaptations and win on the same leaf.',
         },
         {
           type: 'prose',
@@ -391,7 +391,7 @@ const brandTheme = defineTheme({
       content: [
         {
           type: 'prose',
-          text: 'The `components` field in defineTheme uses semantic component keys and style keys, not raw CSS selectors. Use `base` for all instances, `variant:value` or `stateName` for specific props/states, and let the theme pipeline choose the underlying selector. For raw external CSS escape hatches, prefer the data-attribute selector surface documented in `astryx docs styling`.',
+          text: 'The `components` field in defineTheme uses semantic component keys and style keys, not raw CSS selectors. Use `base` for all instances, `variant:value` or `stateName` for specific props/states, and let the theme pipeline choose the underlying selector. For raw external CSS escape hatches, prefer the data-attribute selector surface documented in {@link generic:styling}.',
         },
         {
           type: 'code',
@@ -464,7 +464,7 @@ const brandTheme = defineTheme({
   banner: {
     // Any extensible prop axis works — not just variant
     'status:neutral': {
-      backgroundColor: 'var(--color-muted)',
+      backgroundColor: 'var(--color-background-muted)',
       color: 'var(--color-text-secondary)',
     },
   },
@@ -489,7 +489,8 @@ const brandTheme = defineTheme({
       ],
     },
     {
-      title: 'Building Themes for Production',
+      id: 'building-themes-for-production',
+      title: 'Build a theme',
       category: 'guide',
       content: [
         {
@@ -516,7 +517,7 @@ const brandTheme = defineTheme({
             ],
             [
               'ocean.js',
-              'ES module exporting the theme object with `__built: true` and pre-resolved token values. Also imports and re-exports an icon registry when the build detects its named import in the source theme (see the limitations below).',
+              'ES module exporting the theme object with `__built: true` and pre-resolved token values. Also imports and re-exports an icon registry when the build detects its named import in the source theme (see Built themes with an icon registry).',
             ],
             [
               'ocean.d.ts',
@@ -528,6 +529,36 @@ const brandTheme = defineTheme({
             ],
           ],
         },
+        {
+          type: 'prose',
+          text: 'The `__built: true` flag tells Theme to skip runtime `<style>` injection; the CSS file handles it.',
+        },
+        {
+          type: 'prose',
+          text: 'After upgrading Astryx across a selector-contract change, rerun `astryx theme build <theme-file>` for every custom prebuilt theme. Deploy the regenerated `.css`, `.js`, `.d.ts`, and optional `.variants.d.ts` together. The runtime intentionally trusts `__built: true` and will not repair stale CSS from an older build.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Using a custom built theme',
+          code: `import {oceanTheme} from './themes/ocean';
+import './themes/ocean.css';
+
+<Theme theme={oceanTheme}>
+  <App />
+</Theme>`,
+        },
+        {
+          type: 'prose',
+          text: "The build also warns when the theme names font families it does not load (webfonts like Fraunces) and prints the `<link>`/`@font-face` to add. The built CSS only sets font-family, so loading the font files stays the app's job. See {@link generic:typography} for the full recipe.",
+        },
+      ],
+    },
+    {
+      id: 'icon-registry',
+      title: 'Built themes with an icon registry',
+      category: 'guide',
+      content: [
         {
           type: 'prose',
           text: "The current `theme build` implementation emits an icon import when it detects a named import used by the theme’s `icons:` field, such as `import {oceanIcons} from './icons'` with `icons: oceanIcons`. It does not compile that registry module. Inline registries, including local constants, are currently omitted from the generated theme even though `defineTheme` accepts them at runtime. Move the registry to a separate module and use a named import for this build flow. For a registry that uses React and lucide-react, the following example compiles it alongside the generated theme:",
@@ -551,29 +582,6 @@ esbuild src/themes/icons.tsx --bundle --format=esm --outfile=dist/icons.mjs \\
           type: 'prose',
           text: 'Without `--icons-specifier`, the detected source import specifier is emitted unchanged. In the default no-`--out` flow, a bundler can resolve an extensionless `./icons` to the neighboring `icons.tsx` source. Node ESM does not perform that lookup and reports `ERR_MODULE_NOT_FOUND`. Moving the output with `--out` also changes where relative imports resolve; the generated module cannot find the original source merely because a bundler is used.',
         },
-        {
-          type: 'prose',
-          text: 'The `__built: true` flag tells Theme to skip runtime `<style>` injection; the CSS file handles it.',
-        },
-        {
-          type: 'prose',
-          text: 'After upgrading Astryx across a selector-contract change, rerun `astryx theme build <theme-file>` for every custom prebuilt theme. Deploy the regenerated `.css`, `.js`, `.d.ts`, and optional `.variants.d.ts` together. The runtime intentionally trusts `__built: true` and will not repair stale CSS from an older build.',
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Using a custom built theme',
-          code: `import {oceanTheme} from './themes/ocean';
-import './themes/ocean.css';
-
-<Theme theme={oceanTheme}>
-  <App />
-</Theme>`,
-        },
-        {
-          type: 'prose',
-          text: "The build also warns when the theme names font families it does not load (webfonts like Fraunces) and prints the `<link>`/`@font-face` to add. The built CSS only sets font-family, so loading the font files stays the app's job. See `astryx docs typography` for the full recipe.",
-        },
       ],
     },
     {
@@ -677,7 +685,8 @@ import './themes/ocean.css';
       ],
     },
     {
-      title: 'Light/Dark Mode',
+      id: 'light-dark-mode',
+      title: 'Dark mode',
       category: 'guide',
       content: [
         {
@@ -706,12 +715,13 @@ import './themes/ocean.css';
       ],
     },
     {
-      title: 'Nesting Themes',
+      id: 'nesting-themes',
+      title: 'Nested themes',
       category: 'guide',
       content: [
         {
           type: 'prose',
-          text: 'Wrap different sections in separate [`<Theme>`](/components/Theme) providers.',
+          text: 'Wrap different sections in separate `<Theme>` providers.',
         },
         {
           type: 'code',
@@ -811,7 +821,7 @@ function ChartConfig() {
         },
         {
           type: 'prose',
-          text: 'See `astryx docs styling-libraries` for styling-library interop and `astryx docs tokens` for the full token reference.',
+          text: 'See {@link generic:styling-libraries} for styling-library interop and {@link generic:tokens} for the full token reference.',
         },
       ],
     },

package/assets/docs/theme.doc.zh.mjs

@@ -3,17 +3,18 @@
 /** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */
 
 export const docsZh = {
-  description: 'Theme 提供者、自定义主题、亮/暗模式和组件样式覆盖。',
+  description: 'Theme 提供者、自定义主题、生产/SSR 主题构建、亮/暗模式和组件样式覆盖。',
   sections: [
-    { section: 'Quick Start', title: '快速开始', content: [null, null, null, null, { type: 'prose', text: '默认导入使用运行时样式注入。/built 导入使用预编译 CSS（需配合 theme.css）。' }] },
+    { section: 'Wrap your app in a theme', 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: '用 `theme list` + `theme add <slug>` 从内置主题或已安装集成提供的主题开始；重名时传 `--package`。也可以用 defineTheme 从零编写。只覆盖与默认值不同的令牌。' }, null, { type: 'prose', text: '`astryx theme template` 会写入 theme.template.ts：带注释的完整参考，涵盖每个 defineTheme 字段、令牌族和覆盖语法，并标明打印各自参考的 CLI 命令。' }] },
+    { section: 'Theme Props', title: 'Theme 属性', content: [{ type: 'prose', text: "`<Theme>` 接受 `theme`（必填）、`mode`（默认 `'system'`，也可以是 `'light'` 或 `'dark'`）和 `children`。运行 `astryx component Theme` 查看全部属性。" }] },
+    { section: 'Custom themes', title: '自定义主题', content: [{ type: 'prose', text: '用 `theme list` + `theme add <slug>` 从内置主题或已安装集成提供的主题开始；重名时传 `--package`。也可以用 defineTheme 从零编写。只覆盖与默认值不同的令牌。' }, null, { type: 'prose', text: '`astryx theme template` 会写入 theme.template.ts：带注释的完整参考，涵盖每个 defineTheme 字段、令牌族和覆盖语法，并标明打印各自参考的 CLI 命令。' }] },
     { section: 'defineTheme', title: 'defineTheme', content: [{ type: 'prose', text: '支持比例配置（color、typography、radius、motion）+ 显式令牌覆盖 + 组件覆盖。color 通过 HCT 从 accent 派生完整调色板；accent 接受单个十六进制值或 [light, dark] 元组（每个模式使用各自的种子色）。tokens 覆盖按令牌逐个生效；--color-on-accent 始终由 color.accent 计算得出，因此优先使用元组 accent 而不是覆盖 --color-accent。' }, 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, { type: 'prose', text: '当前 theme build 仅在检测到 icons: 字段使用的具名导入时，才在生成的模块中导入图标注册表；它不会编译注册表模块。defineTheme 在运行时接受的内联注册表（包括本地常量）目前会在构建产物中被省略。使用此构建流程时，请把注册表移到独立模块并使用具名导入。以下示例适用于使用 React 和 lucide-react 的注册表。' }, null, { type: 'prose', text: '上例中生成的主题从 dist 导入 ./icons.mjs。如果跳过第二条命令，theme build 仍可能成功，但加载或打包生成的模块都会因缺少 dist/icons.mjs 而失败。--icons-specifier 只更改生成的导入，不会创建或验证目标文件。路径应相对于生成的 JS 文件可解析。将 react 和图标库标记为 external，避免在注册表中重复打包这些依赖。' }, { type: 'prose', text: '不传 --icons-specifier 时，会原样保留检测到的源码导入路径。默认不传 --out 时，打包器可以把无扩展名的 ./icons 解析为旁边的 icons.tsx；Node ESM 不执行这种查找，会报 ERR_MODULE_NOT_FOUND。用 --out 移动输出位置也会改变相对导入的解析位置；使用打包器并不意味着它能自动找到原来的源码。' }, null, null, null] },
+    { section: 'Build a theme', title: '构建主题', content: [{ type: 'prose', text: 'astryx theme build 将 defineTheme 编译为静态 CSS。输出 .css + .js（__built:true）+ .d.ts。' }] },
+    { section: 'Built themes with an icon registry', title: '带图标注册表的构建主题', content: [{ type: 'prose', text: '当前 theme build 仅在检测到 icons: 字段使用的具名导入时，才在生成的模块中导入图标注册表；它不会编译注册表模块。defineTheme 在运行时接受的内联注册表（包括本地常量）目前会在构建产物中被省略。使用此构建流程时，请把注册表移到独立模块并使用具名导入。以下示例适用于使用 React 和 lucide-react 的注册表。' }, null, { type: 'prose', text: '上例中生成的主题从 dist 导入 ./icons.mjs。如果跳过第二条命令，theme build 仍可能成功，但加载或打包生成的模块都会因缺少 dist/icons.mjs 而失败。--icons-specifier 只更改生成的导入，不会创建或验证目标文件。路径应相对于生成的 JS 文件可解析。将 react 和图标库标记为 external，避免在注册表中重复打包这些依赖。' }, { type: 'prose', text: '不传 --icons-specifier 时，会原样保留检测到的源码导入路径。默认不传 --out 时，打包器可以把无扩展名的 ./icons 解析为旁边的 icons.tsx；Node ESM 不执行这种查找，会报 ERR_MODULE_NOT_FOUND。用 --out 移动输出位置也会改变相对导入的解析位置；使用打包器并不意味着它能自动找到原来的源码。' }] },
     { 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>。' }] },
+    { section: 'Dark mode', title: '亮/暗模式', content: [{ type: 'prose', text: "令牌值使用 [light, dark] 元组实现自动模式切换。Theme 上 mode='system'（默认）跟随系统偏好。" }, null, null] },
+    { section: 'Nested themes', title: '嵌套主题', content: [{ type: 'prose', text: '将不同部分包裹在独立的 <Theme> 提供者中。' }, null] },
+    { section: 'useTheme Hook', title: 'useTheme 钩子', content: [null, null, { type: 'prose', text: '普通样式优先使用 CSS 变量、StyleX 令牌导入、xstyle 或 className。useTheme() 是只读的：要更改主题或模式，在应用层管理状态并传递给 <Theme>。' }] },
   ],
 };

package/assets/docs/tokens.doc.dense.mjs

@@ -3,10 +3,10 @@
 /** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */
 
 export const docsDense = {
-  description: 'spacing/color/radius/type/shadow token ref',
+  description: 'color/data-viz/syntax/spacing/size/radius/shadow/motion/type token ref',
   sections: [
     { 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: 'Spacing Tokens', title: 'Spacing', content: [{ type: 'prose', text: 'padding/gap/margin scale. gap props take steps 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.' }, 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] },