Skip to content

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

TypeScript

docs: add READMEs to all packages for LLM discoverability (#1615)

Cindy Zhange5ea18fbd417
diff --git a/README.md b/README.md
index 17b7e25b5c..93b5ec0dbc 100644
--- a/README.md
+++ b/README.md
@@ -30,12 +30,15 @@ Then follow the [setup guide](packages/core/README.md#quick-start) to import sty
## Packages
-| Package | Description | README |
-| ----------------------------------------------- | --------------------------------------------------- | --------------------------------- |
-| [`@xds/core`](packages/core) | Components, theme system, and utilities | [README](packages/core/README.md) |
-| [`@xds/cli`](packages/cli) | CLI tooling — component docs, scaffolding, codemods | [README](packages/cli/README.md) |
-| [`@xds/theme-default`](packages/themes/default) | Clean, professional default theme | |
-| [`@xds/theme-neutral`](packages/themes/neutral) | Muted, minimal aesthetic theme | |
+| Package | Description | README |
+| ----------------------------------------------- | ----------------------------------------------------- | -------------------------------------------- |
+| [`@xds/core`](packages/core) | Components, theme system, and utilities | [README](packages/core/README.md) |
+| [`@xds/cli`](packages/cli) | CLI tooling — component docs, scaffolding, codemods | [README](packages/cli/README.md) |
+| [`@xds/build`](packages/build) | Build plugins for StyleX source builds | [README](packages/build/README.md) |
+| [`@xds/vega`](packages/vega) | Vega/Vega-Lite chart wrapper | [README](packages/vega/README.md) |
+| [`@xds/theme-default`](packages/themes/default) | Clean, professional default theme | [README](packages/themes/default/README.md) |
+| [`@xds/theme-neutral`](packages/themes/neutral) | Muted, minimal aesthetic theme | [README](packages/themes/neutral/README.md) |
+| [`@xds/theme-daily`](packages/themes/daily) | Warm, productivity-focused theme | [README](packages/themes/daily/README.md) |
## Philosophy
diff --git a/packages/README.md b/packages/README.md
index f94443a098..74b7f70e38 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -4,7 +4,11 @@ Published npm packages for the XDS design system.
<!-- SYNC: When files in this directory change, update this document. -->
-| Directory | Role | Purpose |
-| --------- | ------- | ------------------------------------------------- |
-| `core/` | Primary | Core UI components library (`@xds/core`) |
-| `vega/` | Add-on | Vega-Lite chart wrapper components (`@xds/vega`) |
+| Directory | Package | Purpose |
+|-----------|---------|---------|
+| `core/` | `@xds/core` | Core UI components, theme system, and utilities |
+| `cli/` | `@xds/cli` | CLI tooling — component docs, templates, scaffolding, codemods |
+| `build/` | `@xds/build` | Build plugins for StyleX source builds (Babel, PostCSS, Vite) |
+| `vega/` | `@xds/vega` | Vega/Vega-Lite chart wrapper |
+| `themes/` | `@xds/theme-*` | Visual themes (default, neutral, daily, brutalist, meta, whatsapp) |
+| `lab/` | — | Experimental components (not published) |
diff --git a/packages/core/README.md b/packages/core/README.md
index d1742a9eee..bf7e0f0e37 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -1,6 +1,6 @@
-# XDS
+# @xds/core
-XDS is a design system for building internal tools and products.
+Core UI components, theme system, and utilities for the XDS design system. For project setup, see [Quick Start](#quick-start) below.
## Component Docs
@@ -44,7 +44,152 @@ npx xds discover # discover external XDS packages
npx xds gap-report # report a missing capability
```
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@xds/cli`](https://github.com/facebookexperimental/xds/tree/main/packages/cli) | CLI tooling — component docs, templates, scaffolding, codemods |
+| [`@xds/build`](https://github.com/facebookexperimental/xds/tree/main/packages/build) | Build plugins for StyleX source builds (Babel, PostCSS, Vite) |
+| [`@xds/theme-default`](https://github.com/facebookexperimental/xds/tree/main/packages/themes/default) | Default theme (Heroicons) |
+| [`@xds/theme-neutral`](https://github.com/facebookexperimental/xds/tree/main/packages/themes/neutral) | Muted, minimal theme (Lucide icons) |
+| [`@xds/theme-daily`](https://github.com/facebookexperimental/xds/tree/main/packages/themes/daily) | Warm, productivity-focused theme (Lucide icons) |
+
## Resources
- [Component Storybook](https://facebookexperimental.github.io/xds/)
- [GitHub Repository](https://github.com/facebookexperimental/xds)
+
+---
+
+## Quick Start
+
+Install XDS and a theme:
+
+```bash
+npm install @xds/core @xds/theme-default
+```
+
+Then pick your setup below based on your framework and styling approach.
+
+### Next.js + Tailwind (simplest)
+
+No build plugins needed — XDS ships pre-built CSS that works alongside Tailwind.
+
+**`src/app/globals.css`**
+
+```css
+@layer reset, theme, base, xds-base, xds-theme, components, utilities;
+
+@import "tailwindcss/theme.css" layer(theme);
+@import "tailwindcss/preflight.css" layer(base);
+@import "@xds/core/reset.css";
+@import "@xds/core/xds.css";
+@import "@xds/theme-default/theme.css";
+@import "tailwindcss/utilities.css" layer(utilities);
+```
+
+**`src/app/providers.tsx`**
+
+```tsx
+'use client';
+
+import Link from 'next/link';
+import {XDSTheme} from '@xds/core/theme';
+import {XDSLinkProvider} from '@xds/core/Link';
+import {defaultTheme} from '@xds/theme-default/built';
+
+export function Providers({children}: {children: React.ReactNode}) {
+ return (
+ <XDSTheme theme={defaultTheme}>
+ <XDSLinkProvider component={Link}>{children}</XDSLinkProvider>
+ </XDSTheme>
+ );
+}
+```
+
+**`src/app/layout.tsx`**
+
+```tsx
+import './globals.css';
+import {Providers} from './providers';
+
+export default function RootLayout({children}: {children: React.ReactNode}) {
+ return (
+ <html lang="en">
+ <body>
+ <Providers>{children}</Providers>
+ </body>
+ </html>
+ );
+}
+```
+
+That's it — start using components:
+
+```tsx
+import {XDSButton} from '@xds/core/Button';
+
+export default function Page() {
+ return <XDSButton label="Hello XDS" variant="primary" />;
+}
+```
+
+### Next.js + StyleX (source build)
+
+Compiles XDS from TypeScript source for tree-shaking and custom StyleX overrides.
+
+```bash
+npm install @xds/core @xds/theme-default
+npm install -D @xds/build @stylexjs/babel-plugin @babel/core
+```
+
+See the [`@xds/build` README](../build/README.md) for full `babel.config.js`, `postcss.config.js`, and `next.config.mjs` setup. The key difference from the Tailwind path is that `@xds/build` compiles StyleX from source with split CSS layer prefixes.
+
+**`src/app/globals.css`**
+
+```css
+@import './layers.css';
+@import '@xds/core/reset.css';
+@import '@xds/theme-default/theme.css';
+
+@stylex;
+```
+
+**`src/app/layers.css`**
+
+```css
+@layer reset, xds-base, xds-theme, product;
+```
+
+The providers file is the same as above, but import theme from `@xds/theme-default` (not `/built`):
+
+```tsx
+import {defaultTheme} from '@xds/theme-default';
+```
+
+### Vite + StyleX
+
+```bash
+npm install @xds/core @xds/theme-default
+npm install -D @xds/build @stylexjs/unplugin @vitejs/plugin-react
+```
+
+See the [`@xds/build` README](../build/README.md) for full `vite.config.ts` setup with `xdsStylex()`.
+
+### Next.js (dist, no Tailwind, no StyleX)
+
+The lightest path — no build plugins at all.
+
+```bash
+npm install @xds/core @xds/theme-default
+```
+
+**`src/app/globals.css`**
+
+```css
+@import "@xds/core/reset.css";
+@import "@xds/core/xds.css";
+@import "@xds/theme-default/theme.css";
+```
+
+Providers and layout are the same as the Tailwind example (use `@xds/theme-default/built`).
diff --git a/packages/lab/README.md b/packages/lab/README.md
index 388da3a666..31f97286d4 100644
--- a/packages/lab/README.md
+++ b/packages/lab/README.md
@@ -1,10 +1,10 @@
# @xds/lab
-Experimental XDS components. This package is **never published** — it exists as a staging area for components that are functional but not yet hardened for production.
+Experimental XDS components. This package is **not published** — it exists as a staging area for components being developed before graduating to `@xds/core`.
## Purpose
-Designers and engineers can vibe components here without the quality bar required for `@xds/core`. Components in lab:
+Components in lab:
- Are importable in storybook and sandbox for testing
- Can be iterated on freely without worrying about breaking consumers
@@ -17,21 +17,10 @@ Designers and engineers can vibe components here without the quality bar require
**Core:** Full keyboard/a11y, hover guards, theming story, status states, spec compliance, vibe tested. Shipped to consumers.
-## Components
-
-| Component | Status | Notes |
-| -------------- | ---------- | ----------------------------------------------------------------------------- |
-| CommandPalette | Functional | Dialog shell, input, list, items, groups, footer, context provider, filtering |
-
## Usage
```tsx
-import {
- XDSCommandPalette,
- XDSCommandPaletteInput,
- XDSCommandPaletteList,
- XDSCommandPaletteItem,
-} from '@xds/lab';
+import {XDSCodeEditor} from '@xds/lab';
```
Since this is a workspace package (not published), imports resolve via yarn workspaces in storybook and sandbox.
diff --git a/packages/themes/brutalist/README.md b/packages/themes/brutalist/README.md
new file mode 100644
index 0000000000..6f62c1ba5e
--- /dev/null
+++ b/packages/themes/brutalist/README.md
@@ -0,0 +1,54 @@
+# @xds/theme-brutalist
+
+Zero radius, monospace, heavy borders.
+> **Note:** This theme is private and not published to npm.
+## Install
+
+```bash
+npm install @xds/theme-brutalist
+```
+
+## Usage
+
+Wrap your app with `XDSTheme` and pass the theme:
+
+```tsx
+import {XDSTheme} from '@xds/core/theme';
+import {brutalistTheme} from '@xds/theme-brutalist/built';
+
+function App() {
+ return (
+ <XDSTheme theme={brutalistTheme}>
+ {/* your app */}
+ </XDSTheme>
+ );
+}
+```
+
+### Import paths
+
+| Path | Use case |
+|------|----------|
+| `@xds/theme-brutalist` | Source build (StyleX compilation via `@xds/build`) |
+| `@xds/theme-brutalist/built` | Pre-built dist (Tailwind, plain CSS, or no build step) |
+| `@xds/theme-brutalist/theme.css` | Pre-built CSS file (import in your stylesheet) |
+
+If you're using `@xds/build` for StyleX source compilation, import from the bare path. Otherwise, use `/built`.
+
+### CSS import
+
+Add the theme CSS to your stylesheet:
+
+```css
+@import "@xds/theme-brutalist/theme.css";
+```
+
+This is required for component-level theme overrides (colors, radii, typography) to take effect.
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@xds/core`](https://github.com/facebookexperimental/xds/tree/main/packages/core) | Core components and theme system |
+| [`@xds/build`](https://github.com/facebookexperimental/xds/tree/main/packages/build) | Build plugins for StyleX source builds |
+| [`@xds/cli`](https://github.com/facebookexperimental/xds/tree/main/packages/cli) | CLI tooling including `xds docs theme` |
diff --git a/packages/themes/daily/README.md b/packages/themes/daily/README.md
new file mode 100644
index 0000000000..e2f7ecbb59
--- /dev/null
+++ b/packages/themes/daily/README.md
@@ -0,0 +1,54 @@
+# @xds/theme-daily
+
+Warm, productivity-focused theme. Uses [Lucide](https://lucide.dev) icons.
+
+## Install
+
+```bash
+npm install @xds/theme-daily
+```
+
+## Usage
+
+Wrap your app with `XDSTheme` and pass the theme:
+
+```tsx
+import {XDSTheme} from '@xds/core/theme';
+import {dailyTheme} from '@xds/theme-daily/built';
+
+function App() {
+ return (
+ <XDSTheme theme={dailyTheme}>
+ {/* your app */}
+ </XDSTheme>
+ );
+}
+```
+
+### Import paths
+
+| Path | Use case |
+|------|----------|
+| `@xds/theme-daily` | Source build (StyleX compilation via `@xds/build`) |
+| `@xds/theme-daily/built` | Pre-built dist (Tailwind, plain CSS, or no build step) |
+| `@xds/theme-daily/theme.css` | Pre-built CSS file (import in your stylesheet) |
+
+If you're using `@xds/build` for StyleX source compilation, import from the bare path. Otherwise, use `/built`.
+
+### CSS import
+
+Add the theme CSS to your stylesheet:
+
+```css
+@import "@xds/theme-daily/theme.css";
+```
+
+This is required for component-level theme overrides (colors, radii, typography) to take effect.
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@xds/core`](https://github.com/facebookexperimental/xds/tree/main/packages/core) | Core components and theme system |
+| [`@xds/build`](https://github.com/facebookexperimental/xds/tree/main/packages/build) | Build plugins for StyleX source builds |
+| [`@xds/cli`](https://github.com/facebookexperimental/xds/tree/main/packages/cli) | CLI tooling including `xds docs theme` |
diff --git a/packages/themes/default/README.md b/packages/themes/default/README.md
new file mode 100644
index 0000000000..63678a38a4
--- /dev/null
+++ b/packages/themes/default/README.md
@@ -0,0 +1,54 @@
+# @xds/theme-default
+
+Clean, professional default theme. Uses [Heroicons](https://heroicons.com) icons.
+
+## Install
+
+```bash
+npm install @xds/theme-default
+```
+
+## Usage
+
+Wrap your app with `XDSTheme` and pass the theme:
+
+```tsx
+import {XDSTheme} from '@xds/core/theme';
+import {defaultTheme} from '@xds/theme-default/built';
+
+function App() {
+ return (
+ <XDSTheme theme={defaultTheme}>
+ {/* your app */}
+ </XDSTheme>
+ );
+}
+```
+
+### Import paths
+
+| Path | Use case |
+|------|----------|
+| `@xds/theme-default` | Source build (StyleX compilation via `@xds/build`) |
+| `@xds/theme-default/built` | Pre-built dist (Tailwind, plain CSS, or no build step) |
+| `@xds/theme-default/theme.css` | Pre-built CSS file (import in your stylesheet) |
+
+If you're using `@xds/build` for StyleX source compilation, import from the bare path. Otherwise, use `/built`.
+
+### CSS import
+
+Add the theme CSS to your stylesheet:
+
+```css
+@import "@xds/theme-default/theme.css";
+```
+
+This is required for component-level theme overrides (colors, radii, typography) to take effect.
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@xds/core`](https://github.com/facebookexperimental/xds/tree/main/packages/core) | Core components and theme system |
+| [`@xds/build`](https://github.com/facebookexperimental/xds/tree/main/packages/build) | Build plugins for StyleX source builds |
+| [`@xds/cli`](https://github.com/facebookexperimental/xds/tree/main/packages/cli) | CLI tooling including `xds docs theme` |
diff --git a/packages/themes/meta/README.md b/packages/themes/meta/README.md
new file mode 100644
index 0000000000..befd046675
--- /dev/null
+++ b/packages/themes/meta/README.md
@@ -0,0 +1,54 @@
+# @xds/theme-meta
+
+Meta brand identity with blue accent and clean aesthetics. Includes custom icon set.
+> **Note:** This theme is private and not published to npm.
+## Install
+
+```bash
+npm install @xds/theme-meta
+```
+
+## Usage
+
+Wrap your app with `XDSTheme` and pass the theme:
+
+```tsx
+import {XDSTheme} from '@xds/core/theme';
+import {metaTheme} from '@xds/theme-meta/built';
+
+function App() {
+ return (
+ <XDSTheme theme={metaTheme}>
+ {/* your app */}
+ </XDSTheme>
+ );
+}
+```
+
+### Import paths
+
+| Path | Use case |
+|------|----------|
+| `@xds/theme-meta` | Source build (StyleX compilation via `@xds/build`) |
+| `@xds/theme-meta/built` | Pre-built dist (Tailwind, plain CSS, or no build step) |
+| `@xds/theme-meta/theme.css` | Pre-built CSS file (import in your stylesheet) |
+
+If you're using `@xds/build` for StyleX source compilation, import from the bare path. Otherwise, use `/built`.
+
+### CSS import
+
+Add the theme CSS to your stylesheet:
+
+```css
+@import "@xds/theme-meta/theme.css";
+```
+
+This is required for component-level theme overrides (colors, radii, typography) to take effect.
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@xds/core`](https://github.com/facebookexperimental/xds/tree/main/packages/core) | Core components and theme system |
+| [`@xds/build`](https://github.com/facebookexperimental/xds/tree/main/packages/build) | Build plugins for StyleX source builds |
+| [`@xds/cli`](https://github.com/facebookexperimental/xds/tree/main/packages/cli) | CLI tooling including `xds docs theme` |
diff --git a/packages/themes/neutral/README.md b/packages/themes/neutral/README.md
new file mode 100644
index 0000000000..936b3952ca
--- /dev/null
+++ b/packages/themes/neutral/README.md
@@ -0,0 +1,54 @@
+# @xds/theme-neutral
+
+Muted, minimal aesthetic. Uses [Lucide](https://lucide.dev) icons.
+
+## Install
+
+```bash
+npm install @xds/theme-neutral
+```
+
+## Usage
+
+Wrap your app with `XDSTheme` and pass the theme:
+
+```tsx
+import {XDSTheme} from '@xds/core/theme';
+import {neutralTheme} from '@xds/theme-neutral/built';
+
+function App() {
+ return (
+ <XDSTheme theme={neutralTheme}>
+ {/* your app */}
+ </XDSTheme>
+ );
+}
+```
+
+### Import paths
+
+| Path | Use case |
+|------|----------|
+| `@xds/theme-neutral` | Source build (StyleX compilation via `@xds/build`) |
+| `@xds/theme-neutral/built` | Pre-built dist (Tailwind, plain CSS, or no build step) |
+| `@xds/theme-neutral/theme.css` | Pre-built CSS file (import in your stylesheet) |
+
+If you're using `@xds/build` for StyleX source compilation, import from the bare path. Otherwise, use `/built`.
+
+### CSS import
+
+Add the theme CSS to your stylesheet:
+
+```css
+@import "@xds/theme-neutral/theme.css";
+```
+
+This is required for component-level theme overrides (colors, radii, typography) to take effect.
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@xds/core`](https://github.com/facebookexperimental/xds/tree/main/packages/core) | Core components and theme system |
+| [`@xds/build`](https://github.com/facebookexperimental/xds/tree/main/packages/build) | Build plugins for StyleX source builds |
+| [`@xds/cli`](https://github.com/facebookexperimental/xds/tree/main/packages/cli) | CLI tooling including `xds docs theme` |
diff --git a/packages/themes/whatsapp/README.md b/packages/themes/whatsapp/README.md
new file mode 100644
index 0000000000..8429bbb4e5
--- /dev/null
+++ b/packages/themes/whatsapp/README.md
@@ -0,0 +1,54 @@
+# @xds/theme-whatsapp
+
+WhatsApp brand identity — green accent, warm grays, Roboto, rounded surfaces. Includes custom icon set.
+> **Note:** This theme is private and not published to npm.
+## Install
+
+```bash
+npm install @xds/theme-whatsapp
+```
+
+## Usage
+
+Wrap your app with `XDSTheme` and pass the theme:
+
+```tsx
+import {XDSTheme} from '@xds/core/theme';
+import {whatsappTheme} from '@xds/theme-whatsapp/built';
+
+function App() {
+ return (
+ <XDSTheme theme={whatsappTheme}>
+ {/* your app */}
+ </XDSTheme>
+ );
+}
+```
+
+### Import paths
+
+| Path | Use case |
+|------|----------|
+| `@xds/theme-whatsapp` | Source build (StyleX compilation via `@xds/build`) |
+| `@xds/theme-whatsapp/built` | Pre-built dist (Tailwind, plain CSS, or no build step) |
+| `@xds/theme-whatsapp/theme.css` | Pre-built CSS file (import in your stylesheet) |
+
+If you're using `@xds/build` for StyleX source compilation, import from the bare path. Otherwise, use `/built`.
+
+### CSS import
+
+Add the theme CSS to your stylesheet:
+
+```css
+@import "@xds/theme-whatsapp/theme.css";
+```
+
+This is required for component-level theme overrides (colors, radii, typography) to take effect.
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@xds/core`](https://github.com/facebookexperimental/xds/tree/main/packages/core) | Core components and theme system |
+| [`@xds/build`](https://github.com/facebookexperimental/xds/tree/main/packages/build) | Build plugins for StyleX source builds |
+| [`@xds/cli`](https://github.com/facebookexperimental/xds/tree/main/packages/cli) | CLI tooling including `xds docs theme` |