@astryxdesign/cli 0.1.6 → 0.1.7-canary.04cd8f7

package/src/doc.test.mjs

@@ -0,0 +1,383 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+  createComponentDoc,
+  createFunctionDoc,
+  createDoc,
+  ComponentDocSchema,
+  ComponentDocKindSchema,
+  FunctionDocKindSchema,
+  GenericDocKindSchema,
+} from './doc.mjs';
+import {loadComponentDoc} from './lib/component-loader.mjs';
+
+// The factories are stamp-only (like createConfig / createBlockTemplate): they
+// inject a `type` discriminant and are otherwise identity, performing NO
+// runtime validation. Validation happens at the LOAD boundary
+// (loadComponentDoc runs the loaded value through ComponentDocSchema), so the
+// rejection cases assert the schema rejects rather than the factory throwing.
+
+const goodComponent = {
+  name: 'Widget',
+  displayName: 'Widget',
+  description: 'A small widget.',
+  props: [
+    {name: 'label', type: 'string', description: 'Visible label.', required: true},
+    {name: 'size', type: "'sm' | 'md'", description: 'Control size.', default: "'md'"},
+  ],
+};
+
+const goodFunction = {
+  name: 'useThing',
+  displayName: 'useThing',
+  description: 'A thing hook.',
+  params: [{name: 'input', type: 'string', description: 'The input.', required: true}],
+  returns: [{name: 'value', type: 'string', description: 'The result.'}],
+};
+
+const goodGeneric = {
+  name: 'Theming',
+  displayName: 'Theming',
+  description: 'How theming works.',
+};
+
+describe('doc factories (stamp-only)', () => {
+  it('createComponentDoc stamps type: component and is otherwise identity', () => {
+    const doc = createComponentDoc(goodComponent);
+    expect(doc.type).toBe('component');
+    const {type, ...rest} = doc;
+    expect(rest).toEqual(goodComponent);
+  });
+
+  it('createFunctionDoc stamps type: function and is otherwise identity', () => {
+    const doc = createFunctionDoc(goodFunction);
+    expect(doc.type).toBe('function');
+    const {type, ...rest} = doc;
+    expect(rest).toEqual(goodFunction);
+  });
+
+  it('createDoc stamps type: generic and is otherwise identity', () => {
+    const doc = createDoc(goodGeneric);
+    expect(doc.type).toBe('generic');
+    const {type, ...rest} = doc;
+    expect(rest).toEqual(goodGeneric);
+  });
+
+  it('does NOT validate — stamps invalid shapes unchanged', () => {
+    const bogus = {group: 'Buttons'}; // no name
+    expect(createComponentDoc(bogus)).toEqual({...bogus, type: 'component'});
+  });
+});
+
+describe('per-kind schemas (new stamped format)', () => {
+  it('ComponentDocKindSchema accepts a valid component doc', () => {
+    expect(() =>
+      ComponentDocKindSchema.parse(createComponentDoc(goodComponent)),
+    ).not.toThrow();
+  });
+
+  it('ComponentDocKindSchema rejects a missing name with a readable message', () => {
+    expect(() =>
+      ComponentDocKindSchema.parse({type: 'component', name: '', props: []}),
+    ).toThrow(/name is required/);
+  });
+
+  it('ComponentDocKindSchema rejects a prop missing its type with a readable message', () => {
+    expect(() =>
+      ComponentDocKindSchema.parse({
+        type: 'component',
+        name: 'Widget',
+        props: [{name: 'label', description: 'no type'}],
+      }),
+    ).toThrow(/type/);
+  });
+
+  it('ComponentDocKindSchema surfaces the custom message for an empty prop type', () => {
+    expect(() =>
+      ComponentDocKindSchema.parse({
+        type: 'component',
+        name: 'Widget',
+        props: [{name: 'label', type: '', description: 'empty type'}],
+      }),
+    ).toThrow(/prop type is required/);
+  });
+
+  it('FunctionDocKindSchema accepts a valid function doc', () => {
+    expect(() =>
+      FunctionDocKindSchema.parse(createFunctionDoc(goodFunction)),
+    ).not.toThrow();
+  });
+
+  it('FunctionDocKindSchema rejects a function doc missing returns', () => {
+    expect(() =>
+      FunctionDocKindSchema.parse({
+        type: 'function',
+        name: 'useThing',
+        params: [],
+      }),
+    ).toThrow();
+  });
+
+  it('GenericDocKindSchema accepts a valid generic doc', () => {
+    expect(() =>
+      GenericDocKindSchema.parse(createDoc(goodGeneric)),
+    ).not.toThrow();
+  });
+
+  it('keeps nested rich blobs loose (usage/theming/playground passthrough)', () => {
+    const doc = createComponentDoc({
+      ...goodComponent,
+      usage: {description: 'Use it.', anatomy: [{name: 'root'}]},
+      theming: {targets: [{className: 'astryx-widget'}]},
+      playground: {defaults: {label: 'Hi'}},
+      examples: [{title: 'Basic', code: '<Widget />'}],
+    });
+    expect(() => ComponentDocKindSchema.parse(doc)).not.toThrow();
+  });
+
+  it('accepts parent + relatedDocs on the shared base', () => {
+    const doc = createComponentDoc({
+      ...goodComponent,
+      parent: 'WidgetGroup',
+      relatedDocs: ['Gauge', 'useThing'],
+      group: 'Widgets',
+    });
+    const parsed = ComponentDocKindSchema.parse(doc);
+    expect(parsed.parent).toBe('WidgetGroup');
+    expect(parsed.relatedDocs).toEqual(['Gauge', 'useThing']);
+  });
+});
+
+describe('ComponentDocSchema (load-boundary, both formats)', () => {
+  it('accepts a stamped component doc via the per-kind schema', () => {
+    expect(() =>
+      ComponentDocSchema.parse(createComponentDoc(goodComponent)),
+    ).not.toThrow();
+  });
+
+  it('accepts a stamped function doc', () => {
+    expect(() =>
+      ComponentDocSchema.parse(createFunctionDoc(goodFunction)),
+    ).not.toThrow();
+  });
+
+  it('accepts a stamped generic doc', () => {
+    expect(() =>
+      ComponentDocSchema.parse(createDoc(goodGeneric)),
+    ).not.toThrow();
+  });
+
+  it('accepts the OLD loose single-component shape (no type)', () => {
+    expect(() => ComponentDocSchema.parse(goodComponent)).not.toThrow();
+  });
+
+  it('accepts the OLD loose multi-component shape (components[])', () => {
+    const multi = {
+      name: 'Table',
+      displayName: 'Table',
+      components: [{name: 'TableRow', displayName: 'Table Row', description: 'A row.'}],
+    };
+    expect(() => ComponentDocSchema.parse(multi)).not.toThrow();
+  });
+
+  it('accepts the OLD loose sub-component shape (subComponentOf)', () => {
+    const sub = {
+      name: 'GaugeItem',
+      subComponentOf: 'Gauge',
+      displayName: 'Gauge Item',
+      description: 'A gauge item.',
+      props: [{name: 'item', type: 'Item', description: 'The item.'}],
+    };
+    expect(() => ComponentDocSchema.parse(sub)).not.toThrow();
+  });
+
+  it('accepts the OLD loose standalone-hook shape (params + returns, no type)', () => {
+    const hook = {
+      name: 'useThing',
+      displayName: 'useThing',
+      params: [{name: 'q', type: 'string', description: 'query'}],
+      returns: [{name: 'value', type: 'boolean', description: 'match'}],
+    };
+    expect(() => ComponentDocSchema.parse(hook)).not.toThrow();
+  });
+
+  it('accepts BOTH parent and legacy subComponentOf', () => {
+    const withParent = {name: 'A', parent: 'B', props: []};
+    const withSubComponentOf = {
+      name: 'A',
+      subComponentOf: 'B',
+      description: 'sub',
+      props: [],
+    };
+    expect(() => ComponentDocSchema.parse(withParent)).not.toThrow();
+    expect(() => ComponentDocSchema.parse(withSubComponentOf)).not.toThrow();
+  });
+
+  it('accepts BOTH relatedDocs and legacy relatedComponents/relatedHooks', () => {
+    const legacy = {
+      name: 'useThing',
+      displayName: 'useThing',
+      params: [],
+      returns: [],
+      relatedComponents: ['Gauge'],
+      relatedHooks: ['useOther'],
+    };
+    const modern = {...goodComponent, relatedDocs: ['Gauge', 'useThing']};
+    expect(() => ComponentDocSchema.parse(legacy)).not.toThrow();
+    expect(() =>
+      ComponentDocSchema.parse(createComponentDoc(modern)),
+    ).not.toThrow();
+  });
+
+  it('passes through loose extras (usage, playground, theming, importPath, showcase)', () => {
+    const loose = {
+      ...goodComponent,
+      usage: {description: 'Use it wisely.'},
+      playground: {defaults: {label: 'Hi'}},
+      theming: {targets: [{className: 'astryx-widget'}]},
+      keywords: ['widget', 'thing'],
+      category: 'Content',
+      isHiddenFromOverview: true,
+      importPath: '@astryxdesign/core/Widget',
+      showcase: 'WidgetHero',
+    };
+    const parsed = ComponentDocSchema.parse(loose);
+    expect(parsed.importPath).toBe('@astryxdesign/core/Widget');
+    expect(parsed.showcase).toBe('WidgetHero');
+  });
+
+  it('rejects a doc with no name', () => {
+    expect(() => ComponentDocSchema.parse({props: []})).toThrow();
+  });
+
+  it('rejects an empty name with a readable message', () => {
+    expect(() => ComponentDocSchema.parse({name: '', props: []})).toThrow(
+      /name is required/,
+    );
+  });
+});
+
+describe('loadComponentDoc (load boundary)', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-doc-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, {recursive: true, force: true});
+  });
+
+  const docModule = () => JSON.stringify(path.resolve(import.meta.dirname, 'doc.mjs'));
+
+  it('loads a .doc.ts fixture via jiti (createComponentDoc default export)', async () => {
+    const file = path.join(tmpDir, 'Widget.doc.ts');
+    fs.writeFileSync(
+      file,
+      [
+        `import {createComponentDoc} from ${docModule()};`,
+        'export default createComponentDoc({',
+        "  name: 'Widget',",
+        "  displayName: 'Widget',",
+        "  description: 'A small widget.',",
+        '  props: [',
+        "    {name: 'label', type: 'string', description: 'Visible label.', required: true},",
+        '  ],',
+        '});',
+      ].join('\n'),
+    );
+    const docs = await loadComponentDoc(file);
+    expect(docs.type).toBe('component');
+    expect(docs.name).toBe('Widget');
+    expect(docs.props).toHaveLength(1);
+  });
+
+  it('loads a .doc.ts fixture via jiti (createFunctionDoc default export)', async () => {
+    const file = path.join(tmpDir, 'useThing.doc.ts');
+    fs.writeFileSync(
+      file,
+      [
+        `import {createFunctionDoc} from ${docModule()};`,
+        'export default createFunctionDoc({',
+        "  name: 'useThing',",
+        "  displayName: 'useThing',",
+        "  params: [{name: 'input', type: 'string', description: 'The input.'}],",
+        "  returns: [{name: 'value', type: 'string', description: 'The result.'}],",
+        '});',
+      ].join('\n'),
+    );
+    const docs = await loadComponentDoc(file);
+    expect(docs.type).toBe('function');
+    expect(docs.params).toHaveLength(1);
+    expect(docs.returns).toHaveLength(1);
+  });
+
+  it('loads a .doc.ts fixture via jiti (createDoc generic default export)', async () => {
+    const file = path.join(tmpDir, 'Theming.doc.ts');
+    fs.writeFileSync(
+      file,
+      [
+        `import {createDoc} from ${docModule()};`,
+        'export default createDoc({',
+        "  name: 'Theming',",
+        "  displayName: 'Theming',",
+        "  description: 'How theming works.',",
+        '});',
+      ].join('\n'),
+    );
+    const docs = await loadComponentDoc(file);
+    expect(docs.type).toBe('generic');
+    expect(docs.name).toBe('Theming');
+  });
+
+  it('REGRESSION: loads the OLD loose `export const docs = {}` format', async () => {
+    const file = path.join(tmpDir, 'Legacy.doc.mjs');
+    fs.writeFileSync(
+      file,
+      [
+        'export const docs = {',
+        "  name: 'Legacy',",
+        "  displayName: 'Legacy',",
+        "  description: 'A loose named-export doc.',",
+        "  relatedComponents: ['Gauge'],",
+        "  relatedHooks: ['useThing'],",
+        "  importPath: '@astryxdesign/core/Legacy',",
+        "  props: [{name: 'value', type: 'string', description: 'A value.'}],",
+        '};',
+      ].join('\n'),
+    );
+    const docs = await loadComponentDoc(file);
+    expect(docs.name).toBe('Legacy');
+    expect(docs.props[0].name).toBe('value');
+    expect(docs.relatedComponents).toEqual(['Gauge']);
+    expect(docs.importPath).toBe('@astryxdesign/core/Legacy');
+  });
+
+  it('REGRESSION: loads the OLD loose standalone-hook `docs` format', async () => {
+    const file = path.join(tmpDir, 'useLegacy.doc.mjs');
+    fs.writeFileSync(
+      file,
+      [
+        'export const docs = {',
+        "  name: 'useLegacy',",
+        "  displayName: 'useLegacy',",
+        "  params: [{name: 'q', type: 'string', description: 'query'}],",
+        "  returns: [{name: 'value', type: 'boolean', description: 'match'}],",
+        "  relatedHooks: ['useThing'],",
+        '};',
+      ].join('\n'),
+    );
+    const docs = await loadComponentDoc(file);
+    expect(docs.name).toBe('useLegacy');
+    expect(docs.returns[0].name).toBe('value');
+  });
+
+  it('throws a readable error for an invalid doc', async () => {
+    const file = path.join(tmpDir, 'Bad.doc.mjs');
+    fs.writeFileSync(file, 'export default {group: "Buttons"};\n');
+    await expect(loadComponentDoc(file)).rejects.toThrow(/is invalid|name/);
+  });
+});

