design-md

デザイン言語ドキュメント（DESIGN.md）

このリポジトリのデザイン言語の指針を作成します。ルートに置く DESIGN.md では、UI の構築方法をエージェントと人間が正確に把握できるようにし、あわせて移植可能な frontend-design クラフトスキルを用意します。このドキュメントはコードに基づくものです。すでに存在するデザイン言語を記述するか、ユーザーの承認を得て提案します。デザイン言語をでっち上げて事実として提示したり、ドキュメントに合わせて既存の UI を作り直したりしてはいけません。

目標

1. ルートの DESIGN.md — 実際のファイルやトークンを根拠として記述する、リポジトリのデザイン言語
2. .agents/skills/frontend-design/SKILL.md — どのリポジトリにも適用できる、移植可能なクラフト指針
3. エージェントが1ステップでデザイン言語を見つけられるよう、AGENTS.md からリンクする

参考テンプレート

ファイル	用途
references/design-md-template.md	根拠をもとに記入する DESIGN.md のひな形
references/skill-frontend-design.md	そのまま作成する .agents/skills/frontend-design/SKILL.md

フェーズ 0：監査してから分類する（何も書き始める前に）

根拠を集めます。DESIGN.md のすべての記述は、ここで確認した内容に基づいている必要があります。

• package.json：フレームワーク、UI ライブラリ（react/vue/svelte、tailwind、shadcn、radix/base-ui、motion/framer-motion、lucide、フォント関連パッケージ）
• トークンレイヤー：globals.css / tailwind.config.* / テーマファイル — CSS 変数、@theme ブロック、カスタムユーティリティ（シャドウ、角丸、アニメーション）
• フォント：読み込み方法（next/font、@font-face、リンクタグ）、使用するファミリーと役割
• コンポーネントシステム：components/ui/、共有プリミティブ、バリアントのパターン（cva、variants props）
• モーション：キーフレーム、トランジションユーティリティ、モーションライブラリの使用、prefers-reduced-motion への対応
• アプリ内で最も完成度の高い画面を3～5個 — トークンの説明にかかわらず、これらが実際のデザイン言語を定義します
• 既存のデザインドキュメント：DESIGN.md、docs/design*、ブランドガイドライン、README 内の Figma リンク、デザイン関連の Cursor ルールやエージェント向けドキュメント

次に、リポジトリを以下のいずれか1つに分類します。

モード A — ドキュメント化（確立されたデザイン言語があり、デザインドキュメントはない）

リポジトリには、一貫性のあるトークン、意図的に選ばれたフォント、コンポーネントシステム、繰り返し使われるモチーフがあります。ここで行うのは抽出です。実在する内容を記述し、その根拠となるファイルを示した DESIGN.md を作成します。実際のデザインは変更しません。コードベース内に一貫しない箇所がある場合は、主流または最新のパターンを記録し、逸脱について注記します。独断で不整合を解消してはいけません。

モード B — 統合（既存のデザインドキュメントがある）

DESIGN.md、ブランドガイド、またはデザイン関連のルールがすでに存在します。再生成せず、統合します。ローカル固有のルールをすべて維持し、テンプレートの構成に沿って重複を整理し、情報源を一元化します。ドキュメントを統合する場合は、元の資料への参照を残します。既存のドキュメントとコードが矛盾している場合は、どちらかを黙って選ぶのではなく、ユーザーに矛盾を伝えます。

モード C — 提案（新規プロジェクトで、一貫したデザイン言語がない）

確立されたデザイン言語がありません。美的方向性の選択は、根拠から導く判断ではなく、ユーザーが決めることです。docs/plans/design-language.md（リポジトリに docs/plans/ がない場合は PLAN.md）に、次の内容を含む1ページの提案を作成します。美的方向性とトーン、フォントの組み合わせ（ディスプレイ用＋本文用）、色の方針とアクセントの使用範囲、エレベーション戦略、モーションの方針です。製品の状況に応じて、異なる方向性を2～3案提示します。**ユーザーの承認を得るまで、DESIGN.md は作成しません。**承認後、承認された提案に基づいて完全なドキュメントを作成します。

成果物

DESIGN.md                              # root design-language contract (living document)
.agents/
  skills/
    frontend-design/SKILL.md           # portable craft doctrine (references/skill-frontend-design.md)
docs/
  plans/
    design-language.md                 # Mode C only: the approved proposal

