An open source design system that's fully customizable and agent ready
TypeScript
refactor(cli): fold agent-docs into init, add --features flag (#639)
Joey10e85e6bd4a5
diff --git a/CLAUDE.md b/CLAUDE.mdindex fd46baac38..f2ba05b9e1 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -84,21 +84,3 @@ Look for `<!-- SYNC: ... -->` comments and `SYNC:` in file headers as reminders.- **`@example` code fences must use plain ` ``` `, not ` ```tsx `.**Storybook's autodocs parser doesn't handle language-tagged fences in JSDoc correctly — the code block won't render as a proper code block. Always use untagged fences in `@example` blocks.--<!-- XDS:START -->--[XDS v0.0.3]|IMPORTANT: Prefer retrieval-led reasoning. Run CLI to read docs before generating code.-|npx xds --detail compact component <Name> Docs (props, usage) — or --source for code-|npx xds component --list All components by category-|npx xds docs principles Design rules, anti-patterns, StyleX patterns-|npx xds docs tokens Token reference (spacing, color, radius, type)-|npx xds docs theme Theme system: XDSTheme, custom themes, overrides, nesting-|npx xds template <name> [path] Scaffold page (blank, table, login)-|npx xds swizzle <Name> --gap "<reason>" Copy component source for customization + file gap report-|npx xds gap-report --component <Name> --category <cat> --reason "<why>" File gap without swizzle-|npx xds upgrade Preview API migrations for your version-|npx xds upgrade --apply Apply codemods to update breaking API changes-|RULE: After bumping @xds/core version, ALWAYS run npx xds upgrade --apply to migrate breaking API changes.-|RULE: When swizzling to unblock yourself, ALWAYS use --gap to explain what capability was missing.--<!-- XDS:END -->diff --git a/apps/sandbox/README.md b/apps/sandbox/README.mdindex 7eb2867004..3dc9f25980 100644--- a/apps/sandbox/README.md+++ b/apps/sandbox/README.md@@ -12,12 +12,12 @@ Before writing any code, install dependencies:npm install```-This automatically generates `AGENTS.md` with the XDS component index via `xds agent-docs`. **Read `AGENTS.md` for all XDS component documentation** — it contains CLI commands to browse components, tokens, themes, and design rules.+This automatically generates `AGENTS.md` with the XDS component index via `xds init --features agents`. **Read `AGENTS.md` for all XDS component documentation** — it contains CLI commands to browse components, tokens, themes, and design rules.If `AGENTS.md` is missing, regenerate it:```bash-npx xds agent-docs+npx xds init --features agents```## How it worksdiff --git a/internal/vibe-tests/scripts/generate-skill-doc.sh b/internal/vibe-tests/scripts/generate-skill-doc.shindex a3d8af74e3..9203d204cb 100644--- a/internal/vibe-tests/scripts/generate-skill-doc.sh+++ b/internal/vibe-tests/scripts/generate-skill-doc.sh@@ -3,7 +3,7 @@# @position internal/vibe-tests/scripts/generate-skill-doc.sh## Generates a skill doc by combining CLI outputs:-# - agent-docs framing (AGENTS.md index)+# - init --features agents framing (AGENTS.md index)# - component list --detail brief (component catalog)# - docs principles (design rules)# - docs tokens (token reference)diff --git a/packages/cli/src/commands/init.mjs b/packages/cli/src/commands/init.mjsindex e929703545..179c6dc86e 100644--- a/packages/cli/src/commands/init.mjs+++ b/packages/cli/src/commands/init.mjs@@ -1,21 +1,25 @@/**- * @file init command — Interactive initialization wizard+ * @file init command — Interactive initialization wizard + feature installer*- * Orchestrates the full XDS setup flow using @clack/prompts:- * 1. Intro- * 2. Agent docs installation- * 3. Swizzle awareness- * 4. Template selection- * 5. Success outro+ * Interactive: `xds init` walks through all features+ * Non-interactive: `xds init --features agents,theme,template`+ * Re-runnable: safe to run multiple times, idempotent+ *+ * Features:+ * agents — Install AGENTS.md/CLAUDE.md cheat sheet for AI coding agents+ * theme — Scaffold a custom theme file+ * template — Copy a starter page template*/import * as p from '@clack/prompts';import * as path from 'node:path';import * as fs from 'node:fs';import {CLI_ROOT} from '../utils/paths.mjs';-import {installAgentDocs} from './agent-docs.mjs';+import {installAgentDocs, removeAgentDocs} from './agent-docs.mjs';import {listTemplates} from './template.mjs';+const VALID_FEATURES = ['agents', 'theme', 'template'];+function isCancel(value) {if (p.isCancel(value)) {p.cancel('Setup cancelled.');@@ -24,12 +28,155 @@ function isCancel(value) {return value;}+// ─── Feature: agents ─────────────────────────────────────────────────────────++function runAgents(targetDir, {interactive = true} = {}) {+ try {+ installAgentDocs(targetDir);+ if (interactive) {+ p.log.success('AI agent docs installed');+ } else {+ console.log('✓ AI agent docs installed');+ }+ } catch {+ const msg = 'Could not install agent docs. Try again with `npx xds init --features agents`.';+ if (interactive) {+ p.log.warning(msg);+ } else {+ console.error(msg);+ }+ }+}++// ─── Feature: theme ──────────────────────────────────────────────────────────++async function runTheme({interactive = true} = {}) {+ if (!interactive) {+ console.log('✓ Theme scaffolding requires interactive mode. Run `npx xds theme` instead.');+ return;+ }++ p.note(+ 'Create a custom theme with your brand colors.\n' ++ 'Run `npx xds theme` for the full theme wizard.\n' ++ 'Run `npx xds theme --list` to see existing themes.',+ 'Themes',+ );+}++// ─── Feature: template ───────────────────────────────────────────────────────++async function runTemplate(targetDir, {interactive = true, templateName} = {}) {+ const templates = listTemplates();+ if (templates.length === 0) return;++ if (!interactive) {+ if (!templateName) {+ console.log(`✓ Available templates: ${templates.join(', ')}. Use npx xds template <name> [path].`);+ return;+ }++ if (!templates.includes(templateName)) {+ console.error(`Error: Unknown template "${templateName}". Available: ${templates.join(', ')}`);+ return;+ }++ const outputDir = path.resolve(targetDir, `./src/pages/${templateName}`);+ const templateDir = path.join(CLI_ROOT, 'templates', templateName);+ fs.mkdirSync(outputDir, {recursive: true});++ const files = fs.readdirSync(templateDir);+ for (const file of files) {+ const srcPath = path.join(templateDir, file);+ if (fs.statSync(srcPath).isFile()) {+ fs.copyFileSync(srcPath, path.join(outputDir, file));+ }+ }+ console.log(`✓ Template created at ${path.relative(targetDir, outputDir)}/`);+ return;+ }++ const TEMPLATE_OPTIONS = [+ {value: 'skip', label: 'Skip — No template'},+ {value: 'blank', label: 'Blank Page — Minimal scaffold'},+ {value: 'table', label: 'Table Page — Data table with actions'},+ {value: 'login', label: 'Login Page — Auth form with inputs'},+ ];++ const templateChoice = isCancel(+ await p.select({+ message: 'Start with a page template?',+ options: TEMPLATE_OPTIONS,+ }),+ );++ if (templateChoice === 'skip') return;++ const targetPath = isCancel(+ await p.text({+ message: 'Where should the template be created?',+ initialValue: `./src/pages/${templateChoice}`,+ placeholder: `./src/pages/${templateChoice}`,+ }),+ );++ const outputDir = path.resolve(targetDir, targetPath);+ const templateDir = path.join(CLI_ROOT, 'templates', templateChoice);++ fs.mkdirSync(outputDir, {recursive: true});++ const files = fs.readdirSync(templateDir);+ for (const file of files) {+ const srcPath = path.join(templateDir, file);+ if (fs.statSync(srcPath).isFile()) {+ fs.copyFileSync(srcPath, path.join(outputDir, file));+ }+ }++ p.log.success(`Template created at ${path.relative(targetDir, outputDir)}/`);+}++// ─── Command ─────────────────────────────────────────────────────────────────+export function registerInit(program) {program.command('init')- .description('Interactive XDS initialization wizard')- .action(async () => {- // Step 1: Intro+ .description('Initialize XDS in your project')+ .option('--features <list>', 'Comma-separated features to install (agents, theme, template)')+ .option('--all', 'Install all features, no prompts')+ .option('--remove-agents', 'Remove AI agent docs from AGENTS.md/CLAUDE.md')+ .action(async (options) => {+ const targetDir = process.cwd();++ // Remove mode+ if (options.removeAgents) {+ removeAgentDocs(targetDir);+ console.log('✓ AI agent docs removed.');+ return;+ }++ // Non-interactive: --features or --all+ if (options.features || options.all) {+ const features = options.all+ ? VALID_FEATURES+ : options.features.split(',').map(f => f.trim().toLowerCase());++ const invalid = features.filter(f => !VALID_FEATURES.includes(f));+ if (invalid.length > 0) {+ console.error(`Error: Unknown features: ${invalid.join(', ')}`);+ console.error(`Valid features: ${VALID_FEATURES.join(', ')}`);+ process.exit(1);+ }++ for (const feature of features) {+ if (feature === 'agents') runAgents(targetDir, {interactive: false});+ if (feature === 'theme') await runTheme({interactive: false});+ if (feature === 'template') await runTemplate(targetDir, {interactive: false});+ }+ return;+ }++ // Interactive wizardp.intro('Welcome to XDS');p.note(@@ -37,81 +184,34 @@ export function registerInit(program) {'About',);- // Step 2: Agent Docs- const shouldInstallAgentDocs = isCancel(+ // Feature: agents+ const shouldInstallAgents = isCancel(await p.confirm({- message: 'Install AGENTS.md for AI coding agent support?',+ message: 'Install AI agent support? (adds XDS cheat sheet to AGENTS.md)',initialValue: true,}),);- if (shouldInstallAgentDocs) {+ if (shouldInstallAgents) {const s = p.spinner();s.start('Installing agent docs');- try {- installAgentDocs(process.cwd());- s.stop('Agent docs installed');- } catch {- s.stop('Agent docs installation failed');- p.log.warning(- 'Could not install agent docs. Run `npx xds agent-docs` later to retry.',- );- }+ runAgents(targetDir);+ s.stop('Done');}- // Step 3: Swizzle Awareness+ // Feature: swizzle awarenessp.note('You can customize any component with:\n npx xds swizzle XDSButton\n npx xds swizzle --list','Component Customization',);- // Step 4: Template Selection- const templates = listTemplates();-- if (templates.length > 0) {- const templateOptions = [- {value: 'skip', label: 'Skip — No template'},- {value: 'blank', label: 'Blank Page — Minimal scaffold'},- {value: 'table', label: 'Table Page — Data table with actions'},- {value: 'login', label: 'Login Page — Auth form with inputs'},- ];-- const templateChoice = isCancel(- await p.select({- message: 'Start with a page template?',- options: templateOptions,- }),- );-- if (templateChoice !== 'skip') {- const targetPath = isCancel(- await p.text({- message: 'Where should the template be created?',- initialValue: `./src/pages/${templateChoice}`,- placeholder: `./src/pages/${templateChoice}`,- }),- );-- const outputDir = path.resolve(process.cwd(), targetPath);- const templateDir = path.join(CLI_ROOT, 'templates', templateChoice);-- fs.mkdirSync(outputDir, {recursive: true});-- const files = fs.readdirSync(templateDir);- for (const file of files) {- const srcPath = path.join(templateDir, file);- if (fs.statSync(srcPath).isFile()) {- fs.copyFileSync(srcPath, path.join(outputDir, file));- }- }-- p.log.success(- `Template created at ${path.relative(process.cwd(), outputDir)}/`,- );- }- }+ // Feature: template+ await runTemplate(targetDir);++ // Feature: theme awareness+ await runTheme();- // Step 5: Success+ // Outrop.outro('XDS initialized!');console.log('');diff --git a/packages/cli/src/commands/upgrade.mjs b/packages/cli/src/commands/upgrade.mjsindex 1f8df12d5e..a565d82b4b 100644--- a/packages/cli/src/commands/upgrade.mjs+++ b/packages/cli/src/commands/upgrade.mjs@@ -155,7 +155,7 @@ export function registerUpgrade(program) {p.log.success('Agent docs updated to match new version.');} catch {p.log.warn(- 'Could not update agent docs. Run `npx xds agent-docs` to update manually.',+ 'Could not update agent docs. Run `npx xds init --features agents` to update manually.',);}}diff --git a/packages/cli/src/index.mjs b/packages/cli/src/index.mjsindex 7bcdeb642c..05deacb398 100644--- a/packages/cli/src/index.mjs+++ b/packages/cli/src/index.mjs@@ -35,7 +35,7 @@ const commands = [{name: 'component', path: './commands/component/index.mjs', register: 'registerComponent'},{name: 'docs', path: './commands/docs.mjs', register: 'registerDocs'},{name: 'swizzle', path: './commands/swizzle.mjs', register: 'registerSwizzle'},- {name: 'agent-docs', path: './commands/agent-docs.mjs', register: 'registerAgentDocs'},+ // agent-docs folded into init — functions still importable from agent-docs.mjs{name: 'template', path: './commands/template.mjs', register: 'registerTemplate'},{name: 'gap-report', path: './commands/gap-report.mjs', register: 'registerGapReport'},{name: 'upgrade', path: './commands/upgrade.mjs', register: 'registerUpgrade'},@@ -73,7 +73,7 @@ program│ npx xds --help See all commands ││ ││ Or run directly: │- │ npx xds agent-docs Install AI agent docs │+ │ npx xds init Setup + AI agent docs ││ npx xds component Browse component docs ││ npx xds docs Design system reference ││ npx xds swizzle Customize a component │diff --git a/packages/core/xds.md b/packages/core/xds.mdindex 0830358a3d..3fe6d7785f 100644--- a/packages/core/xds.md+++ b/packages/core/xds.md@@ -15,10 +15,10 @@ npx xds docs # principles and tokens reference### For AI-assisted development-Run `xds agent-docs` in your project to install the XDS component catalog into your AGENTS.md:+Run `xds init --features agents` in your project to install the XDS component catalog into your AGENTS.md:```bash-npx xds agent-docs+npx xds init --features agents```This adds an auto-generated component index that AI coding agents use to discover and correctly use XDS components. Re-run after updating XDS to keep the index current.