Astryx で AI 生成フロントエンドをデザインシステムへ接続する方法：React コンポーネント、テーマ、受け入れ条件

AI に1ページを生成させるのは難しくありません。難しいのは2ページ目、3ページ目も正しい色、余白、コンポーネント状態、アクセシビリティ属性、操作境界を守らせることです。Astryx は Meta のオープンソース React デザインシステムです。公式リポジトリでは Beta とされ、150以上のアクセシブルなコンポーネント、テーマ、ダークモード、テンプレート、CLI を提供し、CSS カスタムプロパティでテーマを上書きできます。公式リポジトリ

Astryx を Agent に接続する目的は、モデルを自由にデザインさせることではなく、人と Agent が同じコンポーネントとドキュメントを使うことです。

導入が適切かを先に判断する

次の条件があれば適しています。

React プロジェクトに複数の管理画面があり、AI 生成 UI の見た目がぶれ始めている。
ボタン、フォーム、ダイアログ、空状態、ダークモードを統一したい。
Agent に CSS を毎回書かせず既存コンポーネントを組み合わせさせたい。
Beta 依存を隔離検証し、バージョン固定できる。

React ではない、または成熟した社内ライブラリがあるなら、流行のために作り直さないでください。コンポーネント優先、token 優先、スクリーンショット受け入れの方法を既存システムへ移す方が現実的です。

導入と最小テーマ

公式例のパッケージ名は次のとおりです。

1
2


npm install @astryxdesign/core @astryxdesign/theme-neutral
npm install -D @astryxdesign/cli

最初に独立ブランチまたは小さなページで build、スタイル読み込み、ダークモードを確認してからアプリ入口へ広げます。Agent にグローバルスタイル、ルートシェル、既存 token ファイルを直接置換させないでください。

テーマはブランド制約を表すもので、ページごとの自由な上書きではありません。変更可能な色、角丸、フォント、余白をプロジェクト規則に書き、Agent に「何を再利用すべきか」を伝えます。

アプリの外枠ではなく小さなページから始める

設定ページ、フィルターサイドバー、詳細カードなど1ルートから始めます。現在のフォント、余白、色 token、操作状態、コンポーネントを列挙し、その一部を Astryx で再構築させます。ルーティング、データ取得、権限判定、グローバルスタイル入口は残します。デザインシステムが担うのはコンポーネントとテーマであり、業務移行ではありません。

ローカル検証の順序を固定します。依存を入れて開発サーバーを起動し、ライト／ダークモードを確認し、Tab でフォーム、ダイアログ、ボタンをたどり、モバイル幅に縮め、最後に既存テストまたは build を実行します。問題はそのコンポーネントの変更に記録し、多数ページの後で token 上書き、CSS 優先順位、フォーカス競合を発見しないようにします。

小ページが安定したら、許可パッケージ、テーマ入口、import 形式、変更禁止のグローバルファイルを記録し、参照実装にします。後続の Agent タスクはこれを参照します。

Agent のプロジェクトレベル制約

AGENTS.md、CLAUDE.md、または Skill に次のような規則を置きます。

1
2
3
4
5


- 新页面优先使用 @astryxdesign 现有组件；新增自定义组件前先说明原因。
- 不新增全局 CSS reset，不修改既有主题 token。
- 所有表单字段必须有可见 label、错误态和禁用态。
- 完成后提供桌面和窄屏截图，并列出新增组件与交互状态。
- 不以截图相似为唯一验收；保留键盘操作和语义结构。

これは「デザインシステムでダッシュボードを作る」より実行可能です。禁止事項、再利用の道筋、成果物が明確で、レビュー担当者もコンポーネントライブラリを迂回していないか確認できます。

入力、出力、禁止事項をタスクに書く

実タスクにはページ範囲、利用可能なデータ、変更可能なファイル、必要なスクリーンショットを含めます。たとえば src/features/orders/FilterPanel.tsx のみ変更、既存クエリパラメータを再利用、依存追加・ルート変更・theme.ts 変更なし、デスクトップと狭幅画面のスクリーンショット、Button、Select、Dialog の状態一覧、という指定です。これにより Agent が見た目のために global reset、状態管理、API 層を変えることを防げます。

複雑なコンポーネントでは、先に構造案を出させます。どの区画があり、どの Astryx コンポーネントに対応し、どの loading/error/empty 状態が必要かを確認してからコードに進みます。ライブラリで表現できない設計なら、設計を調整するか新コンポーネントの保守担当を決め、使い捨て CSS を入れません。

4層の受け入れで UI のぶれを減らす

層	確認事項
コンポーネント	Button、Input、Dialog などを再利用し、状態が揃っているか
テーマ	許可された token または CSS 変数だけで見た目を変えているか
操作	キーボードフォーカス、loading、error、empty 状態が使えるか
納品	build が通り、重要ページのスクリーンショットとコンポーネント一覧があるか

視覚的一貫性はピクセルのコピーではありません。安定させるべきなのはアクセシブルな意味構造、状態機械、テーマの出所、保守可能なコンポーネント境界です。

繰り返せる受け入れフロー

マージ前に diff を確認します。ライブラリを回避するグローバルスタイル、固定したブランド色、無関係なファイル変更がないかを見ます。ブラウザで通常データ、loading、空データ、API 失敗を確認し、フォームは必須、形式エラー、無効、送信中も確認します。通常状態だけのスクリーンショットでは多くの回帰を隠します。

最後にキーボードで重要フローを完了します。Tab 順が理解でき、フォーカスが Dialog に入り出られ、エラーが項目に関連付き、色コントラストが十分かを確認します。PR テンプレートに置けば、Agent 生成ページも同じ基準で扱えます。

よくある誤解

Beta を全サイト改修の理由にする：最初にバージョンを固定し、単一領域で更新コストを検証する。
Agent にコンポーネント内部を直接変更させる：組み合わせとテーマ上書きを優先し、必要なときだけソースを引き継ぐ。
ページごとに一時的 CSS を書く：デザインシステムはパッケージ名だけになり、後続 Agent を制約できない。
スクリーンショットだけで受け入れる：tab 順、エラー表示、押せないボタンは分からない。

まとめ

Astryx は人と Agent が共通のフロントエンド言語を使うための制約を作れます。少数ページでコンポーネント、テーマ、受け入れフローを検証し、規則をプロジェクトファイルへ定着させてください。