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.mdindex 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.mdindex 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.mdindex 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 referencediff --git a/internal/vibe-tests/AGENTS.xds-tailwind.md b/internal/vibe-tests/AGENTS.xds-tailwind.mdindex 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, nestingdiff --git a/internal/vibe-tests/scripts/generate-skill-doc.sh b/internal/vibe-tests/scripts/generate-skill-doc.shold mode 100755new mode 100644index 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` prRun 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"# Tokensdiff --git a/packages/cli/docs/theme.md b/packages/cli/docs/theme.mdindex 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']` castdiff --git a/packages/cli/src/commands/agent-docs.mjs b/packages/cli/src/commands/agent-docs.mjsindex 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 placeholderreturn `${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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mdindex 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:```bashnpx xds component --list # browse all components by categorynpx 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 componentsnpx xds docs # principles and tokens reference```diff --git a/yarn.lock b/yarn.lockindex 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==