DESIGN.mdでClaude Codeのデザインを安定させる——このブログをVercel風デザインシステムで作った記録
はじめに
Claude Codeを使っていて、「コードは書けるけど、見た目がいまいち……」 と感じたことはないでしょうか。
機能的には正しく動く。ロジックも問題ない。でも出来上がったUIを見ると、どこか素人っぽい。余白がおかしい、色のバランスが微妙、なんとなく「AIが作りました」感が漂う——そんな経験は、Claude Codeユーザーなら一度はあるはずです。
私自身、デザインは不得手な領域です。エンジニアとしてインフラやバックエンドを中心にやってきたので、「見た目を整える」というスキルが圧倒的に足りていません。
そんな中で出会ったのが、DESIGN.md という仕組みです。
Claude Codeのデザインが苦手な理由
まず前提として、Claude Codeは デザインが得意ではありません。
これはClaude自体の能力の問題というよりも、指示の問題 です。「ログイン画面を作って」と言えばログイン画面は作ってくれますが、その見た目は最低限のHTMLにTailwindのクラスをなんとなく当てた程度のものになりがちです。
なぜなら、Claude Codeには 「どんなデザインにすべきか」という基準が与えられていない からです。
コーディング規約のCLAUDE.mdがコードの品質を担保するように、デザインの品質を担保するためのファイル——それがDESIGN.mdです。
DESIGN.mdとは何か
DESIGN.mdは、UIコンポーネントのデザイン仕様をMarkdownで記述したファイル です。
プロジェクトのルートに配置しておくと、Claude Codeがフロントエンドのコードを生成する際にこのファイルを参照し、指定されたデザインシステムに沿ったUIを出力してくれます。
具体的には、以下のような情報が含まれます。
- カラーパレット（プライマリ、セカンダリ、背景、テキスト色など）
- タイポグラフィ（フォントファミリー、サイズ、ウェイトの体系）
- スペーシング（余白の基準値、グリッドシステム）
- コンポーネント仕様（ボタン、カード、フォーム、ナビゲーションなどの具体的なスタイル）
- レイアウトパターン（ヘッダー、サイドバー、コンテンツ領域の構成）
- アニメーション・トランジション（ホバー効果、ページ遷移など）
つまり、デザイナーが作るスタイルガイドのMarkdown版 のようなものです。
元はGoogle Stitchから生まれたアイデア
DESIGN.mdの発想は、Google Stitch（Googleが発表したAIによるUIプロトタイピングツール）から来ています。
Google Stitchでは、デザインシステムの定義をAIに渡すことで、一貫性のあるUIを生成するというアプローチが採用されていました。この考え方をClaude Codeに応用したのがDESIGN.mdです。
重要なのは、これは特別な機能ではなく、単なるMarkdownファイル だということです。Claude Codeの仕組みとしてはCLAUDE.mdと同じで、プロジェクトのコンテキストとして読み込まれるだけ。つまり 誰でも自作できます し、既存のものをコピーして使うこともできます。
awesome-design-mdという宝庫
自分でゼロからDESIGN.mdを書くのは大変ですが、ありがたいことに コミュニティがすでに多数のデザインテンプレートを公開 しています。
GitHubで公開されている awesome-design-md というリポジトリには、様々なデザインシステムのDESIGN.mdが揃っています。
安全性について
このリポジトリの良いところは、中身がMarkdownファイルだけ という点です。
実行可能なコードは含まれていません。npm installもビルドも不要。気に入ったデザインのMDファイルをコピーしてプロジェクトに配置するだけです。サプライチェーン攻撃のリスクもなく、内容を自分の目で確認できる。これ以上安全な方法はないでしょう。
どんなデザインがあるのか
リポジトリには多種多様なデザインが揃っています。
- ミニマルでモダンなデザイン（SaaSプロダクト風）
- ダッシュボード向けのデザイン（管理画面風）
- LP・マーケティングサイト向けのデザイン
- ポートフォリオ向けのデザイン
「どのデザインにしよう」と選ぶ楽しさすらあります。
入れるだけで何が変わるのか
DESIGN.mdを導入する前と後で、Claude Codeの出力がどう変わるか。一言でいうと、「見たことあるようなUI」になります。
これは褒め言葉です。
「見たことある」ということは、ユーザーが直感的に操作できる ということです。ボタンの位置、カードの余白、ナビゲーションの構成——どこかで見たことのある、安心感のあるデザインになる。
逆に言えば、DESIGN.mdなしのClaude Codeが生成するUIは、「見たことないUI」になりがちでした。独創的という意味ではなく、余白やフォントサイズのバランスがどこか不自然で、プロのデザイナーなら絶対にやらないような構成になってしまう。
DESIGN.mdを入れるだけで、その「不自然さ」がほぼ解消されます。
非エンジニア・非デザイナーにこそ恩恵がある
DESIGN.mdの本当の価値は、デザインの専門知識がない人でも「それらしい」サイトが作れるようになる ことだと思っています。
これまでは、たとえClaude Codeが使えたとしても、「機能は動くけど見た目がちょっと……」というハードルがありました。そしてデザインの修正は、コードの修正以上に「何をどう直せばいいかわからない」という問題があります。
DESIGN.mdは、このハードルを一気に下げてくれます。
- プログラミング経験が浅い人でも、Markdownファイルをコピーするだけ
- デザインの知識がなくても、プロが作ったデザインシステムが適用される
- 「なんかダサい」から「普通にちゃんとしてる」へ、一歩で到達できる
このブログ自体をDESIGN.mdで作った
抽象論で終わらせないために、実例で話します。いまあなたが読んでいるこのブログのデザインは、DESIGN.md で整えたものです。
このリポジトリのルートには DESIGN.md を置いてあり、中身は「Design System: Vercel」と題したデザインシステムの仕様です。Vercel のサイトに通じる方針——ほぼ白（#ffffff）のキャンバスに、少しだけ温かみのある黒（#171717）のテキスト。罫線の代わりに box-shadow: 0 0 0 1px rgba(0,0,0,0.08) を使う「シャドウを枠線として扱う」手法。Geist フォント——が言語化されています。
そして、このサイトの globals.css に並ぶCSS変数は、その DESIGN.md から引いてきた値です。
--bg: #ffffff;
--text: #171717;
--accent: #0072f5; /* リンク・アクセント */
--border: #ebebeb;
--card-alt: #fafafa;
--shadow-border: 0 0 0 1px rgba(0,0,0,0.08); /* 枠線の代わりのシャドウ */
--radius: 8px;
最初にこのブログを組んだときも、その後レイアウトや配色を何度か見直したときも、判断の拠り所はこの DESIGN.md に戻ってくる感覚でした。「この余白でいいか」「この色は浮いていないか」を毎回ゼロから言葉にするのではなく、「DESIGN.md の方針に沿っているか」で判断できる。デザインが不得手な自分にとって、この基準があるのは大きいです。
ただ、正直に書くと DESIGN.md を置けば一発で完璧になるわけではありません。Vercel の英語UIを前提にした仕様なので、日本語フォント（Noto Sans JP）との組み合わせや、記事本文の行間・可読性など、そのまま当てると合わない部分は個別に調整しました。それでも「方向性が定まっている状態から始められる」のは、以前のように「もう少し余白を……」「色をもう少し……」と何往復も言葉で説明していた頃とは、手間がまるで違います。
導入方法
導入は驚くほど簡単です。
- awesome-design-mdリポジトリから気に入ったDESIGN.mdを選ぶ
- プロジェクトのルートにDESIGN.mdとして配置する
- 必要に応じてプロジェクトに合わせてカスタマイズする
以上です。あとはClaude Codeに「ログイン画面を作って」「ダッシュボードを作って」と指示すれば、DESIGN.mdに沿ったUIが生成されます。
カスタマイズのコツとしては、まずはそのまま使ってみて、気になる部分だけをClaude Codeに「DESIGN.mdのプライマリカラーをこの色に変えて」と頼む流れがスムーズです。
まとめ
DESIGN.mdは、Claude Codeのデザイン面での弱点を補う、シンプルかつ強力な仕組み です。
- Markdownファイルを置くだけで導入できる
- Google Stitchの発想が元なので、自作も可能
- awesome-design-mdにテンプレートが豊富に揃っている
- 実行コードを含まないので安全
- 非エンジニア・非デザイナーでも「それらしい」UIの出発点が手に入る
デザインが苦手な人にとって、これはありがたい仕組みです。コードの品質をCLAUDE.mdが担保するように、デザインの方向性をDESIGN.mdが担保してくれる。このブログのデザイントークンが実際にDESIGN.mdから来ているように、「方針を一度ファイルに落とす」だけで、その後の判断がぶれにくくなります。
万能ではなく、日本語まわりや本文の可読性など、最後の詰めは自分の手で調整する必要があります。それでも、ゼロから言語化していた頃に比べれば出発点がはるかに楽になるので、Claude Codeで「見た目がいまいち」と感じている方は一度試す価値があると思います。