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` and start from the closest shipped theme with `theme add <slug>`, which copies it in as editable source; if none of them fit, run `npx @astryxdesign/cli theme template` and fill in the annotated template it writes. 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 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.

bash
npx astryx init

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.

css
@import '@astryxdesign/core/reset.css';
@import '@astryxdesign/core/astryx.css';
@import '@astryxdesign/theme-neutral/theme.css';

Available themes:

• @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. See the Cascade Layer Safety section in astryx docs migration before building screens.

Run astryx docs theme for the full theming guide.

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

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>
  );
}

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.

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