astryx

Astryx — 面向 Agent 的设计系统

Astryx 是一个开源设计系统，经过 Meta 8 年以上、在 13,000 多个应用中的实践和验证。它提供 150 多个无障碍 React 组件、品牌级主题、深色模式、模板和 CLI——专为团队如今的构建方式而设计：由人和与他们协作的 Agent 共同构建。

Astryx 基于 React 和 StyleX 构建，强调开放的内部结构（没有封闭的顶层 API，组件可完全组合）、零样式锁定（使用你自己的 CSS，无需特殊构建插件），以及面向 Agent 的就绪能力（组件在基础层级导出，让 AI 助手能够理解并扩展它们）。

目前处于 Beta 阶段

何时使用此技能

• 你正在构建或扩展组件库，并希望采用经过 Meta 生产环境验证的模式
• 你需要 150 多个无障碍、可直接用于生产的 React 组件，支持深色模式、主题和模板
• 你的设计系统必须支持人类与 AI 共同创作——Agent 需要能够安全地理解、修改和扩展组件
• 你希望实现零样式锁定——使用自己的 CSS 框架（Tailwind、emotion、原生 CSS），无需与设计系统构建插件冲突
• 你需要组件替换能力——可将组件的完整源码移出库并放入项目中自定义，无需派生分支
• 你的团队重视开放的内部结构和可组合性，而非封闭的顶层 API
• 你希望借鉴 Meta 8 年以上的设计系统演进经验，这些经验来自 13,000 多个应用

何时不应使用此技能

• 构建简单的一次性应用（直接使用 Shadcn、Mantine 或 MUI）
• 仅需要无头组件（不需要带样式的组件）——转而采用组件架构模式
• 非 React 项目——Astryx 仅支持 React；转而使用设计令牌工具
• 生命周期不会超过一个季度的快速原型

快速开始

步骤 1 — 在项目中安装 Astryx

# Install the core package (React 18+ required)
npm install @astryxdesign/core

# Install the CLI for scaffolding and setup
npm install --save-dev @astryxdesign/cli

# Install the build utilities (optional, for custom builds)
npm install --save-dev @astryxdesign/build

Astryx 需要处于活跃 LTS 版本线的 Node 22+ 和 pnpm 11+（或启用 Corepack）：

# Enable Corepack once (auto-installs pinned pnpm)
corepack enable

# Install dependencies
pnpm install

步骤 2 — 导入并使用组件

Astryx 在基础层级完整导出组件。没有复合组件 API，也没有 Context 乱象——只需导入所需内容：

import { Button, TextField, Card, Stack } from '@astryxdesign/core'

export function MyApp() {
  return (
    <Card>
      <Stack gap="md">
        <TextField label="Name" placeholder="Enter your name" />
        <Button variant="primary">Submit</Button>
      </Stack>
    </Card>
  )
}

步骤 3 — 应用主题和深色模式

Astryx 通过 CSS 变量支持品牌级主题和自动深色模式：

import { ThemeProvider } from '@astryxdesign/core'

export function App() {
  return (
    <ThemeProvider theme="light" // or "dark" or "auto"
      colorScheme={{
        primary: '#6741d9',
        background: '#ffffff',
      }}
    >
      <MyApp />
    </ThemeProvider>
  )
}

深色模式会自动响应系统偏好设置。

步骤 4 — 通过替换来自定义

需要移出组件并自行维护其实现时：

# Eject a component's full source into your project
astryx swizzle Button --path src/components/Button

# Now you can modify Button.tsx without forking the library

移出的组件完全归你所有——自定义内容在库升级后仍会保留。

步骤 5 — 使用模板实现常见模式

Astryx 提供适用于常见 UI 模式、可直接用于生产的模板：

# List available templates
astryx templates list

# Scaffold a form template
astryx templates create form --name MyForm

# Scaffold a data table
astryx templates create table --name MyDataTable

核心概念

开放的内部结构

Astryx 在基础层级导出基础元素和构建模块，不将它们封闭在顶层 API 之后。这意味着：

• 你可以自由组合 Button、Icon、Loader、Tooltip
• AI Agent 能够理解组件结构，并安全地进行修改
• 你不会受到框架强加的约束

**对比：**许多设计系统会将你限制在其复合组件结构中。需要复合组件时，Astryx 允许你自行构建。

零样式锁定

Astryx 使用 StyleX 提供预构建 CSS，但你可以自由地：

• 完全使用 Tailwind CSS 工具类替换样式
• 将 Astryx 组件与自己的 CSS 框架混合使用
• 通过 CSS Modules 或 emotion 覆盖组件样式
• 将 Astryx 用作组件结构参考，同时自行构建样式

无需构建插件。也不会强制在你的打包文件中加入样式库。

Agent 就绪度

每个组件都专为 AI 协同创作而设计：

