Skip to content

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

TypeScript

feat(cli): add --brief and --brief-all flags for LLM-optimized docs (#254)

Cindy Zhangf3953990314b
diff --git a/packages/cli/src/commands/component.mjs b/packages/cli/src/commands/component.mjs
index 3f5ceedea7..f93b3accc4 100644
--- a/packages/cli/src/commands/component.mjs
+++ b/packages/cli/src/commands/component.mjs
@@ -397,6 +397,181 @@ export function findClosestComponents(name, components, maxDistance = 3) {
return matches;
}
+/**
+ * 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).
+ *
+ * Example output:
+ * Button(variant: primary|secondary|ghost|destructive, size: sm|md|lg)
+ * label: string (required) · isLoading isDisabled icon tooltip children
+ * <XDSButton variant="primary" onClick={fn}>Save</XDSButton>
+ */
+export function extractBrief(content, componentName) {
+ const displayName = componentName.startsWith('XDS')
+ ? componentName
+ : `XDS${componentName}`;
+
+ const lines = content.split('\n');
+
+ // 1. Extract first paragraph as description
+ let description = '';
+ for (let i = 0; i < lines.length; i++) {
+ const line = lines[i].trim();
+ if (line.startsWith('#')) continue;
+ if (line === '') continue;
+ if (line.startsWith('|') || line.startsWith('```')) break;
+ description = line;
+ break;
+ }
+
+ // 2. Extract props from the Props table
+ const props = [];
+ let inPropsTable = false;
+ let headerParsed = false;
+
+ for (const line of lines) {
+ if (/^#{2,3}\s+Props/.test(line)) {
+ inPropsTable = true;
+ headerParsed = false;
+ continue;
+ }
+ if (inPropsTable && /^#{2,3}\s+/.test(line) && !/Props/.test(line)) {
+ inPropsTable = false;
+ continue;
+ }
+ if (!inPropsTable) continue;
+
+ // Skip table header separator
+ if (/^\|\s*-/.test(line)) {
+ headerParsed = true;
+ continue;
+ }
+ // Skip the header row itself
+ if (!headerParsed && /^\|\s*Prop/.test(line)) continue;
+
+ // Parse prop row: | `name` | `type` | `default` | description |
+ const cells = line
+ .split('|')
+ .map(c => c.trim().replace(/`/g, ''))
+ .filter(Boolean);
+ if (cells.length >= 3) {
+ const name = cells[0];
+ const type = cells[1];
+ const defaultVal = cells[2] || '';
+ const desc = cells[3] || '';
+
+ // Skip internal/style props
+ if (['xstyle', 'data-testid', 'className', 'style'].includes(name))
+ continue;
+
+ props.push({name, type, defaultVal, desc});
+ }
+ }
+
+ // 3. Build signature line from variant/size/type/level props
+ const signatureProps = [];
+ const otherProps = [];
+
+ for (const prop of props) {
+ // Props with union types go in the signature
+ if (prop.type.includes('|') && !prop.type.includes('ReactNode')) {
+ const values = prop.type
+ .replace(/['"]/g, '')
+ .split('|')
+ .map(v => v.trim())
+ .join('|');
+ signatureProps.push(`${prop.name}: ${values}`);
+ } else if (prop.desc.includes('required') || prop.defaultVal === '—' || prop.defaultVal === '-') {
+ otherProps.unshift(`${prop.name}: ${prop.type.split('|')[0].trim()}`);
+ } else {
+ otherProps.push(prop.name);
+ }
+ }
+
+ // 4. Extract first code example
+ let example = '';
+ let inCode = false;
+ for (const line of lines) {
+ if (line.startsWith('```tsx') || line.startsWith('```jsx')) {
+ inCode = true;
+ continue;
+ }
+ if (inCode && line.startsWith('```')) {
+ break;
+ }
+ if (inCode) {
+ const trimmed = line.trim();
+ // Take the first substantial JSX line
+ if (trimmed.startsWith('<XDS') || trimmed.startsWith('<')) {
+ // Collect multi-line JSX
+ example = trimmed;
+ if (!trimmed.includes('/>') && !trimmed.includes('</')) {
+ // Multi-line — just take the opening tag
+ example = trimmed;
+ }
+ break;
+ }
+ }
+ }
+
+ // 5. Build output
+ const output = [];
+
+ // Signature line
+ const sigStr =
+ signatureProps.length > 0
+ ? `${displayName}(${signatureProps.join(', ')})`
+ : displayName;
+ output.push(sigStr);
+
+ // Description (shortened)
+ if (description) {
+ const shortDesc =
+ description.length > 80
+ ? description.slice(0, 77) + '...'
+ : description;
+ output.push(` ${shortDesc}`);
+ }
+
+ // Other props
+ if (otherProps.length > 0) {
+ output.push(` ${otherProps.join(' · ')}`);
+ }
+
+ // Example
+ if (example) {
+ output.push(` ${example}`);
+ }
+
+ return output.join('\n') + '\n';
+}
+
+/**
+ * Extract brief summaries for ALL components in one output.
+ * One read, zero round-trips — the LLM gets enough to use any component.
+ */
+export function extractBriefAll(coreDir) {
+ const components = discoverComponents(coreDir);
+ const output = [];
+
+ for (const [category, comps] of Object.entries(components)) {
+ output.push(`## ${category}\n`);
+ for (const comp of comps) {
+ const readmePath = findComponentReadme(coreDir, comp);
+ if (readmePath) {
+ const content = fs.readFileSync(readmePath, 'utf-8');
+ output.push(extractBrief(content, comp));
+ } else {
+ output.push(`XDS${comp}\n (no docs)\n`);
+ }
+ }
+ }
+
+ return output.join('\n');
+}
+
/**
* Extract only the Props section(s) from a README.
* Useful for quick reference and LLM context.
@@ -449,6 +624,8 @@ export function registerComponent(program) {
.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((name, options) => {
@@ -462,6 +639,11 @@ export function registerComponent(program) {
process.exit(1);
}
+ if (options.briefAll) {
+ console.log(extractBriefAll(coreDir));
+ return;
+ }
+
if (options.category || options.list || !name) {
const components = discoverComponents(coreDir);
@@ -546,6 +728,8 @@ export function registerComponent(program) {
if (options.props) {
console.log(extractProps(content, resolvedName));
+ } else if (options.brief) {
+ console.log(extractBrief(content, resolvedName));
} else if (options.compact) {
console.log(extractCompact(content, resolvedName));
} else {