Skip to content

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

TypeScript

refactor(cli): replace --compact/--brief with --detail flag (#634)

Joey8408a2874b7f
diff --git a/.claude/skills/writing-component-docs.md b/.claude/skills/writing-component-docs.md
index c6ba8e2d6f..f481e8b675 100644
--- a/.claude/skills/writing-component-docs.md
+++ b/.claude/skills/writing-component-docs.md
@@ -108,11 +108,12 @@ The CLI merges this onto `docs`: compressed descriptions replace English ones, b
## CLI Flags
```bash
-npx xds component Button # English docs (default)
-npx xds component Button --compact # Token-optimized format
-npx xds component Button --brief # Minimal one-line summary
-npx xds --lang zh component Button # Chinese prose, same structure
-npx xds --lang dense component Button # Compressed prose, same structure
+npx xds component Button # Full docs (default)
+npx xds --detail compact component Button # Token-optimized format
+npx xds --detail brief component Button # Minimal one-line summary
+npx xds --lang zh component Button # Chinese prose, same structure
+npx xds --lang dense component Button # Compressed prose, same structure
+npx xds --detail compact --lang dense component Button # Compact + compressed
```
-`--lang` controls which prose translation is used. `--compact`, `--brief`, `--full` control how much detail. They compose independently.
+`--lang` controls which prose translation is used. `--detail` controls how much detail (full, compact, brief). They compose independently.
diff --git a/CLAUDE.md b/CLAUDE.md
index cf0b31c7eb..fd46baac38 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -88,7 +88,7 @@ Look for `<!-- SYNC: ... -->` comments and `SYNC:` in file headers as reminders.
<!-- XDS:START -->
[XDS v0.0.3]|IMPORTANT: Prefer retrieval-led reasoning. Run CLI to read docs before generating code.
-|npx xds component <Name> --compact|--source Docs (props, usage) or source 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)
diff --git a/internal/vibe-tests/.generated/xds-tailwind-skill.md b/internal/vibe-tests/.generated/xds-tailwind-skill.md
index d1960406e8..83a9260487 100644
--- a/internal/vibe-tests/.generated/xds-tailwind-skill.md
+++ b/internal/vibe-tests/.generated/xds-tailwind-skill.md
@@ -30,7 +30,7 @@ import {XDSButton} from '@xds/core/Button';
Run these commands to get detailed docs on any component:
- `npx xds component <Name>` — full docs (props, usage, examples)
-- `npx xds component <Name> --compact` — condensed reference
+- `npx xds --detail compact component <Name>` — condensed reference
- `npx xds component --list` — all components by category
- `npx xds docs tokens` — token reference (spacing, color, radius)
- `npx xds docs theme` — theme system reference
diff --git a/internal/vibe-tests/AGENTS.xds-tailwind.md b/internal/vibe-tests/AGENTS.xds-tailwind.md
index e7716e9a3a..65374968c1 100644
--- a/internal/vibe-tests/AGENTS.xds-tailwind.md
+++ b/internal/vibe-tests/AGENTS.xds-tailwind.md
@@ -5,7 +5,7 @@ Project-specific guidance for AI coding agents.
<!-- XDS-TAILWIND:START -->
[XDS + Tailwind v0.0.1]|IMPORTANT: Prefer retrieval-led reasoning. Run CLI to read docs before generating code.
-|npx xds component <Name> --compact Docs (props, usage)
+|npx xds --detail compact component <Name> Docs (props, usage)
|npx xds component --list All components by category
|npx xds docs tokens Token reference (spacing, color, radius)
|npx xds docs theme Theme system: XDSTheme, custom themes, overrides, nesting
diff --git a/internal/vibe-tests/scripts/generate-skill-doc.sh b/internal/vibe-tests/scripts/generate-skill-doc.sh
old mode 100755
new mode 100644
index 1c5c79947c..a3d8af74e3
--- a/internal/vibe-tests/scripts/generate-skill-doc.sh
+++ b/internal/vibe-tests/scripts/generate-skill-doc.sh
@@ -4,7 +4,7 @@
#
# Generates a skill doc by combining CLI outputs:
# - agent-docs framing (AGENTS.md index)
-# - component --brief-all (component catalog)
+# - component list --detail brief (component catalog)
# - docs principles (design rules)
# - docs tokens (token reference)
# - docs theme (theme system)
@@ -39,7 +39,7 @@ React design system for building internal tools. All components use the `XDS` pr
Run these commands to get detailed docs on any component:
- `npx xds component <Name>` — full docs (props, usage, examples)
-- `npx xds component <Name> --compact` — condensed reference
+- `npx xds --detail compact component <Name>` — condensed reference
- `npx xds component --list` — all components by category
- `npx xds docs principles` — design rules and anti-patterns
- `npx xds docs tokens` — token reference (spacing, color, radius)
@@ -58,7 +58,7 @@ echo "## Component Catalog" >> "$OUT_FILE"
echo "" >> "$OUT_FILE"
echo "Brief summaries of all available components. Run \`npx xds component <Name>\` for full docs." >> "$OUT_FILE"
echo "" >> "$OUT_FILE"
-node "$CLI" component --brief-all 2>/dev/null >> "$OUT_FILE"
+node "$CLI" --detail brief component --list 2>/dev/null >> "$OUT_FILE"
echo "" >> "$OUT_FILE"
# Tokens
diff --git a/packages/cli/docs/theme.md b/packages/cli/docs/theme.md
index 1e16011f74..9bae511826 100644
--- a/packages/cli/docs/theme.md
+++ b/packages/cli/docs/theme.md
@@ -254,7 +254,7 @@ export const myTheme: Theme = {
| Text | `text` | `styles` (body, large, label, supporting, code) | Font, size, weight, color per type |
| Prose | `prose` | `base`, `styles` (p, ul, ol, li, blockquote, code, pre, hr, strong, em, a) | Prose element styling |
-Run `npx xds component <Name> --compact` to see a component's themeable slots.
+Run `npx xds --detail compact component <Name>` to see a component's themeable slots.
### The `as Theme['components']` cast
diff --git a/packages/cli/src/commands/agent-docs.mjs b/packages/cli/src/commands/agent-docs.mjs
index 8af808637d..00ad6ca072 100644
--- a/packages/cli/src/commands/agent-docs.mjs
+++ b/packages/cli/src/commands/agent-docs.mjs
@@ -26,7 +26,7 @@ export function generateCompressedIndex(version, {zh = false, lang} = {}) {
// For now, zh mode outputs the same English content as a placeholder
return `${XDS_MARKER_START}
[XDS v${version}]|IMPORTANT: Prefer retrieval-led reasoning. Run CLI to read docs before generating code.
-|npx xds component <Name> --compact|--source Docs (props, usage) or source 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)
diff --git a/packages/cli/src/commands/component/index.mjs b/packages/cli/src/commands/component/index.mjs
index 91ef1b4301..72caa62569 100644
--- a/packages/cli/src/commands/component/index.mjs
+++ b/packages/cli/src/commands/component/index.mjs
@@ -1,8 +1,7 @@
/**
* @file component command — List components and print component docs
*
- * Subcommands: list, search, metadata, props, examples, example, source
- * Global options: --detail brief|normal, --lang en|zh|dense
+ * Global options: --detail full|compact|brief, --lang en|zh|dense
*/
import * as fs from 'node:fs';
@@ -26,7 +25,6 @@ import {
cleanReadme,
extractCompact,
extractBrief,
- extractBriefAll,
ensureImportStatement,
extractProps,
} from '../../lib/component-legacy.mjs';
@@ -38,9 +36,6 @@ export function registerComponent(program) {
.description('List components or print component docs')
.option('--list', 'List all components grouped by category')
.option('--category <category>', 'List components in a specific category')
- .option('--compact', 'Token-optimized output for LLMs')
- .option('--brief', 'Minimal LLM output: signature + props + one example (~200 chars)')
- .option('--brief-all', 'Brief summaries of ALL components in one output')
.option('--props', 'Print only the props table')
.option('--source', 'Print component source code')
.action(async (name, options) => {
@@ -48,6 +43,14 @@ export function registerComponent(program) {
const zh = program.opts().zh || false;
const dense = program.opts().dense || false;
const lang = program.opts().lang || null;
+ const detail = program.opts().detail || 'full';
+
+ const validDetails = ['full', 'compact', 'brief'];
+ if (!validDetails.includes(detail)) {
+ console.error(`Error: Invalid --detail value "${detail}".`);
+ console.error(`Valid levels: ${validDetails.join(', ')}`);
+ process.exit(1);
+ }
if (!coreDir) {
console.error(
@@ -57,11 +60,6 @@ export function registerComponent(program) {
process.exit(1);
}
- if (options.briefAll) {
- console.log(await formatBriefAll(coreDir, {zh, lang}));
- return;
- }
-
if (options.category || options.list || !name) {
const components = discoverComponents(coreDir);
@@ -77,24 +75,49 @@ export function registerComponent(program) {
);
process.exit(1);
}
- console.log(`\n${match[0]}:`);
- for (const comp of match[1]) {
- console.log(` ${comp}`);
+
+ if (detail === 'brief') {
+ // Brief list: name + one-line description for each component
+ for (const comp of match[1]) {
+ const readme = findComponentReadme(coreDir, comp);
+ if (readme && readme.endsWith('.doc.mjs')) {
+ try {
+ const docs = await loadDocs(readme, {zh, lang});
+ const importHint = resolveImportPath(coreDir, comp);
+ console.log(formatBrief(docs, comp, importHint));
+ } catch {
+ console.log(` ${comp}`);
+ }
+ } else {
+ console.log(` ${comp}`);
+ }
+ }
+ } else {
+ console.log(`\n${match[0]}:`);
+ for (const comp of match[1]) {
+ console.log(` ${comp}`);
+ }
+ console.log('');
}
- console.log('');
return;
}
- console.log('');
- for (const [category, comps] of Object.entries(components)) {
- console.log(`${category}:`);
- for (const comp of comps) {
- console.log(` ${comp}`);
+ // --list or no name: show all components
+ if (detail === 'brief') {
+ // Brief list: brief summaries of ALL components
+ console.log(await formatBriefAll(coreDir, {zh, lang}));
+ } else {
+ console.log('');
+ for (const [category, comps] of Object.entries(components)) {
+ console.log(`${category}:`);
+ for (const comp of comps) {
+ console.log(` ${comp}`);
+ }
+ console.log('');
}
+ console.log('Usage: npx xds component <name>');
console.log('');
}
- console.log('Usage: npx xds component <name>');
- console.log('');
return;
}
@@ -147,9 +170,9 @@ export function registerComponent(program) {
const importHint = resolveImportPath(coreDir, resolvedName);
if (options.props) {
console.log(formatProps(docs, resolvedName));
- } else if (options.brief) {
+ } else if (detail === 'brief') {
console.log(formatBrief(docs, resolvedName, importHint));
- } else if (options.compact) {
+ } else if (detail === 'compact') {
console.log(formatCompact(docs, resolvedName, importHint));
} else {
console.log(formatFull(docs));
@@ -159,9 +182,9 @@ export function registerComponent(program) {
const content = fs.readFileSync(readmePath, 'utf-8');
if (options.props) {
console.log(extractProps(content, resolvedName));
- } else if (options.brief) {
+ } else if (detail === 'brief') {
console.log(extractBrief(content, resolvedName));
- } else if (options.compact) {
+ } else if (detail === 'compact') {
const compact = extractCompact(content, resolvedName);
console.log(ensureImportStatement(compact, resolvedName, coreDir));
} else {
@@ -177,5 +200,5 @@ export function registerComponent(program) {
export {discoverComponents, findComponentReadme, findComponentSource, resolveImportPath} from '../../lib/component-discovery.mjs';
export {loadDocs} from '../../lib/component-loader.mjs';
export {formatFull, formatCompact, formatBrief, formatProps, formatBriefAll} from '../../lib/component-format.mjs';
-export {cleanReadme, extractCompact, extractBrief, extractBriefAll, ensureImportStatement, extractProps} from '../../lib/component-legacy.mjs';
+export {cleanReadme, extractCompact, extractBrief, ensureImportStatement, extractProps} from '../../lib/component-legacy.mjs';
export {levenshteinDistance, findClosestComponents} from '../../lib/string-utils.mjs';
diff --git a/packages/cli/src/commands/theme.mjs b/packages/cli/src/commands/theme.mjs
index 77d807a99e..16cb2538fa 100644
--- a/packages/cli/src/commands/theme.mjs
+++ b/packages/cli/src/commands/theme.mjs
@@ -220,7 +220,7 @@ function generateThemeFile({name, exportName, colors, includeComponentOverrides,
// Each component reads its overrides from theme.components.<name>.
//
// To discover what's themeable for a component, run:
-// npx xds component <Name> --compact
+// npx xds --detail compact component <Name>
// and look for the "Theme Overrides" section.
// --- Button ---
diff --git a/packages/cli/src/index.mjs b/packages/cli/src/index.mjs
index fbc9d92cbc..7bcdeb642c 100644
--- a/packages/cli/src/index.mjs
+++ b/packages/cli/src/index.mjs
@@ -20,6 +20,7 @@ program
.option('--zh', 'Output docs in Chinese Simplified')
.option('--dense', 'Output docs in compressed dense format (token-efficient)')
.option('--lang <locale>', 'Output docs in specified language/format (en, zh, dense)')
+ .option('--detail <level>', 'Output detail level (full, compact, brief)', 'full')
.addHelpCommand('help', 'Show all commands')
.action(() => {
program.help();
diff --git a/packages/cli/src/lib/component-format.mjs b/packages/cli/src/lib/component-format.mjs
index 069515374e..949ca48225 100644
--- a/packages/cli/src/lib/component-format.mjs
+++ b/packages/cli/src/lib/component-format.mjs
@@ -162,7 +162,7 @@ export function formatCompact(docs, componentName, importHint) {
* Format a brief, LLM-optimized summary (replaces extractBrief).
*
* Format: component signature + key props + one usage example.
- * Targets ~200-400 chars per component (vs ~2-3KB for --compact).
+ * Targets ~200-400 chars per component (vs ~2-3KB for --detail compact).
*
* For multi-component docs, extracts the entry matching componentName.
*/
diff --git a/packages/cli/src/lib/component-legacy.mjs b/packages/cli/src/lib/component-legacy.mjs
index c1ef139879..38480d5952 100644
--- a/packages/cli/src/lib/component-legacy.mjs
+++ b/packages/cli/src/lib/component-legacy.mjs
@@ -168,7 +168,7 @@ export function extractCompact(content, componentName) {
* Extract a brief, LLM-optimized summary from a README.
*
* Format: component signature + key props + one usage example.
- * Targets ~200-400 chars per component (vs ~2-3KB for --compact).
+ * Targets ~200-400 chars per component (vs ~2-3KB for --detail compact).
*
* Example output:
* Button(variant: primary|secondary|ghost|destructive, size: sm|md|lg)
diff --git a/packages/core/xds.md b/packages/core/xds.md
index 4e6bf4e88e..0830358a3d 100644
--- a/packages/core/xds.md
+++ b/packages/core/xds.md
@@ -9,7 +9,7 @@ Use the XDS CLI for component docs, scaffolding, and tooling:
```bash
npx xds component --list # browse all components by category
npx xds component Button # full docs for a component
-npx xds component --brief-all # LLM-optimized summary of all components
+npx xds --detail brief component --list # brief summaries of all components
npx xds docs # principles and tokens reference
```
diff --git a/yarn.lock b/yarn.lock
index 1b5f3499b8..bd8afe58e1 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -2273,7 +2273,7 @@
"@tailwindcss/oxide-win32-arm64-msvc" "4.2.1"
"@tailwindcss/oxide-win32-x64-msvc" "4.2.1"
-"@tailwindcss/postcss@^4.2.1":
+"@tailwindcss/postcss@^4", "@tailwindcss/postcss@^4.2.1":
version "4.2.1"
resolved "https://registry.npmjs.org/@tailwindcss/postcss/-/postcss-4.2.1.tgz"
integrity sha512-OEwGIBnXnj7zJeonOh6ZG9woofIjGrd2BORfvE5p9USYKDCZoQmfqLcfNiRWoJlRWLdNPn2IgVZuWAOM4iTYMw==
@@ -5229,7 +5229,7 @@ symbol-tree@^3.2.4:
resolved "https://registry.npmjs.org/symbol-tree/-/symbol-tree-3.2.4.tgz"
integrity sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw==
[email protected], tailwindcss@^4.2.1:
[email protected], tailwindcss@^4, tailwindcss@^4.2.1:
version "4.2.1"
resolved "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.2.1.tgz"
integrity sha512-/tBrSQ36vCleJkAOsy9kbNTgaxvGbyOamC30PRePTQe/o1MFwEKHQk4Cn7BNGaPtjp+PuUrByJehM1hgxfq4sw==