@astryxdesign/cli 0.1.6-canary.fec872b → 0.1.6-canary.ff5dfca

package/docs/internationalization.doc.mjs

@@ -16,7 +16,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Internationalization ships with `@astryxdesign/core`. There is nothing to install. Wrap your app in `<InternationalizationProvider>` and set a `locale` — astryx components pick up localized strings automatically.',
+          text: 'Internationalization ships with `@astryxdesign/core`. There is nothing to install. Wrap your app in `<InternationalizationProvider>` and set a `locale`, and astryx components pick up localized strings automatically.',
         },
         {
           type: 'code',
@@ -45,11 +45,11 @@ function SaveButton() {
         },
         {
           type: 'prose',
-          text: 'The hook is available to consumer components too, but using it is entirely optional — many teams keep their app strings on their existing i18n library (react-intl, i18next, next-intl, LinguiJS) and only use `useTranslator` when reading astryx keys. If you do route your own strings through it, we recommend namespacing them (`@myapp.*` or your npm scope) to keep them separated from `@astryx.*`, but this is a convention, not a requirement — the resolver treats every key as an opaque string.',
+          text: 'The hook is available to consumer components too, but using it is entirely optional: many teams keep their app strings on their existing i18n library (react-intl, i18next, next-intl, LinguiJS) and only use `useTranslator` when reading astryx keys. If you do route your own strings through it, we recommend namespacing them (`@myapp.*` or your npm scope) to keep them separated from `@astryx.*`, but this is a convention, not a requirement; the resolver treats every key as an opaque string.',
         },
         {
           type: 'prose',
-          text: "Astryx ships translations only for English today. First-party translations for other locales are on the roadmap and coming soon — track https://github.com/facebook/astryx/issues/3641. In the meantime, if you want astryx UI translated into another locale, you can ship your own catalog through the `messages` prop (covered in the next section). If you're using `useTranslator` for your own strings, you'll want to ship your own catalog either way — astryx only carries the fallback for `@astryx.*` keys, not the ones you author.",
+          text: "Astryx ships translations only for English today. First-party translations for other locales are on the roadmap; track https://github.com/facebook/astryx/issues/3641. In the meantime, if you want astryx UI translated into another locale, you can ship your own catalog through the `messages` prop (covered in the next section). If you're using `useTranslator` for your own strings, you'll want to ship your own catalog either way, since astryx only carries the fallback for `@astryx.*` keys, not the ones you author.",
         },
       ],
     },
@@ -59,7 +59,7 @@ function SaveButton() {
       content: [
         {
           type: 'prose',
-          text: 'Astryx bundles only the English catalog today. To render in any other locale, provide a translation catalog through the `messages` prop and set `locale` accordingly. This matches how MUI, Ant Design, and AG Grid work — the consumer app supplies the catalogs it actually needs so unused translations stay out of the bundle.',
+          text: 'Astryx bundles only the English catalog today. To render in any other locale, provide a translation catalog through the `messages` prop and set `locale` accordingly. This matches how MUI, Ant Design, and AG Grid work: the consumer app supplies the catalogs it actually needs so unused translations stay out of the bundle.',
         },
         {
           type: 'code',
@@ -74,11 +74,11 @@ import fr from './locales/astryx/fr.json';
         },
         {
           type: 'prose',
-          text: "See `@astryxdesign/core/locales/en.json` for the full inventory of keys to translate. Copy it as the starting point — every key you translate replaces the English default; anything you omit falls back through the locale chain to English (e.g. `pt-BR` walks to `pt` then to shipped `en`), so a partial translation renders as a mix rather than empty text or raw key names.",
+          text: "See `@astryxdesign/core/locales/en.json` for the full inventory of keys to translate. Copy it as the starting point: every key you translate replaces the English default; anything you omit falls back through the locale chain to English (e.g. `pt-BR` walks to `pt` then to shipped `en`), so a partial translation renders as a mix rather than empty text or raw key names.",
         },
         {
           type: 'prose',
-          text: 'A community-maintained set of astryx translations is on the roadmap but not shipped yet. For now, consumer apps that ship in multiple languages own their astryx catalogs alongside their app catalogs. Contributions to a first-party set are welcome — track discussion at https://github.com/facebook/astryx/issues/3641.',
+          text: 'A community-maintained set of astryx translations is on the roadmap but not shipped yet. For now, consumer apps that ship in multiple languages own their astryx catalogs alongside their app catalogs. Contributions to a first-party set are welcome; track discussion at https://github.com/facebook/astryx/issues/3641.',
         },
       ],
     },
