Skip to content

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.mjs
index 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.mjs
index 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.md
index 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 components
Before writing any UI code:
@@ -22,7 +22,7 @@ If a component prop does what you need, use it — never replicate with CSS/styl
No 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 category
pnpm exec xds component <Name> props, types, examples
pnpm 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.md
index 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 Pattern
Each component is imported from its own subpath:
diff --git a/packages/cli/src/commands/component/index.mjs b/packages/cli/src/commands/component/index.mjs
index 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 category
const 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.tsx
index 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.tsx
similarity index 93%
rename from packages/core/src/CodeBlock/XDSCode.tsx
rename to packages/core/src/Code/XDSCode.tsx
index 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.ts
index 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.ts
index 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.tsx
index 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.tsx
similarity index 100%
rename from packages/core/src/Stack/XDSHStack.test.tsx
rename to packages/core/src/HStack/XDSHStack.test.tsx
diff --git a/packages/core/src/Stack/XDSHStack.tsx b/packages/core/src/HStack/XDSHStack.tsx
similarity index 87%
rename from packages/core/src/Stack/XDSHStack.tsx
rename to packages/core/src/HStack/XDSHStack.tsx
index 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.ts
index 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.tsx
similarity index 100%
rename from packages/core/src/Text/XDSHeading.test.tsx
rename to packages/core/src/Heading/XDSHeading.test.tsx
diff --git a/packages/core/src/Text/XDSHeading.tsx b/packages/core/src/Heading/XDSHeading.tsx
similarity index 96%
rename from packages/core/src/Text/XDSHeading.tsx
rename to packages/core/src/Heading/XDSHeading.tsx
index 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.ts
index 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.tsx
index 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.ts
index 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.ts
index 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 convenience
export type {
diff --git a/packages/core/src/Stack/XDSVStack.test.tsx b/packages/core/src/VStack/XDSVStack.test.tsx
similarity index 100%
rename from packages/core/src/Stack/XDSVStack.test.tsx
rename to packages/core/src/VStack/XDSVStack.test.tsx
diff --git a/packages/core/src/Stack/XDSVStack.tsx b/packages/core/src/VStack/XDSVStack.tsx
similarity index 87%
rename from packages/core/src/Stack/XDSVStack.tsx
rename to packages/core/src/VStack/XDSVStack.tsx
index 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.ts
index 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';