arena

Dravensoft の Arena

1 つの契約から生まれた、React と Angular のための 1 つのデザインシステムです。

MIT ライセンス · React、Angular、Tailwind のための、トークン駆動型デザインシステムです。

提供内容

契約で API が定義されたコンポーネントです。 両方のフレームワークで同じ名前のコンポーネントが、共有 Tailwind レイヤー上で同じピクセルを描画します。メンバーの名前、受け取る値、デフォルト値、その意味は contracts/api/に記述されており、各レイヤーの型と表はそこから生成されるため、2 つのレイヤーが知らないうちに乖離することはありません。コンポーネントが描画するすべての値はデザイントークンを通じて解決されるため、コンポーネント内に16進数カラーも裸のピクセル値も含まれません。

リリースごとの監査ではなく、コンポーネントごとにアクセシビリティを保証します。 各コンポーネントは、実装するパターンを宣言します。その大半は WAI-ARIA オーサリングプラクティスに基づいています。対応するロール、応答するキー、フォーカスの移動先、コンポーネントを閉じる操作を定義します。未対応の要件があれば、その理由とともに記録されます。コンポーネントが宣言したパターンに応答しなくなった日には、bun run check:behaviourが失敗します。

プロジェクトらしさを決めるスタイルカーネルです。 形状、余白、太さ、奥行きに関する問いは Arena が定め、答えはプロジェクトが記述するスタイルプラグインが担います。Arena に同梱される見た目も、そのようなプラグインの 1 つにすぎず、基盤となるものではありません。パレットとフォントはarena.config.jsonに記述し、各パッケージに付属するarenaコマンドが、パッケージに含められない唯一のスタイルシートへと変換します。Arena が提供するのは言語であり、スキンではありません。 Arena 独自の色がビルドに入り込むこともありません。既存の見た目を出発点にするプロジェクトは、 plugin-style-store/catalogue/INDEX.mdに並ぶスタイルプラグインから選べます。このカタログには、実際の製品で評価されたスタイルプラグインが 1 行に 1 つずつ掲載されています。

見つけてもらう必要がある製品のためのメタデータです。ほとんどの製品には、これはありません。 Angular レイヤーは、受け取ったルートに基づいて@dravensoft/arena-angular/metadataでドキュメントの<head>を書き込みます。タイトルの組み立て、説明、canonical、og:*の 2 つのプロパティを扱い、明示されるまでルートをインデックス登録しません。このインポートパスは 2 つ目のエントリーポイントであり、メタデータを必要としないプロジェクトに、その背後にあるルーターが導入されることはありません。React は<head>を一切書き込みません。また、両方のレイヤーは、描画するパンくずリストをschema.orgの形式で公開します。

エージェントが操作できる理由

APIは段落ではなく契約ファイルであり、コンポーネントが適用するパターンや、スタイルプラグインが応答する役割も同様です。ゲートは、コード、ドキュメント、公開済みパッケージがそれらに従っているかを確認します。このリポジトリを渡されたエージェントは、Arenaについて推測しません。これから書こうとしている内容を規定する契約を読み、間違えたときはゲートが知らせます。

これにより、ルールは努力目標ではなく、強制力を持つものになります。これらのルールはそれぞれ contracts/design/AGENTS.md で定められ、 skills/design/SKILL.md を通じてビルダーに渡されます。このファイルでは各ルールをすべて記述し、ゲートがあなたのソースのどれを読み取るかを示しています。

• スタイル設定レイヤーはトークンのみです。
• Arenaコンポーネントに指定できるのは、語彙にあるクラスのみです。
• 外観は語彙にあるクラスであり、メンバーではありません。
• Dangerはアウトラインであり、塗りつぶしではありません。
• ビューごとにプライマリーアクセントは1つです。
• どのサーフェスにもグラデーションは使いません。
• プロダクトにもコピーにも絵文字は使いません。
• アイコンはPhosphorのクラス名文字列で、Arenaのコンポーネントまたは ArenaIconが描画します。生のph-*要素は何も描画しません。
• Arenaコンポーネントを、ルーター独自のリンクでラップしてはいけません。
• Arenaが描画するアンカーは、アクティベーションを分割します。
• コントロール上で始まった押下は、そのコントロールにとどまります。
• テーマは2つで、ダークが先です。
• チャートが示すのは、アイデンティティか意味のどちらか一方であり、両方ではありません。
• コピーは、プロダクトの言語で、フォーマルかつ直接的に書きます。
• 必須メンバーが存在しない場合は、呼び出し元の不具合です。
• リスナーをバインドしたか、スロットを埋めたかによって、レンダリングが行われることはありません。
• 一部のコンポーネントは、メンバーではなくメソッドで応答します。