package/src/index.mjs

@@ -12,7 +12,7 @@ import {fileURLToPath} from 'node:url';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {checkForUpdate} from './utils/update-check.mjs';
-import {getRunPrefix} from './utils/package-manager.mjs';
+import {getCliInvocation} from './utils/package-manager.mjs';
 import {API_VERSION, setJsonMode} from './lib/json.mjs';
 import {buildManifest} from './lib/manifest.mjs';
 import {cliError} from './lib/cli-error.mjs';
@@ -174,7 +174,7 @@ function fullCommandName(actionCommand) {
  *
  * If --json is set on a command that is not on the JSON_SUPPORTED allowlist,
  * emit a structured error envelope and exit 1 — without running the command's
- * action (so no filesystem mutations, no clack prompts, no spawned processes).
+ * action (so no filesystem mutations, no interactive prompts, no spawned processes).
  *
  * This is the single source of truth for "command does not support --json".
  * Individual commands should NOT re-check this; they may assume that if their
@@ -305,15 +305,14 @@ program
       console.log(`  ${c.name}${tag}`);
       if (c.description) console.log(`    ${c.description}`);
     }
-    console.log(`\nRun \`astryx manifest --json\` for the full structured manifest.\n`);
+    console.log(`\nRun \`${getCliInvocation()} manifest --json\` for the full structured manifest.\n`);
   });
 
 // Hidden command used by package.json postinstall scripts
 program
   .command('postinstall', {hidden: true})
   .action(() => {
-    const run = getRunPrefix();
-    const r = `${run} xds`;
+    const r = getCliInvocation();
     const pad = (s, len) => s + ' '.repeat(Math.max(0, len - s.length));
     const W = 49; // inner width of the box
     const line = (s) => `  │ ${pad(s, W)}│`;
@@ -323,7 +322,7 @@ ${line('')}
 ${line('  Design system installed!')}
 ${line('')}
 ${line('  Get started:')}
-${line(`    ${r} init          Interactive setup`)}
+${line(`    ${r} init          Setup + AI agent docs`)}
 ${line(`    ${r} --help        See all commands`)}
 ${line('')}
 ${line('  Or run directly:')}

package/src/integration.mjs

@@ -1,19 +1,8 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * Type-preserving helper for an Astryx integration manifest.
- *
- * This is an intentionally tiny runtime identity function: it returns its
- * argument unchanged. Its value is the exported TypeScript surface from
- * `@astryxdesign/cli/integration`, so manifests get editor/type feedback
- * without coupling to CLI internals. Validation is NOT performed here — it
- * happens at the load boundary (see `loadModuleWithSchema` +
- * `AstryxIntegrationSchema`).
- *
- * @template {import('./types/integration').AstryxIntegration} T
- * @param {T} integration
- * @returns {T}
+ * Re-export of the integration-authoring helper, which now lives in
+ * `@astryxdesign/core/authoring`. Kept here so existing
+ * `@astryxdesign/cli/integration` imports continue to work unchanged.
  */
-export function createIntegration(integration) {
-  return integration;
-}
+export {createIntegration} from '@astryxdesign/core/authoring';

package/src/lib/component-discovery.importpath.test.mjs

@@ -0,0 +1,59 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Verifies that `.ts`-authored sources (hooks and other functions) are
+ * found by `findComponentSource`, so `resolveImportPath` derives a
+ * tree-shakeable subpath instead of falling back to the bare package root.
+ *
+ * Runs against the real packages/core source, not mocks.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {
+  findComponentSource,
+  resolveImportPath,
+} from './component-discovery.mjs';
+import {findCoreDir} from '../utils/paths.mjs';
+
+describe('findComponentSource resolves .ts-authored sources', () => {
+  const coreDir = findCoreDir();
+
+  it('finds a hook authored as a .ts file (not just .tsx)', () => {
+    const src = findComponentSource(coreDir, 'useMediaQuery');
+    expect(src).toBeTruthy();
+    expect(src.endsWith('useMediaQuery.ts')).toBe(true);
+  });
+
+  it('still finds a component authored as .tsx', () => {
+    const src = findComponentSource(coreDir, 'Button');
+    expect(src).toBeTruthy();
+    expect(src.endsWith('.tsx')).toBe(true);
+  });
+});
+
+describe('resolveImportPath reproduces authored hook importPaths', () => {
+  const coreDir = findCoreDir();
+
+  // Representative sample of core hooks whose sources are `.ts` files. Before
+  // the `.ts` fix these fell back to bare `@astryxdesign/core`; the derived
+  // subpath must now match the value each hook's doc currently authors.
+  const cases = [
+    ['useMediaQuery', '@astryxdesign/core/hooks'],
+    ['useResizable', '@astryxdesign/core/Resizable'],
+    ['useTheme', '@astryxdesign/core/theme'],
+    ['useFocusTrap', '@astryxdesign/core/hooks'],
+    ['useOverflow', '@astryxdesign/core/hooks'],
+  ];
+
+  for (const [name, expected] of cases) {
+    it(`${name} derives ${expected}`, () => {
+      expect(resolveImportPath(coreDir, name)).toBe(expected);
+    });
+  }
+
+  it('never falls back to the bare package root for a .ts hook', () => {
+    for (const [name] of cases) {
+      expect(resolveImportPath(coreDir, name)).not.toBe('@astryxdesign/core');
+    }
+  });
+});

package/src/lib/component-discovery.mjs

@@ -273,14 +273,24 @@ export function findComponentReadme(coreDir, name) {
  * For "Button" finds src/Button/XDSButton.tsx
  * For "Layout" finds src/Layout/XDSLayout/XDSLayout.tsx
  * For "Card" finds src/Layout/Container/XDSCard.tsx (deep search fallback)
+ *
+ * Hooks and other functions are authored as `.ts` (e.g. `useMediaQuery.ts`,
+ * `useResizable.ts`), so `.ts` candidates are searched alongside `.tsx`. Without
+ * this, deriving the import path for a `.ts`-authored function falls back to the
+ * bare `@astryxdesign/core` root instead of its tree-shakeable subpath.
  */
 export function findComponentSource(coreDir, name) {
   const srcDir = path.join(coreDir, 'src');
-  // Try the prefixed form (`XDSButton.tsx`) first since that is the current
-  // on-disk convention, then the bare form (`Button.tsx`) that the Astryx-prefix
-  // migration (P4) renames to. Listing the prefixed name first keeps behavior
-  // identical until files are actually renamed.
-  const candidateFiles = [`XDS${name}.tsx`, `${name}.tsx`];
+  // Try the prefixed forms (`XDSButton.tsx`) first since that is the current
+  // on-disk convention, then the bare forms (`Button.tsx`) that the Astryx-prefix
+  // migration (P4) renames to. `.tsx` before `.ts` within each so a component's
+  // `.tsx` wins over a same-named `.ts` helper; `.ts` covers hooks/functions.
+  const candidateFiles = [
+    `XDS${name}.tsx`,
+    `${name}.tsx`,
+    `XDS${name}.ts`,
+    `${name}.ts`,
+  ];
 
   function searchDir(dirPath) {
     if (!fs.existsSync(dirPath)) return null;

package/src/lib/component-format.mjs

@@ -6,6 +6,7 @@
 
 import {discoverComponents, findComponentReadme, resolveImportPath} from './component-discovery.mjs';
 import {loadDocs} from './component-loader.mjs';
+import {getCliInvocation} from '../utils/package-manager.mjs';
 
 /**
  * Derive the `defineTheme` component-override key from a theming target.
@@ -34,15 +35,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');
 }
@@ -66,7 +82,7 @@ function formatSubComponent(comp) {
   if (table) {
     out.push(table + '\n');
   } else {
-    out.push(`See \`astryx component ${comp.name}\` for props and usage.\n`);
+    out.push(`See \`${getCliInvocation()} component ${comp.name}\` for props and usage.\n`);
   }
   return out;
 }
@@ -177,7 +193,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 +298,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 +396,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 +413,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 +452,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 {