Skip to content

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

TypeScript

fix(vibe-tests): add README to XDS project template for agent discoverability (#2410)

Cindy Zhangac34560e4ca7
diff --git a/internal/vibe-tests/environments/project-xds-tailwind/README.md b/internal/vibe-tests/environments/project-xds-tailwind/README.md
index 5083070ec3..cd05b7efe2 100644
--- a/internal/vibe-tests/environments/project-xds-tailwind/README.md
+++ b/internal/vibe-tests/environments/project-xds-tailwind/README.md
@@ -1,55 +1,26 @@
# XDS + Tailwind CSS
-This project uses XDS components for structured UI (cards, buttons, inputs, etc.)
-and Tailwind CSS utilities for layout, spacing, and custom styling.
+This project uses XDS components with Tailwind CSS. Use the CLI to look up component props and usage before writing code:
-## Usage Pattern
-
-Use XDS components for interactive/semantic elements:
-
-```tsx
-import {XDSCard, XDSButton, XDSVStack, XDSHeading, XDSText} from '@xds/core';
-```
-
-Use Tailwind utility classes for layout and customization:
-
-```tsx
-<main className="flex min-h-screen items-center p-8">
- <XDSCard className="max-w-md">
- <XDSVStack gap={4}>
- <XDSHeading level={2}>Dashboard</XDSHeading>
- <XDSButton label="Save" variant="primary" />
- </XDSVStack>
- </XDSCard>
-</main>
+```bash
+npx xds component --list # list all available components
+npx xds component Button # look up props, variants, and usage
+npx xds component IconButton # each component has its own entry
```
-## XDS Tailwind Bridge
+Components use:
-XDS tokens are available as native Tailwind utilities. Instead of:
+- Tailwind CSS utility classes for layout and custom styling
+- XDS Tailwind bridge tokens (`bg-surface`, `text-primary`) for design tokens
+- React 19
-```tsx
-<div className="bg-[var(--color-background-surface)]">
-```
+## Import Pattern
-Write:
+Each component is imported from its own subpath:
```tsx
-<div className="bg-surface text-primary rounded-lg p-4">
+import {XDSButton} from '@xds/core/Button';
+import {XDSIconButton} from '@xds/core/IconButton';
+import {XDSCard} from '@xds/core/Card';
+import {XDSText, XDSHeading} from '@xds/core/Text';
```
-
-Available token utilities include: `text-primary`, `text-secondary`, `bg-surface`,
-`bg-card`, `bg-muted`, `border-default`, `text-error`, `bg-success`, and many more.
-
-## Component Docs
-
-Run `npx xds component <Name>` to look up component props and usage.
-Run `npx xds component --list` to see all available components.
-
-## Key Rules
-
-- XDS components accept `className` — Tailwind utilities override XDS styles
-- Use XDS components for semantic UI (buttons, cards, inputs, headings, text)
-- Use Tailwind for layout (`flex`, `grid`, `gap-*`, `p-*`, `m-*`)
-- Use bridge tokens (`bg-surface`, `text-primary`) instead of raw CSS variables
-- All XDS components are imported from `@xds/core`
diff --git a/internal/vibe-tests/environments/project-xds/README.md b/internal/vibe-tests/environments/project-xds/README.md
new file mode 100644
index 0000000000..7f2f41c4c2
--- /dev/null
+++ b/internal/vibe-tests/environments/project-xds/README.md
@@ -0,0 +1,31 @@
+# XDS
+
+This project uses XDS components. Use the CLI to look up component props and usage before writing code:
+
+```bash
+npx xds component --list # list all available components
+npx xds component Button # look up props, variants, and usage
+npx xds component IconButton # each component has its own entry
+```
+
+If the CLI is not available, install dependencies first:
+
+```bash
+npm install --include=dev
+```
+
+Components use:
+
+- StyleX (`@stylexjs/stylex`) for styling
+- React 19
+
+## Import Pattern
+
+Each component is imported from its own subpath:
+
+```tsx
+import {XDSButton} from '@xds/core/Button';
+import {XDSIconButton} from '@xds/core/IconButton';
+import {XDSCard} from '@xds/core/Card';
+import {XDSText, XDSHeading} from '@xds/core/Text';
+```