XDS — Design System

Getting StartedAdd XDS to your project and start building.

Quick Start with AIPaste this into your AI coding tool and let it handle the setup:

Paste this into your AI

text
Install @xds/core, @xds/theme-default, and @xds/cli in this project. Run `npx xds init` to set up agent docs. Read the generated files to learn the conventions.

InstallAdd the core package, a theme, and the CLI to your existing project.

Terminal

bash
npm install @xds/core @xds/theme-default @xds/cli

Then run the init wizard to set up AI agent docs, pick a starter template, and learn about theming.

Terminal

bash
npx xds init

Add the theme CSSImport the reset stylesheet and a theme in your global CSS file. Themes provide all design tokens (colors, spacing, radius, typography) as CSS custom properties.

globals.css

css
@import '@xds/core/reset.css';
@import '@xds/core/xds.css';
@import '@xds/theme-default/theme.css';

Available themes: @xds/theme-default (blue accent), @xds/theme-neutral (grayscale), @xds/theme-brutalist (zero radius, monospace). See `npx xds docs theme` for the full theming guide.

Add your first componentXDS components are imported from per-category subpath entrypoints. This keeps bundles small and makes intent clear.

app/page.tsx

tsx
import {XDSButton} from '@xds/core/Button';
import {XDSVStack} from '@xds/core/Layout';
export default function Page() {
  return (
    <XDSVStack gap={2}>
      <XDSButton label="Hello XDS" onClick={() => alert('Hi!')} />
    </XDSVStack>
  );
}

Customize with xstyleEvery XDS component accepts an `xstyle` prop for StyleX style overrides created via `stylex.create()`.

Style overrides

tsx
import * as stylex from '@stylexjs/stylex';
const overrides = stylex.create({
  save: { alignSelf: 'flex-end', marginTop: 16 },
});
<XDSButton label="Save" xstyle={overrides.save} />

Example AppsFor a full working project, clone one of the example apps from the XDS repo. These are complete setups with routing, theming, and components wired together.

Example	Stack	Path
Next.js	Next.js + XDS theme CSS	apps/example-nextjs
Next.js + StyleX	Next.js + StyleX for custom styles	apps/example-nextjs-stylex
Next.js + Tailwind	Next.js + Tailwind bridge	apps/example-nextjs-tailwind
Next.js Source	Next.js importing XDS from source	apps/example-nextjs-source
Vite	Vite + XDS	apps/example-vite

Clone and run an example

bash
git clone https://github.com/facebookexperimental/xds.git
cd xds/apps/example-nextjs
pnpm install
pnpm dev

Explore the CLIThe CLI is your reference for components, tokens, templates, and docs. For reliable invocation (especially with AI assistants), add this script to your package.json:

package.json

json
"scripts": {
  "xds": "node node_modules/@xds/cli/bin/xds.mjs"
}

Then discover what's available:

Terminal

bash
npm run xds -- component          # list all components
npm run xds -- component Button   # props, usage, theming for Button
npm run xds -- docs               # list all doc topics
npm run xds -- template --list    # available page templates
npm run xds -- docs tokens        # spacing, color, radius reference