インストール

bun add @dravensoft/arena-react     # or @dravensoft/arena-angular

インストールはこれで完了です。 Bunは、プロジェクトに不足しているピア依存関係をインストールします。Yarnを含む、ピア依存関係をインストールしないパッケージマネージャーでは、install.mdにあるコマンドのように、依存関係を明示する必要があります。アイコンフォントはピア依存関係ではありません。arena buildが、ArenaIconの描画に使うスプライトを書き出します。 install.mdにはレイヤーごとのコマンドが一覧され、以下のレイヤーページには各パッケージが宣言するピア依存関係が記載されています。

次に、npx --no-install arena init（またはpnpm exec arena init、bunx --no-install arena init）を実行します。これにより、サンプルのarena.config.jsonがコピーされ、ビルドスクリプトが設定されます。その後、arena buildが書き出したものをインポートします。 skills/design/references/install.mdでは、ReactとAngularの両方について説明を始め、設定とコマンドへのリンクを掲載しています。npmに表示されるページは導入となる内容で、同じリファレンスにリンクする質問一覧をまとめています。

MCP経由

{
  "mcpServers": {
    "arena": { "command": "npx", "args": ["-y", "@dravensoft/arena-mcp"] }
  }
}

@dravensoft/arena-mcpが言語を届けます。Model Context Protocolを扱うエージェントに、ルーター、リファレンス、すべてのコンポーネントドキュメントを、リソースとツールとして提供します。提供されるレイヤーは、プロジェクトにインストールしたものです。コンポーネントパッケージには、コード、スタイルシート、自分のマークアップが従う契約が含まれますが、説明文は含まれません。

コーパスと、それが説明するコンポーネントは別々の2つのパッケージであり、バージョン番号も2つあります。そのため、互いに食い違うことがあります。arena_startは、プロジェクト内のArenaパッケージのバージョンを読み取り、サーバーのバージョンと比較して、異なる場合はその旨を伝えます。食い違いがある場合、正しいのはコンポーネントで、古いのはテキストです。

Claude Codeプラグインとして

/plugin marketplace add dravensoft-dev/arena
/plugin install arena@dravensoft
/reload-plugins

更新

/plugin marketplace update dravensoft   # refresh the catalog: learns a new version exists
/plugin update arena@dravensoft         # update the plugin you actually have
/reload-plugins                         # apply it to the running session

**1つのバージョンは、1つのコミットを意味します。**各リリースはgitタグから提供され、マーケットプレイスのエントリーではsource.refがvX.Y.Zに固定されています。

スタンドアロンのエージェントスキルとして

エージェントに skills/design/SKILL.md を渡してください。これはルーターで、各質問に対して1つのファイルを提示します。このツリーをたどって案内するため、ファイルだけを受け取ったエージェントは質問を確認し、URLから回答にたどり着けます。クローンまたはプラグインを受け取ったエージェントは、パスから回答にたどり着けます。

コンポーネントパッケージはコードであり、その言語は上記3つのルートのいずれかでエージェントに届きます。 MCP サーバーをインストールするか、プラグインをインストールするか、スキルを渡すと、エージェントはガイドライン、コントラクト、各コンポーネントの使用ドキュメントを受け取ります。これにより、「Arena を統合する」というタスクを自分で最後まで完了できるようになります。

確認する

arena.dravensoft.org には、デザインガイドライン、キッチンシンク、各コンポーネントのプレイグラウンドページがあり、クローンもインストールも必要ありません。

同じ一覧から bun run demos を実行すれば、ローカルでも同じページを表示できます。また、scripts/build/AGENTS.md には、新しいクローンでページを利用できるようにするためにビルドが必要なものが記載されています。

エージェントはまず llms.txt を読み込みます。これは言語のルールへ、続いてフレームワークごとのコーパスである React と Angular へ案内します。意図的に分けています。各コンポーネントは両方の名称で提供されており、2つのドキュメントは互換性がありません。

依存関係

