Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(core): docs.mjs redirects to the CLI (converge agents on init) (#4207)

Joey7ceccc13d13c
diff --git a/packages/core/README.md b/packages/core/README.md
index ce84cf4327..7962582248 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -13,14 +13,16 @@ Core UI components, theme system, and utilities for the Astryx design system. Fo
## Component Docs
-Look up any component's full API (props, types, best practices, and theming):
+Look up any component's full API (props, variants, examples, best practices, and theming) via the Astryx CLI:
```bash
-node node_modules/@astryxdesign/core/docs.mjs Button # full docs for a component
-node node_modules/@astryxdesign/core/docs.mjs --list # list all components
-node node_modules/@astryxdesign/core/docs.mjs --list --brief # brief summaries
+npx @astryxdesign/cli init # one-time: writes the component guide into AGENTS.md / CLAUDE.md
+npx @astryxdesign/cli component Button # full docs for a component
+npx @astryxdesign/cli component --list # list all components
```
+> Use the scoped `@astryxdesign/cli` to run without installing; bare `npx astryx` only resolves once the CLI is a dependency.
+
## Page Layouts
Building a full page? Start with a template rather than composing from scratch.
diff --git a/packages/core/docs.mjs b/packages/core/docs.mjs
index 9dd0aa916a..2acf45df9b 100644
--- a/packages/core/docs.mjs
+++ b/packages/core/docs.mjs
@@ -1,472 +1,43 @@
-#!/usr/bin/env node
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file Lightweight XDS component docs — zero dependencies, ships with @astryxdesign/core.
+ * @file docs.mjs — Astryx component docs are served by the Astryx CLI.
*
- * Usage:
- * node node_modules/@astryxdesign/core/docs.mjs Button
- * node node_modules/@astryxdesign/core/docs.mjs --list
- * node node_modules/@astryxdesign/core/docs.mjs --list --brief
+ * Component docs (props, variants, examples), page templates, design rules, and
+ * tokens are provided by the Astryx CLI — always current and richer than a
+ * bundled snapshot. This script intentionally redirects there instead of
+ * printing docs, so agents and humans converge on the CLI + `init` (which writes
+ * the full guide into AGENTS.md / CLAUDE.md) rather than treating a static doc
+ * dump as the whole story.
+ *
+ * ==========================================================================
+ * AI AGENT: do NOT guess component APIs or hand-write CSS. Run:
+ * npx @astryxdesign/cli init
+ * Use the SCOPED name `@astryxdesign/cli` — bare `npx astryx` resolves to an
+ * unrelated package until the CLI is a dependency. Then, per component:
+ * npx @astryxdesign/cli component <Name>
+ * npx @astryxdesign/cli component --list
+ * ==========================================================================
*/
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import {fileURLToPath, pathToFileURL} from 'node:url';
-
-const coreDir = path.dirname(fileURLToPath(import.meta.url));
-const srcDir = path.join(coreDir, 'src');
-
-// ── Discovery ────────────────────────────────────────────────────────
-
-const CATEGORY_MAP = {
- AspectRatio: 'Layout', Center: 'Layout', CollapsibleGroup: 'Layout',
- Grid: 'Layout', Layout: 'Layout', Stack: 'Layout',
- Avatar: 'Display', Badge: 'Display', Divider: 'Display',
- Icon: 'Display', Skeleton: 'Display', Table: 'Display', Text: 'Display',
- CheckboxInput: 'Form', DateInput: 'Form', Field: 'Form',
- NumberInput: 'Form', RadioList: 'Form', Selector: 'Form',
- Slider: 'Form', Switch: 'Form', TextArea: 'Form', TextInput: 'Form',
- TimeInput: 'Form',
- Button: 'Action', CloseButton: 'Action', DropdownMenu: 'Action', Link: 'Action',
- TabList: 'Navigation', TopNav: 'Navigation',
- Calendar: 'Overlay', Dialog: 'Overlay', Layer: 'Overlay',
-};
-const CATEGORY_ORDER = ['Layout', 'Display', 'Form', 'Action', 'Navigation', 'Overlay', 'Other'];
-const SKIP = new Set(['theme', 'hooks', 'utils', '__tests__', 'node_modules']);
-
-function discoverDocs() {
- const results = [];
- if (!fs.existsSync(srcDir)) return results;
- for (const entry of fs.readdirSync(srcDir, {withFileTypes: true})) {
- if (!entry.isDirectory() || SKIP.has(entry.name)) continue;
- const docPath = findDocFile(entry.name);
- if (docPath) results.push({dir: entry.name, docPath});
- }
- return results;
-}
-
-function findDocFile(name) {
- const direct = path.join(srcDir, name, `${name}.doc.mjs`);
- if (fs.existsSync(direct)) return direct;
- const dir = path.join(srcDir, name);
- if (!fs.existsSync(dir)) return null;
- for (const sub of fs.readdirSync(dir, {withFileTypes: true})) {
- if (sub.isDirectory()) {
- const nested = path.join(dir, sub.name, `${sub.name}.doc.mjs`);
- if (fs.existsSync(nested)) return nested;
- }
- }
- return null;
-}
-
-function findDocByComponent(name) {
- let docPath = findDocFile(name);
- if (docPath) return docPath;
- for (const entry of fs.readdirSync(srcDir, {withFileTypes: true})) {
- if (!entry.isDirectory() || SKIP.has(entry.name)) continue;
- const nested = path.join(srcDir, entry.name, name, `${name}.doc.mjs`);
- if (fs.existsSync(nested)) return nested;
- }
- // Fuzzy: find XDS{Name}.tsx and use parent doc
- for (const entry of fs.readdirSync(srcDir, {withFileTypes: true})) {
- if (!entry.isDirectory() || SKIP.has(entry.name)) continue;
- const dir = path.join(srcDir, entry.name);
- if (hasXDSFile(dir, name)) {
- const doc = findDocInDir(dir);
- if (doc) return doc;
- }
- }
- return null;
-}
-
-function hasXDSFile(dir, name) {
- // Match the current `XDS{Name}.tsx` convention and the post-migration bare
- // `{Name}.tsx` form (XDS-prefix migration P2380608025, P4).
- const targets = [`XDS${name}.tsx`, `${name}.tsx`];
- try {
- for (const f of fs.readdirSync(dir, {withFileTypes: true})) {
- if (targets.includes(f.name)) return true;
- if (f.isDirectory() && hasXDSFile(path.join(dir, f.name), name)) return true;
- }
- } catch {}
- return false;
-}
-
-function findDocInDir(dir) {
- try {
- for (const f of fs.readdirSync(dir)) {
- if (f.endsWith('.doc.mjs')) return path.join(dir, f);
- }
- } catch {}
- return null;
-}
-
-// ── Loading ──────────────────────────────────────────────────────────
-
-async function loadDoc(docPath) {
- const mod = await import(pathToFileURL(docPath).href);
- return mod.docs;
-}
-
-// ── Example extraction ───────────────────────────────────────────────
-
-function extractExamples(docPath) {
- const dir = path.dirname(docPath);
- const examples = [];
- try {
- for (const file of fs.readdirSync(dir)) {
- if (!file.endsWith('.tsx') || file.includes('.test')) continue;
- const content = fs.readFileSync(path.join(dir, file), 'utf-8');
- const regex = /@example\s*\n\s*\*\s*```[\w]*\n([\s\S]*?)```/g;
- let match;
- while ((match = regex.exec(content)) !== null) {
- const code = match[1]
- .split('\n')
- .map(line => line.replace(/^\s*\*\s?/, ''))
- .join('\n')
- .trim();
- if (code.includes('declare module')) continue;
- if (code.includes('stylex.create') && !code.includes('XDS')) continue;
- if (code.length > 0) examples.push(code);
- }
- }
- } catch {}
- return examples;
-}
-
-// ── Formatting ───────────────────────────────────────────────────────
-
-function dataAttrForName(name) {
- return `data-${name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()}`;
-}
-
-function getTargetDataAttributes(target) {
- return [
- ...(target.visualProps || []).map(dataAttrForName),
- ...(target.states || []).map(dataAttrForName),
- ];
-}
-
-function formatPropsTable(props) {
- if (!props?.length) return '';
- const lines = ['| Prop | Type | Default | Description |', '|------|------|---------|-------------|'];
- for (const p of props) {
- const def = p.default ? `\`${p.default}\`` : '—';
- const req = p.required ? ' **(required)**' : '';
- lines.push(`| \`${p.name}\` | \`${p.type}\` | ${def} | ${p.description}${req} |`);
- }
- return lines.join('\n');
-}
-
-function formatFull(docs, docPath) {
- const s = [];
- s.push(`# ${docs.name}\n`);
- s.push((docs.usage?.description || '') + '\n');
-
- // Examples from @example JSDoc blocks in component source
- if (docPath) {
- const examples = extractExamples(docPath);
- if (examples.length) {
- s.push('## Example\n');
- s.push('```tsx');
- s.push(examples.join('\n\n'));
- s.push('```\n');
- }
- }
-
- if (docs.usage?.anatomy?.length) {
- s.push('## Anatomy\n');
- s.push('| Element | Required | Description |');
- s.push('|---------|----------|-------------|');
- for (const el of docs.usage.anatomy)
- s.push(`| ${el.name} | ${el.required ? 'Yes' : 'No'} | ${el.description} |`);
- s.push('');
- }
-
- if (docs.usage?.bestPractices?.length) {
- s.push('## Best Practices\n');
- for (const bp of docs.usage.bestPractices)
- s.push(`- ${bp.guidance ? '**Do:**' : "**Don't:**"} ${bp.description}`);
- s.push('');
- }
-
- if ('props' in docs) {
- s.push('## Props\n');
- s.push(formatPropsTable(docs.props) + '\n');
- }
-
- if ('components' in docs) {
- s.push('## Components\n');
- for (const comp of docs.components) {
- s.push(`### ${comp.name}\n`);
- s.push(comp.description + '\n');
- s.push(formatPropsTable(comp.props) + '\n');
- }
- }
-
- if (docs.theming?.targets?.length) {
- s.push('## Theming\n');
- s.push('| Component class | Preferred data attributes | Props | States |');
- s.push('|-----------------|---------------------------|-------|--------|');
- for (const t of docs.theming.targets) {
- const dataAttrs = getTargetDataAttributes(t);
- const attrs = dataAttrs.length ? dataAttrs.map(attr => `\`${attr}\``).join(', ') : '—';
- const variants = t.visualProps?.join(', ') || '—';
- const states = t.states?.join(', ') || '—';
- s.push(`| \`${t.className}\` | ${attrs} | ${variants} | ${states} |`);
- }
- s.push('');
- const publicVars = docs.theming.vars?.filter(v => !v.private && !v.derived) || [];
- if (publicVars.length) {
- s.push('| CSS Variable | Default | Description |');
- s.push('|-------------|---------|-------------|');
- for (const v of publicVars)
- s.push(`| \`${v.name}\` | \`${v.default}\` | ${v.description} |`);
- s.push('');
- }
- }
-
- return s.join('\n');
-}
-
-function formatBrief(docs) {
- const desc = docs.usage?.description || '';
- const short = desc.length > 80 ? desc.slice(0, 77) + '...' : desc;
- const props = docs.props || docs.components?.[0]?.props || [];
- const sig = props
- .filter(p => p.type.includes('|') && !p.type.includes('ReactNode'))
- .map(p => `${p.name}: ${p.type.replace(/['"]/g, '').split('|').map(v => v.trim()).join('|')}`)
- .join(', ');
- return sig ? `${docs.name}(${sig}) ${short}` : `${docs.name} ${short}`;
-}
-
-// ── Main ─────────────────────────────────────────────────────────────
-
-
-// ── Hook Support ─────────────────────────────────────────────────────
-
-const HOOK_CATEGORY_MAP = {
- useFocusTrap: 'Focus',
- useGridFocus: 'Focus',
- useListFocus: 'Focus',
- useMediaQuery: 'Media',
- useOverflow: 'Layout',
- useScrollOverflow: 'Layout',
- useScrollLock: 'Layout',
- useEntryAnimation: 'Animation',
- useStreamingText: 'Streaming',
- useImageMode: 'Media',
- useClickableContainer: 'Interaction',
- useInputContainer: 'Interaction',
-};
-const HOOK_CATEGORY_ORDER = ['Focus', 'Layout', 'Animation', 'Interaction', 'Media', 'Streaming', 'Other'];
-
-function discoverHookDocs() {
- const results = [];
- const hooksDir = path.join(srcDir, 'hooks');
- if (fs.existsSync(hooksDir)) {
- for (const file of fs.readdirSync(hooksDir)) {
- if (file.endsWith('.doc.mjs')) {
- results.push({name: file.replace('.doc.mjs', ''), docPath: path.join(hooksDir, file)});
- }
- }
- }
- // Also scan component directories for use*.doc.mjs
- if (fs.existsSync(srcDir)) {
- for (const entry of fs.readdirSync(srcDir, {withFileTypes: true})) {
- if (!entry.isDirectory() || SKIP.has(entry.name)) continue;
- const dir = path.join(srcDir, entry.name);
- try {
- for (const file of fs.readdirSync(dir)) {
- if (file.startsWith('use') && file.endsWith('.doc.mjs')) {
- results.push({name: file.replace('.doc.mjs', ''), docPath: path.join(dir, file)});
- }
- }
- } catch {}
- }
- }
- return results;
-}
-
-function findHookDocByName(hookName) {
- const normalized = hookName.replace(/^use/i, '');
- const hooksDir = path.join(srcDir, 'hooks');
-
- // Direct match in hooks/
- for (const variant of [hookName, `use${normalized}`, `useXDS${normalized}`]) {
- const p = path.join(hooksDir, `${variant}.doc.mjs`);
- if (fs.existsSync(p)) return p;
- }
-
- // Search component directories
- if (fs.existsSync(srcDir)) {
- for (const entry of fs.readdirSync(srcDir, {withFileTypes: true})) {
- if (!entry.isDirectory() || SKIP.has(entry.name)) continue;
- const dir = path.join(srcDir, entry.name);
- for (const variant of [hookName, `use${normalized}`, `useXDS${normalized}`]) {
- const p = path.join(dir, `${variant}.doc.mjs`);
- if (fs.existsSync(p)) return p;
- }
- }
- }
- return null;
-}
-
-function formatHookParamsTable(params) {
- if (!params?.length) return '';
- const lines = ['| Param | Type | Default | Description |', '|-------|------|---------|-------------|'];
- for (const p of params) {
- const def = p.default ? `\`${p.default}\`` : '\u2014';
- const req = p.required ? ' **(required)**' : '';
- lines.push(`| \`${p.name}\` | \`${p.type}\` | ${def} | ${p.description}${req} |`);
- }
- return lines.join('\n');
-}
-
-function formatHookReturnsTable(returns) {
- if (!returns?.length) return '';
- const lines = ['| Field | Type | Description |', '|-------|------|-------------|'];
- for (const r of returns) {
- lines.push(`| \`${r.name}\` | \`${r.type}\` | ${r.description} |`);
- }
- return lines.join('\n');
-}
-
-function formatHookFull(docs) {
- const s = [];
- s.push(`# ${docs.name}\n`);
- s.push((docs.usage?.description || '') + '\n');
-
- if (docs.params?.length) {
- s.push('## Parameters\n');
- s.push(formatHookParamsTable(docs.params) + '\n');
- }
-
- if (docs.returns?.length) {
- s.push('## Returns\n');
- s.push(formatHookReturnsTable(docs.returns) + '\n');
- }
-
- if (docs.usage?.bestPractices?.length) {
- s.push('## Best Practices\n');
- for (const bp of docs.usage.bestPractices)
- s.push(`- ${bp.guidance ? '**Do:**' : "**Don't:**"} ${bp.description}`);
- s.push('');
- }
-
- const refs = [];
- if (docs.relatedComponents?.length) refs.push(`Components: ${docs.relatedComponents.map(c => c).join(', ')}`);
- if (docs.relatedHooks?.length) refs.push(`Hooks: ${docs.relatedHooks.join(', ')}`);
- if (docs.importPath) refs.push(`Import: ${docs.importPath}`);
- if (refs.length) {
- s.push('## Related\n');
- for (const r of refs) s.push(r);
- s.push('');
- }
+const BANNER = `
+==========================================================================
+ Astryx component docs are served by the Astryx CLI (accurate + current).
+ Do not guess component APIs or hand-write CSS — set up first (one time):
- return s.join('\n');
-}
+ npx @astryxdesign/cli init
-function formatHookBrief(docs) {
- const desc = docs.usage?.description || '';
- const short = desc.length > 80 ? desc.slice(0, 77) + '...' : desc;
- const params = (docs.params || []).filter(p => p.required).map(p => `${p.name}: ${p.type}`).join(', ');
- const ret = (docs.returns || []).map(r => r.type).join(' | ');
- const sig = params ? `${docs.name}(${params})` : docs.name;
- return ret ? `${sig}: ${ret} ${short}` : `${sig} ${short}`;
-}
+ (Use the scoped name @astryxdesign/cli. Bare \`npx astryx\` resolves to an
+ unrelated package until the CLI is installed as a dependency.)
-// ── Main ─────────────────────────────────────────────────────────────
+ init writes the full component guide, page templates, design rules & tokens
+ into your AGENTS.md / CLAUDE.md. Then, for any component:
-const args = process.argv.slice(2);
-const isList = args.includes('--list');
-const isBrief = args.includes('--brief');
-const isHooks = args.includes('--hooks');
-const name = args.find(a => !a.startsWith('--'));
+ npx @astryxdesign/cli component <Name> # full props, variants, examples
+ npx @astryxdesign/cli component --list # every component
+ npx @astryxdesign/cli build "<what you're building>" # starter kit
+==========================================================================
+`;
-if (isHooks) {
- // Hook listing mode
- const hookDocs = discoverHookDocs();
- const grouped = {};
- for (const {name: hookName, docPath} of hookDocs) {
- const cat = HOOK_CATEGORY_MAP[hookName] || 'Other';
- if (!grouped[cat]) grouped[cat] = [];
- grouped[cat].push({name: hookName, docPath});
- }
- for (const cat of HOOK_CATEGORY_ORDER) {
- if (!grouped[cat]) continue;
- console.log(`\n${cat}:`);
- for (const {name: hookName, docPath} of grouped[cat]) {
- if (isBrief) {
- try {
- const d = await loadDoc(docPath);
- console.log(' ' + formatHookBrief(d));
- } catch {
- console.log(` ${hookName} (error loading docs)`);
- }
- } else {
- console.log(` ${hookName}`);
- }
- }
- }
-} else if (isList) {
- const docs = discoverDocs();
- const grouped = {};
- for (const {dir, docPath} of docs) {
- const cat = CATEGORY_MAP[dir] || 'Other';
- if (!grouped[cat]) grouped[cat] = [];
- grouped[cat].push({dir, docPath});
- }
- for (const cat of CATEGORY_ORDER) {
- if (!grouped[cat]) continue;
- console.log(`\n${cat}:`);
- for (const {dir, docPath} of grouped[cat]) {
- if (isBrief) {
- try {
- const d = await loadDoc(docPath);
- console.log(' ' + formatBrief(d));
- } catch {
- console.log(` ${dir} (error loading docs)`);
- }
- } else {
- console.log(` ${dir}`);
- }
- }
- }
-} else if (name) {
- // Try hook lookup first for names starting with 'use'
- if (name.startsWith('use') || name.startsWith('Use')) {
- const hookDocPath = findHookDocByName(name);
- if (hookDocPath) {
- const docs = await loadDoc(hookDocPath);
- console.log(formatHookFull(docs));
- } else {
- // Fall through to component lookup
- const docPath = findDocByComponent(name);
- if (!docPath) {
- console.error(`Hook or component "${name}" not found.`);
- console.error('Run with --list to see components, or --hooks to see hooks.');
- process.exit(1);
- }
- const docs = await loadDoc(docPath);
- console.log(formatFull(docs, docPath));
- }
- } else {
- const docPath = findDocByComponent(name);
- if (!docPath) {
- console.error(`Component "${name}" not found. Run with --list to see available components.`);
- process.exit(1);
- }
- const docs = await loadDoc(docPath);
- console.log(formatFull(docs, docPath));
- }
-} else {
- console.log('Usage:');
- console.log(' node docs.mjs <ComponentName> Show full component docs');
- console.log(' node docs.mjs <hookName> Show full hook docs');
- console.log(' node docs.mjs --list List all components');
- console.log(' node docs.mjs --list --brief List with brief descriptions');
- console.log(' node docs.mjs --hooks List all hooks');
- console.log(' node docs.mjs --hooks --brief List hooks with brief descriptions');
-}
+console.log(BANNER);
+process.exit(0);
diff --git a/packages/core/src/docs-script.test.mjs b/packages/core/src/docs-script.test.mjs
index c57694d27d..cd1e0a6dbd 100644
--- a/packages/core/src/docs-script.test.mjs
+++ b/packages/core/src/docs-script.test.mjs
@@ -3,12 +3,13 @@
/**
* @file Subprocess smoke tests for the zero-dependency docs script.
*
- * `docs.mjs` resolves the package directory from `import.meta.url`. Using
- * `new URL(...).pathname` there breaks on Windows (drive-letter paths come
- * back as `/D:/...`), which made `--list` print nothing and component
- * lookups crash with ENOENT. These tests spawn the script as a real
- * subprocess from a neutral cwd, so resolution can only come from the
- * module URL, and assert it finds the component catalog on every platform.
+ * `docs.mjs` no longer prints component docs itself — it intentionally
+ * redirects to the Astryx CLI (`npx @astryxdesign/cli init`) so agents and
+ * humans converge on the CLI + `init` rather than a stale bundled snapshot.
+ * These tests spawn the script as a real subprocess from a neutral cwd and
+ * assert that, regardless of the arguments passed, it prints the redirect
+ * banner and exits 0 instead of rendering a component catalog or per-component
+ * docs.
*/
import {describe, it, expect} from 'vitest';
@@ -29,22 +30,26 @@ function runDocs(args) {
});
}
-describe('docs.mjs component discovery', () => {
- it('--list discovers the component catalog', () => {
+describe('docs.mjs redirects to the Astryx CLI', () => {
+ it('redirects to the CLI instead of printing a component catalog for --list', () => {
const r = runDocs(['--list']);
expect(r.error).toBeUndefined();
expect(r.signal).toBeNull();
expect(r.status).toBe(0);
- expect(r.stdout).toMatch(/\bButton\b/);
- expect(r.stdout).toMatch(/\bDialog\b/);
+ // Prints the redirect banner, not a component list.
+ expect(r.stdout).toMatch(/docs are served by the Astryx CLI/);
+ expect(r.stdout).toMatch(/npx @astryxdesign\/cli init/);
+ expect(r.stdout).toMatch(/npx @astryxdesign\/cli component --list/);
});
- it('renders docs for a single component', () => {
+ it('redirects to the CLI instead of rendering docs for a single component', () => {
const r = runDocs(['Button']);
expect(r.error).toBeUndefined();
expect(r.signal).toBeNull();
expect(r.status).toBe(0);
- expect(r.stdout).toMatch(/^# Button$/m);
- expect(r.stdout).toMatch(/## Props/);
+ // A pure redirect: it must not render the component's docs.
+ expect(r.stdout).not.toMatch(/^# Button$/m);
+ expect(r.stdout).not.toMatch(/## Props/);
+ expect(r.stdout).toMatch(/npx @astryxdesign\/cli component <Name>/);
});
});