• 扁平导出结构（Agent 无需遍历嵌套 API 即可找到组件）
• 所有组件的属性命名和类型保持一致
• 以 TypeScript 为先，因此类型定义可指导 Agent 生成代码
• 内置无障碍设计模式（让 Agent 生成符合无障碍要求的代码）
• 可组合的基元（Agent 可以安全地扩展）

架构概览

目录结构

目录	用途
packages/core	150 多个 React 组件、主题引擎、钩子
packages/cli	脚手架、弹出组件、模板生成
packages/build	构建工具、资源优化、CSS 打包
packages/themes	预置品牌主题（浅色、深色、增强对比度）
apps/docsite	完整文档（astryx.atmeta.com）
apps/storybook	交互式组件浏览器
apps/sandbox	用于快速原型设计的在线 Playground

主要导出

// Components (150+)
export { Button, TextField, Select, Checkbox, Card, Stack, Grid, Modal, ... }

// Theming
export { ThemeProvider, useTheme, useColorScheme, createTheme }

// Hooks
export { useFormField, useMediaQuery, useOnClickOutside, useFocusTrap, ... }

// Utilities
export { cn, cva, createVar, ... }  // Style utilities
export { a11y, focus, hover, ... }  // a11y helpers

使用模式

模式 1：组合组件

可自由组合 Astryx 组件，无需受顶层 API 的限制：

import { Button, Stack, Icon, Loader } from '@astryxdesign/core'

export function SubmitButton({ loading, onClick }) {
  return (
    <Button onClick={onClick} disabled={loading}>
      <Stack direction="horizontal" gap="sm">
        {loading && <Loader size="sm" />}
        <span>Submit</span>
      </Stack>
    </Button>
  )
}

模式 2：自定义主题

为你的品牌创建自定义主题：

import { createTheme, ThemeProvider } from '@astryxdesign/core'

const brandTheme = createTheme({
  primary: '#1f2937',
  secondary: '#6366f1',
  success: '#10b981',
  error: '#ef4444',
  fonts: {
    body: '"Inter", sans-serif',
    heading: '"Poppins", sans-serif',
  },
})

export function App() {
  return (
    <ThemeProvider theme={brandTheme}>
      <MyApp />
    </ThemeProvider>
  )
}

模式 3：响应式布局

Astryx 的 Grid 和 Stack 组件支持响应式属性：

import { Grid, Card } from '@astryxdesign/core'

export function Gallery() {
  return (
    <Grid
      columns={{ mobile: 1, tablet: 2, desktop: 4 }}
      gap="lg"
    >
      {items.map(item => (
        <Card key={item.id}>{item.name}</Card>
      ))}
    </Grid>
  )
}

模式 4：无障碍表单

Astryx 表单组件会自动处理无障碍功能：

import { FormField, TextField, Button } from '@astryxdesign/core'

export function LoginForm() {
  return (
    <form>
      <FormField label="Email" required>
        <TextField type="email" placeholder="[email protected]" />
      </FormField>
      <FormField label="Password" required>
        <TextField type="password" placeholder="••••••••" />
      </FormField>
      <Button type="submit">Sign In</Button>
    </form>
  )
}

与 Agent 技能集成

deep-agents-core

构建AI 驱动的组件设计系统时使用：

jeo @deep-agents-core create-component --design astryx

Agent 可以按照 Astryx 模式搭建新组件的脚手架。

react-best-practices

按照 Meta 的模式优化 Astryx 组件性能（规则 2.1：避免使用 barrel imports；规则 4：优化客户端数据获取）：

// Correct: direct import, not barrel
import Button from '@astryxdesign/core/Button'

// Avoid (slow dev boot, slow builds)
import { Button } from '@astryxdesign/core'

responsive-design

验证 Astryx 布局在不同视口下是否正常：

jeo @responsive-design verify --layout astryx-grid

react-grab

从运行中的 UI 捕获准确的 React 元素上下文，以便交给 Agent：

jeo @react-grab capture-element --selector ".astryx-button"

返回：组件名称、源文件、行号、HTML 结构。

常见任务

任务 1：按照 Astryx 模式创建新组件

# Generate a new component scaffold
astryx generate component MyCard

# Or use the CLI directly
npx @astryxdesign/cli component --name MyCard --destination src/components

任务 2：自定义现有组件

# Swizzle (eject) the Button component
astryx swizzle Button

# Edit src/components/Button.tsx as needed
# Your customizations survive library upgrades

任务 3：设置深色模式

添加 prefers-color-scheme 检测：

import { ThemeProvider } from '@astryxdesign/core'

export function App() {
  const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches
  
  return (
    <ThemeProvider theme={prefersDark ? 'dark' : 'light'}>
      <MyApp />
    </ThemeProvider>
  )
}

Astryx 会自动处理 CSS 变量切换。

任务 4：从其他设计系统迁移

Astryx 的 cva（class variance authority）和 StyleX 工具可与其他 CSS 框架协同使用。可以从以下步骤开始：