@@ -113,7 +113,7 @@ import fr from './locales/astryx/fr.json';
       content: [
         {
           type: 'prose',
-          text: "Astryx components render astryx strings through astryx's provider. Consumer components render consumer strings through whatever i18n library you already use — react-intl, i18next, next-intl, LinguiJS, and so on. The two systems coexist and read from the same source of truth for the active locale.",
+          text: "Astryx components render astryx strings through astryx's provider. Consumer components render consumer strings through whatever i18n library you already use: react-intl, i18next, next-intl, LinguiJS, and so on. The two systems coexist and read from the same source of truth for the active locale.",
         },
         {
           type: 'code',
@@ -165,11 +165,11 @@ export default function App() {
         },
         {
           type: 'prose',
-          text: 'Keep the two providers in sync on locale, and each library owns its own catalog. Astryx never sees your app strings, and your i18n library never sees astryx internals. Runtime locale swap works the same way — re-render both providers with a new `locale` prop and the whole tree updates live.',
+          text: 'Keep the two providers in sync on locale, and each library owns its own catalog. Astryx never sees your app strings, and your i18n library never sees astryx internals. Runtime locale swap works the same way: re-render both providers with a new `locale` prop and the whole tree updates live.',
         },
         {
           type: 'prose',
-          text: "Single-catalog usage — where an external i18n runtime like react-intl or i18next resolves both your app strings AND astryx's strings through one provider — is on the roadmap via a `Translator` adapter. Track https://github.com/facebook/astryx/issues/4029. For now, run the two providers side by side as shown above.",
+          text: "Single-catalog usage (where an external i18n runtime like react-intl or i18next resolves both your app strings AND astryx's strings through one provider) is on the roadmap via a `Translator` adapter. Track https://github.com/facebook/astryx/issues/4029. For now, run the two providers side by side as shown above.",
         },
       ],
     },
@@ -225,7 +225,7 @@ export default function App() {
         },
         {
           type: 'prose',
-          text: "Pseudoloc also has a subtle caveat worth knowing: the pseudo catalog is complete (astryx generates it from every shipped key), so a component using an astryx-shipped key will always render its pseudo version. Your handwritten translation catalogs, on the other hand, only cover the keys you translated — anything missing falls back to English. That means \"looks perfect in pseudo\" is not the same guarantee as \"looks perfect in French.\" Check each real locale by hand for coverage gaps.",
+          text: "Pseudoloc also has a subtle caveat worth knowing: the pseudo catalog is complete (astryx generates it from every shipped key), so a component using an astryx-shipped key will always render its pseudo version. Your handwritten translation catalogs, on the other hand, only cover the keys you translated; anything missing falls back to English. That means \"looks perfect in pseudo\" is not the same guarantee as \"looks perfect in French.\" Check each real locale by hand for coverage gaps.",
         },
       ],
     },