さらに、次の編集を1つ行います。AGENTS.md のクイックリンクに - [Design Language](DESIGN.md) を追加します（AGENTS.md があり、該当セクションがない場合はセクションを作成します。AGENTS.md がない場合はスキップします）。

プロセス（順番どおり）

1. フェーズ 0 監査と分類（上記のチェックリストを確認）
2. モード C のみ：提案を作成して提示し、承認を待つ
3. references/design-md-template.md を構成の参考にして DESIGN.md を作成 — 根拠（モード A/B）または承認済みの提案（モード C）に基づいて内容を記入
4. references/skill-frontend-design.md から前文を除き、内容を一字一句そのまま .agents/skills/frontend-design/SKILL.md に作成。ただし、リポジトリに同等のクラフトスキルがすでにある場合は作成を省略
5. AGENTS.md のクイックリンクから DESIGN.md にリンクする
6. 以下の検証パスを実行する
7. 次の内容を報告する：選択したモードとその理由、作成したファイル、ドキュメントとコードの間で見つかった矛盾、既存のドキュメントから維持したルール

DESIGN.md の記述ルール

• 実在するファイルを引用してください。 ドキュメント内で言及するトークン、ユーティリティ、フォント、コンポーネントのパターンは、すべて定義元のファイルにリンクしてください
• 予算を明記してください。 優れたデザイン言語の大半は抑制によって成り立ちます。制限を明確にしてください（「ビューごとにアクセントの組み合わせは 1 つ」「ページごとにディスプレイフォントを使う箇所は最大 1 か所」など）。エージェントは雰囲気よりも予算に従いやすくなります
• 一文要約を含めてください。 冒頭近くに引用ブロックを置き、デザイン言語全体を、エージェントが別の画面にも適用できる一段落にまとめてください
• 最後にページごとのチェックリストを設けてください。 エージェントが自己レビューできるよう、検証可能な項目として記述してください
• 形容詞ではなくサイズを記載してください。 「rounded-3xl のカード、rounded-full の CTA」は、「丸みを大きくする」より明確です
• リポジトリのトークンシステムが適用できる箇所では、ハードコード値よりセマンティックトークンを優先してください。認められている例外は明記してください

制約

• 既存のコンポーネントを DESIGN.md に合わせて再スタイルしないでください。 このドキュメントは現状を記述するか、提案するものです。リファクタリングを許可するものではありません。ユーザーが UI をドキュメントに合わせることを望む場合、それは明示的に依頼された別のタスクです
• モード A と B では、記録の際にデザイン言語を「改善」しないでください。改善案は末尾の「未解決の質問」セクションに明記してください
• THIS リポジトリ内で確認されているか、モード C の提案で承認されていない限り、他の製品のデザイン言語（フォント、カラーパレット、モチーフ）を DESIGN.md にコピーしないでください
• 印象的で長いドキュメントより、正確で短いドキュメントを優先してください。誤ったデザインドキュメントを信頼するエージェントは、自信満々に誤った UI を作成します
• リポジトリの Markdown の文体と書式に合わせてください

検証パス（完了前に必須）

• DESIGN.md で参照されているすべてのファイルパスが、実在するファイルを指している
• ドキュメント内で言及したすべてのトークン、ユーティリティクラス、フォントがコードベースに存在する（grep で検索する）
• モード A/B：ドキュメント内のルールが、実際に最も完成度の高い画面の振る舞いと矛盾していない
• モード B：既存のドキュメントに固有のルールがすべてマージ後も残っている（差分を確認する）
• モード C：ドキュメントが承認済みの提案と一致している。提案ファイルが docs/plans/ に存在する
• AGENTS.md へのリンクが解決できる
• DESIGN.md 末尾のチェックリストに、エージェントがコードから検証できる項目のみが含まれている

完了条件

• このリポジトリで UI を構築するエージェントが、AGENTS.md から 1 つリンクをたどるだけで DESIGN.md を参照し、「どのフォント、どのトークン、どの角丸、どのシャドウ、どのモーションを使うか」に答えられる
• ユーザーが決定した既存のデザインは維持されている — 上書きされておらず、新しい方針は明示的に承認されている
• 持ち運び可能な frontend-design クラフトスキルがインストールされている
• すべてのドキュメントの記述が根拠または承認に基づいており、検証パスに問題がない