• フォントはセルフホストされ、CDN へのリクエストは発生しません。 Arena には Archivo / Familjen Grotesk / Spline Sans Mono の .woff2 バイナリが assets/fonts/ に含まれており、contracts/design-generated/fonts.generated.css で @font-face を宣言しています。そのため、フォントは読み込み元のページと同じオリジンから読み込まれます。パッケージを利用する側は、arena.config.json で独自の3つのフォントファミリーを指定します。src には、arena build が製品で描画されるものだけに切り詰めるフォントファイル、またはスタイルシートの URL を指定します。
• アイコンは Phosphor Icons（MIT）で、アイコンフォントはバンドルされていません。各コンポーネントは Phosphor のクラス文字列を受け取り、arena build が書き出すスプライトを使って ArenaIcon 経由でグリフを描画します。生の ph-* 要素を使うには、プロジェクトで @phosphor-icons/web をインストールする必要があります。アイコノグラフィーを参照してください。

使用するバージョン

パッケージが公開されるのは、パッケージに含まれる内容に変更があったときだけなので、2つのパッケージとプラグインでバージョン番号が異なる場合があります。 skills/design/references/versioning.md では、その意味を説明しています。

プロジェクトの最新アーティファクト

• リポジトリ／Claude Code プラグイン：13.0.0
• npm React パッケージ
• npm Angular パッケージ
• npm コントラクトパッケージ

次に進む場所

どの作業に取り組みますか？ 2 つの対象読者が読むファイルはほとんど重なりません。別の作業の分岐から始めると、短い質問のつもりが長い読書になってしまいます。

Arena を使って何かを構築する場合。 skills/design/SKILL.md が案内役です。そこから、frameworks/INDEX.md ではすべてのコンポーネントをまとめて確認でき、frameworks/<layer>/INDEX.md では使用するフレームワーク固有の名称で同じ一覧を確認できます。各コンポーネントの .prompt.md にはそのコンポーネントの使い方が記載されており、skills/design/references/install.md にはインストール方法が記載されています。

Arena 自体に取り組む場合。 AGENTS.md がその分岐の起点であり、そこから下のすべてに進めます。

• scripts/build/AGENTS.md：Arena を初めてコンパイルする方法です。マシンにあらかじめ用意しておくもの、新しいクローンで bun run demos や bun run check を実行できるようにするためのビルド、生成ファイルの一部が追跡対象で一部がそうでない理由について説明しています。サポート対象のプラットフォームは Linux と macOS です。Windows では WSL2 がサポート対象の方法であり、クローンは Linux ファイルシステム内に配置します。
• frameworks/PACKAGING.md：npm の配布経路について説明しています。ツリーから 2 つのパッケージをその場でどのように組み立てるか、公開される Arena にスキンが含まれない理由、利用者が代わりに何を宣言するのかについて説明しています。
• contracts/AGENTS.md：Arena の 3 つのコントラクトレベルと、このリポジトリ内のすべての項目を示すマップです。
• contracts/design/AGENTS.md：規範となるデザイン仕様です。ボイス、タイポグラフィ、色、間隔、モーション、危険状態の規約、アイコノグラフィ、テーマ設定について説明しています。その隣にある contracts/design/TokenTypes.md には、トークンを作成する人向けに DTCG トークンタイプのマップが記載されています。
• frameworks/react/AGENTS.md：React レイヤーです。
• frameworks/angular/AGENTS.md：Angular レイヤーです。最後のセクションから、上記のパッケージページにある導入方法へ進めます。
• frameworks/tailwind/AGENTS.md：共有 Tailwind レイヤーです。
• frameworks/demos/AGENTS.md：各コンポーネントのプレイグラウンドページを支えるフィクスチャです。そのページで誰もが記述するのは、この部分だけです。
• DOUBTS.md：Arena で負債とみなされるものと、その記録の保存場所について説明しています。

コントリビューションとセキュリティ

Arena では誰でもプルリクエストを送信できます。どの変更をそのままプルリクエストにできるか、どの変更がまず提案から始まるか、また変更によって破壊してはならないものについては、CONTRIBUTING.md を参照してください。脆弱性の報告先は SECURITY.md です。また、CODE_OF_CONDUCT.md には、このプロジェクトが遵守する Contributor Covenant が記載されています。

概要

Arena は、Dravensoft のすべてのソフトウェア製品が構築される共通のインターフェース言語です。MIT ライセンスで公開されており、誰でもこの言語を使って構築できます。