@astryxdesign/cli 0.1.6-canary.7158eaa → 0.1.6-canary.72e34d3

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.6-canary.7158eaa",
+  "version": "0.1.6-canary.72e34d3",
   "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.7158eaa",
-    "@astryxdesign/core": "0.1.6-canary.7158eaa",
-    "@astryxdesign/lab": "0.1.6-canary.7158eaa",
-    "@astryxdesign/theme-neutral": "0.1.6-canary.7158eaa",
+    "@astryxdesign/charts": "0.1.6-canary.72e34d3",
+    "@astryxdesign/core": "0.1.6-canary.72e34d3",
+    "@astryxdesign/lab": "0.1.6-canary.72e34d3",
+    "@astryxdesign/theme-neutral": "0.1.6-canary.72e34d3",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -100,10 +100,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.1.6-canary.7158eaa",
-    "@astryxdesign/core": "0.1.6-canary.7158eaa",
-    "@astryxdesign/lab": "0.1.6-canary.7158eaa",
-    "@astryxdesign/theme-neutral": "0.1.6-canary.7158eaa",
+    "@astryxdesign/charts": "0.1.6-canary.72e34d3",
+    "@astryxdesign/core": "0.1.6-canary.72e34d3",
+    "@astryxdesign/lab": "0.1.6-canary.72e34d3",
+    "@astryxdesign/theme-neutral": "0.1.6-canary.72e34d3",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {

package/src/codemods/__tests__/registry.test.mjs

@@ -20,6 +20,7 @@ describe('registry', () => {
         '0.1.2',
         '0.1.3',
         '0.1.5',
+        '0.1.7',
       ]);
     });
   });

package/src/codemods/registry.mjs

@@ -21,6 +21,7 @@ const registry = new Map([
   ['0.1.2', () => import('./transforms/v0.1.2/index.mjs')],
   ['0.1.3', () => import('./transforms/v0.1.3/index.mjs')],
   ['0.1.5', () => import('./transforms/v0.1.5/index.mjs')],
+  ['0.1.7', () => import('./transforms/v0.1.7/index.mjs')],
 ]);
 
 // Re-export from the shared utility so registry callers and other consumers

package/src/codemods/transforms/v0.1.7/__tests__/migrate-table-tableprops-to-direct-props.test.mjs

