Design System MCP

onsystem

コーディングエージェントがデザインシステムに準拠するよう支援します： 編集やプルリクエストのたびに、パレットの色、ネイティブ要素、システムに不足している API を検出し、修正方法も提示します。デザインシステムのパッケージで一度設定すれば、モノレポ内のすべてのアプリで利用できます。ローカルで動作し、@shadcn/lint と併用できます。

React デザインシステムパッケージを持つデザインシステムチームやプラットフォームチーム向けに構築されています。shadcn/ui アプリなら設定不要でデモを試せます。以前の名称は @dgesteves/design-system-mcp です（変更点）。

GitHub Action を使用していますか？ uses: dgesteves/onsystem@v0 はプルリクエストで変更された行をチェックします。CI とベースラインをご覧ください。

以下でも動作します

ウェブサイトとドキュメント： onsystem.vercel.app。自分のコードをチェックできるプレイグラウンドもあります。

フィードバックをお待ちしています： リリースに関するフィードバックのスレッドで問題が発生する箇所をお知らせください。ロードマップで今後の予定を確認したり、最初に取り組むのに適した課題に着手したりすることもできます。onsystemが役に立ったら、スターを付けていただけると、ほかの人にも見つけてもらいやすくなります。

https://github.com/user-attachments/assets/900cc1fa-387c-4e76-a524-a818521dd1a0

_{ウェブサイトでは、エージェントが設定カードのドラフトを作成し、check_uiが11件の問題とそれぞれの修正案を見つけ、エージェントがそれらを適用します。続いて、プラグインを使った実際のClaude Codeセッションでは、Claudeがコードを書く前にコンポーネントを検索し、check_uiが合格します。最後に、ベンチマークです。}

問題

