@astryxdesign/cli 0.6.4-canary.06c8fa3 → 0.6.4-canary.0e1fbdb

package/assets/docs/styling-libraries.doc.mjs

@@ -185,6 +185,7 @@ const styles = stylex.create({
       ],
     },
     {
+      id: 'semantic-token-systems',
       title: 'Panda, Chakra, and Other Semantic Token Systems',
       category: 'guide',
       content: [
@@ -246,7 +247,7 @@ tokens: {
       content: [
         {
           type: 'prose',
-          text: 'MUI expects palette slots such as primary, background, text, and divider. Map those slots to system variables for ordinary component styling. Use raw values only when MUI or your code needs to parse colors for contrast, alpha, lighten, or darken calculations.',
+          text: '`MUI` expects palette slots such as primary, background, text, and divider. Map those slots to system variables for ordinary component styling. Use raw values only when MUI or your code needs to parse colors for contrast, alpha, lighten, or darken calculations.',
         },
         {
           type: 'code',
@@ -293,12 +294,13 @@ tokens: {
       ],
     },
     {
+      id: 'css-in-js',
       title: 'Emotion, styled-components, Theme UI, and Styled System',
       category: 'guide',
       content: [
         {
           type: 'prose',
-          text: 'Runtime CSS-in-JS libraries usually accept arbitrary theme objects. Keep those objects semantic, but store system CSS variable references as the values. This keeps generated classes stable while the system updates values through the CSS cascade.',
+          text: 'Runtime CSS-in-JS libraries such as `Emotion` and `styled-components` usually accept arbitrary theme objects. Keep those objects semantic, but store system CSS variable references as the values. This keeps generated classes stable while the system updates values through the CSS cascade.',
         },
         {
           type: 'code',
@@ -327,6 +329,7 @@ tokens: {
       ],
     },
     {
+      id: 'unocss',
       title: 'UnoCSS and Custom Utility Systems',
       category: 'guide',
       content: [
@@ -422,6 +425,7 @@ function RevenueChart({data}: {data: Array<{x: string; y: number}>}) {
       ],
     },
     {
+      id: 'non-css-best-practices',
       title: 'Non-CSS Processing Best Practices',
       category: 'guide',
       content: [

package/assets/docs/styling.doc.mjs

@@ -8,6 +8,7 @@ export const docs = {
   category: 'guide',
   description:
     'How to customize component appearance: xstyle prop, Tailwind, StyleX, className, rest props, compound component patterns, theming hooks, and styling-library interop.',
+  keywords: ['override', 'customize', 'css'],
 
   sections: [
     {
@@ -16,7 +17,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'There are several ways to style things. Here is when to use each:',
+          text: 'Style components with `xstyle` (StyleX), `className` (Tailwind or your own CSS), or a styling library aliased to Astryx tokens. All of them resolve to the same tokens.',
         },
         {
           type: 'table',
@@ -30,7 +31,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 {@link generic:styling-libraries}; it covers Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, Sass, and `useTheme()` for non-CSS processing.',
+          text: 'Theming and dark mode work whichever you choose. For external styling libraries, run {@link generic:styling-libraries}; it covers Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, Sass, and `useTheme()` for non-CSS processing.',
         },
       ],
     },
@@ -40,7 +41,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Every component accepts an xstyle prop for style customization. It accepts StyleX styles created via stylex.create(), not inline objects or class name strings. StyleX styles are compiled at build time for optimal deduplication and dead-code elimination.',
+          text: 'Every component accepts an `xstyle` prop for style customization. It accepts StyleX styles created via `stylex.create()`, not inline objects or class name strings. StyleX styles are compiled at build time for optimal deduplication and dead-code elimination.',
         },
         {
           type: 'code',
@@ -94,24 +95,14 @@ const overrides = stylex.create({
           text: 'The package ships a Tailwind v4 theme bridge that maps all design tokens to Tailwind utility classes. Import it once and use Tailwind classes backed by design tokens: colors, spacing, radius, shadows, and typography all resolve to the active theme.',
         },
         {
-          type: 'code',
-          lang: 'css',
-          label: 'globals.css: import the bridge',
-          code: `@layer reset, theme, base, astryx-base, astryx-theme, components, utilities;
-
-@import "tailwindcss/theme.css" layer(theme);
-@import "tailwindcss/preflight.css" layer(base);
-@import "@astryxdesign/core/reset.css";
-@import "@astryxdesign/core/astryx.css";
-@import "@astryxdesign/theme-neutral/theme.css";
-@import "@astryxdesign/core/tailwind-theme.css";
-@import "tailwindcss/utilities.css" layer(utilities);`,
+          type: 'prose',
+          text: 'For the imports and the cascade-layer order to put in your global CSS, see the Tailwind section of {@link generic:styling-libraries}.',
         },
         {
           type: 'code',
           lang: 'tsx',
           label: 'Tailwind utilities alongside components',
-          code: `<div className="text-primary bg-surface rounded-container p-4 flex gap-3">
+          code: `<div className="text-primary bg-surface rounded-lg p-4 flex gap-3">
   <Button label="Save" variant="primary" />
   <Button label="Cancel" variant="secondary" />
 </div>`,
@@ -128,7 +119,7 @@ const overrides = stylex.create({
       content: [
         {
           type: 'prose',
-          text: 'Every component also accepts standard className and style props. className is appended after the component\'s own classes. style is merged after StyleX inline styles, so consumer values win on conflict.',
+          text: 'Every component also accepts standard `className` and `style` props. `className` is appended after the component\'s own classes. `style` is merged after StyleX inline styles, so consumer values win on conflict.',
         },
         {
           type: 'code',
@@ -226,7 +217,10 @@ const overrides = stylex.create({
       ],
     },
     {
-      title: 'Preferred Selector Surface: Data Attributes',
+      // The key it had in 0.6, so `astryx docs styling
+      // preferred-selector-surface-data-attributes` keeps working.
+      id: 'preferred-selector-surface-data-attributes',
+      title: 'Data attribute selectors',
   category: 'guide',
       content: [
         {
@@ -268,12 +262,13 @@ const overrides = stylex.create({
       ],
     },
     {
+      id: 'deprecated-classes',
       title: 'Deprecated: Bare Prop and State Classes',
   category: 'guide',
       content: [
         {
           type: 'prose',
-          text: 'Astryx continues to emit deprecated bare prop/state classes such as `.primary`, `.sm`, `.level-2`, and `.checked` through the 0.7.0 removal window. Prefer the explicit reflected data attributes for new CSS, and run `astryx upgrade --apply` before 0.7.0 to parse `.css` files and rewrite selectors qualified by a known Astryx target when the 0.5.4 target/value pair has one or more known meanings. Declarations, comments, JavaScript/TypeScript strings, and unqualified classes are never rewritten. Stable base target classes (`.astryx-button`, `.astryx-card`, etc.) remain unchanged.',
+          text: 'Astryx still emits the deprecated bare classes (`.primary`, `.sm`, `.level-2`, `.checked`) and will remove them in a later release. Use data attributes for new CSS; `astryx upgrade --from <old version> --apply` rewrites qualified selectors in `.css` files.',
         },
         {
           type: 'code',
@@ -290,7 +285,7 @@ const overrides = stylex.create({
         },
         {
           type: 'prose',
-          text: 'Each known old value becomes a specificity-preserving `:is(...)` union containing the original class arm plus every v0.5.4 data-attribute arm. Both arms match Astryx output during the deprecation window; the data-attribute arm continues matching after the bare compatibility classes are eligible for removal in 0.7.0. The class arm also preserves consumer-supplied `className` matches. Narrow the union later only when class provenance or prop-axis intent is known. Custom/unknown qualified classes and unqualified classes stay unchanged. Search for unqualified old values such as `.primary` or `.sm` and migrate only confirmed Astryx uses manually. Migrate selectors embedded in JavaScript or TypeScript manually with the same rules.',
+          text: 'The upgrade rewrites a selector only when an `.astryx-*` component class qualifies it, turning the old class into an `:is(...)` union of that class and the data attributes it stood for. The union keeps the selector\'s specificity and your own `className` matches, and keeps matching once the bare classes are gone; the `.astryx-*` classes themselves stay. It leaves unqualified classes (a bare `.primary`), unknown classes, and selectors in JavaScript or TypeScript alone: migrate those by hand, and only where they target Astryx.',
         },
       ],
     },
@@ -343,6 +338,7 @@ const styles = stylex.create({
       ],
     },
     {
+      id: 'stylex-setup',
       title: 'StyleX Build Setup (required for swizzled components)',
   category: 'guide',
       content: [
@@ -362,11 +358,11 @@ const styles = stylex.create({
         },
         {
           type: 'prose',
-          text: 'Next.js (App Router) is the sharp edge. StyleX\'s canonical compiler is a Babel plugin, but introducing a Babel config in Next.js disables the SWC compiler, which in turn breaks SWC-dependent features like `next/font`. So the "obvious" Babel setup is actively incompatible with a standard Next 15 App Router app.',
+          text: 'Next.js (App Router) is the sharp edge. StyleX\'s canonical compiler is a Babel plugin, but introducing a Babel config in Next.js disables the SWC compiler, and with it SWC-dependent features like `next/font`.',
         },
         {
           type: 'prose',
-          text: 'The working path on Next.js is an SWC-based StyleX transform (e.g. the community `@stylexswc/nextjs-plugin`) wired into `next.config`, which keeps SWC and `next/font` intact. See the example app `apps/example-nextjs-stylex` in the repo for a complete, working Next.js + StyleX + SWC configuration.',
+          text: 'The repo\'s `apps/example-nextjs-stylex` takes the Babel path (`next/babel`, `@stylexjs/babel-plugin`, `@stylexjs/postcss-plugin`). Babel turns off SWC, so that app does not use `next/font`. To keep `next/font`, use an SWC transform such as `@stylexswc/nextjs-plugin`.',
         },
         {
           type: 'code',
@@ -389,7 +385,7 @@ export default stylexPlugin({
           style: 'unordered',
           items: [
             'Symptom of a missing compiler: swizzled component renders with no styles, but no build or runtime error.',
-            'Do NOT add @stylexjs/babel-plugin to a Next.js App Router app; it disables SWC and breaks next/font.',
+            'A Babel config turns off SWC in Next.js; skip it if you need `next/font`.',
             'Pure theming (defineTheme + astryx theme build) needs NO StyleX compiler; only swizzled/authored StyleX source does.',
           ],
         },

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

@@ -3,11 +3,12 @@
 /** @type {import('@astryxdesign/cli/authoring').ReferenceTranslationDoc} */
 
 export const docsDense = {
-  description: 'Theme provider, custom themes, light/dark, component overrides',
+  description:
+    'Theme provider, custom themes, theme build (prod/SSR), light/dark, component overrides',
   sections: [
     {
-      section: 'Quick Start',
-      title: 'Quick Start',
+      section: 'Wrap your app in a theme',
+      title: 'Wrap your app',
       content: [
         null,
         null,
@@ -31,9 +32,18 @@ export const docsDense = {
         },
       ],
     },
-    {section: 'Theme Props', title: 'Props', content: [null]},
     {
-      section: 'Creating a Custom Theme',
+      section: 'Theme Props',
+      title: 'Props',
+      content: [
+        {
+          type: 'prose',
+          text: "<Theme> props: theme (required), mode ('system' default, or 'light'/'dark'), children. every prop: astryx component Theme.",
+        },
+      ],
+    },
+    {
+      section: 'Custom themes',
       title: 'Custom Theme',
       content: [
         {
@@ -65,10 +75,36 @@ export const docsDense = {
       content: [
         {
           type: 'prose',
-          text: 'adaptations = ordered {when,value} rules over width/pointer/contrast/motion. widthBreakpoints fixed sm|md|lg|xl|2xl defaults 640|768|1024|1280|1536; map alone emits no CSS. width.from inclusive, width.below exclusive; condition fields AND. root first, then matching rules in authored order (later writes win), then onDark/onLight. rules can write typography/color/radius/motion/tokens/localTokens/components; local names belong on root. Component writes validate exactly like root components (same targets/axes/domains); only difference: a rule cannot be the sole enroller of a custom value (type augmentation is unconditional) — declare it on root, then restyle. Built-ins need no root declaration. Co-matching token/localToken writes are validated together; any reachable var() cycle fails. extends inherits breakpoints + ordered rules, appends child rules, re-resolves against child axes. CSS-only; use built themes for SSR first paint.',
+          text: 'adaptations = ordered {when,value} rules over width/pointer/contrast/motion. condition fields AND. rules can write typography/color/radius/motion/tokens/localTokens/components.',
         },
         null,
         null,
+        {
+          type: 'prose',
+          text: 'widthBreakpoints fixed sm|md|lg|xl|2xl defaults 640|768|1024|1280|1536; map alone emits no CSS. width.from inclusive, width.below exclusive. order + validation: see Adaptation Rules.',
+        },
+      ],
+    },
+    {
+      section: 'Adaptation order and validation',
+      title: 'Adaptation Rules',
+      content: [
+        {
+          type: 'prose',
+          text: 'root first, then matching rules in authored order (later writes win), then onDark/onLight on the same leaf.',
+        },
+        {
+          type: 'prose',
+          text: 'extends inherits breakpoints + ordered rules, appends child rules, re-resolves against child axes. an empty child rule is a no-op, not a removal.',
+        },
+        {
+          type: 'prose',
+          text: 'local names belong on root. Component writes validate exactly like root components (same targets/axes/domains); only difference: a rule cannot be the sole enroller of a custom value (type augmentation is unconditional) — declare it on root, then restyle. Built-ins need no root declaration. Co-matching token/localToken writes are validated together; any reachable var() cycle fails.',
+        },
+        {
+          type: 'prose',
+          text: 'CSS-only (media queries, no resize listener); use built themes for SSR first paint.',
+        },
       ],
     },
     {
@@ -77,7 +113,7 @@ export const docsDense = {
       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-focus-offset etc) set directly. private vars (--_*) cannot be set — use CSS properties. run `astryx theme targets [Name]` to enumerate every themeable key (--json for lint), `astryx component <Name>` for one component.',
+          text: 'components field uses semantic component keys + style keys (base, variant:value, stateName), not raw selectors. for external CSS, prefer data-* selectors ({@link generic:styling}). write standard CSS (borderRadius, padding) — pipeline expands to internal vars. public vars (--button-focus-offset etc) set directly. private vars (--_*) cannot be set — use CSS properties. run `astryx theme targets [Name]` to enumerate every themeable key (--json for lint), `astryx component <Name>` for one component.',
         },
         null,
         null,
@@ -100,16 +136,19 @@ export const docsDense = {
       ],
     },
     {
-      section: 'Building Themes for Production',
+      section: 'Build a theme',
       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,
+      ],
+    },
+    {
+      section: 'Built themes with an icon registry',
+      title: 'Icon Registry',
+      content: [
         {
           type: 'prose',
           text: 'current build detects named imports used by icons:. registry module is not compiled. inline/local registries accepted by defineTheme are omitted from built output; move them to a separate module and import by name.',
@@ -123,9 +162,6 @@ export const docsDense = {
           type: 'prose',
           text: 'without --icons-specifier, source import is copied unchanged. default flow without --out: bundlers can resolve ./icons to neighboring icons.tsx; Node ESM fails with ERR_MODULE_NOT_FOUND. moving output changes relative import resolution.',
         },
-        null,
-        null,
-        null,
       ],
     },
     {
@@ -154,8 +190,8 @@ export const docsDense = {
       ],
     },
     {
-      section: 'Light/Dark Mode',
-      title: 'Light/Dark',
+      section: 'Dark mode',
+      title: 'Dark mode',
       content: [
         {
           type: 'prose',
@@ -166,7 +202,7 @@ export const docsDense = {
       ],
     },
     {
-      section: 'Nesting Themes',
+      section: 'Nested themes',
       title: 'Nesting',
       content: [
         {type: 'prose', text: 'wrap sections in separate <Theme> providers'},
@@ -178,7 +214,11 @@ export const docsDense = {
       title: 'useTheme',
       content: [
         null,
-        {type: 'prose', text: 'read-only. manage state at app level.'},
+        null,
+        {
+          type: 'prose',
+          text: 'read-only. ordinary styling: CSS vars, StyleX tokens, xstyle, className. to change theme/mode, manage state at app level and pass it to <Theme>.',
+        },
       ],
     },
   ],

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: [
         {
@@ -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: [
@@ -157,7 +149,8 @@ function App() {
       ],
     },
     {
-      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',
@@ -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,29 +529,6 @@ const brandTheme = defineTheme({
             ],
           ],
         },
-        {
-          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:",
-        },
-        {
-          type: 'code',
-          lang: 'bash',
-          label: 'Compiling the icon registry sidecar',
-          code: `# Emit the built theme; point its icon import at the file the next step produces
-astryx theme build ./src/themes/ocean.ts -o dist/theme.css --icons-specifier ./icons.mjs
-
-# Compile the icon registry to a real ES module next to the generated JS
-esbuild src/themes/icons.tsx --bundle --format=esm --outfile=dist/icons.mjs \\
-  --external:react --external:lucide-react --jsx=automatic`,
-        },
-        {
-          type: 'prose',
-          text: 'In the example above, the generated theme imports `./icons.mjs` from `dist`. If the second command is skipped, `theme build` can still succeed, but loading or bundling the generated module fails because `dist/icons.mjs` is missing. `--icons-specifier` changes the emitted import; it does not create or verify the target file. Match the specifier to a module that resolves from the generated JS file. Keep `react` and the icon library external so the registry does not bundle its own copies of those dependencies.',
-        },
-        {
-          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.',
@@ -576,6 +554,36 @@ import './themes/ocean.css';
         },
       ],
     },
+    {
+      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:",
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          label: 'Compiling the icon registry sidecar',
+          code: `# Emit the built theme; point its icon import at the file the next step produces
+astryx theme build ./src/themes/ocean.ts -o dist/theme.css --icons-specifier ./icons.mjs
+
+# Compile the icon registry to a real ES module next to the generated JS
+esbuild src/themes/icons.tsx --bundle --format=esm --outfile=dist/icons.mjs \\
+  --external:react --external:lucide-react --jsx=automatic`,
+        },
+        {
+          type: 'prose',
+          text: 'In the example above, the generated theme imports `./icons.mjs` from `dist`. If the second command is skipped, `theme build` can still succeed, but loading or bundling the generated module fails because `dist/icons.mjs` is missing. `--icons-specifier` changes the emitted import; it does not create or verify the target file. Match the specifier to a module that resolves from the generated JS file. Keep `react` and the icon library external so the registry does not bundle its own copies of those dependencies.',
+        },
+        {
+          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.',
+        },
+      ],
+    },
     {
       title: 'Building a Theme Family',
       category: 'guide',
@@ -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',

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] },