astryx

Astryx — エージェント対応デザインシステム

Astryx は、Meta で 8 年以上にわたり 13,000 以上のアプリで構築・実証されたオープンソースのデザインシステムです。アクセシビリティに配慮した 150 以上の React コンポーネント、ブランドレベルのテーマ設定、ダークモード、テンプレート、CLI を備えています。すべて、チームが現在どのように開発しているか、つまり 人と、そのそばで協働するエージェントによる開発を想定して設計されています。

Astryx と StyleX を基盤とする Astryx は、内部構造の公開（非公開のトップレベル API がなく、コンポーネントを完全に組み合わせ可能）、スタイリングのロックインなし（独自の CSS を使用でき、特別なビルドプラグインも不要）、エージェント対応（コンポーネントを基盤レベルでエクスポートすることで、AI アシスタントが理解し、拡張できる）を重視しています。

現在ベータ版です

このスキルを使う場面

• コンポーネントライブラリを構築または拡張していて、Meta で実証された本番環境向けのパターンを取り入れたい
• ダークモード、テーマ設定、テンプレートを備えた、本番ですぐに使えるアクセシビリティ対応の React コンポーネントを 150 以上必要としている
• 人と AI による共同作成の両方をデザインシステムでサポートする必要がある — エージェントがコンポーネントを安全に理解、変更、拡張できるようにしたい
• スタイリングのロックインを避けたい — デザインシステムのビルドプラグインと競合することなく、独自の CSS フレームワーク（Tailwind、emotion、vanilla CSS）を使いたい
• コンポーネントのスウィズリングが必要 — ライブラリをフォークせずにカスタマイズできるよう、コンポーネントのソース全体をプロジェクトに取り込む機能が必要
• チームが、固定されたトップレベル API よりも内部構造の公開とコンポーザビリティを重視している
• 13,000 以上のアプリケーションを通じた、Meta の 8 年以上にわたるデザインシステムの進化を活用したい

このスキルを使わない場面

• シンプルな単発アプリケーションを構築する場合（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 エージェントがコンポーネントの構造を理解し、安全に変更できる
• フレームワークによる制約に悩まされることがない

対照例： 多くのデザインシステムでは、独自の複合コンポーネント構造に縛られます。Astryx なら、必要に応じて複合コンポーネントを自分で構築できます。

スタイリングのロックインなし

Astryx は StyleX を使ったビルド済み CSSを提供しますが、次のことも自由に行えます。

• スタイリング全体を Tailwind CSS のユーティリティに置き換える
• Astryx のコンポーネントと独自の CSS フレームワークを組み合わせる
• CSS モジュールや emotion を使ってコンポーネントのスタイルを上書きする
• 独自のスタイルを構築する際に、Astryx をコンポーネントの構造を知るための参考として使う

ビルドプラグインは不要です。スタイリングライブラリをバンドルに強制的に組み込むこともありません。

エージェント対応

すべてのコンポーネントは、AI との共同制作を前提に設計されています。

• フラットなエクスポート構造（エージェントはネストされた API をたどらずにコンポーネントを見つけられます）
• すべてのコンポーネントで一貫したプロパティの命名と型付け
• TypeScript を最優先しているため、型定義がエージェントのコード生成を支援します
• アクセシビリティのパターンを組み込み済み（エージェントがアクセシビリティに準拠したコードを生成できます）
• 合成可能なプリミティブ（エージェントは安全に拡張できます）

アーキテクチャの概要

ディレクトリ構成

ディレクトリ	用途
packages/core	150 以上の React コンポーネント、テーマエンジン、フック
packages/cli	スキャフォールディング、スウィズリング、テンプレート生成
packages/build	ビルドツール、アセット最適化、CSS バンドル
packages/themes	ビルド済みのブランドテーマ（ライト、ダーク、コントラスト強化）
apps/docsite	ドキュメント一式（astryx.atmeta.com）
apps/storybook	インタラクティブなコンポーネントエクスプローラー
apps/sandbox	素早いプロトタイピングのためのライブプレイグラウンド

主なエクスポート

// 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：コンポーネントの合成

トップレベル API に縛られることなく、Astryx のコンポーネントを自由に組み合わせられます。

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

エージェントスキルとの連携

deep-agents-core

AI 主導のコンポーネント設計システムを構築する際に使用します。

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

エージェントは Astryx のパターンに従って、新しいコンポーネントをスキャフォールディングできます。

react-best-practices

Meta のパターンに基づいて Astryx コンポーネントのパフォーマンスを最適化します（ルール 2.1：バレルインポートを避ける、ルール 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 要素のコンテキストを正確に取得し、エージェントに渡します。

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（クラスバリアンスオーソリティ）と 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. コンポーネントのモジュールから直接インポートする — 頻繁に実行されるコードパスではバレルインポートを避けます（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 のストーリーを追加します

トラブルシューティング

Q: カスタムテーマの色が適用されません

A: <ThemeProvider> がアプリのルートでコンポーネントツリー全体をラップしていることを確認してください。 テーマコンテキストは、ポータルやサスペンド中のコンポーネントには継承されません。

Q: カスタムコンポーネントの props で TypeScript エラーが発生します

A: Astryx は TypeScript 5.0 以降を使用します。tsconfig.json を更新してください。

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

Q: ダークモードの設定が検出されません

A: お使いのブラウザーで prefers-color-scheme メディアクエリーがサポートされていることを確認してください。 検出には window.matchMedia('(prefers-color-scheme: dark)').matches を使用してください。

Q: ライブラリのバージョンが上がっても、スウィズルしたコンポーネントが更新されません

A: スウィズルしたコンポーネントは、切り離した時点の状態で固定されます。それ以降の 更新はすべてご自身で行う必要があります。バックポートしたい破壊的変更がないか、上流リポジトリを確認してください。

リソース

• 公式ドキュメント: 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

エージェント向けベストプラクティス

1. 直接エクスポートからコンポーネントを見つける — ネストされたモジュールをたどらないでください。 Astryx はエージェントが簡単に使えるよう、すべてのコンポーネントをベースレベルでエクスポートします。

2. スウィズルの適用範囲を守る — コンポーネントに高度なカスタマイズが必要な場合にのみスウィズルし、 単純な変更には props を使用してください。

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
• コンポーネントのスウィズルガイド: references/swizzling.md
• セットアップスクリプト: scripts/setup.sh
• コンポーネントのひな形テンプレート: scripts/scaffold-component.sh