1. 在当前设计系统旁安装 Astryx
2. 仅导入所需组件
3. 逐步用 Astryx 对应组件替换旧组件
4. 迁移完成后移除旧设计系统

任务 5：构建设计令牌使用方

导出 Astryx 设计令牌，以供其他工具（Figma、Zeplin）使用：

import { theme } from '@astryxdesign/core'

const tokens = {
  colors: theme.colors,
  spacing: theme.spacing,
  typography: theme.typography,
  breakpoints: theme.breakpoints,
}

export { tokens }

最佳实践

1. 直接从组件模块导入 — 在热代码路径中避免使用 barrel imports （参见 react-best-practices 规则 2.1）

2. 仅在必要时弹出组件 — 仅在需要深度自定义时才弹出组件；优先使用属性

3. 使用响应式属性 — Astryx 的响应式 API（columns={{ mobile: 1, desktop: 4 }}）性能出色；优先使用它，而非媒体查询

4. 优先组合，而非子类化 — 通过组合 Astryx 基元构建自定义组件，而非扩展类

5. 验证无障碍性 — 使用自动化无障碍工具（axe DevTools、Pa11y）测试弹出的组件

6. 在应用根节点设置主题 — 使用 <ThemeProvider> 包裹整个应用，而非单独包裹各个路由

7. 充分利用 StyleX — Astryx 的 StyleX 集成提供零运行时的 CSS-in-JS，且不增加打包体积

8. 为自定义组件编写文档 — 为自定义或弹出的组件添加 Storybook stories，方便 Agent 发现

故障排除

问：自定义主题颜色没有生效

答：确保 <ThemeProvider> 在应用根节点包裹整个组件树。 主题上下文不会跨门户或挂起的组件继承。

问：自定义组件属性出现 TypeScript 错误

答：Astryx 使用 TypeScript 5.0+。更新 tsconfig.json：

{
  "compilerOptions": {
    "target": "ES2020",
    "moduleResolution": "bundler"
  }
}

问：未检测到深色模式偏好

答：检查浏览器是否支持 prefers-color-scheme 媒体查询。 使用 window.matchMedia('(prefers-color-scheme: dark)').matches 进行检测。

问：库版本升级后，Swizzle 的组件没有更新

答：Swizzle 的组件在弹出时即被冻结。后续所有更新都由你负责。 请关注上游仓库，以便了解可能需要回移植的重大变更。

资源

• 官方文档：https://astryx.atmeta.com
• Storybook：https://facebook.github.io/astryx/storybook/
• 在线沙盒：https://facebook.github.io/astryx/sandbox/
• GitHub：https://github.com/facebook/astryx
• 贡献指南：https://github.com/facebook/astryx/wiki/Contributing
• API 约定：https://github.com/facebook/astryx/wiki/API-Conventions
• 设计约定：https://github.com/facebook/astryx/wiki/Design-Conventions
• 组件生命周期：https://github.com/facebook/astryx/wiki/Component-Lifecycle
• 博客：https://facebook.github.io/astryx/blog/

输出格式

当用户请求 Astryx 帮助时，返回一份简短摘要：

# Astryx Routing Brief

## Scope
- Task: setup | build-component | theme | migrate | swizzle | a11y-check | integrate
- Target: new-app | existing-app | design-tokens | agent-driven

## Recommended next move
- install-and-setup | scaffold-component | customize-theme | migrate-from-old-design-system | swizzle-component | run-a11y-tests | integrate-with-agent-skill

## Why
- 2-3 bullets grounded in the user's request

## Route-outs
- `deep-agents-core` for AI-driven component generation
- `react-best-practices` for component performance optimization
- `responsive-design` for layout verification across viewports
- `react-grab` for UI element context capture and inspection

Agent 最佳实践

1. 通过直接导出发现组件 — 不要遍历嵌套模块； Astryx 会在基础层级导出所有组件，方便 Agent 使用

2. 遵守 Swizzle 边界 — 仅在组件需要深度自定义时才使用 Swizzle； 简单修改请使用属性

3. 生成易于访问的代码 — Astryx 内置的 a11y 模式（标签、 ARIA、焦点管理）已就绪；不要重复添加

4. 测试响应式布局 — 使用 columns={{ mobile, tablet, desktop }} 并 在多个断点上验证；不要硬编码宽度

5. 保留主题设置 — 遵循用户主题上下文；不要硬编码颜色

6. 组合基础组件 — 组合使用基础组件（Button、Icon、Stack）构建 复杂 UI；不要创建庞大的单体组件

参考资料

• Astryx GitHub：https://github.com/facebook/astryx
• TypeScript 最佳实践：references/typescript.md
• StyleX 文档：references/stylex.md
• 组件 Swizzle 指南：references/swizzling.md
• 设置脚本：scripts/setup.sh
• 组件脚手架模板：scripts/scaffold-component.sh