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
yarn install
yarn dev

Explore the CLIThe CLI is your reference for components, tokens, templates, and docs. Use it to discover what’s available.

Terminal

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