@@ -0,0 +1,120 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source) {
+  const {default: transform} = await import(
+    '../migrate-table-tableprops-to-direct-props.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;
+}
+
+const TODO = 'TODO(astryx): tableProps is deprecated';
+
+describe('migrate-table-tableprops-to-direct-props', () => {
+  it('lifts className and style to sibling props', async () => {
+    const input = `import {Table} from '@astryxdesign/core';
+const x = <Table tableProps={{className: 'striped', style: {width: 400}}} columns={cols} />;`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`className='striped'`);
+    expect(output).toContain('style={{width: 400}}');
+    expect(output).not.toContain('tableProps');
+  });
+
+  it(`lifts 'aria-label' and 'data-testid' string keys to hyphenated props`, async () => {
+    const input = `import {Table} from '@astryxdesign/core/Table';
+const x = <Table tableProps={{'aria-label': 'Users', 'data-testid': 'users-table'}} />;`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`aria-label='Users'`);
+    expect(output).toContain(`data-testid='users-table'`);
+    expect(output).not.toContain('tableProps');
+  });
+
+  it('lifts id and an onClick handler', async () => {
+    const input = `import {Table} from '@xds/core';
+const x = <Table tableProps={{id: 'users', onClick: (e) => handle(e)}} />;`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`id='users'`);
+    expect(output).toContain('onClick={(e) => handle(e)}');
+    expect(output).not.toContain('tableProps');
+  });
+
+  it('keeps colliding keys in a shrunken tableProps with a TODO comment', async () => {
+    const input = `import {Table} from '@astryxdesign/core';
+const x = <Table className='mine' tableProps={{className: 'theirs', id: 'users'}} />;`;
+    const output = await applyTransform(input);
+    // Non-colliding key lifted
+    expect(output).toContain(`id='users'`);
+    // Existing sibling wins; colliding key stays inside tableProps
+    expect(output).toContain(`className='mine'`);
+    expect(output).toContain('tableProps={{');
+    expect(output).toContain(`className: 'theirs'`);
+    expect(output).not.toContain('id: ');
+    expect(output).toContain(TODO);
+  });
+
+  it('leaves a dynamic tableProps={identifier} untouched with a TODO comment', async () => {
+    const input = `import {Table} from '@astryxdesign/core';
+const x = <Table tableProps={props} />;`;
+    const output = await applyTransform(input);
+    expect(output).toContain('tableProps={props}');
+    expect(output).toContain(TODO);
+  });
+
+  it('leaves an object containing a spread untouched with a TODO comment (no partial lift)', async () => {
+    const input = `import {Table} from '@astryxdesign/core';
+const x = <Table tableProps={{className: 'x', ...rest}} />;`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`tableProps={{className: 'x', ...rest}}`);
+    expect(output).not.toContain(`<Table className=`);
+    expect(output).toContain(TODO);
+  });
+
+  it('transforms aliased Table imports', async () => {
+    const input = `import {Table as DataTable} from '@astryxdesign/core';
+const x = <DataTable tableProps={{className: 'x'}} />;`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`<DataTable className='x' />`);
+    expect(output).not.toContain('tableProps');
+  });
+
+  it('does not touch other components with a tableProps attribute', async () => {
+    const input = `import {Table} from '@astryxdesign/core';
+const a = <Table tableProps={{id: 'users'}} />;
+const b = <OtherComponent tableProps={{className: 'x'}} />;`;
+    const output = await applyTransform(input);
+    expect(output).toContain(`<Table id='users' />`);
+    expect(output).toContain(`<OtherComponent tableProps={{className: 'x'}} />`);
+  });
+
+  it('returns undefined for files without a Table import', async () => {
+    const {default: transform} = await import(
+      '../migrate-table-tableprops-to-direct-props.mjs'
+    );
+    const jscodeshift = (await import('jscodeshift')).default;
+    const j = jscodeshift.withParser('tsx');
+    const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+    const source = `import {Grid} from '@astryxdesign/core';
+const x = <Table tableProps={{className: 'x'}} />;`;
+    const result = transform({source, path: 'test.tsx'}, api);
+    expect(result).toBeUndefined();
+  });
+
+  it('returns undefined for already-migrated files (no tableProps)', async () => {
+    const {default: transform} = await import(
+      '../migrate-table-tableprops-to-direct-props.mjs'
+    );
+    const jscodeshift = (await import('jscodeshift')).default;
+    const j = jscodeshift.withParser('tsx');
+    const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+    const source = `import {Table} from '@astryxdesign/core';
+const x = <Table className='x' />;`;
+    const result = transform({source, path: 'test.tsx'}, api);
+    expect(result).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file v0.1.7 transform manifest
+ *
+ * Lists all codemods for the v0.1.7 release in the order they should run.
+ */
+
+import migrateTableTablePropsToDirectProps, {
+  meta as migrateTableTablePropsToDirectPropsMeta,
+} from './migrate-table-tableprops-to-direct-props.mjs';
+
+export default [
+  {
+    name: 'migrate-table-tableprops-to-direct-props',
+    transform: migrateTableTablePropsToDirectProps,
+    meta: migrateTableTablePropsToDirectPropsMeta,
+  },
+];

package/src/codemods/transforms/v0.1.7/migrate-table-tableprops-to-direct-props.mjs

@@ -0,0 +1,188 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: Migrate Table tableProps to direct root props
+ * @see https://github.com/facebook/astryx/issues/3679
+ *
+ * `tableProps` (typed HTMLAttributes<HTMLTableElement>, nesting HTML
+ * attributes one level deep) is deprecated. As of v0.1.7, <Table> honors
+ * className/style/xstyle directly and spreads all other BaseProps
+ * (id, aria-*, data-*, event handlers, ...) onto the root <table>, with
+ * direct props taking precedence over tableProps.
+ *
+ * This codemod lifts object-literal `tableProps` keys into sibling JSX
+ * props:
+ *
+ * - tableProps={{className: 'x', style: s}} → className="x" style={s}
+ * - String-literal keys ('aria-label', 'data-testid') become hyphenated
+ *   JSX attributes.
+ * - Keys that collide with an existing sibling attribute (or fail the
+ *   attribute-name guard) are kept inside a shrunken tableProps with a
+ *   trailing TODO comment for manual migration.
+ * - Dynamic values (tableProps={props}, tableProps={fn()}, objects with
+ *   spreads/computed keys/methods) are left untouched with a TODO comment.
+ *
+ * Only elements whose name resolves to a `Table` import (alias-aware)
+ * from an Astryx core source are rewritten. No import changes are needed.
+ */
+
+export const meta = {
+  title: 'Migrate Table tableProps to direct root props',
+  description:
+    'Lifts object-literal `tableProps` keys on <Table> into sibling JSX props ' +
+    '(className, style, id, aria-*, data-*, event handlers). Dynamic or ' +
+    'colliding entries are kept and annotated with a TODO comment.',
+  pr: '#3679',
+};
+
+/** Import sources that provide the Astryx Table component. */
+const TABLE_IMPORT_SOURCES = new Set([
+  '@astryxdesign/core',
+  '@astryxdesign/core/Table',
+  '@xds/core',
+  '@xds/core/Table',
+]);
+
+/** Keys must be valid JSX attribute names to be lifted. */
+const LIFTABLE_KEY_RE = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
+
+const TODO_COMMENT =
+  ' TODO(astryx): tableProps is deprecated — merge these into direct props manually ';
+
+/**
+ * Extract the static key name from an object property, or null when the
+ * property is not a simple liftable entry (spread, computed key, method,
+ * getter/setter, non-string literal key).
+ */
+function getPropertyKeyName(prop) {
+  if (prop.type !== 'ObjectProperty' && prop.type !== 'Property') return null;
+  // espree-style Property nodes: skip methods and accessors
+  if (prop.method || (prop.kind != null && prop.kind !== 'init')) return null;
+  if (prop.computed) return null;
+  const key = prop.key;
+  if (key.type === 'Identifier') return key.name;
+  if (
+    (key.type === 'StringLiteral' || key.type === 'Literal') &&
+    typeof key.value === 'string'
+  ) {
+    return key.value;
+  }
+  return null;
+}
+
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  // --- 1. Track local names for the Table import (alias-aware) ---
+  const tableLocals = new Set();
+  root.find(j.ImportDeclaration).forEach((path) => {
+    if (!TABLE_IMPORT_SOURCES.has(path.node.source.value)) return;
+    for (const spec of path.node.specifiers ?? []) {
+      if (spec.type === 'ImportSpecifier' && spec.imported.name === 'Table') {
+        tableLocals.add(spec.local.name);
+      }
+    }
+  });
+
+  if (tableLocals.size === 0) return undefined;
+
+  function attachTodo(attr) {
+    if (!attr.comments) attr.comments = [];
+    if (attr.comments.some((c) => c.value === TODO_COMMENT)) return;
+    attr.comments.push(j.commentBlock(TODO_COMMENT, false, true));
+    hasChanges = true;
+  }
+
+  function buildAttributeValue(valueNode) {
+    if (
+      valueNode.type === 'StringLiteral' ||
+      (valueNode.type === 'Literal' && typeof valueNode.value === 'string')
+    ) {
+      return j.stringLiteral(valueNode.value);
+    }
+    return j.jsxExpressionContainer(valueNode);
+  }
+
+  // --- 2. Rewrite tableProps on tracked <Table> elements ---
+  root.find(j.JSXOpeningElement).forEach((path) => {
+    const name = path.node.name;
+    const componentName = name.type === 'JSXIdentifier' ? name.name : null;
+    if (!componentName || !tableLocals.has(componentName)) return;
+
+    const attrs = path.node.attributes;
+    const tablePropsAttr = attrs.find(
+      (a) => a.type === 'JSXAttribute' && a.name?.name === 'tableProps',
+    );
+    if (!tablePropsAttr) return;
+
+    const value = tablePropsAttr.value;
+    const isObjectLiteral =
+      value?.type === 'JSXExpressionContainer' &&
+      value.expression.type === 'ObjectExpression';
+
+    // Dynamic case: tableProps={identifier}, tableProps={fn()}, ... —
+    // leave the attribute untouched and warn via a trailing comment
+    // (api.report is a stub; comments are the only warning channel).
+    if (!isObjectLiteral) {
+      attachTodo(tablePropsAttr);
+      return;
+    }
+
+    const obj = value.expression;
+
+    // Objects containing spreads, computed keys, or methods are treated
+    // as dynamic: no partial lift, just the TODO comment.
+    const allSimple = obj.properties.every(
+      (prop) => getPropertyKeyName(prop) !== null,
+    );
+    if (!allSimple) {
+      attachTodo(tablePropsAttr);
+      return;
+    }
+
+    const lifted = [];
+    const kept = [];
+    for (const prop of obj.properties) {
+      const keyName = getPropertyKeyName(prop);
+      const collidesWithSibling = attrs.some(
+        (a) => a.type === 'JSXAttribute' && a.name?.name === keyName,
+      );
+      const collidesWithLifted = lifted.some(
+        (a) => a.name.name === keyName,
+      );
+      if (
+        !LIFTABLE_KEY_RE.test(keyName) ||
+        collidesWithSibling ||
+        collidesWithLifted
+      ) {
+        kept.push(prop);
+        continue;
+      }
+      lifted.push(
+        j.jsxAttribute(
+          j.jsxIdentifier(keyName),
+          buildAttributeValue(prop.value),
+        ),
+      );
+    }
+
+    const tablePropsIdx = attrs.indexOf(tablePropsAttr);
+    if (kept.length === 0) {
+      // All keys lifted — replace tableProps with the sibling attributes.
+      attrs.splice(tablePropsIdx, 1, ...lifted);
+      hasChanges = true;
+    } else {
+      // Some keys collide or fail the name guard — keep only those in a
+      // shrunken tableProps and flag it for manual migration.
+      attrs.splice(tablePropsIdx, 0, ...lifted);
+      obj.properties = kept;
+      attachTodo(tablePropsAttr);
+      if (lifted.length > 0) 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/);

package/src/lib/component-format.mjs

@@ -34,15 +34,30 @@ function getTargetDataAttributes(target) {
   ];
 }
 
+/**
+ * Escape a value for a markdown table cell.
+ *
+ * A prop type is a union, and a union is spelled with the same `|` that GFM
+ * uses to separate cells — backticks do not protect it. A row with more cells
+ * than the header has columns gets the excess *discarded*, so an unescaped
+ * `gap: 0 | 0.5 | ...` silently eats its own Default and Description columns.
+ * <!-- SYNC: packages/core/src/Markdown/parser.ts (splits on unescaped pipes) -->
+ */
+export function mdCell(value) {
+  return String(value ?? '').replace(/\|/g, '\\|');
+}
+
 function formatPropsTable(props) {
   if (!props || props.length === 0) return '';
   const lines = [];
   lines.push('| Prop | Type | Default | Description |');
   lines.push('|------|------|---------|-------------|');
   for (const p of props) {
-    const def = p.default ? `\`${p.default}\`` : '—';
+    const def = p.default ? `\`${mdCell(p.default)}\`` : '—';
     const req = p.required ? ' **(required)**' : '';
-    lines.push(`| \`${p.name}\` | \`${p.type}\` | ${def} | ${p.description}${req} |`);
+    lines.push(
+      `| \`${mdCell(p.name)}\` | \`${mdCell(p.type)}\` | ${def} | ${mdCell(p.description)}${req} |`,
+    );
   }
   return lines.join('\n');
 }
@@ -177,7 +192,7 @@ export function formatFull(docs, options = {}) {
     sections.push('|---------|----------|-------------|');
     for (const el of docs.usage.anatomy) {
       const req = el.required ? 'Yes' : 'No';
-      sections.push(`| ${el.name} | ${req} | ${el.description} |`);
+      sections.push(`| ${mdCell(el.name)} | ${req} | ${mdCell(el.description)} |`);
     }
     sections.push('');
   }
@@ -282,7 +297,9 @@ export function formatFull(docs, options = {}) {
         varLines.push('| CSS Variable | Default | Description |');
         varLines.push('|-------------|---------|-------------|');
         for (const v of publicVars) {
-          varLines.push(`| \`${v.name}\` | \`${v.default}\` | ${v.description} |`);
+          varLines.push(
+            `| \`${mdCell(v.name)}\` | \`${mdCell(v.default)}\` | ${mdCell(v.description)} |`,
+          );
         }
         sections.push(varLines.join('\n') + '\n');
       }
@@ -378,8 +395,8 @@ export function formatCompact(docs, componentName, importHint) {
     propLines.push('| CSS Property | Sets |');
     propLines.push('|-------------|------|');
     for (const d of docs.theming.derived) {
-      const target = d.expand === 'container' ? 'container layout tokens' : (d.vars || []).map(v => `\`${v}\``).join(', ');
-      propLines.push(`| \`${d.property}\` | ${target} |`);
+      const target = d.expand === 'container' ? 'container layout tokens' : (d.vars || []).map(v => `\`${mdCell(v)}\``).join(', ');
+      propLines.push(`| \`${mdCell(d.property)}\` | ${target} |`);
     }
     sections.push(propLines.join('\n') + '\n');
   }
@@ -395,6 +412,19 @@ export function formatCompact(docs, componentName, importHint) {
  *
  * For multi-component docs, extracts the entry matching componentName.
  */
+/**
+ * Longest union `--detail brief` will spell out inside the one-line signature.
+ *
+ * The signature is a glance, not a reference: a six-member enum like
+ * `start|center|end|between|around|evenly` reads at a glance, an eleven-member
+ * spacing scale does not — and Stack carries four of them (gap, padding,
+ * paddingInline, paddingBlock), so it printed the same scale four times. Longer
+ * unions fall through to the terse prop list, exactly as they did when the type
+ * was still the bare name `SpacingStep`. The full values are always one
+ * `astryx component <Name>` away.
+ */
+const SIGNATURE_UNION_MAX_MEMBERS = 8;
+
 export function formatBrief(docs, componentName, importHint, options = {}) {
   const displayName = componentName.startsWith('XDS')
     ? componentName.slice(3)
@@ -421,13 +451,15 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
   const otherProps = [];
 
   for (const prop of props) {
-    if (prop.type.includes('|') && !prop.type.includes('ReactNode')) {
-      const values = prop.type
-        .replace(/['"]/g, '')
-        .split('|')
-        .map(v => v.trim())
-        .join('|');
-      signatureProps.push(`${prop.name}: ${values}`);
+    const values =
+      prop.type.includes('|') && !prop.type.includes('ReactNode')
+        ? prop.type
+            .replace(/['"]/g, '')
+            .split('|')
+            .map(v => v.trim())
+        : null;
+    if (values && values.length <= SIGNATURE_UNION_MAX_MEMBERS) {
+      signatureProps.push(`${prop.name}: ${values.join('|')}`);
     } else if (prop.required) {
       otherProps.unshift(`${prop.name}: ${prop.type.split('|')[0].trim()}`);
     } else {

package/src/lib/component-format.test.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 import {describe, it, expect} from 'vitest';
-import {formatFull} from './component-format.mjs';
+import {formatBrief, formatFull} from './component-format.mjs';
 
 describe('formatFull sub-component rendering', () => {
   // Regression guard: sub-components are sometimes declared as a bare
@@ -93,3 +93,97 @@ describe('formatFull theming override keys', () => {
     expect(out).not.toContain("'astryx-table-cell': {");
   });
 });
+
+/** Pipes that actually separate cells — a `\|` is content, not a separator. */
+function cellPipes(row) {
+  return (row.match(/(?<!\\)\|/g) || []).length;
+}
+
+describe('markdown table cells escape their pipes', () => {
+  // A prop type is a union, and a union is spelled with `|` — the very
+  // character GFM uses to separate cells. Backticks do not protect it: a row
+  // with more cells than the header has columns gets its excess *discarded*,
+  // so an unescaped `gap: 0 | 0.5 | ...` silently eats its own Default and
+  // Description columns. See packages/core/src/Markdown/parser.ts, which
+  // splits on unescaped pipes and preserves `\|` as literal.
+  it('keeps a union-typed prop row at four cells', () => {
+    const docs = {
+      name: 'Grid',
+      description: 'A grid.',
+      props: [
+        {
+          name: 'gap',
+          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+          default: '2',
+          description: 'Spacing between all items.',
+        },
+      ],
+    };
+    const row = formatFull(docs)
+      .split('\n')
+      .find(l => l.startsWith('| `gap`'));
+
+    // A 4-column row has exactly 5 separators. Unescaped, this row had 15.
+    expect(cellPipes(row)).toBe(5);
+    expect(row).toContain('\\|');
+    // The columns the unescaped pipes were swallowing.
+    expect(row).toContain('`2`');
+    expect(row).toContain('Spacing between all items.');
+  });
+
+  it('escapes pipes in a description too', () => {
+    const docs = {
+      name: 'AppShell',
+      description: 'A shell.',
+      props: [
+        {
+          name: 'mobileNav',
+          type: 'ReactNode',
+          description: "Config. breakpoint is 'sm' | 'md' | 'lg' | 'none'.",
+        },
+      ],
+    };
+    const row = formatFull(docs)
+      .split('\n')
+      .find(l => l.startsWith('| `mobileNav`'));
+
+    expect(cellPipes(row)).toBe(5);
+  });
+});
+
+describe('formatBrief signature stays terse', () => {
+  // `--detail brief` exists to be token-cheap. It hoists union-typed props into
+  // the signature because a short enum reads at a glance — but an 11-member
+  // spacing scale does not, and Stack carries four of them (gap, padding,
+  // paddingInline, paddingBlock), so the same scale got printed four times.
+  // Long unions stay in the terse prop list, exactly as they did when the type
+  // was still the bare name `SpacingStep`.
+  it('hoists a short enum but not a long scale', () => {
+    const docs = {
+      name: 'HStack',
+      description: 'A stack.',
+      props: [
+        {
+          name: 'gap',
+          type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+          description: 'Gap.',
+        },
+        {name: 'wrap', type: "'nowrap' | 'wrap' | 'wrap-reverse'", description: 'Wrap.'},
+        {
+          name: 'hAlign',
+          type: "'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'",
+          description: 'Align.',
+        },
+      ],
+    };
+    const signature = formatBrief(docs, 'HStack', '').split('\n')[0];
+
+    // Short enums still earn their place in the signature.
+    expect(signature).toContain('wrap: nowrap|wrap|wrap-reverse');
+    expect(signature).toContain('hAlign: start|center|end|between|around|evenly');
+    // The long scale does not.
+    expect(signature).not.toContain('0|0.5|1|1.5|2|3|4|5|6|8|10');
+    // But the prop is still named, so it is not lost.
+    expect(formatBrief(docs, 'HStack', '')).toContain('gap');
+  });
+});

package/src/lib/component-loader.mjs

@@ -144,15 +144,64 @@ export async function loadDocs(readmePath, {zh = false, dense = false, lang} = {
 
   const translation = mod[translationKey];
 
-  // If the translation is a full ComponentDoc (legacy docsZh shape), return it directly
+  // A full ComponentDoc-shaped translation (legacy docsZh shape) used to be
+  // returned wholesale. That made it a REPLACEMENT, not an overlay: any prop
+  // the translation had not caught up with simply ceased to exist —
+  // `component Button --zh` silently omitted `isInterruptible` and
+  // `isIconOnly`. A reader of the translated docs cannot discover a prop that
+  // is not there. Overlay it instead, so an untranslated prop falls back to
+  // its English entry. (Same principle as the reference-doc overlays, #2182.)
   if (translation.props || translation.components?.some(c => c.props)) {
-    return translation;
+    return overlayComponentDoc(docs, translation);
   }
 
   // Otherwise it's a TranslationDoc — merge it onto docs
   return mergeTranslation(docs, translation);
 }
 
+/**
+ * Overlay a full-ComponentDoc-shaped translation onto the English doc.
+ *
+ * Base order and completeness win; the translation supplies text for the
+ * entries it covers. Props are matched by name, never by position, so a
+ * translation that is missing entries (or lists them in another order) can no
+ * longer drop or misattribute one.
+ *
+ * @param {any} docs Base (English) component doc.
+ * @param {any} translation Translated doc, possibly covering only some props.
+ * @returns {any} Merged doc with every base prop present.
+ */
+function overlayComponentDoc(docs, translation) {
+  /** Merge one prop list: keep base entries and order, translate what's covered. */
+  const overlayProps = (baseProps, tProps) => {
+    if (!baseProps) return baseProps;
+    const byName = new Map((tProps ?? []).map(p => [p.name, p]));
+    return baseProps.map(prop => {
+      const t = byName.get(prop.name);
+      // Take the translated text, but never let it drop the prop's contract
+      // (type/default/required stay authoritative from the English doc).
+      return t ? {...prop, ...t, name: prop.name, type: prop.type} : prop;
+    });
+  };
+
+  const merged = {...docs, ...translation};
+
+  merged.props = overlayProps(docs.props, translation.props);
+
+  if (docs.components) {
+    const tByName = new Map(
+      (translation.components ?? []).map(c => [c.name, c]),
+    );
+    merged.components = docs.components.map(base => {
+      const t = tByName.get(base.name);
+      if (!t) return base;
+      return {...base, ...t, props: overlayProps(base.props, t.props)};
+    });
+  }
+
+  return merged;
+}
+
 /**
  * Find the doc file for a component, checking both top-level
  * and nested directories. Prefers {Name}.doc.mjs, then README.md

package/src/lib/componentDocOverlay.test.mjs

@@ -0,0 +1,111 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Guards translated/compressed component docs against dropping props.
+ * @input packages/core/src/{Name}/{Name}.doc.mjs — its `docs`, `docsZh`, `docsDense`.
+ * @output Vitest failures naming every prop that exists in `docs` but vanishes
+ *   from a translated view.
+ * @position Regression gate for component-loader.mjs.
+ *
+ * A `docsZh` that carries its own `props` array used to REPLACE the base doc
+ * wholesale, so any prop the translation had not caught up with simply ceased
+ * to exist: `astryx component Button --zh` silently omitted `isInterruptible`
+ * and `isIconOnly`. A reader of the translated docs cannot discover a prop that
+ * is not there, and CLAUDE.md tells every AI agent to read these docs.
+ *
+ * Translations are now an overlay: a prop the translation does not cover falls
+ * back to its English entry rather than disappearing. Same principle as the
+ * reference-doc overlays in #2182 — an overlay covering a subset must not
+ * destroy what it does not cover.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {loadDocs} from './component-loader.mjs';
+
+const CORE_SRC = path.join(
+  import.meta.dirname,
+  '..',
+  '..',
+  '..',
+  'core',
+  'src',
+);
+
+/** Component dirs that ship a doc file. */
+function componentDocs() {
+  const out = [];
+  for (const dir of fs.readdirSync(CORE_SRC)) {
+    const docPath = path.join(CORE_SRC, dir, `${dir}.doc.mjs`);
+    if (!fs.existsSync(docPath)) continue;
+    if (!fs.readdirSync(path.join(CORE_SRC, dir)).includes(`${dir}.doc.mjs`)) {
+      continue; // case-exact match only
+    }
+    out.push({name: dir, docPath});
+  }
+  return out;
+}
+
+/** Prop names on a doc, across single- and multi-component shapes. */
+function propNames(doc) {
+  const names = new Set();
+  for (const p of doc?.props ?? []) names.add(p.name);
+  for (const c of doc?.components ?? []) {
+    for (const p of c.props ?? []) names.add(`${c.name ?? '?'}.${p.name}`);
+  }
+  return names;
+}
+
+describe('translated component docs never drop a prop', () => {
+  const comps = componentDocs();
+
+  it('finds component docs to check', () => {
+    expect(comps.length).toBeGreaterThan(0);
+  });
+
+  for (const {name, docPath} of comps) {
+    for (const locale of ['zh', 'dense']) {
+      it(`${name} --${locale}: documents every prop the English doc documents`, async () => {
+        const mod = await import(pathToFileURL(docPath).href);
+        const key = locale === 'zh' ? 'docsZh' : 'docsDense';
+        if (!mod[key]) return; // no overlay, nothing to drift
+
+        const english = propNames(mod.docs);
+        const translated = propNames(
+          await loadDocs(docPath, {[locale]: true}),
+        );
+
+        const dropped = [...english].filter(p => !translated.has(p));
+        expect(
+          dropped,
+          `${name}.doc.mjs ${key} drops ${dropped.length} prop(s) from the ` +
+            `--${locale} view: ${dropped.join(', ')}. A reader of the ` +
+            `translated docs cannot discover a prop that is not there. An ` +
+            `untranslated prop must fall back to its English entry, not vanish.`,
+        ).toEqual([]);
+      });
+    }
+  }
+});
+
+describe('the reported symptom', () => {
+  it('astryx component Button --zh still lists isInterruptible and isIconOnly', async () => {
+    const docPath = path.join(CORE_SRC, 'Button', 'Button.doc.mjs');
+    const zh = await loadDocs(docPath, {zh: true});
+    const names = propNames(zh);
+    expect(names.has('isInterruptible')).toBe(true);
+    expect(names.has('isIconOnly')).toBe(true);
+  });
+
+  it('keeps the translated descriptions it does have', async () => {
+    const docPath = path.join(CORE_SRC, 'Button', 'Button.doc.mjs');
+    const mod = await import(pathToFileURL(docPath).href);
+    const zh = await loadDocs(docPath, {zh: true});
+
+    const translated = mod.docsZh.props.find(p => p.name === 'variant');
+    const merged = zh.props.find(p => p.name === 'variant');
+    expect(merged.description).toBe(translated.description);
+  });
+});

package/src/lib/hook-format.mjs

@@ -11,6 +11,7 @@
 
 import {discoverHooks, findHookDoc} from './hook-discovery.mjs';
 import {loadDocs} from './component-loader.mjs';
+import {mdCell} from './component-format.mjs';
 
 /**
  * Build a signature string from hook docs.
@@ -51,9 +52,11 @@ function formatParamsTable(params) {
   lines.push('| Param | Type | Default | Description |');
   lines.push('|-------|------|---------|-------------|');
   for (const p of params) {
-    const def = p.default ? `\`${p.default}\`` : '\u2014';
+    const def = p.default ? `\`${mdCell(p.default)}\`` : '\u2014';
     const req = p.required ? ' **(required)**' : '';
-    lines.push(`| \`${p.name}\` | \`${p.type}\` | ${def} | ${p.description}${req} |`);
+    lines.push(
+      `| \`${mdCell(p.name)}\` | \`${mdCell(p.type)}\` | ${def} | ${mdCell(p.description)}${req} |`,
+    );
   }
   return lines.join('\n');
 }
@@ -67,7 +70,9 @@ function formatReturnsTable(returns) {
   lines.push('| Field | Type | Description |');
   lines.push('|-------|------|-------------|');
   for (const r of returns) {
-    lines.push(`| \`${r.name}\` | \`${r.type}\` | ${r.description} |`);
+    lines.push(
+      `| \`${mdCell(r.name)}\` | \`${mdCell(r.type)}\` | ${mdCell(r.description)} |`,
+    );
   }
   return lines.join('\n');
 }

package/templates/pages/ide/page.tsx

@@ -69,8 +69,8 @@ const styles: Record<string, CSSProperties> = {
   propertyActions: {
     marginTop: 'auto',
   },
-  terminalArea: {
-    height: '100%',
+  terminalPanel: {
+    flexShrink: 0,
     overflow: 'hidden',
   },
 };
@@ -301,46 +301,40 @@ export default function ResizableWorkspacePage() {
                           label="Resize terminal"
                         />
                         {!bottomPanel.isCollapsed && (
-                          <div
-                            style={{
-                              height: bottomPanel.size,
-                              flexShrink: 0,
-                              overflow: 'hidden',
-                            }}>
-                            <Stack
-                              direction="vertical"
-                              style={styles.contentFill}>
-                              <TabList
-                                value={activeTermTab}
-                                onChange={val => setActiveTermTab(val)}
+                          <Stack
+                            direction="vertical"
+                            height={bottomPanel.size}
+                            style={styles.terminalPanel}>
+                            <TabList
+                              value={activeTermTab}
+                              onChange={val => setActiveTermTab(val)}
+                              size="sm"
+                              hasDivider={false}
+                              style={styles.tabListPadding}>
+                              <Tab label="Terminal" value="terminal" />
+                              <Tab label="Problems" value="problems" />
+                              <Tab label="Output" value="output" />
+                              <Tab label="Debug" value="debug" />
+                            </TabList>
+                            <StackItem
+                              size="fill"
+                              style={styles.terminalWrapper}>
+                              <CodeBlock
+                                code={TERMINAL_OUTPUT}
+                                language="bash"
+                                container="section"
+                                hasLanguageLabel={false}
+                                hasCopyButton={false}
                                 size="sm"
-                                hasDivider={false}
-                                style={styles.tabListPadding}>
-                                <Tab label="Terminal" value="terminal" />
-                                <Tab label="Problems" value="problems" />
-                                <Tab label="Output" value="output" />
-                                <Tab label="Debug" value="debug" />
-                              </TabList>
-                              <StackItem
-                                size="fill"
-                                style={styles.terminalWrapper}>
-                                <CodeBlock
-                                  code={TERMINAL_OUTPUT}
-                                  language="bash"
-                                  container="section"
-                                  hasLanguageLabel={false}
-                                  hasCopyButton={false}
-                                  size="sm"
-                                  style={{
-                                    width: '100%',
-                                    height: '100%',
-                                    borderWidth: 0,
-                                    borderRadius: 0,
-                                  }}
-                                />
-                              </StackItem>
-                            </Stack>
-                          </div>
+                                style={{
+                                  width: '100%',
+                                  height: '100%',
+                                  borderWidth: 0,
+                                  borderRadius: 0,
+                                }}
+                              />
+                            </StackItem>
+                          </Stack>
                         )}
                       </Stack>
                     </LayoutContent>