Skip to content

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

TypeScript

feat(cli): update agent-docs block, add CLAUDE.md support, remove theme command (#458)

Cindy Zhang7832288366a1
diff --git a/packages/cli/src/commands/agent-docs.mjs b/packages/cli/src/commands/agent-docs.mjs
index fe55c274b9..c95780738d 100644
--- a/packages/cli/src/commands/agent-docs.mjs
+++ b/packages/cli/src/commands/agent-docs.mjs
@@ -1,7 +1,7 @@
/**
- * @file agent-docs command — Install/update AGENTS.md
+ * @file agent-docs command — Install/update AGENTS.md and CLAUDE.md
*
- * Injects a compressed XDS component index into AGENTS.md.
+ * Injects a compressed XDS component index into AGENTS.md and/or CLAUDE.md.
* Component docs are served via `npx xds component <name>` instead of
* being copied into the project.
*/
@@ -11,12 +11,13 @@ import * as path from 'node:path';
import {findCoreDir, CLI_ROOT} from '../utils/paths.mjs';
const AGENTS_MD = 'AGENTS.md';
+const CLAUDE_MD = 'CLAUDE.md';
const XDS_MARKER_START = '<!-- XDS:START -->';
const XDS_MARKER_END = '<!-- XDS:END -->';
/**
- * Compressed index for AGENTS.md.
+ * Compressed index for agent docs.
* Directs agents to use CLI commands for retrieval.
*/
export function generateCompressedIndex(version) {
@@ -27,11 +28,8 @@ export function generateCompressedIndex(version) {
|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 swizzle <Name> Copy component source for customization
-|npx xds theme Scaffold a custom theme (interactive)
-|npx xds theme --list List existing themes in the project
|npx xds template <name> [path] Scaffold page (blank, table, login)
-|npx xds swizzle <Name> --gap "<reason>" Swizzle + file gap report
+|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
|RULE: When swizzling to unblock yourself, ALWAYS use --gap to explain what capability was missing.
${XDS_MARKER_END}`;
@@ -54,16 +52,18 @@ export function getXdsVersion(coreDir) {
}
/**
- * Inject or update XDS section in AGENTS.md.
+ * Inject or update XDS section in a file using XDS markers.
+ * If the file has existing markers, replaces the content between them.
+ * If the file exists without markers, appends the block.
+ * If createIfMissing is true and the file doesn't exist, creates it with a header.
+ *
+ * @returns {boolean} Whether the file was written
*/
-export function injectAgentsMd(targetDir, version) {
- const agentsPath = path.join(targetDir, AGENTS_MD);
- const compressedIndex = generateCompressedIndex(version);
-
+export function injectXdsBlock(filePath, compressedIndex, {createIfMissing = false, header = ''} = {}) {
let content = '';
- if (fs.existsSync(agentsPath)) {
- content = fs.readFileSync(agentsPath, 'utf-8');
+ if (fs.existsSync(filePath)) {
+ content = fs.readFileSync(filePath, 'utf-8');
const startIdx = content.indexOf(XDS_MARKER_START);
const endIdx = content.indexOf(XDS_MARKER_END);
@@ -76,44 +76,90 @@ export function injectAgentsMd(targetDir, version) {
} else {
content = content.trimEnd() + '\n\n' + compressedIndex + '\n';
}
+ } else if (createIfMissing) {
+ content = header ? header + '\n\n' + compressedIndex + '\n' : compressedIndex + '\n';
} else {
- content = `# AGENTS.md
+ return false;
+ }
+
+ fs.writeFileSync(filePath, content);
+ return true;
+}
+
+/**
+ * Inject or update XDS section in AGENTS.md.
+ * Always creates the file if it doesn't exist.
+ */
+export function injectAgentsMd(targetDir, version) {
+ const agentsPath = path.join(targetDir, AGENTS_MD);
+ const compressedIndex = generateCompressedIndex(version);
+ injectXdsBlock(agentsPath, compressedIndex, {
+ createIfMissing: true,
+ header: `# AGENTS.md\n\nProject-specific guidance for AI coding agents.`,
+ });
+}
+
+/**
+ * Inject or update XDS section in CLAUDE.md.
+ * Only injects if CLAUDE.md already exists.
+ *
+ * @returns {boolean} Whether the file was written
+ */
+export function injectClaudeMd(targetDir, version) {
+ const claudePath = path.join(targetDir, CLAUDE_MD);
+ const compressedIndex = generateCompressedIndex(version);
+ return injectXdsBlock(claudePath, compressedIndex);
+}
+
+/**
+ * Remove XDS section from a file.
+ * If the file becomes empty (only boilerplate header remains), deletes it.
+ *
+ * @returns {boolean} Whether the XDS section was found and removed
+ */
+export function removeXdsBlock(filePath, {deleteIfEmpty = false} = {}) {
+ if (!fs.existsSync(filePath)) return false;
+
+ let content = fs.readFileSync(filePath, 'utf-8');
+ const startIdx = content.indexOf(XDS_MARKER_START);
+ const endIdx = content.indexOf(XDS_MARKER_END);
-Project-specific guidance for AI coding agents.
+ if (startIdx === -1 || endIdx === -1) return false;
-${compressedIndex}
-`;
+ const before = content.slice(0, startIdx).trimEnd();
+ const after = content.slice(endIdx + XDS_MARKER_END.length).trimStart();
+ content = before + (after ? '\n\n' + after : '') + '\n';
+
+ if (deleteIfEmpty) {
+ const stripped = content.replace(/^#.*\n+.*guidance.*\n*/m, '').trim();
+ if (!stripped) {
+ fs.unlinkSync(filePath);
+ return true;
+ }
}
- fs.writeFileSync(agentsPath, content);
+ fs.writeFileSync(filePath, content);
+ return true;
}
/**
- * Remove XDS section from AGENTS.md.
+ * Remove XDS section from AGENTS.md and CLAUDE.md.
*/
export function removeAgentDocs(targetDir) {
const agentsPath = path.join(targetDir, AGENTS_MD);
+ const claudePath = path.join(targetDir, CLAUDE_MD);
- if (fs.existsSync(agentsPath)) {
- let content = fs.readFileSync(agentsPath, 'utf-8');
- const startIdx = content.indexOf(XDS_MARKER_START);
- const endIdx = content.indexOf(XDS_MARKER_END);
-
- if (startIdx !== -1 && endIdx !== -1) {
- const before = content.slice(0, startIdx).trimEnd();
- const after = content.slice(endIdx + XDS_MARKER_END.length).trimStart();
- content = before + (after ? '\n\n' + after : '') + '\n';
-
- const stripped = content.replace(/^#.*\n+.*guidance.*\n*/m, '').trim();
- if (!stripped) {
- fs.unlinkSync(agentsPath);
- console.log(`✓ Removed empty ${AGENTS_MD}`);
- } else {
- fs.writeFileSync(agentsPath, content);
- console.log(`✓ Removed XDS section from ${AGENTS_MD}`);
- }
+ if (removeXdsBlock(agentsPath, {deleteIfEmpty: true})) {
+ if (!fs.existsSync(agentsPath)) {
+ console.log(`✓ Removed empty ${AGENTS_MD}`);
+ } else {
+ console.log(`✓ Removed XDS section from ${AGENTS_MD}`);
}
}
+
+ if (removeXdsBlock(claudePath)) {
+ console.log(`✓ Removed XDS section from ${CLAUDE_MD}`);
+ }
}
/**
@@ -124,13 +170,14 @@ export function installAgentDocs(targetDir) {
const coreDir = findCoreDir(targetDir);
const version = getXdsVersion(coreDir);
injectAgentsMd(targetDir, version);
+ injectClaudeMd(targetDir, version);
}
export function registerAgentDocs(program) {
program
.command('agent-docs')
- .description('Install/update XDS component index in AGENTS.md')
- .option('--remove', 'Remove XDS section from AGENTS.md')
+ .description('Install/update XDS component index in AGENTS.md (and CLAUDE.md if present)')
+ .option('--remove', 'Remove XDS section from AGENTS.md and CLAUDE.md')
.action(options => {
const targetDir = process.cwd();
const coreDir = findCoreDir(targetDir);
@@ -148,11 +195,15 @@ export function registerAgentDocs(program) {
injectAgentsMd(targetDir, version);
console.log(`✓ Injected compressed index into ${AGENTS_MD}`);
+ if (injectClaudeMd(targetDir, version)) {
+ console.log(`✓ Injected compressed index into ${CLAUDE_MD}`);
+ }
+
console.log(`
✅ XDS agent docs installed!
Your AI coding agent will now:
- • See the XDS component index in AGENTS.md
+ • See the XDS component index in AGENTS.md${fs.existsSync(path.join(targetDir, CLAUDE_MD)) ? ' and CLAUDE.md' : ''}
• Run \`npx xds component <name>\` to read detailed docs
• Run \`npx xds docs principles\` for design principles
• Run \`npx xds docs tokens\` for design token reference
diff --git a/packages/cli/src/commands/agent-docs.test.mjs b/packages/cli/src/commands/agent-docs.test.mjs
index ba9a24d597..735fbe2bdf 100644
--- a/packages/cli/src/commands/agent-docs.test.mjs
+++ b/packages/cli/src/commands/agent-docs.test.mjs
@@ -6,7 +6,10 @@ import {
generateCompressedIndex,
getXdsVersion,
injectAgentsMd,
+ injectClaudeMd,
+ injectXdsBlock,
removeAgentDocs,
+ removeXdsBlock,
} from './agent-docs.mjs';
let tmpDir;
@@ -27,6 +30,11 @@ describe('generateCompressedIndex', () => {
expect(result).toContain('<!-- XDS:START -->');
expect(result).toContain('<!-- XDS:END -->');
});
+
+ it('does not include theme command references', () => {
+ const result = generateCompressedIndex('1.0.0');
+ expect(result).not.toContain('npx xds theme');
+ });
});
describe('getXdsVersion', () => {
@@ -42,6 +50,56 @@ describe('getXdsVersion', () => {
});
});
+describe('injectXdsBlock', () => {
+ it('injects into an existing file without markers', () => {
+ const filePath = path.join(tmpDir, 'test.md');
+ fs.writeFileSync(filePath, '# Existing content\n');
+
+ const result = injectXdsBlock(filePath, '<!-- XDS:START -->\nnew\n<!-- XDS:END -->');
+
+ expect(result).toBe(true);
+ const content = fs.readFileSync(filePath, 'utf-8');
+ expect(content).toContain('# Existing content');
+ expect(content).toContain('<!-- XDS:START -->');
+ });
+
+ it('replaces existing markers', () => {
+ const filePath = path.join(tmpDir, 'test.md');
+ fs.writeFileSync(filePath, 'before\n<!-- XDS:START -->\nold\n<!-- XDS:END -->\nafter\n');
+
+ injectXdsBlock(filePath, '<!-- XDS:START -->\nnew\n<!-- XDS:END -->');
+
+ const content = fs.readFileSync(filePath, 'utf-8');
+ expect(content).toContain('new');
+ expect(content).not.toContain('old');
+ expect(content).toContain('before');
+ expect(content).toContain('after');
+ });
+
+ it('returns false and does not create file when createIfMissing is false', () => {
+ const filePath = path.join(tmpDir, 'nonexistent.md');
+
+ const result = injectXdsBlock(filePath, '<!-- XDS:START -->\ncontent\n<!-- XDS:END -->');
+
+ expect(result).toBe(false);
+ expect(fs.existsSync(filePath)).toBe(false);
+ });
+
+ it('creates file when createIfMissing is true', () => {
+ const filePath = path.join(tmpDir, 'new.md');
+
+ const result = injectXdsBlock(filePath, '<!-- XDS:START -->\ncontent\n<!-- XDS:END -->', {
+ createIfMissing: true,
+ header: '# Header',
+ });
+
+ expect(result).toBe(true);
+ const content = fs.readFileSync(filePath, 'utf-8');
+ expect(content).toContain('# Header');
+ expect(content).toContain('<!-- XDS:START -->');
+ });
+});
+
describe('injectAgentsMd', () => {
it('creates new AGENTS.md when none exists', () => {
injectAgentsMd(tmpDir, '1.0.0');
@@ -91,6 +149,47 @@ Existing agent docs.
});
});
+describe('injectClaudeMd', () => {
+ it('injects into existing CLAUDE.md', () => {
+ fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude Config\n\nExisting rules.\n');
+
+ const result = injectClaudeMd(tmpDir, '1.0.0');
+
+ expect(result).toBe(true);
+ const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+ expect(content).toContain('# Claude Config');
+ expect(content).toContain('Existing rules.');
+ expect(content).toContain('<!-- XDS:START -->');
+ expect(content).toContain('[XDS v1.0.0]');
+ });
+
+ it('does not create CLAUDE.md when it does not exist', () => {
+ const result = injectClaudeMd(tmpDir, '1.0.0');
+
+ expect(result).toBe(false);
+ expect(fs.existsSync(path.join(tmpDir, 'CLAUDE.md'))).toBe(false);
+ });
+
+ it('updates existing markers in CLAUDE.md', () => {
+ const existing = `# Claude Config
+
+<!-- XDS:START -->
+old content
+<!-- XDS:END -->
+
+Other rules.
+`;
+ fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), existing);
+
+ injectClaudeMd(tmpDir, '2.0.0');
+
+ const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+ expect(content).toContain('[XDS v2.0.0]');
+ expect(content).not.toContain('old content');
+ expect(content).toContain('Other rules.');
+ });
+});
+
describe('removeAgentDocs', () => {
it('removes XDS section from AGENTS.md', () => {
const content = `# My Project
@@ -131,4 +230,23 @@ XDS index stuff
expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
});
+
+ it('removes XDS section from CLAUDE.md when present', () => {
+ fs.writeFileSync(
+ path.join(tmpDir, 'AGENTS.md'),
+ '# AGENTS.md\n\n<!-- XDS:START -->\nstuff\n<!-- XDS:END -->\n',
+ );
+ fs.writeFileSync(
+ path.join(tmpDir, 'CLAUDE.md'),
+ '# Claude\n\nRules.\n\n<!-- XDS:START -->\nstuff\n<!-- XDS:END -->\n\nMore rules.\n',
+ );
+ vi.spyOn(console, 'log').mockImplementation(() => {});
+
+ removeAgentDocs(tmpDir);
+
+ const claudeContent = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+ expect(claudeContent).toContain('Rules.');
+ expect(claudeContent).toContain('More rules.');
+ expect(claudeContent).not.toContain('<!-- XDS:START -->');
+ });
});
diff --git a/packages/cli/src/commands/init.mjs b/packages/cli/src/commands/init.mjs
index e132191e2d..e929703545 100644
--- a/packages/cli/src/commands/init.mjs
+++ b/packages/cli/src/commands/init.mjs
@@ -4,18 +4,16 @@
* Orchestrates the full XDS setup flow using @clack/prompts:
* 1. Intro
* 2. Agent docs installation
- * 3. Theme selection
- * 4. Swizzle awareness
- * 5. Template selection
- * 6. Success outro
+ * 3. Swizzle awareness
+ * 4. Template selection
+ * 5. Success outro
*/
import * as p from '@clack/prompts';
import * as path from 'node:path';
import * as fs from 'node:fs';
-import {findCoreDir, CLI_ROOT} from '../utils/paths.mjs';
+import {CLI_ROOT} from '../utils/paths.mjs';
import {installAgentDocs} from './agent-docs.mjs';
-import {discoverThemes, writeThemeConfig} from './theme.mjs';
import {listTemplates} from './template.mjs';
function isCancel(value) {
@@ -61,51 +59,13 @@ export function registerInit(program) {
}
}
- // Step 3: Theme Selection
- const coreDir = findCoreDir(process.cwd());
-
- if (coreDir) {
- const themes = discoverThemes(coreDir);
-
- if (themes.length > 0) {
- const themeOptions = [
- ...themes.map(t => ({
- value: t.exportName,
- label:
- t.name === 'default'
- ? 'Default — Blue accent, system fonts'
- : t.name === 'neutral'
- ? 'Neutral — Grayscale, shadcn-inspired'
- : t.name,
- })),
- {value: 'skip', label: 'Skip — Configure later'},
- ];
-
- const themeChoice = isCancel(
- await p.select({
- message: 'Choose a theme:',
- options: themeOptions,
- }),
- );
-
- if (themeChoice !== 'skip') {
- writeThemeConfig(process.cwd(), themeChoice);
- p.log.success(`Theme set to ${themeChoice}`);
- p.note(
- `import { XDSTheme, ${themeChoice} } from '@xds/core/theme';\n\n<XDSTheme theme={${themeChoice}}>\n {children}\n</XDSTheme>`,
- 'Add to your root layout',
- );
- }
- }
- }
-
- // Step 4: Swizzle Awareness
+ // Step 3: Swizzle Awareness
p.note(
'You can customize any component with:\n npx xds swizzle XDSButton\n npx xds swizzle --list',
'Component Customization',
);
- // Step 5: Template Selection
+ // Step 4: Template Selection
const templates = listTemplates();
if (templates.length > 0) {
@@ -151,7 +111,7 @@ export function registerInit(program) {
}
}
- // Step 6: Success
+ // Step 5: Success
p.outro('XDS initialized!');
console.log('');
diff --git a/packages/cli/src/index.mjs b/packages/cli/src/index.mjs
index ce7c6ed460..cdda8192e4 100644
--- a/packages/cli/src/index.mjs
+++ b/packages/cli/src/index.mjs
@@ -1,7 +1,7 @@
/**
* @file XDS CLI — Commander program setup
*
- * Registers all commands: init, swizzle, agent-docs, component, docs, template, theme.
+ * Registers all commands: init, swizzle, agent-docs, component, docs, template.
*/
import {Command} from 'commander';
@@ -11,7 +11,6 @@ import {registerAgentDocs} from './commands/agent-docs.mjs';
import {registerComponent} from './commands/component.mjs';
import {registerDocs} from './commands/docs.mjs';
import {registerTemplate} from './commands/template.mjs';
-import {registerTheme} from './commands/theme.mjs';
import {registerGapReport} from './commands/gap-report.mjs';
export const program = new Command();
@@ -31,7 +30,6 @@ registerDocs(program);
registerSwizzle(program);
registerAgentDocs(program);
registerTemplate(program);
-registerTheme(program);
registerGapReport(program);
// Hidden command used by package.json postinstall scripts
@@ -51,7 +49,6 @@ program
│ npx xds agent-docs Install AI agent docs │
│ npx xds component Browse component docs │
│ npx xds docs Design system reference │
- │ npx xds theme Apply a theme │
│ npx xds swizzle Customize a component │
│ npx xds template Add a page template │
│ │