开始使用

环境要求

React 与 React DOM 需要 19 或更高版本；CLI 需要 Node.js 22.13 或更高版本。先检查项目版本，不使用 --force 或 --legacy-peer-deps 绕过冲突。Astryx 当前为 Beta，示例与文档固定为 0.7.1。

安装

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

按顺序导入样式

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

配置主题

'use client';
import {Theme} from '@astryxdesign/core/theme';
import {neutralTheme} from '@astryxdesign/theme-neutral/built';
import {Button} from '@astryxdesign/core/Button';
export default function Example() {
  return <Theme theme={neutralTheme} mode="light"><Button label="开始使用" variant="primary" /></Theme>;
}

Vite 可直接使用上述入口。Next.js 中将主题包装放在客户端 Provider，CSS 从布局入口导入；本站使用独立预览，不把 Astryx reset 引入主站。

验证

运行项目现有类型检查与生产构建，实际点击按钮、打开弹层，并检查窄屏和深色模式。安装成功不等于交互已验证。

上游完整参考（英文）

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