ClaudeCode時代のDESIGN.md実践Tips ── AIフレンドリーのUIデザイン
「DESIGN.md を作るべきだ」という話を、最近よく見かけるようになった。 Claude Code や Cursor の文脈もあり、AI にデザインルールや UI の文脈を共有するためのドキュメントとして使われることが増えている。
ただ、自分の場合、プロジェクト開始時点では DESIGN.md は書けなかった。
というより、あとから振り返ると、それは自然なことだった気がしている。
デザインはプロダクトの“個性”でもある。 そして個性は、最初から明確に決まっているというより、実際に作りながら少しずつ輪郭が見えてくるものだった。
この記事では、Chrome 拡張 + Next.js で作った UI Review Capture を題材に、どんな流れで DESIGN.md を書くようになったのか、そして実際にどう役立ったのかを書いてみたい。
「便利そう」から始まった
UI Review Capture は、かなり小さな不満から始まった。 UI レビューをするとき、
スクリーンショットを撮る
Slack に貼る
コメントを書く
エンジニアに送る
という流れが、地味に面倒だった。 だったら、
スクショを撮れて
Web 上で整理できて
URL を渡せる
だけのツールがあればいい。 最初は本当にそれだけだった。 だから最初に考えていたのは「世界観」より機能だった。
コメント機能は後回し
チーム機能も後回し
AI 分析もまだ不要
まずは「撮る → まとめる → 渡す」が成立すること。 その中で、「何を入れないか」を決めていくうちに、少しずつプロダクトの方向性が見えてきた。
実装すると、あとから共通パターンが見えてくる
実際に UI を作り始めると、同じような形が繰り返し出てくる。
「またこのレイアウトを書いてるな」 「このバッジ、さっきも作ったな」
そういうタイミングで初めて、「これはコンポーネントとして整理した方がよさそうだ」と気づく。
個人的には、最初から再利用前提で設計しようとすると、抽象的すぎる構造になりやすかった。 それよりも、
実際に作る
同じものが増える
共通点を見つける
後から整理する
という流れの方が自然だった。 例えば整理画面では、
左に一覧
右に詳細
という 2 ペイン構成が必要になった。
その中で min-h-0 を使って overflow を制御するパターンが自然に固まっていった。
これは設計書から生まれたというより、実際に画面を作っていて見つけたパターンだった。
開発→気づき→メモ→修正の繰り返しでDESIGN.mdの解像度が上がっていく
ボタンの色を決めるとき、ユーザー像が見えてきた
あるとき、プライマリーボタンの色を決めようとして、「誰が使うツールなのか」を改めて考えた。
使うのは、
プロダクトデザイナー
エンジニア
が中心になる。 毎日開く“作業ツール”で、エンタメ系サービスではない。
その視点で見ると、彩度の高い青ボタンが少し主張しすぎるように感じた。もっと静かでいい。
暗い背景の中で、白に近いアクセントが少しだけ視線を誘導する。そのくらいがちょうどよかった。 そうして、
——ほぼ白——をアクセントにした。 セカンダリーも背景色は使わず、accent:
border-border text-muted hover:text-accent くらいで十分だった。
インタラクションもそのサービスの個性。スピード感や動きの幅も実際動きを見ると「こうじゃない」って気がつく
ユーザー像が具体的になると、デザインの方向性も自然に決まっていく感覚があった。
「これは違う」がルールになっていった
LP を作っているとき、グラデーションを試したことがあった。 でも、しっくり来なかった。
LPにもDESIGN.mdを影響させることでブランディングの統一感を担保する。
グローも試した。 アニメーションも試した。
ただ、どれも少し違った。 そのとき頭の中にあったのは、
このツールは“ショーケース”というより“作業台”に近い
という感覚だった。 そこから、
グラデーションを多用しない
グローを使わない
過剰なアニメーションを入れない
というルールが自然にできていった。 面白かったのは、これらが最初から決めていたルールではなかったことだ。 むしろ、
実際に試す
違和感が出る
「これは違う」と感じる
禁止事項になる
という順番だった。
このプロジェクトでは、実装の中から出てきたルールの方が運用しやすかった。
色に少しずつ意味が宿っていく
danger を強調用に使いそうになったことがあった。 でも途中で止まった。 「これはシステムフィードバック用の色だな」と感じたからだった。 そこから、
danger は削除・エラー専用
code は selector/path 専用
という使い分けが固まっていった。
text-danger text-code
ただの色指定だったものに、少しずつ役割が生まれていく。 これも実装を繰り返す中で自然に整理されていった部分だった。
個性が言語化できたタイミングで、DESIGN.md が書けた
ここまで来て、ようやく DESIGN.md が書ける状態になった。 やってみると、やることは意外とシンプルだった。
「なぜそうしたか」をコード付きで残す
それだけだった。
最初に書いたのは「世界観」だった
トークン表より先に、まず世界観を書いた。
これがベースになる。できるだけシンプルに、揺るがないものにしていく。
世界観
作業台（workbench）としての UI。 エンターテインメントではなく、デベロッパーが日常的に使う実務ツール。
暗く静かな背景に、白に近いアクセントで視線を誘導する
グラデーション・グロー・アニメーションは使わない
「邪魔しない」を優先する
これを書いてから、Claude Code の出力もかなり安定した感覚があった。 トークンや className だけでなく、「このプロダクトは何者か」を書いておくと、意図が伝わりやすかった。
抽象論より、実コードを書いた
コンポーネントルールも、説明よりコードをそのまま書くようにした。
// 標準ボタン "inline-flex items-center text-[11px] px-3 py-1.5 rounded border border-border text-muted hover:text-accent hover:border-accent transition-colors outline-none focus-visible:ring-2 focus-visible:ring-accent/45" 少なくとも今回のケースでは、抽象的な説明より、実コードの方が意図を共有しやすかった。
「違う」をコードで残した
禁止事項も、文章だけよりコード比較の方が伝わりやすかった。
❌ Don't
className="bg-gradient-to-r from-slate-900 to-zinc-900 shadow-glow"
✅ Do
className="bg-canvas" こうして並べると、「なぜ違うのか」が感覚レベルで共有しやすくなる。 DESIGN.md はルールブックというより、“違和感の記録”に近いのかもしれない。
DESIGN.md があると、レビュー観点を共有しやすかった
実際に Claude Code に、
「DESIGN.md を参照して LP をレビューして」
と依頼してみた。
すると、ナビリンクに focus-visible:ring-* が入っていないことを指摘してくれた。
// 修正前 <Link className="transition-colors hover:text-accent"> // 修正後 <Link className="transition-colors hover:text-accent outline-none focus-visible:ring-2 focus-visible:ring-accent/45"> これは人間のレビューでも普通に見落としやすい部分だと思う。
ただ、DESIGN.md に UI パターンやアクセシビリティ方針を書いていたことで、レビュー観点を共有しやすくなっていた。
ルールと実装が衝突したこともあった
もうひとつ印象的だったのが、LP のパーティクル背景。 内部的には radial-gradient を使っていた。 つまり、
「グラデーションを使わない」
というルールと少し矛盾していた。 ただ、これは意図的な例外だった。 なので DESIGN.md に追記した。
> 例外: > LP の <LandingParticles> 背景演出レイヤーでは、 > palette-canvas 派生色のグラデーションを限定的に許容する
この経験から、DESIGN.md は固定ルールというより、運用しながら更新されるものなんだと感じた。
DESIGN.md は、意思決定ログに近かった
書いてみて感じたのは、DESIGN.md は AI 向け instruction file というより、
デザイン上の意思決定を残しておく場所
に近いということだった。
なぜアクセントが白なのか
なぜ danger を装飾に使わないのか
なぜグローを避けたのか
その場では自然に決めたことでも、半年後には意外と忘れる。 新しく入ったメンバーにも伝わらない。 DESIGN.md に残しておくと、人間にも AI にも共有しやすくなる。 結果として、
AI は文脈を踏まえてコードを書きやすくなる
人間は判断理由を理解しながら実装できる
そんな状態に少し近づけた気がしている。
DESIGN.md は、あとから書いてもよかった
最初から書けなくても問題なかった。 むしろ、自分の場合は、あとから整理する形の方が合っていた。
例えば、
同じ UI を何度も書き始めたとき
「これは違う」と感じたとき
ボタン色に迷ったとき
禁止したい表現が出てきたとき
そういう瞬間を少しずつメモしていく。 気づくと、それが DESIGN.md になっていた。 プロダクトの個性は、開発の中で少しずつ見えてくる。
DESIGN.md は、その過程で見えてきた判断基準を、あとから整理したものに近いのかもしれない。
読んでくださってありがとうございました。
この記事が「なるほど」と思えたら、「スキ」や「フォロー」もらえるとうれしいです。チームにもシェアしてもらえると、次の記事のモチベーションになります。
プロモーション
iCAREでは、一緒に成長しながら新しいチャレンジに挑戦できる仲間を募集しています。
まずは、カジュアル面談のお申し込み からお気軽にお話ししてみませんか？
皆さまのご応募を、心よりお待ちしています。
XでもUIデザインやプロダクト開発に関する投稿をしています。ご興味がありましたら、ぜひフォローしていただけると嬉しいです。
いいなと思ったら応援しよう！
よろしければ応援お願いします！いただいたチップはUIデザインプロダクト開発に関するnote作成に使わせていただきます！