@@ -235,7 +235,7 @@ export default function App() {
       content: [
         {
           type: 'prose',
-          text: "Astryx's own strings live in `packages/core/locales/en.json`. New user-facing strings must go through `useTranslator` — this is enforced by the `@astryx/no-hardcoded-i18n-string` ESLint rule. See the AI contribution guide for the alias-and-resolve pattern used when adding new keys.",
+          text: "Astryx's own strings live in `packages/core/locales/en.json`. New user-facing strings must go through `useTranslator`; this is enforced by the `@astryx/no-hardcoded-i18n-string` ESLint rule. See the AI contribution guide for the alias-and-resolve pattern used when adding new keys.",
         },
       ],
     },

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/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 npx astryx docs tokens for full reference' }] },
   ],
 };

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: '运行 npx astryx docs tokens 查看完整参考' }] },
   ],
 };

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 `npx astryx component <Name>` for details.' }, null, null, null, null] },
+    { section: 'Custom Variants', title: 'Custom Variants', content: [{ type: 'prose', text: 'any unknown prop:value in components becomes a new variant. astryx theme build generates TS augmentations. works on any extensible prop axis (variant, status, etc).' }, null, null, null, null] },
+    { section: 'Building Themes for Production', title: 'Build for Production', content: [{ type: 'prose', text: 'npx astryx theme build compiles defineTheme to static CSS. outputs .css + .js (__built:true) + .d.ts.' }, null, null, null, null] },
+    { section: '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.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: 'npx 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.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.6-canary.fec872b",
+  "version": "0.1.6-canary.ff5dfca",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -79,10 +79,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.1.6-canary.fec872b",
-    "@astryxdesign/core": "0.1.6-canary.fec872b",
-    "@astryxdesign/lab": "0.1.6-canary.fec872b",
-    "@astryxdesign/theme-neutral": "0.1.6-canary.fec872b",
+    "@astryxdesign/charts": "0.1.6-canary.ff5dfca",
+    "@astryxdesign/core": "0.1.6-canary.ff5dfca",
+    "@astryxdesign/lab": "0.1.6-canary.ff5dfca",
+    "@astryxdesign/theme-neutral": "0.1.6-canary.ff5dfca",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -100,10 +100,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.1.6-canary.fec872b",
-    "@astryxdesign/core": "0.1.6-canary.fec872b",
-    "@astryxdesign/lab": "0.1.6-canary.fec872b",
-    "@astryxdesign/theme-neutral": "0.1.6-canary.fec872b",
+    "@astryxdesign/charts": "0.1.6-canary.ff5dfca",
+    "@astryxdesign/core": "0.1.6-canary.ff5dfca",
+    "@astryxdesign/lab": "0.1.6-canary.ff5dfca",
+    "@astryxdesign/theme-neutral": "0.1.6-canary.ff5dfca",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {

package/src/api/docOverlays.test.mjs

@@ -0,0 +1,133 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Guards the --dense / --zh reference-doc overlays against drift (#2182).
+ * @input packages/cli/docs/{topic}.doc.mjs and its .doc.dense.mjs / .doc.zh.mjs overlays.
+ * @output Vitest failures naming any overlay section that does not anchor to a
+ *   real base section, or whose content overrides land on the wrong block type.
+ * @position Regression gate for the docs API. Sits with the loader it guards.
+ *
+ * The overlays used to be applied BY ARRAY POSITION, so an overlay whose
+ * sections were ordered differently from the base grafted every title onto the
+ * wrong body. `docs tokens --dense` printed the entire colour table under a
+ * heading that said "## Spacing", above prose reading "gap props use
+ * space0-space12" — teaching any agent that spacing tokens are named
+ * `--color-*`. CLAUDE.md tells every agent to run that exact command at
+ * bootstrap, which is what made a doc bug into a codegen bug.
+ *
+ * Overlays now anchor to a base section by title, so a reordered or
+ * partial overlay is correct by construction. These tests keep it that way.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {docs} from './docs.mjs';
+
+const DOCS_DIR = path.join(import.meta.dirname, '..', '..', 'docs');
+
+/** Every base reference doc that has at least one overlay. */
+function overlayPairs() {
+  const pairs = [];
+  for (const file of fs.readdirSync(DOCS_DIR)) {
+    const m = file.match(/^(.+)\.doc\.(dense|zh)\.mjs$/);
+    if (!m) continue;
+    const [, topic, variant] = m;
+    pairs.push({
+      topic,
+      variant,
+      basePath: path.join(DOCS_DIR, `${topic}.doc.mjs`),
+      overlayPath: path.join(DOCS_DIR, file),
+    });
+  }
+  return pairs;
+}
+
+async function load(p) {
+  return await import(pathToFileURL(p).href);
+}
+
+describe('reference doc overlays (#2182)', () => {
+  const pairs = overlayPairs();
+
+  it('finds overlays to check', () => {
+    // A rename that stops overlays being discovered must not silently pass.
+    expect(pairs.length).toBeGreaterThan(0);
+  });
+
+  for (const {topic, variant, basePath, overlayPath} of pairs) {
+    it(`${topic} --${variant}: every overlay section anchors to a real base section`, async () => {
+      const base = await load(basePath);
+      const overlayMod = await load(overlayPath);
+      const overlay = overlayMod.docsDense || overlayMod.docsZh;
+
+      const baseTitles = base.docs.sections.map(s => s.title);
+      const unanchored = (overlay.sections || [])
+        .filter(s => s.section == null || !baseTitles.includes(s.section))
+        .map(s => s.section ?? `(no anchor) "${s.title}"`);
+
+      expect(
+        unanchored,
+        `${topic}.doc.${variant}.mjs has section entries that do not name a ` +
+          `base section via \`section:\`. Without an anchor the overlay is ` +
+          `applied by array position, which silently grafts each title onto ` +
+          `the wrong body. Base sections are: ${baseTitles.join(', ')}.`,
+      ).toEqual([]);
+    });
+
+    it(`${topic} --${variant}: no base section is overridden twice`, async () => {
+      const overlayMod = await load(overlayPath);
+      const overlay = overlayMod.docsDense || overlayMod.docsZh;
+      const anchors = (overlay.sections || []).map(s => s.section);
+      const dupes = anchors.filter((a, i) => anchors.indexOf(a) !== i);
+      expect(dupes, `${topic}.doc.${variant}.mjs overrides the same base section twice`).toEqual([]);
+    });
+  }
+});
+
+describe('the reported defect: docs tokens --dense (#2182)', () => {
+  it('does not print the colour table under the Spacing heading', async () => {
+    const result = await docs('tokens', null, {dense: true});
+    const spacing = result.data.sections.find(s => /spacing/i.test(s.title));
+    expect(spacing, 'tokens docs should have a spacing section').toBeTruthy();
+
+    const text = JSON.stringify(spacing);
+    expect(
+      text.includes('--color-'),
+      `The "${spacing.title}" section of \`docs tokens --dense\` contains ` +
+        `colour tokens. An agent reading this learns that spacing tokens are ` +
+        `named --color-*.`,
+    ).toBe(false);
+    expect(text).toContain('--spacing-');
+  });
+
+  it('keeps every base section reachable, even without an overlay entry', async () => {
+    // The tokens overlay compresses only 6 of 13 sections. The other 7 must
+    // still render (in English), not vanish or absorb a neighbour's title.
+    const full = await docs('tokens', null, {});
+    const dense = await docs('tokens', null, {dense: true});
+    expect(dense.data.sections.length).toBe(full.data.sections.length);
+  });
+
+  it('does not lose the Extending a Theme section from docs theme --dense', async () => {
+    const dense = await docs('theme', null, {dense: true});
+    const titles = dense.data.sections.map(s => s.title);
+    expect(titles).toContain('Extending a Theme');
+  });
+
+  it('does not emit a duplicate useTheme heading in docs theme --dense', async () => {
+    const dense = await docs('theme', null, {dense: true});
+    const titles = dense.data.sections.map(s => s.title.toLowerCase());
+    const useTheme = titles.filter(t => t.includes('usetheme'));
+    expect(useTheme.length).toBe(1);
+  });
+
+  it('does not leak English headings into docs theme --zh', async () => {
+    const zh = await docs('theme', null, {zh: true});
+    const titles = zh.data.sections.map(s => s.title);
+    // Every section the overlay translates must appear once, in Chinese only.
+    expect(titles).not.toContain('Light/Dark Mode');
+    expect(titles).toContain('亮/暗模式');
+  });
+});

package/src/api/docs.mjs

@@ -38,11 +38,23 @@ async function loadReferenceDocs(docPath, {lang} = {}) {
   const translation = translationMod.docsZh || translationMod.docsDense;
   if (!translation) return docs;
 
+  // Overlays are keyed to a base section by title (`section`), not by array
+  // position. Position-keying silently grafted each overlay title onto whatever
+  // base section happened to share its index, so an overlay that omitted or
+  // reordered a section corrupted every section after it — `docs tokens --dense`
+  // printed the colour table under a "Spacing" heading (#2182). An overlay may
+  // now cover any subset of sections, in any order; sections it does not name
+  // keep their base content.
+  const bySection = new Map();
+  for (const ts of translation.sections ?? []) {
+    if (ts?.section != null) bySection.set(ts.section, ts);
+  }
+
   return {
     ...docs,
     description: translation.description || docs.description,
-    sections: docs.sections.map((section, si) => {
-      const ts = translation.sections?.[si];
+    sections: docs.sections.map(section => {
+      const ts = bySection.get(section.title);
       if (!ts) return section;
       return {
         ...section,

package/src/codemods/transforms/v0.1.7/__tests__/rename-table-renderprops-styles-to-xstyle.test.mjs

@@ -0,0 +1,112 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source) {
+  const {default: transform} = await import(
+    '../rename-table-renderprops-styles-to-xstyle.mjs'
+  );
+  const jscodeshift = (await import('jscodeshift')).default;
+  const j = jscodeshift.withParser('tsx');
+  const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+  const file = {source, path: 'test.tsx'};
+  const result = transform(file, api);
+  return result ?? source;
+}
+
+describe('rename-table-renderprops-styles-to-xstyle', () => {
+  it('renames `props.styles` reads when the param is typed TableRenderProps', async () => {
+    const input = `function transformTable(props: TableRenderProps) {
+  return {...props, styles: [...props.styles, tableStyles.base]};
+}`;
+    const output = await applyTransform(input);
+    expect(output).toContain('...props.xstyle');
+    expect(output).toContain('xstyle: [');
+    expect(output).not.toMatch(/\bstyles:/);
+    expect(output).not.toContain('props.styles');
+  });
+
+  it('renames reads/writes for BodyCellRenderProps', async () => {
+    const input = `const transformBodyCell = (props: BodyCellRenderProps) => ({
+  ...props,
+  styles: [...props.styles, cellStyles.padded],
+});`;
+    const output = await applyTransform(input);
+    expect(output).toContain('...props.xstyle');
+    expect(output).toContain('xstyle: [');
+    expect(output).not.toContain('props.styles');
+  });
+
+  it('handles all six render-prop interface names as param types', async () => {
+    for (const typeName of [
+      'TableRenderProps',
+      'HeaderRowRenderProps',
+      'HeaderCellRenderProps',
+      'BodyRowRenderProps',
+      'BodyCellRenderProps',
+      'ScrollWrapperRenderProps',
+    ]) {
+      const input = `function t(p: ${typeName}) { return p.styles; }`;
+      const output = await applyTransform(input);
+      expect(output).toContain('p.xstyle');
+      expect(output).not.toContain('p.styles');
+    }
+  });
+
+  it('renames the `styles:` key on a render-prop-shaped object literal (htmlProps + styles siblings)', async () => {
+    const input = `const rp = {htmlProps: {}, styles: []};`;
+    const output = await applyTransform(input);
+    expect(output).toContain('xstyle: []');
+    expect(output).not.toMatch(/\bstyles:/);
+  });
+
+  it('does NOT touch an unrelated `styles` from stylex.create', async () => {
+    const input = `import * as stylex from '@stylexjs/stylex';
+const styles = stylex.create({base: {color: 'red'}});
+function useStuff() {
+  return stylex.props(styles.base);
+}`;
+    const output = await applyTransform(input);
+    // No render-prop binding, no htmlProps-shaped object -> unchanged
+    expect(output).toContain('const styles = stylex.create');
+    expect(output).toContain('styles.base');
+    expect(output).not.toContain('xstyle');
+  });
+
+  it('does NOT rename `.styles` on an unrelated (untyped) object even when a render-prop binding exists elsewhere', async () => {
+    const input = `function transformTable(props: TableRenderProps) {
+  const theme = getTheme();
+  return {...props, styles: [...props.styles, theme.styles.base]};
+}`;
+    const output = await applyTransform(input);
+    // props.styles renamed; theme.styles left alone
+    expect(output).toContain('...props.xstyle');
+    expect(output).toContain('theme.styles.base');
+  });
+
+  it('returns undefined for files with no render-prop usage', async () => {
+    const {default: transform} = await import(
+      '../rename-table-renderprops-styles-to-xstyle.mjs'
+    );
+    const jscodeshift = (await import('jscodeshift')).default;
+    const j = jscodeshift.withParser('tsx');
+    const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+    const source = `const styles = {a: 1};\nconst x = styles.a;`;
+    const result = transform({source, path: 'test.tsx'}, api);
+    expect(result).toBeUndefined();
+  });
+
+  it('returns undefined for already-migrated code (xstyle only)', async () => {
+    const {default: transform} = await import(
+      '../rename-table-renderprops-styles-to-xstyle.mjs'
+    );
+    const jscodeshift = (await import('jscodeshift')).default;
+    const j = jscodeshift.withParser('tsx');
+    const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+    const source = `function transformTable(props: TableRenderProps) {
+  return {...props, xstyle: [...props.xstyle]};
+}`;
+    const result = transform({source, path: 'test.tsx'}, api);
+    expect(result).toBeUndefined();
+  });
+});

package/src/codemods/transforms/v0.1.7/index.mjs

@@ -9,6 +9,9 @@
 import migrateTableTablePropsToDirectProps, {
   meta as migrateTableTablePropsToDirectPropsMeta,
 } from './migrate-table-tableprops-to-direct-props.mjs';
+import renameTableRenderPropsStylesToXstyle, {
+  meta as renameTableRenderPropsStylesToXstyleMeta,
+} from './rename-table-renderprops-styles-to-xstyle.mjs';
 
 export default [
   {
@@ -16,4 +19,9 @@ export default [
     transform: migrateTableTablePropsToDirectProps,
     meta: migrateTableTablePropsToDirectPropsMeta,
   },
+  {
+    name: 'rename-table-renderprops-styles-to-xstyle',
+    transform: renameTableRenderPropsStylesToXstyle,
+    meta: renameTableRenderPropsStylesToXstyleMeta,
+  },
 ];

package/src/codemods/transforms/v0.1.7/rename-table-renderprops-styles-to-xstyle.mjs

@@ -0,0 +1,197 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: Rename Table render-prop `styles` field to `xstyle`
+ *
+ * As of v0.1.7, the Table plugin render-prop interfaces
+ * (`TableRenderProps`, `HeaderRowRenderProps`, `HeaderCellRenderProps`,
+ * `BodyRowRenderProps`, `BodyCellRenderProps`, `ScrollWrapperRenderProps`)
+ * and the `scrollWrapper` component contract renamed their StyleX array
+ * field `styles` -> `xstyle`, matching the prop name sub-components
+ * receive it under.
+ *
+ * Custom plugin authors read `props.styles` and write `styles: [...]`
+ * inside their transform functions (`transformTable`, `transformHeaderRow`,
+ * `transformHeaderCell`, `transformBodyRow`, `transformBodyCell`,
+ * `transformScrollWrapper`). This codemod renames those reads and writes.
+ *
+ * A blind global `styles` rename is unsafe — `styles` is also the
+ * conventional local name for a `stylex.create({...})` bag, which is
+ * unrelated. So this transform only rewrites `styles` when it is
+ * *scoped to a render-prop object*: a function parameter (or a variable)
+ * whose TypeScript type annotation is one of the render-prop interfaces.
+ * Within such a scope it rewrites:
+ *
+ *   - `<param>.styles`            -> `<param>.xstyle`   (member reads/writes)
+ *   - `{ ..., styles: [...] }`    -> `{ ..., xstyle: [...] }`
+ *     for object literals that carry the render-prop shape (a sibling
+ *     `htmlProps` key), and object literals assigned/spread from the
+ *     tracked render-prop binding.
+ *
+ * Ambiguous cases that can't be resolved from types alone (e.g. a
+ * render-prop object passed through an untyped variable, or a `styles`
+ * bag from `stylex.create`) are left untouched, so the transform never
+ * renames an unrelated `styles`. This mirrors the conservative,
+ * scope-limited approach of the sibling
+ * `migrate-table-tableprops-to-direct-props` codemod.
+ */
+
+export const meta = {
+  title: 'Rename Table render-prop `styles` field to `xstyle`',
+  description:
+    'Renames the `styles` StyleX-array field to `xstyle` on Table plugin ' +
+    'render-prop objects (TableRenderProps, HeaderRowRenderProps, ' +
+    'HeaderCellRenderProps, BodyRowRenderProps, BodyCellRenderProps, ' +
+    'ScrollWrapperRenderProps) inside plugin transform functions. Reads ' +
+    '(`props.styles`) and writes (`styles: [...]`) are renamed; unrelated ' +
+    '`styles` bindings (e.g. from stylex.create) are left untouched.',
+};
+
+/** The render-prop interface type names whose `styles` field became `xstyle`. */
+const RENDER_PROP_TYPES = new Set([
+  'TableRenderProps',
+  'HeaderRowRenderProps',
+  'HeaderCellRenderProps',
+  'BodyRowRenderProps',
+  'BodyCellRenderProps',
+  'ScrollWrapperRenderProps',
+]);
+
+/** Resolve the base type name from a TS type annotation node. */
+function typeNameOf(typeAnnotation) {
+  // `x: TableRenderProps`
+  const t = typeAnnotation?.typeAnnotation ?? typeAnnotation;
+  if (!t) return null;
+  if (t.type === 'TSTypeReference' && t.typeName?.type === 'Identifier') {
+    return t.typeName.name;
+  }
+  return null;
+}
+
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  // --- 1. Collect binding names typed as a render-prop interface. ---
+  // Function/arrow params: (props: TableRenderProps) => ...
+  const renderPropBindings = new Set();
+
+  function collectParam(param) {
+    if (
+      param.type === 'Identifier' &&
+      RENDER_PROP_TYPES.has(typeNameOf(param.typeAnnotation))
+    ) {
+      renderPropBindings.add(param.name);
+    }
+  }
+
+  root
+    .find(j.Function)
+    .forEach((p) => (p.node.params ?? []).forEach(collectParam));
+  root
+    .find(j.FunctionDeclaration)
+    .forEach((p) => (p.node.params ?? []).forEach(collectParam));
+  root
+    .find(j.FunctionExpression)
+    .forEach((p) => (p.node.params ?? []).forEach(collectParam));
+  root
+    .find(j.ArrowFunctionExpression)
+    .forEach((p) => (p.node.params ?? []).forEach(collectParam));
+
+  // Variable declarations: `const rp: BodyCellRenderProps = ...`
+  root.find(j.VariableDeclarator).forEach((p) => {
+    const id = p.node.id;
+    if (
+      id?.type === 'Identifier' &&
+      RENDER_PROP_TYPES.has(typeNameOf(id.typeAnnotation))
+    ) {
+      renderPropBindings.add(id.name);
+    }
+  });
+
+  const hasTypedBinding = renderPropBindings.size > 0;
+
+  // Also detect object literals that are structurally a render-prop object.
+  // Two shapes qualify:
+  //  1. An `htmlProps` sibling key alongside a `styles`/`xstyle` key — the
+  //     literal shape a transform function returns from scratch.
+  //  2. A spread of a tracked render-prop binding (`{...props, styles: [...]}`)
+  //     — the common "carry the render-prop object forward, override styles"
+  //     shape. (Only counts when `renderPropBindings` is non-empty.)
+  function isRenderPropShapedObject(objExpr) {
+    if (objExpr.type !== 'ObjectExpression') return false;
+    const keyNames = objExpr.properties
+      .map((pr) =>
+        pr.type === 'ObjectProperty' || pr.type === 'Property'
+          ? pr.key?.name ?? pr.key?.value
+          : null,
+      )
+      .filter(Boolean);
+    if (keyNames.includes('htmlProps') && keyNames.includes('styles')) {
+      return true;
+    }
+    // Spread of a tracked render-prop binding.
+    const spreadsRenderProp = objExpr.properties.some(
+      (pr) =>
+        (pr.type === 'SpreadElement' || pr.type === 'ExperimentalSpreadProperty') &&
+        pr.argument?.type === 'Identifier' &&
+        renderPropBindings.has(pr.argument.name),
+    );
+    return spreadsRenderProp && keyNames.includes('styles');
+  }
+
+  if (!hasTypedBinding) {
+    // Nothing is typed as a render-prop interface. Only rewrite clearly
+    // render-prop-shaped object literals (htmlProps + styles siblings);
+    // never touch bare `styles` in this file (too ambiguous).
+    let touched = false;
+    root.find(j.ObjectExpression).forEach((p) => {
+      if (!isRenderPropShapedObject(p.node)) return;
+      for (const prop of p.node.properties) {
+        if (
+          (prop.type === 'ObjectProperty' || prop.type === 'Property') &&
+          !prop.computed &&
+          prop.key?.type === 'Identifier' &&
+          prop.key.name === 'styles'
+        ) {
+          prop.key.name = 'xstyle';
+          touched = true;
+        }
+      }
+    });
+    if (!touched) return undefined;
+    return root.toSource({quote: 'single'});
+  }
+
+  // --- 2. Rewrite `<binding>.styles` member access -> `.xstyle`. ---
+  root.find(j.MemberExpression).forEach((p) => {
+    const {object, property, computed} = p.node;
+    if (computed) return;
+    if (property?.type !== 'Identifier' || property.name !== 'styles') return;
+    if (object?.type !== 'Identifier' || !renderPropBindings.has(object.name)) {
+      return;
+    }
+    property.name = 'xstyle';
+    hasChanges = true;
+  });
+
+  // --- 3. Rewrite `styles:` keys on render-prop-shaped object literals. ---
+  root.find(j.ObjectExpression).forEach((p) => {
+    if (!isRenderPropShapedObject(p.node)) return;
+    for (const prop of p.node.properties) {
+      if (
+        (prop.type === 'ObjectProperty' || prop.type === 'Property') &&
+        !prop.computed &&
+        prop.key?.type === 'Identifier' &&
+        prop.key.name === 'styles'
+      ) {
+        prop.key.name = 'xstyle';
+        hasChanges = true;
+      }
+    }
+  });
+
+  if (!hasChanges) return undefined;
+  return root.toSource({quote: 'single'});
+}

package/src/commands/agent-docs.mjs

@@ -197,6 +197,20 @@ export function generateCompressedIndex(version, {coreDir, runPrefix = getRunPre
     lines.push("- Custom styling: component props first; else style/className with tokens — var(--color-*|--spacing-*|--radius-*). No raw hex/px. (No StyleX/Tailwind compiler here — don't use xstyle/utility classes.)");
   }
   lines.push('- Tokens for every value (`astryx docs tokens`). Brand/accent via `astryx theme` — never override --color-* in :root.');
+  // Self-check — post-generation pass. Validated via vibe tests (internal/vibe-tests/
+  // prompt-purity-test): on complex multi-step UIs the rules above alone still leave raw
+  // CSS in ~11-13% of runs; a re-read-and-fix pass cuts that ~4x at negligible token cost.
+  // The fix names the sanctioned escape hatch for the configured system.
+  const selfCheckFix = {
+    stylex:
+      'replace any className=, style={{…}}, raw <div>/<span> layout, imported .css/@apply, or hardcoded #hex/px with the component or the xstyle prop + a token',
+    tailwind:
+      'replace any style={{…}}, raw <div>/<span> layout, imported .css/@apply, or hardcoded/arbitrary value (e.g. bg-[#fff], p-[13px]) with the component or a token-backed utility',
+    css: 'replace any raw <div>/<span> layout, imported .css/@apply, or hardcoded value (#hex, 16px) with the component or a token (var(--color-*|--spacing-*|…))',
+  };
+  lines.push(
+    `- SELF-CHECK before you finish: re-read the file and ${selfCheckFix[stylingSystem] ?? selfCheckFix.css}. If unsure a component/prop exists, run \`astryx component <Name>\` / \`astryx search "<thing>"\`; don't hand-roll CSS.`,
+  );
   lines.push('');
 
   // Command reference — build/template/component are covered in WORKFLOW above.

package/src/commands/agent-docs.test.mjs

@@ -43,6 +43,26 @@ describe('generateCompressedIndex', () => {
     expect(result).toMatch(/never override --color-/);
   });
 
+  it('includes the post-generation self-check rule', () => {
+    const result = generateCompressedIndex('1.0.0');
+    expect(result).toContain('SELF-CHECK before you finish');
+    expect(result).toMatch(/re-read the file/);
+    expect(result).toMatch(/don't hand-roll CSS/);
+  });
+
+  it('tailors the self-check to the styling system (xstyle for StyleX, not className for Tailwind)', () => {
+    // StyleX path: className/inline style are veers; the fix is the xstyle prop + a token
+    const stylex = generateCompressedIndex('1.0.0', {stylingSystem: 'stylex'});
+    const stylexSelfCheck = stylex.split('\n').find(l => l.includes('SELF-CHECK'));
+    expect(stylexSelfCheck).toMatch(/xstyle/);
+    expect(stylexSelfCheck).toMatch(/className=/);
+    // className IS the system in Tailwind — it must NOT be flagged
+    const tailwind = generateCompressedIndex('1.0.0', {stylingSystem: 'tailwind'});
+    const tailwindSelfCheck = tailwind.split('\n').find(l => l.includes('SELF-CHECK'));
+    expect(tailwindSelfCheck).toBeDefined();
+    expect(tailwindSelfCheck).not.toMatch(/className=/);
+  });
+
   it('defaults to the CSS-variable styling path (no compiler)', () => {
     const result = generateCompressedIndex('1.0.0');
     expect(result).toMatch(/style\/className with tokens/);