Getting Started

Paste this into your AI coding tool and let it handle the setup:

text
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:

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

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.

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

Then run npx @astryxdesign/cli 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.

bash
npx @astryxdesign/cli init

Install the CLI once for your computer too, and the astryx command works in any folder, for you and for any coding agent, even before a project exists. Inside a project, the project's own version still answers, so a global install never changes what your team and CI get. Keep it in the project as well; that is the recommended setup.

bash
npm i -g @astryxdesign/cli

Project, global, or both: npx @astryxdesign/cli docs global/project-global-or-both. Everything else about global mode: npx @astryxdesign/cli docs global.

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

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

Run npx @astryxdesign/cli theme list to see every theme.

tsx
import {Theme} from '@astryxdesign/core/theme';
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 npx @astryxdesign/cli docs migration/migration-setup.

Run npx @astryxdesign/cli docs use-a-theme for the full theming guide.

Import each component from its own entry, the path npx @astryxdesign/cli component <Name> prints. This keeps bundles small and makes intent clear.

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

Astryx components support various styling solutions, from plain CSS and className to Tailwind and CSS-in-JS. See npx @astryxdesign/cli docs 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.

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

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.

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

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:

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

Then discover what's available:

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