Claude Code に UI 実装を頼むと、初回の差分はかなり速く出ます。ですが、実務で困るのは「それっぽい画面」は作れるのに、余白、情報密度、レスポンシブ、hover 状態、空状態、エラー表示、アクセシビリティのどこかが抜けることです。デザインを丸投げすると、見た目の近さだけで完了扱いになり、あとから人間が細部を直す作業が残ります。
この記事は、Claude Code で UI デザイン実装を進めたいが、毎回の見た目チェックと手戻りを減らしたい人向けです。Figma からの完全自動変換ではなく、既存プロダクトの文脈を読み、スクリーンショットと期待状態を渡し、ブラウザで確認しながら仕上げる実務ワークフローとして整理します。
Claude Code 全体の導入順は Claude Code の使い方 実践ガイド、ルールの固定は CLAUDE.md の書き方と育て方、強制チェックは Claude Code Hooks の使い方 実践ガイド を先に読むとつながります。UI 実装を単発プロンプトではなく再現可能な作業系にしたいなら、Harness Engineering 入門 も補助線になります。
先に結論: UI実装は「画像を渡す」だけでは足りない
Claude Code 公式 docs では、視覚的な作業では期待する UI のスクリーンショットを渡し、実装と比較させる使い方が紹介されています。Desktop でも画像やデザイン mockup を添付でき、preview や visual diff review と組み合わせやすくなっています。
ただし、私の実感ではスクリーンショットだけでは足りません。Claude Code は画像を読めますが、画像だけでは次の情報が欠けます。
- どの状態を最優先で合わせるか
- どの余白やタイポグラフィを既存デザインから継承するか
- どの viewport で崩れてはいけないか
- hover / focus / loading / empty / error をどこまで作るか
- 実装後に何をもって合格とするか
つまり、UI 実装で渡すべきものは「画像」ではなく、参照画像、期待状態、検証方法、変更範囲の4点です。
私が使う依頼テンプレート
最初の依頼は長くて構いません。むしろ短すぎると、Claude Code が勝手にスコープを広げます。
この画面の [対象コンポーネント名] を改善したい。
目的:
- 一覧画面で情報を素早く比較できるようにする
- 既存の色・余白・角丸・フォントサイズは src/styles/global.css を優先する
入力:
- 参照スクリーンショット: 添付画像
- 実装対象: src/components/ProjectCard.astro
- 表示確認: /blog または /projects
期待状態:
- desktop では3カラム、tablet では2カラム、mobile では1カラム
- title は2行まで、長い場合はカード高さを壊さない
- hover は影を強めるだけで、位置は動かさない
- empty state と loading state は今回は作らない
検証:
- pnpm run build
- 可能なら Playwright かブラウザで 1440px / 768px / 390px のスクリーンショットを確認
- 変更後に、見た目で自信がない点を箇条書きで報告ポイントは「かっこよくして」ではなく、比較できる、崩れない、既存ルールに寄せるのように評価軸を先に渡すことです。
ワークフローは4段階に分ける
UI 実装を一回の依頼で終わらせようとすると、だいたい荒れます。私は次の4段階に分けます。
1. 既存UIを読ませる
最初にコードだけでなく、既存のページ構造とスタイル変数を読ませます。
実装前に src/styles/global.css、対象ページ、関連コンポーネントを読み、
このサイトのUIルールを10項目以内で要約して。
まだ編集しないで。ここで編集を止めるのが重要です。Claude Code はすぐ実装に入りたがりますが、UI は既存文脈を外すと一気に安っぽくなります。色、余白、border radius、カードの情報密度、見出しサイズを先に要約させるだけで、初回差分のズレが減ります。
2. 期待状態を固定する
次に、何を作るかを決めます。ここで「全状態を作って」と言うと過剰実装になりやすいので、必要な状態だけに絞ります。
今回作る状態は normal / hover / mobile の3つだけ。
loading / error / empty は既存コンポーネントに存在しないため追加しない。業務ツールなら dense なテーブル、SaaS の設定画面なら情報の読み取りやすさ、ブログなら本文導線というように、画面の目的で判断基準を変えます。Claude Code に UI を任せるときほど、目的語を「画面」ではなく「利用者の作業」に寄せた方が安定します。
3. 実装後にブラウザで確認する
Claude Code 公式 docs は、テストケースや期待出力を渡すと自己検証しやすいと説明しています。UI でも同じです。pnpm run build だけでは、見た目の破綻は拾えません。
Playwright を使える環境なら、最低でも viewport を切って確認します。
import { test, expect } from "@playwright/test";
test("blog cards do not overflow on mobile", async ({ page }) => {
await page.setViewportSize({ width: 390, height: 844 });
await page.goto("/blog");
await expect(page.getByRole("main")).toBeVisible();
await expect(page.locator(".blog-card").first()).toBeVisible();
});Playwright 公式 docs は web-first assertions や trace viewer を推奨しています。UI 変更では、スクリーンショットだけでなく「主要要素が見える」「テキストが溢れない」「操作対象が存在する」のような DOM ベースの確認も混ぜると、見た目だけの合格を避けられます。
4. 不安点を自己申告させる
最後に、Claude Code に「完了しました」だけを言わせないようにします。
実装後、次の形式で報告して。
- 変更したUI意図
- 確認したviewport
- 自信がない箇所
- 人間が見るべき差分UI は主観が残ります。だからこそ、Claude Code に「自信がない箇所」を出させるとレビュー効率が上がります。特に spacing、折り返し、画像 crop、contrast は自己申告させた方がよいです。
CLAUDE.md に書くべきUIルール
毎回プロンプトに書くと漏れるルールは、CLAUDE.md に短く固定します。ただし、全部は書きません。Claude がコードから読める情報は残さず、判断に使うルールだけを置きます。
## UI implementation
- Prefer existing CSS variables and component patterns before adding new colors or spacing scales.
- For UI changes, verify desktop and mobile layouts before reporting completion.
- Do not add decorative gradients, oversized hero sections, or nested cards to operational pages.
- When text may be long, preserve layout with wrapping, min/max widths, or line clamping.ここで「美しくする」「モダンにする」のような曖昧な言葉を入れてはいけません。曖昧な形容詞は、余計な装飾を呼びます。UI ルールは、禁止する崩れ方と優先する既存パターンだけに絞る方が効きます。
Hooks に寄せるべきチェック
文章で守らせるより、機械的に確認できるものは Hooks や npm scripts に逃がします。
- format
- typecheck
- build
- Playwright の主要 smoke test
- スクリーンショット保存
- forbidden file の編集禁止
たとえば UI 変更後に必ず build を走らせたいなら、CLAUDE.md に長く書くより、既存の作業ルールや Hook に寄せた方が確実です。Hooks の考え方は Claude Code Hooks の使い方 実践ガイド で詳しく書きましたが、UI 実装でも本質は同じです。忘れると困る処理は、お願いではなく仕組みにする。
Claude Code に任せてよいUI、任せないUI
私なら、次のように分けます。
| 任せやすい | 人間が先に設計すべき |
|---|---|
| 既存コンポーネントの整理 | 新規プロダクトの情報設計 |
| カード、一覧、設定画面の改善 | ブランドの第一印象を決めるトップヒーロー |
| レスポンシブ崩れの修正 | 複雑なグラフィックや独自アニメーション |
| フォームの状態追加 | 価格体系や権限モデルを含む画面設計 |
| Playwright で再現できる不具合 | 事業上の優先順位が絡む UX 判断 |
Claude Code は既存ルールに寄せる作業が強いです。逆に、まだルールがない画面で「いい感じにして」と頼むと、見た目の方向性を勝手に作ります。最初のデザインシステムや情報設計は人間が責任を持ち、Claude Code にはその制約内で実装・検証・微修正を回させる方が堅いです。
実務でよくある失敗
スクリーンショットだけで期待状態を書かない
画像は完成形の一瞬しか表しません。レスポンシブ、長文、空データ、権限差分、hover は画像に出ません。スクリーンショットを渡すなら、必ず「この画像で合わせたいのは何か」を書きます。
1回で全画面を直そうとする
UI は差分が広がるほどレビューが難しくなります。カード、ヘッダー、フィルター、詳細ページを一気に頼むより、1つの画面の1つの役割に絞った方が品質が上がります。
見た目確認を build 成功で代替する
build は構文や型の確認であって、UI の確認ではありません。文字がボタンからはみ出しても、カードが不自然に伸びても、build は通ります。UI 変更では、少なくとも desktop / mobile の表示確認を別に置くべきです。
装飾を増やして品質が上がったと錯覚する
Claude Code に「もっとリッチに」と言うと、影、グラデーション、大きなカード、不要なアニメーションが増えやすいです。業務画面や技術ブログでは、装飾より情報密度と可読性の方が重要です。必要なのは派手さではなく、利用者が迷わず読めることです。
まとめ
Claude Code で UI デザイン実装を進めるなら、コツは「画像を読ませること」ではありません。Claude Code が自分で正誤を判断できる状態を作ることです。
- 既存 UI ルールを先に読ませる
- 参照スクリーンショットと期待状態を分けて渡す
- desktop / mobile の確認を検証手順に入れる
- 不安点を自己申告させる
- 繰り返すルールは
CLAUDE.mdと Hooks に固定する
この流れにすると、Claude Code は単なる UI 生成ツールではなく、実装、確認、修正を回す UI ワークフローの一部になります。最初に仕組みを作る手間はありますが、毎回の「なんとなく違う」を減らせるので、結果的に人間のレビュー時間も短くなります。
参考情報
- Claude Code docs: How Claude Code works: https://code.claude.com/docs/en/how-claude-code-works
- Claude Code docs: Desktop application: https://code.claude.com/docs/en/desktop
- Claude Help Center: Claude Code common developer use cases: https://support.claude.com/en/articles/14553517-claude-code-common-developer-use-cases
- Playwright docs: Best Practices: https://playwright.dev/docs/best-practices