An open source design system that's fully customizable and agent ready
TypeScript
fix(cli): show import paths in component list for agent discoverability (#2634)
Cindy Zhanga8ec18c6cb57
diff --git a/.github/scripts/cli-json-smoke-test.mjs b/.github/scripts/cli-json-smoke-test.mjsindex 02b042ea2c..6418132bbc 100644--- a/.github/scripts/cli-json-smoke-test.mjs+++ b/.github/scripts/cli-json-smoke-test.mjs@@ -173,7 +173,7 @@ const listResult = run(['component', '--list']);const componentNames = listResult.stdout.split('\n').filter(line => /^\s+[A-Z]/.test(line))- .map(line => line.trim());+ .map(line => line.trim().split(/\s{2,}/)[0]);console.log(`\ndiscovered ${componentNames.length} components`);diff --git a/.github/scripts/cli-smoke-test.mjs b/.github/scripts/cli-smoke-test.mjsindex aea4fc1116..f16d87310c 100644--- a/.github/scripts/cli-smoke-test.mjs+++ b/.github/scripts/cli-smoke-test.mjs@@ -95,7 +95,7 @@ const listResult = run(['component', '--list']);const componentNames = listResult.stdout.split('\n').filter(line => /^\s+[A-Z]/.test(line))- .map(line => line.trim());+ .map(line => line.trim().split(/\s{2,}/)[0]);console.log(`discovered ${componentNames.length} components`);@@ -109,8 +109,8 @@ if (componentNames.length === 0) {// ---------------------------------------------------------------------------const categories = listResult.stdout.split('\n')- .filter(line => /^[A-Z].*:$/.test(line))- .map(line => line.replace(/:$/, ''));+ .filter(line => /^[A-Z].*\(group\)$/.test(line))+ .map(line => line.replace(/\s*\(group\)$/, ''));console.log(`discovered ${categories.length} categories: ${categories.join(', ')}`);diff --git a/apps/sandbox/.claude/CLAUDE.md b/apps/sandbox/.claude/CLAUDE.mdindex de01df92fb..c8db7a709e 100644--- a/apps/sandbox/.claude/CLAUDE.md+++ b/apps/sandbox/.claude/CLAUDE.md@@ -4,7 +4,7 @@ Project-specific guidance for AI coding agents.<!-- XDS:START -->-XDS v0.0.14 — 170 components+XDS v0.0.14 — 166 componentsBefore writing any UI code:@@ -22,7 +22,7 @@ If a component prop does what you need, use it — never replicate with CSS/stylNo magic values — run `pnpm exec xds docs tokens` for spacing/color/radius.To change accent/brand colors: `pnpm exec xds theme` — never override --xds-color-\* in :root.-pnpm exec xds component --list 170 components by category+pnpm exec xds component --list 166 components by categorypnpm exec xds component <Name> props, types, examplespnpm exec xds docs color Semantic color tokens for surfaces, text, icons...pnpm exec xds docs elevation Shadow tokens for visual elevation and inset st...diff --git a/internal/vibe-tests/environments/project-xds/README.md b/internal/vibe-tests/environments/project-xds/README.mdindex 7f2f41c4c2..32b32f33a7 100644--- a/internal/vibe-tests/environments/project-xds/README.md+++ b/internal/vibe-tests/environments/project-xds/README.md@@ -19,6 +19,29 @@ Components use:- StyleX (`@stylexjs/stylex`) for styling- React 19+## Styling with StyleX++Custom styles must use `stylex.create()` — plain objects are not valid:++```tsx+import stylex from '@stylexjs/stylex';++const styles = stylex.create({+ container: {+ padding: 16,+ backgroundColor: '#f5f5f5',+ },+});++// Apply to XDS components via the xstyle prop:+<XDSCard xstyle={styles.container}>...</XDSCard>++// Apply to HTML elements via stylex.props():+<div {...stylex.props(styles.container)}>...</div>+```++**Important:** Never pass plain `{padding: '16px'}` objects to `xstyle` — always use `stylex.create()`.+## Import PatternEach component is imported from its own subpath:diff --git a/packages/cli/src/commands/component/index.mjs b/packages/cli/src/commands/component/index.mjsindex 20f9ad8263..6244a69b57 100644--- a/packages/cli/src/commands/component/index.mjs+++ b/packages/cli/src/commands/component/index.mjs@@ -82,24 +82,32 @@ export function registerComponent(program) {switch (result.type) {case 'component.list': {- // --detail brief (default for list views) — names only.+ // --detail brief (default for list views) — names with import paths.if (options.category) {const [cat, comps] = Object.entries(result.data)[0];humanLog(`\n${cat}:`);- for (const comp of comps) humanLog(` ${comp}`);+ for (const comp of comps) {+ const importPath = resolveImportPath(coreDir, comp);+ humanLog(` ${comp} ← ${importPath}`);+ }humanLog('');} else {humanLog('');for (const [key, comps] of Object.entries(result.data)) {const isUngrouped = comps.length === 1 && comps[0] === key;if (isUngrouped) {- humanLog(key);+ const importPath = resolveImportPath(coreDir, key);+ humanLog(`${key} ← ${importPath}`);} else {- humanLog(key);- for (const comp of comps) humanLog(` ${comp}`);+ humanLog(`${key} (group)`);+ for (const comp of comps) {+ const importPath = resolveImportPath(coreDir, comp);+ humanLog(` ${comp} ← ${importPath}`);+ }}}humanLog('');+ humanLog(`Import from the path shown (e.g. import {XDSButton} from '@xds/core/Button')`);humanLog(`Usage: ${run} xds component <name>`);humanLog('');}@@ -114,13 +122,15 @@ export function registerComponent(program) {// Skip the synthetic group header when there's only one ungrouped categoryconst isUngrouped =entries.length === 1 && items.length === 1 && items[0]?.name === cat;- if (!isUngrouped) humanLog(cat);+ if (!isUngrouped) humanLog(`${cat} (group)`);for (const item of items) {+ const importHint = item.import ? ` ← ${item.import}` : '';const desc = item.description ? ` — ${item.description}` : '';- humanLog(` XDS${item.name}${desc}`);+ humanLog(` XDS${item.name}${importHint}${desc}`);}humanLog('');}+ humanLog(`Import from the path shown (e.g. import {XDSButton} from '@xds/core/Button')`);humanLog(`Usage: ${run} xds component <name>`);humanLog('');break;diff --git a/packages/core/src/AlertDialog/XDSAlertDialog.tsx b/packages/core/src/AlertDialog/XDSAlertDialog.tsxindex 3c5c911b1c..c8c2e05c19 100644--- a/packages/core/src/AlertDialog/XDSAlertDialog.tsx+++ b/packages/core/src/AlertDialog/XDSAlertDialog.tsx@@ -22,7 +22,7 @@ import {XDSLayout} from '../Layout/XDSLayout';import {XDSLayoutContent} from '../Layout/XDSLayoutContent';import {XDSLayoutFooter} from '../Layout/XDSLayoutFooter';import {XDSHStack} from '../Stack';-import {XDSHeading} from '../Text/XDSHeading';+import {XDSHeading} from '../Heading/XDSHeading';import {XDSText} from '../Text/XDSText';import {XDSButton, type XDSButtonVariant} from '../Button';import type {XDSBaseProps} from '../XDSBaseProps';diff --git a/packages/core/src/CodeBlock/XDSCode.tsx b/packages/core/src/Code/XDSCode.tsxsimilarity index 93%rename from packages/core/src/CodeBlock/XDSCode.tsxrename to packages/core/src/Code/XDSCode.tsxindex 7181b16026..ea3a507193 100644--- a/packages/core/src/CodeBlock/XDSCode.tsx+++ b/packages/core/src/Code/XDSCode.tsx@@ -6,10 +6,11 @@* @file XDSCode.tsx* @input Uses React, StyleX, theme tokens* @output Exports XDSCode component for inline code styling- * @position Core implementation; inline code display+ * @position Core implementation; lives in own Code/ dir, re-exported by CodeBlock/** SYNC: When modified, update:* - /packages/core/src/CodeBlock/index.ts (exports if types change)+ * - /packages/cli/templates/blocks/components/Code/ (showcase blocks)* - /packages/cli/templates/blocks/components/CodeBlock/ (showcase blocks)*/diff --git a/packages/core/src/Code/index.ts b/packages/core/src/Code/index.tsindex fa4e241cb5..9b1a3b58ee 100644--- a/packages/core/src/Code/index.ts+++ b/packages/core/src/Code/index.ts@@ -1,11 +1,10 @@// Copyright (c) Meta Platforms, Inc. and affiliates./**- * @file Convenience re-export for XDSCode- * @position Subpath export so `@xds/core/Code` resolves correctly- *- * XDSCode lives in the CodeBlock directory (shared code rendering internals),- * but agents and developers naturally expect `@xds/core/Code` to work.+ * @file index.ts+ * @input XDSCode component source+ * @output Exports XDSCode and its props type+ * @position Entry point for @xds/core/Code subpath export*/-export {XDSCode, type XDSCodeProps} from '../CodeBlock';+export {XDSCode, type XDSCodeProps} from './XDSCode';diff --git a/packages/core/src/CodeBlock/index.ts b/packages/core/src/CodeBlock/index.tsindex 3e54a6f497..7ccec2d3eb 100644--- a/packages/core/src/CodeBlock/index.ts+++ b/packages/core/src/CodeBlock/index.ts@@ -14,8 +14,8 @@export {XDSCodeBlock} from './XDSCodeBlock';export type {XDSCodeBlockProps} from './XDSCodeBlock';-export {XDSCode} from './XDSCode';-export type {XDSCodeProps} from './XDSCode';+export {XDSCode} from '../Code';+export type {XDSCodeProps} from '../Code';export {tokenize,diff --git a/packages/core/src/Dialog/XDSDialogHeader.tsx b/packages/core/src/Dialog/XDSDialogHeader.tsxindex 46517ec4ae..a795a6c7b7 100644--- a/packages/core/src/Dialog/XDSDialogHeader.tsx+++ b/packages/core/src/Dialog/XDSDialogHeader.tsx@@ -22,7 +22,7 @@ import {spacingVars, sizeVars, typeScaleVars} from '../theme/tokens.stylex';import {XDSLayoutHeader} from '../Layout/XDSLayoutHeader';import {XDSButton} from '../Button';import {XDSIcon} from '../Icon';-import {XDSHeading} from '../Text/XDSHeading';+import {XDSHeading} from '../Heading/XDSHeading';import {XDSText} from '../Text/XDSText';import type {XDSBaseProps} from '../XDSBaseProps';diff --git a/packages/core/src/Stack/XDSHStack.test.tsx b/packages/core/src/HStack/XDSHStack.test.tsxsimilarity index 100%rename from packages/core/src/Stack/XDSHStack.test.tsxrename to packages/core/src/HStack/XDSHStack.test.tsxdiff --git a/packages/core/src/Stack/XDSHStack.tsx b/packages/core/src/HStack/XDSHStack.tsxsimilarity index 87%rename from packages/core/src/Stack/XDSHStack.tsxrename to packages/core/src/HStack/XDSHStack.tsxindex 1c79ad8a4c..90edb2b697 100644--- a/packages/core/src/Stack/XDSHStack.tsx+++ b/packages/core/src/HStack/XDSHStack.tsx@@ -8,12 +8,15 @@** SYNC: When modified, update these files to stay in sync:* - /packages/core/src/Stack/Stack.doc.mjs- * - /packages/core/src/Stack/XDSHStack.test.tsx- * - /packages/cli/templates/blocks/components/Stack/ (showcase blocks)+ * - /packages/core/src/HStack/XDSHStack.test.tsx+ * - /packages/cli/templates/blocks/components/HStack/ (showcase blocks)*/-import {XDSStack, type XDSStackProps} from './XDSStack';-import type {StackCrossAlignment, StackMainAlignment} from './stack.stylex';+import {XDSStack, type XDSStackProps} from '../Stack/XDSStack';+import type {+ StackCrossAlignment,+ StackMainAlignment,+} from '../Stack/stack.stylex';export interface XDSHStackProps extends Omit<XDSStackProps,diff --git a/packages/core/src/HStack/index.ts b/packages/core/src/HStack/index.tsindex 47a52ff1e0..f9af7dc501 100644--- a/packages/core/src/HStack/index.ts+++ b/packages/core/src/HStack/index.ts@@ -1,8 +1,10 @@// Copyright (c) Meta Platforms, Inc. and affiliates./**- * @file Convenience re-export for XDSHStack- * @position Subpath export so `@xds/core/HStack` resolves correctly+ * @file index.ts+ * @input XDSHStack component source+ * @output Exports XDSHStack and its props type+ * @position Entry point for @xds/core/HStack subpath export*/-export {XDSHStack, type XDSHStackProps} from '../Stack';+export {XDSHStack, type XDSHStackProps} from './XDSHStack';diff --git a/packages/core/src/Text/XDSHeading.test.tsx b/packages/core/src/Heading/XDSHeading.test.tsxsimilarity index 100%rename from packages/core/src/Text/XDSHeading.test.tsxrename to packages/core/src/Heading/XDSHeading.test.tsxdiff --git a/packages/core/src/Text/XDSHeading.tsx b/packages/core/src/Heading/XDSHeading.tsxsimilarity index 96%rename from packages/core/src/Text/XDSHeading.tsxrename to packages/core/src/Heading/XDSHeading.tsxindex 9903c1375c..02acc0bef1 100644--- a/packages/core/src/Text/XDSHeading.tsx+++ b/packages/core/src/Heading/XDSHeading.tsx@@ -6,13 +6,14 @@* @file XDSHeading.tsx* @input Uses React, HTMLAttributes, ReactNode* @output Exports XDSHeading component, XDSHeadingProps, XDSHeadingLevel types- * @position Core implementation; consumed by index.ts, tested by XDSHeading.test.tsx+ * @position Core implementation; lives in own Heading/ dir, re-exported by Text/** SYNC: When modified, update these files to stay in sync:* - /packages/core/src/Text/Text.doc.mjs (props table, features, implementation notes)- * - /packages/core/src/Text/XDSHeading.test.tsx (tests for new/changed behavior)+ * - /packages/core/src/Heading/XDSHeading.test.tsx (tests for new/changed behavior)* - /packages/core/src/Text/index.ts (exports if types change)* - /apps/storybook/stories/Text.stories.tsx (storybook stories)+ * - /packages/cli/templates/blocks/components/Heading/ (showcase blocks)* - /packages/cli/templates/blocks/components/Text/ (showcase blocks)*/@@ -38,8 +39,8 @@ import {capsizeStyles,decorationStyles,truncationTooltipStyles,-} from './text.stylex';-import {useTruncation} from './useTruncation';+} from '../Text/text.stylex';+import {useTruncation} from '../Text/useTruncation';import type {LayerPlacement} from '../Layer';import {xdsClassName, mergeProps, mergeRefs} from '../utils';import type {XDSBaseProps} from '../XDSBaseProps';diff --git a/packages/core/src/Heading/index.ts b/packages/core/src/Heading/index.tsindex 9b96382b7d..c9ee781532 100644--- a/packages/core/src/Heading/index.ts+++ b/packages/core/src/Heading/index.ts@@ -1,11 +1,10 @@// Copyright (c) Meta Platforms, Inc. and affiliates./**- * @file Convenience re-export for XDSHeading- * @position Subpath export so `@xds/core/Heading` resolves correctly- *- * XDSHeading lives in the Text directory (shared typography internals),- * but agents and developers naturally expect `@xds/core/Heading` to work.+ * @file index.ts+ * @input XDSHeading component source+ * @output Exports XDSHeading and its props/types+ * @position Entry point for @xds/core/Heading subpath export*/export {@@ -13,4 +12,4 @@ export {type XDSHeadingProps,type XDSHeadingLevel,type XDSHeadingType,-} from '../Text';+} from './XDSHeading';diff --git a/packages/core/src/MobileNav/XDSMobileNav.tsx b/packages/core/src/MobileNav/XDSMobileNav.tsxindex cf311f7181..849e190609 100644--- a/packages/core/src/MobileNav/XDSMobileNav.tsx+++ b/packages/core/src/MobileNav/XDSMobileNav.tsx@@ -44,7 +44,7 @@ import {} from '../theme/tokens.stylex';import {XDSButton} from '../Button';import {XDSIcon} from '../Icon';-import {XDSHeading} from '../Text/XDSHeading';+import {XDSHeading} from '../Heading/XDSHeading';import {useXDSAppShellMobile} from '../AppShell/XDSAppShellMobileContext';import {xdsClassName, mergeProps, mergeRefs} from '../utils';import type {XDSBaseProps} from '../XDSBaseProps';diff --git a/packages/core/src/Stack/index.ts b/packages/core/src/Stack/index.tsindex e169329e64..aea5cc3958 100644--- a/packages/core/src/Stack/index.ts+++ b/packages/core/src/Stack/index.ts@@ -17,12 +17,10 @@ export type {StackAlignment,} from './XDSStack';-// Convenience wrappers-export {XDSHStack} from './XDSHStack';-export type {XDSHStackProps} from './XDSHStack';+// Convenience wrappers (re-exported from their own directories)+export {XDSHStack, type XDSHStackProps} from '../HStack';-export {XDSVStack} from './XDSVStack';-export type {XDSVStackProps} from './XDSVStack';+export {XDSVStack, type XDSVStackProps} from '../VStack';export {XDSStackItem} from './XDSStackItem';export type {XDSStackItemProps} from './XDSStackItem';diff --git a/packages/core/src/Text/index.ts b/packages/core/src/Text/index.tsindex 941fe43335..14e572a0f4 100644--- a/packages/core/src/Text/index.ts+++ b/packages/core/src/Text/index.ts@@ -18,7 +18,7 @@ export {type XDSHeadingProps,type XDSHeadingLevel,type XDSHeadingType,-} from './XDSHeading';+} from '../Heading';// Re-export shared types from theme for convenienceexport type {diff --git a/packages/core/src/Stack/XDSVStack.test.tsx b/packages/core/src/VStack/XDSVStack.test.tsxsimilarity index 100%rename from packages/core/src/Stack/XDSVStack.test.tsxrename to packages/core/src/VStack/XDSVStack.test.tsxdiff --git a/packages/core/src/Stack/XDSVStack.tsx b/packages/core/src/VStack/XDSVStack.tsxsimilarity index 87%rename from packages/core/src/Stack/XDSVStack.tsxrename to packages/core/src/VStack/XDSVStack.tsxindex f83d70dc12..0e7f549a2e 100644--- a/packages/core/src/Stack/XDSVStack.tsx+++ b/packages/core/src/VStack/XDSVStack.tsx@@ -8,12 +8,15 @@** SYNC: When modified, update these files to stay in sync:* - /packages/core/src/Stack/Stack.doc.mjs- * - /packages/core/src/Stack/XDSVStack.test.tsx- * - /packages/cli/templates/blocks/components/Stack/ (showcase blocks)+ * - /packages/core/src/VStack/XDSVStack.test.tsx+ * - /packages/cli/templates/blocks/components/VStack/ (showcase blocks)*/-import {XDSStack, type XDSStackProps} from './XDSStack';-import type {StackCrossAlignment, StackMainAlignment} from './stack.stylex';+import {XDSStack, type XDSStackProps} from '../Stack/XDSStack';+import type {+ StackCrossAlignment,+ StackMainAlignment,+} from '../Stack/stack.stylex';export interface XDSVStackProps extends Omit<XDSStackProps,diff --git a/packages/core/src/VStack/index.ts b/packages/core/src/VStack/index.tsindex e4d2d6255a..9706ed4412 100644--- a/packages/core/src/VStack/index.ts+++ b/packages/core/src/VStack/index.ts@@ -1,8 +1,10 @@// Copyright (c) Meta Platforms, Inc. and affiliates./**- * @file Convenience re-export for XDSVStack- * @position Subpath export so `@xds/core/VStack` resolves correctly+ * @file index.ts+ * @input XDSVStack component source+ * @output Exports XDSVStack and its props type+ * @position Entry point for @xds/core/VStack subpath export*/-export {XDSVStack, type XDSVStackProps} from '../Stack';+export {XDSVStack, type XDSVStackProps} from './XDSVStack';