Getting started

Astryx 0.7.1: Getting started.

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:

Install @astryxdesign/core, @stylexjs/stylex, @astryxdesign/theme-neutral, and @astryxdesign/cli in this project, then run `npx @astryxdesign/cli init` to set up agent docs. Read the generated files to learn the conventions.

Then give it a look. Every app gets a theme whether or not anyone picks one, so it is worth one question at setup rather than revisiting screens later that were built around the wrong look:

Ask me what look and feel this app should have. Run `npx @astryxdesign/cli theme list`, install the closest theme package, and run `theme add <slug>`; use `--package` when owners share a slug. Import `themes` and `defaultThemeSlug` from the generated module once and pass `themes[defaultThemeSlug]` to `<Theme>`. Customize with `defineTheme({extends: importedTheme, ...})`. Use `theme eject` only when I ask for an independent source fork. Default to neutral if I have no preference, and show me the result before moving on.

Install

Astryx requires React 19 or later: react and react-dom >= 19.0.0 are peer dependencies of @astryxdesign/core.

Add the core package and its @stylexjs/stylex peer dependency, plus a theme and the CLI.

npm install @astryxdesign/core @stylexjs/stylex @astryxdesign/theme-neutral @astryxdesign/cli

Then run astryx init to install the AI agent cheat sheet (AGENTS.md/CLAUDE.md). It's non-interactive; no prompts; so it's safe for AI agents, CI, and scripts. Add --all for pointers to the theme and page-building workflows.

npx @astryxdesign/cli@0.7.1 init

Add base CSS and a theme

Import the reset and base styles in your global CSS. Then run astryx theme add neutral; the generated app module imports the theme’s production CSS and font CSS.

@import '@astryxdesign/core/reset.css';
@import '@astryxdesign/core/astryx.css';

Run astryx theme list to see every theme.

import {Theme} from '@astryxdesign/core';
import {themes, defaultThemeSlug} from './astryx-themes';

<Theme theme={themes[defaultThemeSlug]}><App /></Theme>

• @astryxdesign/theme-neutral: muted and minimal; a good starting point
• @astryxdesign/theme-butter: warm, golden tones with blue accents
• @astryxdesign/theme-chocolate: rich chocolate and caramel tones
• @astryxdesign/theme-gothic: dark-only theme with ink and noir influences
• @astryxdesign/theme-matcha: earthy greens and botanical tones
• @astryxdesign/theme-stone: warm neutrals inspired by sandstone
• @astryxdesign/theme-y2k: playful early-2000s pop aesthetic

These stylesheets are cascade-layered: the reset loads in @layer reset and component styles in @layer astryx-base. If your project has existing global CSS, a legacy reset, or Tailwind, declare the layer order explicitly and assign every stylesheet to a layer deliberately: unlayered styles and later layers both override astryx-base regardless of specificity. Before building screens, read the two cascade layer sections of migration-setup.

Run use-a-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.

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 styling 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.

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.

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:

"scripts": {
  "astryx": "node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs"
}

Then discover what's available:

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

Pinned install:

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0