# 开始使用

- 页面: https://jiguang132.com/zh/resources/astryx/docs/getting-started
- 资源: Astryx (https://jiguang132.com/zh/resources/astryx.md)
- 全部指南: https://jiguang132.com/zh/resources/astryx/docs.md

## 环境要求

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

## 安装

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

## 按顺序导入样式

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

## 配置主题

```tsx
'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:

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

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

```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 @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.

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

Run `astryx theme list` to see every theme.

```tsx
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.

```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 `styling` for the full guide. Astryx also has a deep integration with [StyleX](https://stylexjs.com/), 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} />
```

### 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](https://github.com/facebook/astryx/tree/main/apps/example-nextjs) |
| Next.js + StyleX | Next.js + StyleX for custom styles | [apps/example-nextjs-stylex](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-stylex) |
| Next.js + Tailwind | Next.js + Tailwind bridge | [apps/example-nextjs-tailwind](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-tailwind) |
| Vite + Tailwind | Vite + Tailwind bridge | [apps/example-vite-tailwind](https://github.com/facebook/astryx/tree/main/apps/example-vite-tailwind) |

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

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

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt