Agentが作った画面はそれぞれバラバラ？Astryxなら4ステップで統一できます

著者注：Astryx は Meta がオープンソースとして公開した、現在もベータ版の React デザインシステムです。コンポーネント、テーマ、Agent 向けのドキュメントをまとめて提供します。モデルではなく、大規模言語モデルのインターフェースも備えていません。

Claude Code、Cursor、Codex などの Agent を使って React の画面を変更すると、ページによってボタンの角丸が異なったり、オーバーレイをクリックして閉じられるダイアログと、閉じられないダイアログが混在したり、余白が 12px だったり 14px だったりすることがあります。原因はモデルの能力ではなく、Agent が参照できるデザインシステムがないことです。Agent はコンポーネント名や props を記憶頼みで推測するしかありません。Astryx は、人と Agent が同じコンポーネントリファレンスを参照できる仕組みを用意しています。人はドキュメントサイトを閲覧し、Agent は CLI、AGENTS.md、または MCP を通じて同じ内容を取得します。

この記事は、インストールコマンドを繰り返すだけの内容ではありません。 Meta が公式に公表している情報、第三者の著者による単発の試用結果、2026-11-10 時点で確認できるものの変動する件数を区別して説明します。また、現時点で移行に適さないプロジェクトも別途取り上げます。

この記事でわかること：読み終えると、Astryx が自分の React プロジェクトに適しているか判断し、人と Agent が同じ経路を利用できるよう、4 つの手順で接続する方法がわかります。

上の画像は、Astryx が公式に公開しているバナーです。実際の画面は、次の 3 つの公式ページで確認できます。この記事では、別途スクリーンショットを掲載しません。

ドキュメントサイト：astryx.atmeta.com
コンポーネント一覧（Storybook）：astryx.atmeta.com/storybook/
オンライン試用（Sandbox）：astryx.atmeta.com/sandbox/

Table of Contents

Astryxの要点：何であり、何ではないのか

まず、Astryxの位置づけをはっきりさせておきましょう。公式リポジトリではAstryxを、外観を完全にカスタマイズでき、「人とAgentが協力して働く」ことを前提に設計されたオープンソースのデザインシステムと説明しています。ライセンスはMIT、主な開発言語はTypeScriptです。READMEには「Currently in Beta」と記載されており、まだバージョン1.0には達していません。

要点	説明	あなたにとっての意味
技術基盤	公式情報によると、React 19以降とStyleXをベースにしています	React 18のプロジェクトはサポート対象外です
コンポーネントの規模	公式発表では、TypeScriptの型定義を備えたアクセシブルなコンポーネントが150種類以上あります	一般的なページに必要なパーツは、ひと通りそろっています
外観の設定方法	7種類の既成テーマがあり、トークンのレベルで色、フォント、角丸、アニメーションを変更できます	スタイルを変えるときは、各コンポーネントではなくテーマを編集します
Agentの利用方法	CLI、生成される`AGENTS.md`、リモートMCPを利用できます	Agentは記憶を頼りにコードを書くのではなく、ドキュメントを参照します
モデルとの連携	モデル連携機能は提供されていません。APIYI（apiyi.com）などを利用して、コーディングツール側でモデルに接続する必要があります	コンポーネントのレンダリング自体にモデルは必要ありません

Astryxの成り立ち：公式発表の内容

以下はすべてREADMEと、2026-06-18に公開された公式紹介記事（著者欄はAstryx team）に記載された内容であり、公式発表に基づくものです。独立した監査は行われていません。公式発表によると、AstryxはMeta社内で8年にわたって開発され、社内で最も広く使われている最大規模のデザインシステムであり、13,000以上のアプリを支えています。紹介記事では、デザインシステムはこれまで人が読むことを前提に作られてきたものの、現在はコードの多くをAgentが書くようになっているという見解も示されています。そのためAstryxは、完成後にAgent対応を追加するのではなく、最初からAIが操作できるように設計されています。

日付は2つあるため、混同しないようにしましょう。公式紹介記事の公開日は2026-06-18、@astryxdesign/coreが初めてnpmに登場したのは2026-06-24です。また、GitHubリポジトリが作成されたのは2026-01-09です。これはリポジトリの作成日であり、一般公開日ではありません。

Astryxと、パッケージ全体の置き換えやコピー＆ペーストとの違い

公式の紹介文では、よくある2つの手法と比較しています。以下の表は公式の位置づけをまとめたもので、ベンチマーク結果には触れていません。

手法	公式が指摘する問題	Astryxでの役割分担
パッケージ全体の置き換え：大企業のデザインシステム一式をそのまま使う	アプリにその企業のブランドイメージが持ち込まれる	システムが動作、アクセシビリティ、品質を担う
コピー＆ペースト：コンポーネントのコードを各プロジェクトに個別にフォークする	アップグレードが統一されず、アクセシビリティの確保は利用者自身に委ねられる	テーマが外観を担い、トークン層で変更する
Astryx：パッケージをインストールし、テーマで外観を変更する	まだベータ版で、0.xバージョンの段階	必要に応じて swizzle で個々のコンポーネントのソースコードを取り出す

READMEでは、さらに4つの違いを挙げています。1つ目は、内部構造がオープンであることです。コンポーネントは任意の階層で組み合わせられ、よく使う部品は直接エクスポートされています。また、swizzleを使えば特定のコンポーネントのソースコード一式をプロジェクトに取り込み、その後は自分で管理できます。2つ目は、スタイルが固定されないことです。classNameで上書きでき、Tailwind、CSS modules、通常のCSSのいずれも利用できます。3つ目は、ラッパーで包まずにカスタマイズできることです。テーマは本質的に、CSSカスタムプロパティの上書き設定です。4つ目は、API、ドキュメント、CLIが一体的に設計されていることです。人もAIアシスタントも、同じリファレンスを参照できます。

第三者による事例：ある作者のテーマ切り替え実験

LogRocketは2026-08-13、作者のChizaram Ken氏がClaude CodeをAstryxに接続して3つの画面を作り、さらにshadcn/uiでも同じ3つの画面を作った記事を公開しました。作者によると、テーマをneutralからgothicに切り替えた際、変更したのは2つのファイルと4行のコードだけで、コンポーネントファイルには手を加えなかったそうです。

これは作者自身による実験であり、ベンチマークでも、本記事での検証結果でもありません。実験は現行の0.7.11より前に行われており、当時のバージョンは現在のものとは異なります。「テーマとコンポーネントを分離する」という設計の一例として参考にできますが、性能に関する結論として捉えることはできません。

Astryxクイックスタート：4ステップで人とAgentを同じ流れに乗せる

以下の4ステップは、公式ドキュメントの「Getting Started」と「Working with AI」に基づいています。各ステップでは、ターミナルやファイルで行う作業と、完了の目安となる結果を説明します。以下は公式ドキュメントをもとに整理した手順であり、本記事では実際にインストールを行っていません。

第 1 ステップ：Astryx の 4 つのパッケージをインストールする

ターミナルで実行します：npm install @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex
続けて実行します：npm install -D @astryxdesign/cli
pnpm や yarn でも同様にインストールできます。パッケージ名は変わりません。
完了条件：package.json にこの 4 つのパッケージ名があり、react と react-dom のバージョンが 19 以上であること。

StyleX のインストールは必須です。core の peer dependency だからです。ただし公式の説明によると、Astryx が StyleX でスタイルを記述していることは利用者から見えないため、プロジェクトで StyleX に切り替える必要はありません。StyleX を自分で使う場合に限り、コンポーネントで xstyle を使ってスタイルを受け取れます。

第 2 ステップ：init で Agent 向けのドキュメントを生成する

ターミナルで実行します：npx @astryxdesign/cli init
このコマンドは対話形式ではないため、人、CI、スクリプト、Agent のいずれからでもそのまま実行できます。
完了条件：プロジェクトのルートディレクトリに AGENTS.md が作成されていること。プロジェクトに CLAUDE.md がすでにある場合は、同じ説明がそのファイルにも書き込まれます。

CLAUDE.md にも書き込む理由は、公式の説明によると、プロジェクトに CLAUDE.md がある場合、Claude Code は AGENTS.md を読み飛ばすためです。ツールを指定する場合は、--agent claude、--agent cursor、--agent codex、--agent all などのパラメーターを追加できます。Gemini CLI が読み込むのは GEMINI.md のみです。init はそこに AGENTS.md を参照する行を追加します。

ファイル内のマーカーで囲まれた Astryx のセクションは Astryx が管理します。init と upgrade が変更するのはこの部分だけなので、自分で書いた他の内容には影響しません。また公式によると、Agent は CLI のパスを誤って推測することがよくあります。そのため、package.json に次のスクリプトエイリアスを追加することが推奨されています。

スクリプト名：astryx
スクリプトの値：node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs
呼び出し方：npm run astryx -- component --list

第 3 步：CSS を導入し、neutral テーマでアプリをラップする

グローバル CSS で @astryxdesign/core/reset.css を読み込みます。
続けて @astryxdesign/core/astryx.css を読み込みます。
ターミナルで npx @astryxdesign/cli theme add neutral を実行し、アプリ側のテーマモジュールを生成します。
@astryxdesign/core/theme から Theme を読み込み、themes[defaultThemeSlug] を渡してアプリ全体をラップします。
@astryxdesign/core/Button から Button を読み込みます。公式サンプルでは、label と onClick の 2 つの props を使います。
完了の目安：ページに Astryx スタイルの Button が表示され、ブラウザー標準のボタンではなくなっていること。

この方法では、ビルドプラグインは不要で、PostCSS や Babel の設定も必要ありません。ただし、事前に確認しておきたい点があります。reset のスタイルは @layer reset、コンポーネントのスタイルは @layer astryx-base に配置されています。プロジェクトに既存のグローバル CSS、古い reset、Tailwind がある場合は、layer の順序を自分で宣言する必要があります。レイヤーに属さないスタイルは astryx-base を上書きするためです。これはセレクターの優先度とは関係ありません。公式では、ページ制作を始める前に npx @astryxdesign/cli docs migration/migration-setup にある 2 つのセクションを読むことを推奨しています。

すぐに使える 7 種類のテーマについて、公式の説明を以下にまとめました。特に好みがなければ、まず neutral を使うのがおすすめです。

テーマパッケージ	公式の説明	用途の例
`theme-neutral`	低彩度でミニマル	デフォルトの出発点
`theme-butter`	温かみのあるゴールドにブルーのアクセント	温かみのあるプロダクト
`theme-chocolate`	チョコレート色とキャラメル色	レトロなスタイル
`theme-gothic`	ダークのみ。インクとノワールのスタイル	ダークカラーのインターフェース
`theme-matcha`	草木を思わせるグリーン	ナチュラルなスタイル
`theme-stone`	砂岩のような温かみのあるニュートラルカラー	落ち着いた管理画面
`theme-y2k`	2000 年前後を思わせる、活気のあるスタイル	イベントページ、遊び心のあるプロダクト

第 4 ステップ：Agent に公式の 3 ステップに沿って UI を作らせ、必要に応じて MCP を接続する

init で生成されるルールでは、Agent に対し、UI を作成する前に次の順序で操作するよう求めています。

npx @astryxdesign/cli build "<想法>"：最も近いページテンプレート（少なくともアプリの外枠を含む）、代替テンプレート 2 つ、不足しているブロックやコンポーネントを返します。
npx @astryxdesign/cli template <名字> <路径>：テンプレートをプロジェクトに追加します。既存のフレームワークや余白は維持し、内容だけを置き換えます。
npx @astryxdesign/cli component <组件名>：使用する各コンポーネントの props とサンプルを確認します。
ルールには、禁止事項も記載されています。すべてのページをテンプレートから始めること、素の div を使わないこと、style={{}} を書かないこと、マジックナンバーではなくトークンを使うことです。
完了条件：Agent が参照するコンポーネント名と props が、独自に考えたものではなく CLI の出力に基づいていること。

公式が推奨する次の 3 つの質問で確認できます。Button の正しいインポートパスは何か、Dialog を簡単に閉じられないようにするにはどう設定するか、Selector で items を渡す prop はどれか。Agent が答えられない場合は、まず init を実行してください。正しい答えは、お使いの環境で CLI が出力した内容を基準にします。

リモートで調べる必要がある場合は、公式 MCP（https://astryx.atmeta.com/mcp）を接続できます。次の 2 つのツールが提供されています。コンポーネント、ドキュメント、テンプレートを検索する search(query) と、完全なドキュメントを取得する get(name) です。クライアントによって設定方法が異なります。

クライアント	設定方法	注意点
Claude Code	ターミナルで `claude mcp add --transport http astryx https://astryx.atmeta.com/mcp` を実行	サービス名は astryx
Cursor	`.cursor/mcp.json` に url のみを記載	リモートサービスでは type を指定しません
Cline	transport に `streamableHttp` を指定	`http` ではありません
Claude Desktop	設定画面の Connectors → Add custom connector を選び、URL を貼り付ける	設定ファイルにはローカルの stdio のみを記載
その他の汎用クライアント	type に `http` を指定し、url を追加	認識できない transport は無視されます。接続済みと表示されても、ツールが使えないことがあります

公式からは、このリモートアドレスの SLA や、サービスが利用できない場合の対応について説明されていません。CLI は同じドキュメントを利用するローカルの入口なので、MCP に接続できなくても CLI を引き続き利用できます。

コーディング Agent のモデルはどこから利用する？

デザインシステムはコンポーネントとドキュメントを担当しますが、コーディング Agent が実際にコードを生成するには、別途モデルを接続する必要があります。チームで Claude Code や Cursor などのツールに独自のモデルを提供する場合は、APIYI（apiyi.com）の OpenAI 互換インターフェースを利用できます。base_url に https://api.apiyi.com/v1 を指定し、モデル名にはその日のモデル一覧に記載された名称を設定してください。モデルの種類と料金は APIYI のモデル一覧を確認してください。利用可能なモデルは、一覧に掲載されています。

なお、コンポーネントはブラウザー上でレンダリングされるため、モデルのインターフェースは必要ありません。APIYI を利用するかどうかは、Astryx のインストールや実行には影響しません。

🚀 まずはここから：上記の4つの手順に沿って、新しいブランチにテンプレートページを作成してみましょう。そのうえで、同じモデルを使い、AGENTS.md がある場合とない場合のそれぞれで Agent にコードを書かせ、生成されたコンポーネント名や props を比較してみてください。APIYI（apiyi.com）では、新規ユーザー向けにこのような比較に使える無料のテスト枠を提供しています。

Astryx のリスクと移行に適さないケース

Astryx 自体のリスク

Astryx はまだ Beta 段階で、バージョン番号は 0.x です。2026-11-10 時点で、npm の latest は 0.7.11（2026-11-07 リリース）です。その前の安定版 0.7.10 は 2026-11-06 にリリースされており、安定版もほぼ毎日更新されています。アップグレード時には、プロジェクトで使用しているすべての @astryxdesign/* パッケージを同じバージョンにそろえたうえで、npx @astryxdesign/cli upgrade --from <旧的 core 版本> --apply を実行してください。各テーマには対応する core のバージョンが指定されているため、テーマのアップグレードを忘れると、テーマと core のバージョンが合わなくなります。パッケージマネージャーがリリースから一定期間を空けて新バージョンをインストールする設定の場合は、@astryxdesign/* の範囲全体を除外してください。pnpm では minimumReleaseAgeExclude に @astryxdesign/* を追加します。

グラフについては、@astryxdesign/vega と @astryxdesign/charts は npm の canary タグでのみ公開されており、安定版はありません。2026-11-10 時点の canary は 0.7.12-canary.dfd75a6 です。バージョン番号は latest より新しいものの、本番環境の依存関係として使用するのは避けてください。

APIYI 経由でモデルを利用する際のリスク

ここで扱うのは、コーディングエージェントによるモデル呼び出しのみです。リクエストは APIYI のゲートウェイを経由します。APIキーと費用は利用者自身が管理し、モデルの実際の性能は選択したモデルとゲートウェイからの応答によって異なります。Meta アカウントへのログインや、アカウントプールの利用ではありません。

現時点で移行をおすすめしないプロジェクト

React 18 を使い続けているプロジェクト：core の peer dependency では、react と react-dom の両方に 19.0.0 以上が必要です。
すぐに 1.0 の安定性が必要なプロジェクト：公式は現在 Beta としており、そのような保証は示していません。
安定版のグラフがすぐに必要なプロジェクト：グラフ関連パッケージは canary 版のみです。
最初からすべてのコンポーネントのソースコードを自分のリポジトリで管理したい場合：これはコピー＆ペーストで導入する方法にあたります。Astryx は通常、パッケージをインストールして利用し、必要に応じて swizzle で個々のコンポーネントのソースコードを取り出します。

Astryx の人気とバージョン：2026-11-10 時点の数値

以下は2026-11-10時点の数値です。今後変動するため、固定された事実として扱わないでください。

指標	数値	出典
GitHub stars	20,217	GitHub API `meta/astryx`
forks	1,536	GitHub API
未クローズの issue / PR	297 / 373	GitHub Search API（合計670件ですが、670個のバグを意味するわけではありません）
core の週間ダウンロード数	661,968回（2026-11-02〜11-08）	npm ダウンロード API。ユーザー数ではなく、ダウンロード回数です
core の過去30日間のダウンロード数	1,725,492回（2026-10-10〜11-08）	npm ダウンロード API

よくある質問（FAQ）

Q1：Astryx は Tailwind コンポーネントライブラリですか？

いいえ。公式ドキュメントによると、Astryx は React 19 以降と StyleX をベースにしており、コンパイル済みの CSS を配布しています。Tailwind と併用することもできます。`className` で外観を上書きできるほか、リポジトリの `apps/` ディレクトリには `example-vite-tailwind` と `example-nextjs-tailwind` のサンプルもあります。併用する場合は、前述の CSS レイヤーの順序に注意してください。

Q2：React 18 のプロジェクトで Astryx を使えますか？

使えません。バージョン 0.7.11 の core パッケージは、`react` と `react-dom` の両方で 19.0.0 以上を要求しているため、React 18 は条件を満たしません。まずプロジェクトを React 19 にアップグレードしてください。

Q3：MCP を接続しなくても、Agent は Astryx のドキュメントを利用できますか？

はい。`init` で生成される `AGENTS.md` とローカル CLI を使えば、build、template、component の3ステップを実行できます。MCP はリモートで検索するための別の手段にすぎません。Web版のチャットに内容を貼り付ける場合は、`–detail brief`、`–detail compact`、または `–dense` を指定すると、出力を短くできます。

Q4：facebook/astryx と meta/astryx は別々のリポジトリですか？

同じリポジトリです。2026-11-10時点で、`github.com/facebook/astryx` にアクセスすると301リダイレクトが返され、`github.com/meta/astryx` に転送されます。後者が正式なリポジトリのURLです。以前の記事にある facebook/astryx は、このリポジトリを指しています。

Q5：Astryx のチャートコンポーネントは本番環境で使えますか？

現時点ではおすすめしません。`@astryxdesign/vega` と `@astryxdesign/charts` は canary タグでのみ公開されており、README にも安定版がないと記載されています。本番プロジェクトでは、ひとまず既存のチャートライブラリを使い続けるのがよいでしょう。

Q6：アップグレード時に core だけを更新してもよいですか？

いいえ。公式では、プロジェクトで使用しているすべての `@astryxdesign/*` パッケージを同じバージョンにそろえるよう求めています。そうしないと、テーマと core のバージョンが合わなくなります。アップグレード後に `upgrade –from <旧バージョン> –apply` を実行すると、古くなった `AGENTS.md` 内の Astryx セクションも更新されます。

Q7：Astryx の利用にモデル API は必要ですか？APIYI とはどのような関係ですか？

コンポーネントのレンダリングにモデル API は必要ありません。モデルとの接続が必要になるのは、コーディング Agent にコードを書かせる場合だけです。この作業は Claude Code や Cursor などのツールが担います。チームでモデルを用意する場合は、APIYI（apiyi.com）で1つの APIキーを使い、複数の主要モデルを呼び出せます。APIYI と Meta、Astryx の間に提携関係はありません。

Q8：特定のコンポーネントのソースコードを自分のリポジトリにコピーして、変更できますか？

できますが、標準的な使い方ではありません。swizzle を実行すると、単一コンポーネントのソースコード一式がプロジェクトに取り込まれます。その後は自分でコードを管理し、今後のアップグレードにも対応する必要があります。公式も `theme eject` の利用は、ソースコードを独立して管理する必要が明確にある場合に限るよう推奨しています。

Astryxの要点（Key Takeaways）

位置づけ：Metaがオープンソースで公開しているReactデザインシステムです。MITライセンスで、現在もBeta版の0.x系です。
役割分担：システムが動作とアクセシビリティを担い、テーマが見た目を担います。テーマを変更しても、コンポーネントのファイルを編集する必要はありません。
必須条件：React 19以降が必要です。また、peer依存関係としてStyleXをインストールする必要があります。
Agentの利用手順：まずinitを実行してAGENTS.mdを生成し、その後、build → template → componentの順にページを作成します。
MCPは任意：リモートアドレスはhttps://astryx.atmeta.com/mcpです。ローカルCLIからも同じドキュメントを参照できます。
アップグレードのルール：すべての@astryxdesign/*パッケージを同じバージョンにそろえてアップグレードします。チャートパッケージはcanary版のみです。
モデルは別途接続：コーディングAgentで使うモデルは、APIYI（apiyi.com）を通じて一元的に接続できます。

まとめ：AstryxでAgentが一貫性のあるUIを作れるのか

Agentが作るUIに一貫性がないのは、コンポーネント名やpropsを推測するしかないことが根本的な原因です。Astryxは、コンポーネント、テーマ、Agent向けのドキュメントを1つのシステムにまとめることで、この課題に対応します。

導入は4ステップ：4つのパッケージをインストールし、initを実行して、CSSを読み込み、アプリをThemeで包みます。Agentには、3つの手順で情報を確認してから実装するよう指示します。
情報の出どころを区別する：13,000以上のアプリでの利用や、社内で8年間使われているという情報は公式発表です。テーマの変更が4行で済むという話は、第三者による一度の試行に基づいています。スター数とダウンロード数は、2026-11-10時点の数値です。
まず適合性を確認する：プロジェクトがまだReact 18を使っている場合、安定版のチャートが必要な場合、または1.0のリリース保証を求める場合は、移行を急がず、しばらく様子を見るのがよいでしょう。

プロジェクトがすでにReact 19を使っていて、Agentがpropsを作り上げてしまうのを減らしたい場合は、まずブランチを切り、テンプレートを使ったページを1つ試してみましょう。コーディングAgentで使うモデルはAPIYI（apiyi.com）経由で接続できます。無料のテスト枠を使って、同じAGENTS.mdのもとで複数のモデルが生成するコードを比較できます。

📚 参考資料

Astryx GitHubリポジトリ：README、パッケージ一覧、テーマ一覧、設計原則
リンク：github.com/meta/astryx
説明：公式発表の主な情報源です。facebook/astryx はこちらにリダイレクトされます。
Astryx公式紹介記事：2026-06-18公開の設計理念に関する説明
リンク：astryx.atmeta.com/blog/introducing-astryx
説明：パッケージ全体の置き換えとコピー＆ペーストという2つの手法との比較は、この記事に基づいています。
Getting Started と Working with AI のドキュメント：インストール、テーマ、init、MCPの設定
リンク：astryx.atmeta.com/docs/getting-started、astryx.atmeta.com/docs/working-with-ai
説明：本記事で紹介する4つの手順の公式な根拠です。
Astryx v0.7.11 リリースノート：現行の安定版とアップグレード方法
リンク：github.com/meta/astryx/releases/tag/v0.7.11
説明：すべてのパッケージでバージョンを統一する必要があることを示す原文です。
LogRocketの比較記事：2026-08-13公開、著者 Chizaram Ken
リンク：blog.logrocket.com/astryx-vs-shadcn-meta-ai-react-claude
説明：第三者による単一の試験で、対象バージョンは0.7.11より前のものです。

著者：APIYI 技術チーム
技術に関するお問い合わせ：コーディングエージェントとモデルの連携についてお困りの場合は、APIYI公式サイトのトップページからお問い合わせください。

Agentが作った画面はそれぞれバラバラ？Astryxなら4ステップで統一できます