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.mdindex 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) |## Philosophydiff --git a/packages/README.md b/packages/README.mdindex 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.mdindex 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 packagesnpx 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.mdindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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` |