ColorwayKit

エージェント向け ColorwayKit

AI コーディングエージェントが実際に使える、ブランドのカラーパレットを提供します。

ColorwayKit は、ブランドカラー1色から、アクセシビリティに配慮したライトテーマとダークテーマを生成します。セマンティックな役割を持つ23色、WCAG 2.1 と APCA によるコントラストチェック、プロジェクトにそのまま貼り付けられるエクスポートを提供します。

• ウェブサイト：https://www.colorwaykit.com
• テーマの作成とエクスポート：https://www.colorwaykit.com/brand

解決する課題

コーディングエージェントは動作する UI を作成しますが、色を独自に決めてしまいます。ここでは青いボタン、あちらでは別のグレー、しかもコントラスト比は誰も確認していません。プロンプトのたびにパレットを説明し直す方法では、規模が大きくなると対応できません。

DESIGN.md は、AI コーディングツールに採用されているオープンな形式です。デザインシステムを1つのプレーンテキストファイルにまとめ、YAML のデザイントークン（機械可読な値）と Markdown の本文（いつ、なぜ使用するか）で構成します。プロジェクトのルートに配置すると、エージェントは推測する代わりにこのファイルを読み込みます。

このリポジトリには、ColorwayKit で生成したテンプレートとサンプルをまとめています。これにより、そのファイルを既に利用しているエージェントに組み込めます。

エージェントに渡す2つの方法

	MCP サーバー（ライブ）	ファイル（このリポジトリ）
エージェントが取得するもの	必要に応じて取得する測定済みトークンと、色のペアごとのコントラスト結果	リポジトリにコミットされたバージョン管理済みの DESIGN.md
セットアップ	1つのコマンドとトークン	2つのファイルをプロジェクトのルートにコピー
おすすめの用途	日々の開発、複数プロジェクトでの利用	ブランドをコードベースに組み込む、CI、オフラインでの利用
利用枠	アカウントごとに計測（Free は1日5回・Plus は月1,000回・Pro は無制限）	なし — ファイルです

どちらも ColorwayKit アカウントがあれば無料です。どちらかを選ぶか、バージョン管理されたソースとしてファイルを、ライブインターフェースとして MCP を利用してください。

方法 A：MCP サーバー（ライブ）

1. colorwaykit.com で無料アカウントを作成し、My Projects → Agent tab → Generate token に進みます。

2. 接続します（Claude Code の例）：

   claude mcp add --transport http colorwaykit https://www.colorwaykit.com/api/mcp --header "Authorization: Bearer ck_YOUR_TOKEN"
   

3. エージェントに 「#4F46E5 のカラートークンを一覧表示して」 と尋ねます。名前付きの役割と測定済みのコントラスト値が返ってくれば、接続されています。Cursor／Codex／Gemini CLI の完全なセットアップ方法：https://www.colorwaykit.com/mcp

ツール：get_theme（HEXカラー1色から、検証済みのライトテーマとダークテーマを生成）、check_pair（テキストと背景のあらゆる組み合わせをその場で検証）、get_theme_by_project（クラウドに保存したプロジェクトを取得）、list_projects（保存済みのプロジェクトを新しい順に一覧表示）。

方法 B：ファイルを使う（クイックスタート）

1. Brand Theme Engine を開き、ブランドカラーのHEX値（ロゴまたはガイドラインから取得）を貼り付けます。
2. Take it to dev タブに移動し、DESIGN.md をコピーまたはダウンロードします。これは、CSS 変数、Tailwind 設定、Tokens Studio JSON、W3C DTCG トークンと並ぶ、無料のエクスポート形式です。
3. プロジェクトのルートに DESIGN.md として保存します。
4. エージェントにこのファイルを参照させます。詳しくは templates/ をご覧ください。

エクスポートされたファイルの内容

