Skip to content

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

TypeScript

fix(docs): remove source paths from READMEs and ensure CLI compact docs include imports (#310)

Cindy Zhanged71298cac56
diff --git a/packages/cli/src/commands/component.mjs b/packages/cli/src/commands/component.mjs
index 0e17458204..76f09522f6 100644
--- a/packages/cli/src/commands/component.mjs
+++ b/packages/cli/src/commands/component.mjs
@@ -411,7 +411,7 @@ export function findClosestComponents(name, components, maxDistance = 3) {
* label: string (required) · isLoading isDisabled icon tooltip children
* <XDSButton variant="primary" onClick={fn}>Save</XDSButton>
*/
-export function extractBrief(content, componentName) {
+export function extractBrief(content, componentName, importHint) {
const displayName = componentName.startsWith('XDS')
? componentName
: `XDS${componentName}`;
@@ -575,7 +575,7 @@ export function extractBrief(content, componentName) {
signatureProps.length > 0
? `${displayName}(${signatureProps.join(', ')})`
: displayName;
- output.push(sigStr);
+ output.push(importHint ? `${sigStr} ← from '${importHint}'` : sigStr);
// Description (shortened)
if (description) {
@@ -613,7 +613,8 @@ export function extractBriefAll(coreDir) {
const readmePath = findComponentReadme(coreDir, comp);
if (readmePath) {
const content = fs.readFileSync(readmePath, 'utf-8');
- output.push(extractBrief(content, comp));
+ const importPath = resolveImportPath(coreDir, comp);
+ output.push(extractBrief(content, comp, importPath));
} else {
output.push(`XDS${comp}\n (no docs)\n`);
}
@@ -623,6 +624,72 @@ export function extractBriefAll(coreDir) {
return output.join('\n');
}
+/**
+ * Resolve the import path for a component.
+ * Returns e.g. '@xds/core/Table' or '@xds/core' depending on package.json exports.
+ */
+export function resolveImportPath(coreDir, componentName) {
+ const srcDir = path.join(coreDir, 'src');
+ const sourcePath = findComponentSource(coreDir, componentName);
+ if (!sourcePath) return '@xds/core';
+
+ // Get the top-level directory under src/ from the source path
+ const relToSrc = path.relative(srcDir, sourcePath);
+ const topDir = relToSrc.split(path.sep)[0];
+
+ // Check package.json exports for ./${topDir}
+ const pkgPath = path.join(coreDir, 'package.json');
+ if (fs.existsSync(pkgPath)) {
+ const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+ if (pkg.exports && pkg.exports[`./${topDir}`]) {
+ return `@xds/core/${topDir}`;
+ }
+ }
+
+ return '@xds/core';
+}
+
+/**
+ * Ensure compact output includes an import statement.
+ * If the output already contains `from '@xds/core`, returns as-is.
+ * Otherwise, injects an ## Import section after the title/description,
+ * before the first ## section.
+ */
+export function ensureImportStatement(compactOutput, componentName, coreDir) {
+ // Already has an Import section — return as-is
+ if (/^## Import$/m.test(compactOutput)) {
+ return compactOutput;
+ }
+
+ const displayName = componentName.startsWith('XDS')
+ ? componentName
+ : `XDS${componentName}`;
+
+ const importPath = resolveImportPath(coreDir, componentName);
+ const importBlock = `## Import\n\n\`\`\`tsx\nimport { ${displayName} } from '${importPath}';\n\`\`\`\n`;
+
+ // Find the first ## section and inject before it
+ const lines = compactOutput.split('\n');
+ const output = [];
+ let injected = false;
+
+ for (let i = 0; i < lines.length; i++) {
+ if (!injected && lines[i].startsWith('## ')) {
+ output.push(importBlock);
+ injected = true;
+ }
+ output.push(lines[i]);
+ }
+
+ // If no ## section found, append at the end
+ if (!injected) {
+ output.push('');
+ output.push(importBlock);
+ }
+
+ return output.join('\n');
+}
+
/**
* Extract only the Props section(s) from a README.
* Useful for quick reference and LLM context.
@@ -782,7 +849,8 @@ export function registerComponent(program) {
} else if (options.brief) {
console.log(extractBrief(content, resolvedName));
} else if (options.compact) {
- console.log(extractCompact(content, resolvedName));
+ const compact = extractCompact(content, resolvedName);
+ console.log(ensureImportStatement(compact, resolvedName, coreDir));
} else {
console.log(cleanReadme(content, resolvedName));
}
diff --git a/packages/core/src/AppShell/README.md b/packages/core/src/AppShell/README.md
index 0258a61f93..9f06c5c1d4 100644
--- a/packages/core/src/AppShell/README.md
+++ b/packages/core/src/AppShell/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/AppShell
+# AppShell
Application-level layout shell component.
diff --git a/packages/core/src/Avatar/README.md b/packages/core/src/Avatar/README.md
index e1b516b190..363716e836 100644
--- a/packages/core/src/Avatar/README.md
+++ b/packages/core/src/Avatar/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/Avatar
+# Avatar
Avatar component for displaying user profile pictures with fallback support.
diff --git a/packages/core/src/Button/README.md b/packages/core/src/Button/README.md
index a9b084ee70..76b6190216 100644
--- a/packages/core/src/Button/README.md
+++ b/packages/core/src/Button/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/Button
+# Button
XDSButton component with multiple variants, sizes, and isLoading state support.
diff --git a/packages/core/src/Calendar/README.md b/packages/core/src/Calendar/README.md
index 7df7ce42fc..ab8da5fd70 100644
--- a/packages/core/src/Calendar/README.md
+++ b/packages/core/src/Calendar/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/Calendar
+# Calendar
XDSCalendar component for date selection with single and range modes.
diff --git a/packages/core/src/Card/README.md b/packages/core/src/Card/README.md
index a8981275c8..1dae5871e1 100644
--- a/packages/core/src/Card/README.md
+++ b/packages/core/src/Card/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/Card
+# Card
Card container component with elevation and themed styling.
diff --git a/packages/core/src/CheckboxInput/README.md b/packages/core/src/CheckboxInput/README.md
index 9a796d5622..b590ed4f53 100644
--- a/packages/core/src/CheckboxInput/README.md
+++ b/packages/core/src/CheckboxInput/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/CheckboxInput
+# CheckboxInput
A checkbox input component for toggling boolean values.
diff --git a/packages/core/src/Collapsible/README.md b/packages/core/src/Collapsible/README.md
index c501a9ff41..ff82c15d28 100644
--- a/packages/core/src/Collapsible/README.md
+++ b/packages/core/src/Collapsible/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/Collapsible
+# Collapsible
Collapsible content primitive and group coordination.
diff --git a/packages/core/src/DateInput/README.md b/packages/core/src/DateInput/README.md
index 535409d3c1..2d9c003e80 100644
--- a/packages/core/src/DateInput/README.md
+++ b/packages/core/src/DateInput/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/DateInput
+# DateInput
XDSDateInput component combining a text input with a calendar popover for date selection.
diff --git a/packages/core/src/Dialog/README.md b/packages/core/src/Dialog/README.md
index 00f05962bb..777fc052bb 100644
--- a/packages/core/src/Dialog/README.md
+++ b/packages/core/src/Dialog/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/Dialog
+# Dialog
XDSDialog component using the native `<dialog>` element for modal dialogs.
diff --git a/packages/core/src/DropdownMenu/README.md b/packages/core/src/DropdownMenu/README.md
index 5fb96f8897..1546742d9d 100644
--- a/packages/core/src/DropdownMenu/README.md
+++ b/packages/core/src/DropdownMenu/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/DropdownMenu
+# DropdownMenu
A dropdown menu component for displaying actionable items in a popup menu.
diff --git a/packages/core/src/Field/README.md b/packages/core/src/Field/README.md
index 9c0dd7e916..8b52b267e8 100644
--- a/packages/core/src/Field/README.md
+++ b/packages/core/src/Field/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/Field
+# Field
A form field wrapper component that provides label and description.
diff --git a/packages/core/src/Icon/README.md b/packages/core/src/Icon/README.md
index 767535fda0..f7ad785c62 100644
--- a/packages/core/src/Icon/README.md
+++ b/packages/core/src/Icon/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/Icon
+# Icon
Renders icons with XDS design system colors and sizes. Supports both direct SVG icon components and semantic icon names that adapt to the active theme.
diff --git a/packages/core/src/Layer/README.md b/packages/core/src/Layer/README.md
index cb6656bfa9..4e11873a05 100644
--- a/packages/core/src/Layer/README.md
+++ b/packages/core/src/Layer/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/Layer
+# Layer
Layer components for overlay content using modern browser APIs.
diff --git a/packages/core/src/Layout/README.md b/packages/core/src/Layout/README.md
index da104f0d81..c708666828 100644
--- a/packages/core/src/Layout/README.md
+++ b/packages/core/src/Layout/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/Layout
+# Layout
XDS Layout System - composable utilities and components for building structured layouts.
@@ -125,13 +125,13 @@ See [Container/README.md](./Container/README.md) for full documentation.
Use XDSLayout for page shells and app layouts — any UI with a header bar, sidebar navigation,
scrollable content area, or action footer. Don't use for simple stacking (use XDSVStack/XDSHStack).
-| Component | Description |
-| ------------------ | ------------------------------------------------------------------------- |
-| `XDSLayout` | Page shell with header, sidebar(s), content, and footer slots |
-| `XDSLayoutHeader` | Top bar — page titles, app bars, toolbars |
-| `XDSLayoutFooter` | Bottom bar — action bars, pagination, status bars |
-| `XDSLayoutContent` | Scrollable main content area |
-| `XDSLayoutPanel` | Sidebar — navigation panels, settings sidebars, detail/inspector panels |
+| Component | Description |
+| ------------------ | ----------------------------------------------------------------------- |
+| `XDSLayout` | Page shell with header, sidebar(s), content, and footer slots |
+| `XDSLayoutHeader` | Top bar — page titles, app bars, toolbars |
+| `XDSLayoutFooter` | Bottom bar — action bars, pagination, status bars |
+| `XDSLayoutContent` | Scrollable main content area |
+| `XDSLayoutPanel` | Sidebar — navigation panels, settings sidebars, detail/inspector panels |
See [XDSLayout/README.md](./XDSLayout/README.md) for full documentation.
diff --git a/packages/core/src/Link/README.md b/packages/core/src/Link/README.md
index 9daac5f99f..8e9790140e 100644
--- a/packages/core/src/Link/README.md
+++ b/packages/core/src/Link/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/Link
+# Link
XDSLink component for styled anchor links with multiple variants and features.
diff --git a/packages/core/src/NumberInput/README.md b/packages/core/src/NumberInput/README.md
index de9b39c3da..1c63d11f7c 100644
--- a/packages/core/src/NumberInput/README.md
+++ b/packages/core/src/NumberInput/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/NumberInput
+# NumberInput
A number input component for collecting numeric user input with validation.
diff --git a/packages/core/src/RadioList/README.md b/packages/core/src/RadioList/README.md
index 4beeab9906..063396dc6d 100644
--- a/packages/core/src/RadioList/README.md
+++ b/packages/core/src/RadioList/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/RadioList
+# RadioList
A radio group component for single-value selection from a list of options.
diff --git a/packages/core/src/Section/README.md b/packages/core/src/Section/README.md
index 4b40de5ee0..0eaa8d5365 100644
--- a/packages/core/src/Section/README.md
+++ b/packages/core/src/Section/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/Section
+# Section
Section container component with background variants.
diff --git a/packages/core/src/Skeleton/README.md b/packages/core/src/Skeleton/README.md
index de6e362b6e..3710a87f95 100644
--- a/packages/core/src/Skeleton/README.md
+++ b/packages/core/src/Skeleton/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/Skeleton
+# Skeleton
A placeholder loading component that displays an animated pulsing effect while content is loading.
diff --git a/packages/core/src/Slider/README.md b/packages/core/src/Slider/README.md
index 78f88e6c4d..ae05add1df 100644
--- a/packages/core/src/Slider/README.md
+++ b/packages/core/src/Slider/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/Slider
+# Slider
A slider component for selecting numeric values or ranges with full keyboard and pointer support.
diff --git a/packages/core/src/Spinner/README.md b/packages/core/src/Spinner/README.md
index 23ce7862e2..c3ee269865 100644
--- a/packages/core/src/Spinner/README.md
+++ b/packages/core/src/Spinner/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/Spinner
+# Spinner
A pure spinner component for indicating loading state. No layout, no text — just the spinning indicator.
diff --git a/packages/core/src/Stack/README.md b/packages/core/src/Stack/README.md
index fc49bcc2fd..7e3b31cdc9 100644
--- a/packages/core/src/Stack/README.md
+++ b/packages/core/src/Stack/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/Layout/Stack
+# Stack
Stack layout primitives for arranging items in horizontal or vertical sequences.
diff --git a/packages/core/src/Switch/README.md b/packages/core/src/Switch/README.md
index 444dca677a..4cf1a4c051 100644
--- a/packages/core/src/Switch/README.md
+++ b/packages/core/src/Switch/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/Switch
+# Switch
A toggle switch component for boolean values with integrated label support.
diff --git a/packages/core/src/TabList/README.md b/packages/core/src/TabList/README.md
index 044fedeab3..f4dca080dd 100644
--- a/packages/core/src/TabList/README.md
+++ b/packages/core/src/TabList/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/TabList
+# TabList
XDSTabList component for tab navigation with overflow menu support.
diff --git a/packages/core/src/Table/README.md b/packages/core/src/Table/README.md
index 9aab068adc..e06099582c 100644
--- a/packages/core/src/Table/README.md
+++ b/packages/core/src/Table/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/Table
+# Table
Table components for the XDS design system.
@@ -158,11 +158,6 @@ The selection plugin uses React Context so that `SelectAllCheckbox` and `Selecti
Body rows are memoized via `React.memo` with a custom comparison function. When a single data item changes, only that row re-renders — unchanged rows are skipped. For this to work optimally, consumers should define `columns` outside the component or memoize them.
-## Related Files
-
-- `/packages/core/src/theme/tokens.stylex.ts` — Design tokens used by table component styling
-- `/packages/core/src/CheckboxInput/` — Checkbox component used by selection plugin
-
## Theming
Themes can override `Table` styles via `ComponentStyles`:
diff --git a/packages/core/src/Text/README.md b/packages/core/src/Text/README.md
index b1379c1a06..ac92229c3e 100644
--- a/packages/core/src/Text/README.md
+++ b/packages/core/src/Text/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/Text
+# Text
Typography components for the XDS design system.
@@ -61,8 +61,3 @@ function Article() {
);
}
```
-
-## Related Files
-
-- `/packages/core/src/typography.css` — CSS stylesheet for native element styling
-- `/packages/core/src/theme/types.ts` — Type definitions for `ProseElement` and component styles
diff --git a/packages/core/src/TextArea/README.md b/packages/core/src/TextArea/README.md
index f8d871479d..20b5ad963b 100644
--- a/packages/core/src/TextArea/README.md
+++ b/packages/core/src/TextArea/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/TextArea
+# TextArea
A multi-line text input component for collecting longer user input.
diff --git a/packages/core/src/TextInput/README.md b/packages/core/src/TextInput/README.md
index a657566e08..f1b96791b4 100644
--- a/packages/core/src/TextInput/README.md
+++ b/packages/core/src/TextInput/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/TextInput
+# TextInput
A text input component for collecting user text input.
diff --git a/packages/core/src/TopNav/README.md b/packages/core/src/TopNav/README.md
index 0b3b2c650e..92104d9b3e 100644
--- a/packages/core/src/TopNav/README.md
+++ b/packages/core/src/TopNav/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/TopNav
+# TopNav
Top navigation bar component for application headers.
diff --git a/packages/core/src/theme/README.md b/packages/core/src/theme/README.md
index 4745516c94..3655be2385 100644
--- a/packages/core/src/theme/README.md
+++ b/packages/core/src/theme/README.md
@@ -1,4 +1,4 @@
-# /packages/core/src/theme
+# theme
XDS theme provider and design tokens.