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 @astryxdesign/core, @astryxdesign/theme-neutral, and @astryxdesign/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 @astryxdesign/core @astryxdesign/theme-neutral @astryxdesign/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 '@astryxdesign/core/reset.css';
@import '@astryxdesign/core/astryx.css';
@import '@astryxdesign/theme-neutral/theme.css';

Available themes: @astryxdesign/theme-neutral (muted minimal, a good starting point), @astryxdesign/theme-butter, @astryxdesign/theme-chocolate, @astryxdesign/theme-gothic (dark-only), @astryxdesign/theme-matcha, @astryxdesign/theme-stone, and @astryxdesign/theme-y2k. 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 '@astryxdesign/core/Button';
import {VStack} from '@astryxdesign/core/Layout';
export default function Page() {
  return (
    <VStack gap={2}>
      <Button label="Hello Astryx" onClick={() => alert('Hi!')} />
    </VStack>
  );
}

Customize with StyleX

Astryx components support various styling solutions, from plain CSS and className to Tailwind and CSS-in-JS. See the styling docs for the full guide. Astryx also has a deep integration with StyleX, an atomic CSS-in-JS library: create styles with stylex.create() and pass them to components with the xstyle prop.

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/facebook/astryx.git
cd astryx/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": {
  "astryx": "node node_modules/@astryxdesign/cli/bin/astryx.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