• YAML フロントマターの colors：両テーマのセマンティックロール （primary、on-primary、surface、on-surface、outline、error、…）を含みます。 ダークテーマのロールには dark- が接頭辞として付きます。
• {colors.x} 構文でそれらの色を参照する components。変更を 1 か所に加えるだけで反映されます。
• Markdown の Colors セクションには、すべてのテキスト／背景の組み合わせについて測定済みの結果が記載されています。WCAG 2.1 のしきい値に対する比率に加え、ユースケースのしきい値に対する APCA Lc も記載されます。不合格の組み合わせには不合格の印が付きます。このファイルに記載されるのはツールが計算した結果のみで、それ以上のものはありません。
• typography、rounded、spacing は omitted として宣言されています。カラーエンジンにはこれらの測定値がないため、値を作り出すのではなく、使用するフレームワークのデフォルト設定が適用されます。

examples/DESIGN.md をご覧ください。ColorwayKit がブランドカラー #4F46E5 から生成したもので、手書きではありません。

テンプレート

ファイル	用途
templates/SKILL.md	エージェントのスキル／ツールの手順
templates/AGENTS.md	リポジトリレベルのエージェント向け手順（多くのツールが読み込みます）
templates/CLAUDE.md	Claude Code のプロジェクトメモリ
templates/cursorrules.md	Cursor のルール（インストール時に .cursorrules に名前を変更してください）

各テンプレートには、DESIGN.md の利用方法だけが記載されています。テンプレートをプロジェクトにコピーし、パスを調整してください。すべてのテンプレートに実行可能な検証ステップが含まれるようになりました。詳しくは以下をご覧ください。

リンターで検証する（CLI）

付属のチェッカーで新しい色が適切か確認しましょう。ワイルドカラーのスキャンと WCAG 2.1 のペア検証を行い、CI 用の終了コードを返します。このリポジトリに含まれており、インストール不要で Node 18+ で実行できます。

node cli/index.js --tokens DESIGN.md --target .

終了コード 0 = 問題なし、終了コード 1 = ワイルドな 16 進カラー値、または不合格のペアがあります。--apca を追加すると、各ペアの APCA Lc も報告します。ソースは cli/ にあります。CI のステップに組み込み、新しい色がまずこのファイルを通るようにしてください。

すでに色を抽出していますか？

DevTools の調査や色の抽出ツールを使った場合、手元の 16 進カラー値のリストには、まだロールも測定値もありません。移行ガイドで仕上げまで進められます： docs/migration-extracted-css.md。生の 16 進カラー値からセマンティックロール、測定済みペアを経て、正式な DESIGN.md を作成します。実際に不合格となるペアを含む、実例も掲載しています。

FAQ

テンプレートはどこにありますか？ このリポジトリにあります。自由にコピーしてご利用ください。DESIGN.md のフォーマット自体は Google Labs が仕様を定めており、Apache-2.0 でライセンスされています。

Claude Code 以外でも使えますか？ はい。テンプレートは通常の Markdown です。Cursor には .cursorrules、Codex とほとんどのエージェントには AGENTS.md、スキル対応クライアントには SKILL.md をお使いください。

スキルと MCP サーバーの両方が必要ですか？ これらは組み合わせて使えます。このファイルはチームが配布するバージョン管理された契約であり、MCP はペアを検証し、調整済みのテーマを必要に応じて取得するためのライブ測定ツールです。

すべて無料ですか？ テンプレート、Brand Theme Engine、コントラストチェッカーは無料です。MCP サーバーはアカウントごとの従量制です。Free は 1 日 5 回、Plus は月 1,000 回、Pro は無制限です。

注意事項と制限

• DESIGN.md の仕様は Google Labs が定めており、google-labs-code/design.md にて Apache-2.0 ライセンスで提供されています。 ColorwayKit はこの仕様の作成者ではなく、この仕様に沿ってエクスポートします。
• 仕様は初期バージョンであり、一部の記述では進化中であるとされています。コンポーネントのトークン構造は変更される場合があります。
• コントラスト値は自動計算され、デザインの参考値です。正式なアクセシビリティ認証ではありません。
• ColorwayKit のエンジンが扱うのは色です。生成ファイル内のフォント、間隔、角丸はご自身で定義してください。

ライセンス

このリポジトリのテンプレートとサンプルは、ご自身のプロジェクトで実用するために提供されています。DESIGN.md のフォーマット自体には独自の仕様とライセンスが適用されます（上記のリンクをご覧ください）。