Getting Started

Add the design system to your project and start building.

Quick Start with AI

Paste 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 astryx init` to set up agent docs. Read the generated files to learn the conventions.

Install

Add 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 astryx init

Add the theme CSS

Import 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/astryx.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 astryx docs theme for the full theming guide.

Add your first component

Components are imported from per-category subpath entrypoints. This keeps bundles small and makes intent clear.

app/page.tsx

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

Customize with xstyle

Every 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 },
});
<Button label="Save" xstyle={overrides.save} />

Example Apps

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

Example	Stack	Path
Next.js	Next.js + 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 from source	apps/example-nextjs-source
Vite	Vite	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 CLI

The 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
npx astryx component          # list all components
npx astryx component Button   # props, usage, theming for Button
npx astryx docs               # list all doc topics
npx astryx template --list    # available page templates
npx astryx docs tokens        # spacing, color, radius reference