クラメソのデザインガイドをDESIGN.mdで実装してみた
こんにちは、せーのです。今日は社内向けに使っているクラスメソッドのデザインガイドを、DESIGN.md という形に置き換えてみましたので、共有します。
みなさん、AIに画面や資料を作らせるときに「背景は #f4f4f4、角丸はなし、ロゴは右上……」と毎回プロンプトに書いていませんか。私もずっとそうでした。
嘘です。正確には、Claude Code のスキルに寄せて省略しました。/classmethod-brand-guidelines というスキルを作成し、それを呼べば、そこにロゴやトーンのルールがまとまっているので、毎回ゼロから色の指定をしなくて済む、という方法をとっていました。
問題は「スキルは明示的に呼ばないと効かない」「Cursor や別のエージェントでは同じ資産を共有しづらい」あたりが、少しモヤッとするところにあります。
私は今までは
- Claude Code 上ではスキルでブランドを固定する
- それ以外では、長めのプロンプトでなんとか寄せる
という運用でした。
もう一歩だけ「プロジェクトのルートに置くだけで、エージェント側が前提を掴む」寄りに寄せてみたらどうなるだろう、ということで、DESIGN.md への移行を試してみました。
DESIGN.md とは（おさらい）
DESIGN.md は、Google Labs の Google Stitch（Gemini ベースの UI デザインツール）まわりで注目されている考え方で、README.md がプロジェクト説明の定番であるのと同様に、デザインシステムを 1 枚の Markdown に集約するフォーマットです。
- カラーパレット・タイポグラフィ・スペーシング・コンポーネントの型を 1 ファイルに書く
- Claude Code / Cursor / Gemini CLI / GitHub Copilot などが、ルートの
DESIGN.mdを参照しやすい
従来は毎回プロンプトで「色は #1a1a1a、フォントは Inter、角丸 8px…」のように指定していたものを、ファイル側に退避しておくイメージです。
Stitch 上で作った UI を DESIGN.md としてエクスポートしたり、URL からデザインルールを抽出したり、MCP 経由で開発ツールと連携したり、という流れも整備されつつあります。公式の紹介は Design UI using AI with Stitch from Google Labs がわかりやすいです。
awesome-design-md の 9 セクション
コミュニティでは VoltAgent の awesome-design-md が、DESIGN.md の構成例としてよく参照されます。2026 年 3 月末公開で、多数のブランドの DESIGN.md をリバースエンジニアリングして公開しているリポジトリです。
ざっくり、次のような章立てが「型」として共有されています。
- ビジュアルテーマと雰囲気
- カラーパレットと役割
- タイポグラフィ規則
- コンポーネントスタイル
- レイアウト原則
- 深さと段階（シャドウ等）
- Do's and Don'ts
- レスポンシブ動作
- エージェント向けプロンプトガイド
各ブランドフォルダには DESIGN.md に加えて preview.html / preview-dark.html がある例も多く、「人間が眺める用」と「エージェントが読む用」が分かれているのが特徴です。
classmethod-brand-guidelines.skill と DESIGN.md
さて、いよいよ本題です。自分で使っている classmethod-brand-guidelines.skill と、DESIGN.md を並べると次のような対比になります。
| 観点 | スキル | DESIGN.md |
|---|---|---|
| 形式 | Claude Code スキル | ルートの Markdown |
| 発動 | 明示的にスキル呼び出し | 置くだけで参照されやすい |
| ツール | 基本は Claude Code | 複数のエージェントで共有可能 |
| アセット | スキル内にロゴ同梱 | assets/ などに別置き |
| 保守 | スキル定義の更新 | ファイル 1 枚の更新 |
違いを整理すると、スキルは「呼んだときに効くブランドパック」、**DESIGN.md は「リポジトリの見た目の憲法」**に近い、というイメージです。
DESIGN.md はテキスト中心なので、ロゴの PNG などバイナリは別フォルダ管理になります。推奨はルートに DESIGN.md、その隣に assets/logo-black.png のように置き、Markdown から相対パス参照する形です。
Claude Code では、CLAUDE.md に「UI や資料生成時は DESIGN.md の値だけ使うこと」と書いておくと、毎回スキル名を唱えなくても寄りやすくなる、というパターンが紹介されています（例: MindStudio の解説）。
手順
DESIGN.mdの作成は非常に簡単です。
DESIGN.mdとassets/（ロゴ）をプロジェクトルートに用意するDESIGN.mdに色・タイポ・ロゴ位置・禁止事項（フラット、単一グレーなど）を書くCLAUDE.mdに DESIGN.md 参照の一文を足す（Claude Code 向け）- 「コスト最適化レポートの HTML を」と頼んで、背景の統一やロゴ位置を目視確認する
ハイブリッド運用も現実的で、PDF 生成スキルなど ロゴの実パスが要る処理だけスキル側に残し、references/design-guidelines.md と DESIGN.md を同期させる、といった折衷案もあります。
やってみた
静的 HTML の対比（ブラウザだけで確認）
ログイン不要で済むところから、同じリポジトリ内に小さな実験フォルダを置きました。
experiment/DESIGN.md… クラスメソッド用ドラフトexperiment/sample-branded.html… DESIGN.md の「HTML Documents」に沿った例（ページ全体#f4f4f4単一、フラット、右上にロゴ用スペース、区切りは#ddddddの 1px）experiment/sample-unbranded.html… 意図的なアンチパターン（背景グラデーション、カードとページでグレー値がバラバラ、box-shadow、青・紫のアクセント）
ブラウザで両方を並べると、「単一グレー＋フラット」がノイズをどれだけ減らすかが一発で分かります。ロゴ PNG は環境依存なので、experiment/assets/README.md にスキルからのコピー手順だけ書いてあります（この Vault ではバイナリは同梱していません）。
ブランドガイドライン準拠
アンチパターン
Claude Code × DESIGN.md（コスト最適化レポート HTML）
experiment/DESIGN.md をルート相当の前提に置き、CLAUDE.md 側で「UI 生成時は DESIGN.md の値のみ使う」と書いたうえで、と同じ依頼を出しました。
DESIGN.mdのデザインに従って、コスト最適化レポートのHTMLを生成して。
チェックポイントを設けて確認してみたところ、いずれも問題なし（○） でした。
| 確認項目 | 結果のメモ |
|---|---|
背景が #f4f4f4 でページ全体が単一トーンか |
body / .page / セクション背景がすべて #f4f4f4 で統一 |
| ロゴが右上か | position: absolute; top / right で右上固定（画像が無い場合はテキストプレースホルダ） |
| フォント指定 | スタイルシート上は Univia Pro, Noto Sans JP ＋ macOS / Windows フォールバック（実機で Univia が効いているかは未計測） |
| グラデ・シャドウなし | box-shadow や gradient 系の指定なし |
| フッターに著作権 | © 2025 Classmethod, Inc. 相当の表記あり |
生成物の一例を experiment/generated-by-claude.html として残してあります。タイトルは「AWSコスト最適化レポート（Claude生成・DESIGN.md準拠）」で、右上は画像ではなく 「CLASSMETHOD」テキストのロゴ代わり、本文は見出し・箇条書き・表組みのレポート構成です。別途、ロゴ画像パス付きの版として experiment/cost-optimization-report.html もあり、assets/logo-black.png が無いときは onerror でプレースホルダに落ちるようにしてあります。
プロンプト長の比較（スキル呼び出し vs DESIGN.md 前提）
同じ「コスト最適化レポートの HTML を作って」に近い依頼を想定し、ブランド指定の入れ方だけを変えて文字数をざっくり数えました（2026-04-05 時点・1 回の実測）。
| パターン | おおよその文字数 | メモ |
|---|---|---|
/classmethod-brand-guidelines 相当（スキル本文を毎回コンテキストに載せるイメージ） |
約 11,520 文字 | ロゴ配置・禁止事項・色コードまで一式がプロンプト側に乗る |
| DESIGN.md ＋ 短い依頼（ファイルはリポジトリに既にある前提） | 約 3,513 文字 | 「DESIGN.md に従え」に寄せられるぶん、約 7 割削減 |
「スキルは呼ばないと効かない」の逆は、正規のデザイン情報をファイルに寄せておけば、依頼文は短くて済むという実感に近い数字でした。もちろん、初回に DESIGN.md を整備するコストは別です。
DESIGN.md を匂わせずに HTML を依頼
最後に、「DESIGN.md を読め」「ブランドに従え」といった文言なしに、次だけ投げました。
1ページのコスト最適化レポート HTML を生成して
エージェント側の応答では、探索のあと 「DESIGN.md に沿い、1ページに収まるコスト最適化レポートの HTML を作成します」 と明示されていました。生成・更新された cost-optimization-report.html の CSS コメントには Classmethod DESIGN.md: 単一グレー #f4f4f4, フラット のような記述があり、フッターの年表記も DESIGN.md の © 2026 Classmethod, Inc. に合わせて調整されていました。プロンプトにファイル名を出していなくても、ルート付近の DESIGN.md を自分から拾って当てにいく挙動がこの一回では確認できました（再現性やモデル差は別途たたき台が要る、という位置づけです）。assetsにロゴをセットしたところ、ロゴもバッチリ表示されました。ただ大きさや余白は調整が必要かな、と感じます。ここらへんはDESIGN.mdの作り込みですね。
まだ手を付けていない／保留にしたもの
次はログインや追加の再現実験が要るものだけ列挙します。
- Google Stitch での DESIGN.md エクスポートや URL からのルール抽出（Labs アカウントが必要）
- DevTools で computed font を確認し、Univia Pro が実表示かフォールバックかをスクショ付きで残すこと
PDF 化まで含めたパイプラインは、利用するスキル（例: create-pdf）と環境に依存するので、別のタイミングでまた試してみたいと思います。
限界とハイブリッド案の所感
DESIGN.md だけにすると、ロゴの実体パスや 社内スキルに閉じたテンプレートのような「ツール連携の都合でスキルの方が楽」なケースは残ります。だからこそ、スキルは削除せず並存し、テキストの正は DESIGN.md に寄せる、が落ち着きどころだと思います。
また、フォントが Univia Pro であることは DESIGN.md に書けますが、実行環境にフォントが入っていなければフォールバックになります。
まとめ
DESIGN.md を使ってみて感じたのは次の点です。
- スキル呼び出しに依存せず、リポジトリ単位で「ブランドの前提」を共有しやすい
- Cursor など複数ツールに同じファイルを持ち込める
- 一方で ロゴ等のアセットと実フォントは別問題なので、ハイブリッド運用のほうが現実的
もっとスマートな運用例や、Stitch との連携でハマった点などを御存知の方がいれば、ぜひ X などで教えてください。