コーディングエージェントは、デザインシステムではなく、学習データをもとにUIを作成します。設定カードを頼むと、bg-[#ef4444]やp-[13px]、ネイティブの<button>、destructiveしかないButtonに対するvariant="danger"、そしてシステムがCardHeaderをエクスポートしているのに<Card.Header>が出てきます。上のデモ用ドラフトでは、tscが11件の問題のうち3件を報告し、残りは誰かに時間があるときにレビューで見つかります。エージェントにデザインシステムを説明するのも役立ちますが、重要なのは実際に書かれたコードを編集時とプルリクエスト時にチェックすることです。

チェック内容

onsystem は TypeScript コンパイラーを使って、ソースコードからコンポーネント、cva と tv のバリアント、パーツ、トークンを読み取り、それらに照らして .tsx と .jsx をチェックします。各検出項目には、ルール ID、場所、修正方法が示されます。トークンはスタイルシート、DTCG 2025.10 files or a DESIGN.md から取得でき、onsystem export でいずれかの形式として書き出せます。

ルール	デフォルト	検出内容
no-unknown-component	error	存在しないコンポーネントとパーツ（<Card.Header>、タイプミスなど）
no-unknown-prop	error	コンポーネントが受け取らないプロパティ（tone、isDisabled）
no-unknown-variant	error	バリアントにない値（variant="danger"）
prefer-design-system-component	error	デザインシステムに対応するコンポーネントがあるネイティブ要素（<button> → <Button>）
no-hardcoded-color	error	Hex、rgb、hsl、oklch、Tailwind のパレットカラー（bg-gray-100 → bg-muted）
icon-button-accessible-name	error	アクセシブルな名前のないアイコンのみのボタン
no-hardcoded-spacing	warn	任意のパディング、マージン、ギャップ（p-[13px] → p-3）
no-hardcoded-radius	warn	任意の角丸（rounded-[7px] → rounded-sm）

誤検出の頻度。 corpus ジョブでは、コミットに固定された12の公開リポジトリ（Documenso、Dub、Cal.com、midday、Flowise など）に対して、依存関係をインストールせずに check を実行します（MUI を使う2つのアプリでは MUI をインストールします。計24回の実行で、異なる検出項目は14,539件です）。その検出項目からルール別に層化したランダムサンプル80件を、コードだけを基にラベル付けしました。人間ではなく、AI レビュアー（Claude Opus 5.5）がブラインドでラベル付けしています。正しいものが57件、議論の余地があるものが14件、誤検出が9件でした。誤検出率は11.2％（95％ Wilson 区間：6.0～20.0％）で、全検出項目に占める各ルールの割合で重み付けしてもほぼ同じです（11.0％）。その多くは no-hardcoded-color に由来します（サンプル65件中7件）。プロジェクト独自のデザインシステムがすでに使っている値を「議論の余地あり」と数えると、誤検出は80件中6件です（7.5％、3.5～15.4％）。サンプル には、各ラベルとその理由、ラベラーのメモ、これらの数値を算出したスクリプトが含まれています。リリース済みのコードでコンポーネント、プロパティ、バリアントが新たに定義されることはほとんどありません。また、依存関係がない場合、no-unknown-prop はプロパティを解決できないコンポーネントをスキップします。そのため、この3つのルールの検出は corpus 全体で56件、そのうち55件が MUI アプリの Flowise で、サンプルでは3件でした。いずれも正しい結果でしたが、独自の誤検出率を算出するには件数が少なすぎます。corpus の以前のラベルは、検出項目を見られる AI レビュアーがブラインドではない状態で付けたものであり、真陽性が報告されなくなった場合や、修正済みの誤検出が再発した場合、ジョブは失敗します。chatbot の components/ai-elements など、shadcn レジストリからインストールしたコードには、まだラベルがありません（shadcn レジストリのコード）。ルールのリファレンスでは、各ルールの例と、検出項目を抑制する方法を確認できます。

クイックスタート

Node.js 20.19 以降を使い、アプリのフォルダーまたはモノレポのルートから実行します。

npx -y onsystem inspect   # what it found; --explain says why
npx -y onsystem check .   # the same check the agent and CI run
npx -y onsystem init      # write the config, and offer a baseline

モノレポのルートで実行すると、inspect はすべてのアプリとデザインシステムのパッケージを一覧表示し、check は各ファイルをそのファイルが属するプロジェクトのデザインシステムに照らしてチェックします。デザインシステムのパッケージで実行すると、init は依存しているすべてのアプリで使えるように設定します。アプリ側に設定は不要です。ワークスペースのパッケージとして使う場合も、npm からインストールする場合も同様です。インストールしたアプリは、パッケージが公開するソースからコンポーネントを読み込むか、コンパイル済みの dist/ のみを公開する場合は型宣言（.d.ts）から読み込み、どちらの場合もすべてのルールが適用されます（init は files リストをチェックします）。コンパイル済みコードを公開し、型宣言を公開しないパッケージでは、トークンのルールは適用されますが、コンポーネント、プロパティ、バリアント、ネイティブ要素のチェックは行われません。

新しい create-next-app では、テンプレートページにハードコードされた色があるため、最初の check . はすでに失敗します。init ではそれらをベースラインとして記録できるので、新たに見つかった問題だけが失敗の対象になります。shadcn レジストリからインストールした components/ai-elements などのフォルダーは、他者のコードです。shadcn レジストリのコードでは、それらをチェックする方法や対象外にする方法を説明しています。

Claude Code。 プラグインにはフック、MCP サーバー、スキルが含まれています。

/plugin marketplace add dgesteves/onsystem
/plugin install onsystem@dgesteves

.tsx または .jsx ファイルに Write または Edit が行われるたびに、フックはそのファイルに対して onsystem check を実行します。エラーは修正方法とともにブロッキングエラーとして Claude に返されるため、Claude は次に進む前にファイルを修正します。警告は注記として返されます。デザインシステムのないプロジェクトでは何も表示されません。Codex も同じプラグインをインストールし、フックは apply_patch が変更したファイルをチェックします。実行内容と対象。

Cursor または VS Code。 するか、設定をコミットしてください。エージェントはツールを使って、書き込んだ内容に対して check_ui を実行します。

その他のエージェント。 npx skills add dgesteves/onsystem を実行すると、Agent Skills に対応する任意のエージェントにスキルを追加できます。また、Codex、GitHub Copilot CLI、VS Code、Cursor 向けのプラグインもあります。

任意の MCP クライアント。 npx -y onsystem を stdio サーバーとして実行します。Claude Desktop、Codex CLI、GitHub Copilot CLI、Windsurf、JetBrains IDE、Zed、Gemini CLI、Antigravity、Grok Build 向けの設定があります。

CI。 開発用依存関係としてインストールし、コードベースにすでにある問題を一度だけ受け入れてから、新たに見つかった問題だけを対象にプルリクエストを失敗させます。

npm install --save-dev onsystem
npx onsystem check . --update-baseline   # writes onsystem.baseline.json: commit it

- run: npx onsystem check . --format github --require-design-system

問題はプルリクエストのアノテーションとして表示され、デザインシステムが見つからなくなった場合は --require-design-system によってジョブが失敗します。CI とベースラインでは、ワークフロー全体を説明しています。

GitHub Action。 アクションは同じチェックを実行し、ベースラインを考慮して、プルリクエストで変更された行にのみアノテーションを付けます。デザインシステムを読み込めるように、チェックアウトとインストールの後に配置します。

steps:
  - uses: actions/checkout@v7
  - uses: actions/setup-node@v7
    with:
      node-version: 24
      cache: npm
  - run: npm ci
  - uses: dgesteves/onsystem@v0

エージェントのプルリクエストで必須チェックにするでは、ワークフロー全体とその入力を説明しています。 ESLint. ESLint 8.57、9、10で同じルールを使用できます。onsystem/eslint の onsystem.configs.recommended を eslint.config.mjs に追加してください（ESLint プラグイン、@shadcn/lint と併用）。

@shadcn/lint と併用する

@shadcn/lint は、Tailwind v4 でコンポーネントとテーマに照らして書かれた Tailwind クラス（スタイルの再設定、未加工の色、任意のクラス、未知のクラス）を、ESLint または Oxlint のルールとしてチェックします。onsystem は、Tailwind v3 または v4 でコンポーネント、props、バリアント値が存在するかをチェックし、ネイティブ要素や名前のないアイコンボタンにフラグを立てます。onsystem の MCP サーバーは、エージェントがコードを書く前にコンポーネントとトークンを表示し、Claude Code ではフックが編集のたびにチェックします。両方を実行してください。Benchmark v2 では、すべての出力を @shadcn/lint でも採点しています。独立評価者の表をご覧ください。

効果はありますか？

Benchmark v2 では、3つのプロバイダー（Anthropic、OpenAI、Google）の6つのモデルに、5つのオープンソースリポジトリで20件の単一ファイル UI タスクを実行させました。onsystem なし、スキルあり、MCP サーバーあり、フックあり、そして3つすべてありの条件で、合計1,200回、各条件240回実行しました。onsystem 0.5.0 の独自チェックで集計すると、実行あたりのデザインシステムのエラーは、onsystem なしの0.85から、3つすべてを使用した場合の0.00に減少し、tsc の合格率には測定可能な変化がありませんでした（93% → 92%）。

この集計は onsystem 独自のものであり、MCP サーバーとフックは、エージェントに修正すべき同じエラーを表示します。成功を示すトークンがないデザインシステムで、緑色のステータスラベルを求められるタスクでは、onsystem を使用したエージェントは chart-* トークンを使うことが多く、onsystem はこれを問題なしと数えます。AI レビュアーによるブラインド評価のラベルは、各条件12ファイルと少なく、この集計を肯定も否定もできません。また、フックありまたは3つすべての条件で見つかった違反はすべて、Dub のパレットカラーでした。0.5.0 は Dub のトークンを読み取っていませんでした。ベンチマークページにはすべての表があり、bench/v2には手法、実行ごとのデータ、生成されたすべてのファイルがあります。

互換性

package.json の宣言内容と CI の実行内容：

対象	サポート
Node.js	Node.js 20.19 以降（engines）。CI では Node.js 22、24、26 でテストを実行し、ビルド済みパッケージは 20.19 でテストします
オペレーティングシステム	Linux、macOS、Windows：CI では各環境でテストとパックテストを実行します
ESLint	ESLint 8.57、9、10（ESLint プラグインのみ）：eslint はオプションの peer であり、CLI、MCP サーバー、フック、Action では必要ありません
TypeScript	プロジェクトの TypeScript は使用されず、JavaScript プロジェクトでは不要です。onsystem は独自の TypeScript 6.0（依存関係であり peer ではありません）で .tsx と .jsx を読み取ります
React	React 18（forwardRef）または React 19（prop としての ref）向けに書かれたコンポーネントを、ソースまたは型宣言から読み取ります。onsystem は React に依存しません
Tailwind CSS	v4（@theme）と v3（tailwind.config、実行せずに読み取り）に対応しています。Tailwind を使用しない場合、トークンは CSS カスタムプロパティ、DTCG ファイル、または DESIGN.md から取得されます
shadcn/ui	Tailwind v3 または v4 で、Radix（asChild）と Base UI（render）の両方のベースに設定なしで対応します
MCP クライアント	stdio サーバーを起動する任意のクライアントに対応します。CI は 2025-11-25 と 2026-07-28 のプロトコルで接続します。エージェントのセットアップには、各クライアントの設定とサポートレベルが記載されています

ドキュメント

ウェブサイトと、Markdown 形式のdocs/にあります。

• クイックスタート、Claude Code プラグイン、CI とベースライン、エージェントのセットアップ（各クライアントの設定を掲載）
• 設定、ルール、MCP ツール、トラブルシューティング
• 仕組み、FAQ、design-system-mcp からの移行

貢献ガイド、セキュリティ、変更履歴はリポジトリにあります。

ライセンス

MIT © Diogo Esteves