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

package/assets/docs/spacing.doc.mjs

@@ -8,6 +8,7 @@ export const docs = {
   category: 'foundations',
   description:
     'Spacing scale tokens for padding, gap, and margin: the rhythmic foundation of design system layouts.',
+  keywords: ['padding', 'margin', 'gap'],
   tokenCategory: 'spacing',
 
   sections: [
@@ -25,6 +26,10 @@ export const docs = {
       title: 'Scale',
   category: 'foundations',
       content: [
+        {
+          type: 'prose',
+          text: 'Fifteen spacing tokens, from 0px to 48px.',
+        },
         {
           type: 'token-ref',
           topic: 'tokens',
@@ -38,7 +43,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Most components accept a `gap` prop using step values (0 through 12). For custom layouts, use the spacing tokens directly in StyleX.',
+          text: 'Stack, HStack, VStack, Grid, Toolbar, OverflowList, and ChatMessageList take a `gap` step: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, or 10 (×4px). Carousel takes the steps from 0 to 4. For custom layouts, use the spacing tokens in StyleX.',
         },
         {
           type: 'code',
@@ -48,7 +53,7 @@ export const docs = {
 <Stack gap={4}>{/* 16px gap */}</Stack>
 
 // Via StyleX tokens (custom layouts)
-import {spacingVars} from '@astryxdesign/core';
+import {spacingVars} from '@astryxdesign/core/theme/tokens.stylex';
 
 const styles = stylex.create({
   custom: {

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

@@ -24,7 +24,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          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`.',
+          text: 'For available token names and values, run {@link generic:tokens}. Focused references are also available with {@link generic:color}, {@link generic:spacing}, {@link generic:shape}, {@link generic:typography}, {@link generic:elevation}, and {@link generic:motion}.',
         },
       ],
     },
@@ -150,7 +150,7 @@ const styles = stylex.create({
       content: [
         {
           type: 'prose',
-          text: 'The Tailwind v4 bridge at `@astryxdesign/core/tailwind-theme.css` maps Tailwind theme variables to system CSS variables with `@theme inline`, so utility classes like `text-primary`, `bg-surface`, `border-border`, `rounded-lg`, and `shadow-md` stay in sync with the active theme.',
+          text: 'The Tailwind v4 bridge at `@astryxdesign/core/tailwind-theme.css` maps Tailwind theme variables to system CSS variables with `@theme reference inline`, so utility classes like `text-primary`, `bg-surface`, `border-border`, `rounded-lg`, and `shadow-md` stay in sync with the active theme without emitting competing runtime declarations.',
         },
         {
           type: 'code',
@@ -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: [
@@ -351,7 +354,7 @@ tokens: {
     },
   },
   shortcuts: {
-    'xds-card': 'bg-surface text-primary border border-border rounded-lg p-4',
+    'astryx-card': 'bg-surface text-primary border border-border rounded-lg p-4',
   },
 });`,
         },
@@ -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: [
@@ -455,7 +459,7 @@ function RevenueChart({data}: {data: Array<{x: string; y: number}>}) {
             '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 `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 {@link generic: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/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 `astryx docs 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,31 +95,21 @@ 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>`,
         },
         {
           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 `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 {@link generic:styling-libraries}.',
         },
       ],
     },
@@ -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: [
         {
@@ -263,17 +257,18 @@ 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 `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 {@link generic:theme} for the full theming guide.',
         },
       ],
     },
     {
+      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.',
         },
       ],
     },
@@ -338,11 +333,12 @@ const styles = stylex.create({
         },
         {
           type: 'prose',
-          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.',
+          text: 'See {@link generic:tokens} for the full token reference (all spacing, color, radius, shadow, and typography tokens with values). See {@link generic:theme} for how to override tokens via defineTheme.',
         },
       ],
     },
     {
+      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>.',
+        },
       ],
     },
   ],