Claude Code でより美しい UI/UX を得るフロー

この til リポを雑に作ったあと反省し、2026-05 時点のエコシステムを調査して整理した推奨フロー。

1. Specification（言葉で固める）

  • 参照したいサイト 3〜5 個（"Stripe の docs のような"）
  • 避けたいサイト 1〜2 個（"これっぽくはしないで"）
  • 形容詞 3 つ（"serious, monospaced, calm" / "brutalist" / "retro-futuristic" など）
  • 想定読者とデバイス
  • Anthropic 公式 Frontend Aesthetics Cookbook を CLAUDE.md に取り込み、"AI slop" 回避ルール（Inter / Roboto などの定番フォント禁止、紫グラデ禁止、影過多禁止 等）を最初から効かせる
  • 公式の frontend-design skill を有効化すると、デザイン哲学が CLAUDE.md ベースで自動注入される

最初にここを詰めると、Claude の推測幅が一気に狭まる。

2. Exploration（並列で 3 案）

  • claude --worktree で 3〜5 個の独立セッションを起動、各 worktree で違う方向のデザインを並列実装
  • UI 生成 MCP の使い分け:
    • shadcn 公式 MCP — 複数 registry 横断で component install。事実上の標準
    • 21st.dev Magic MCP — 1 プロンプトで複数バリエーションを同時生成、比較選択型なので並列案向き
    • v0 MCP — 画像 → React コード変換が必要な時に
  • 1 案を磨くより、3 案出して 2 案捨てる方が早く正解に近づく

3. Local preview + 自己検証ループ

  • bundle exec jekyll serve などローカル起動
  • Playwright MCP（microsoft/playwright-mcp）で Claude 自身に navigate → screenshot → console 確認 → 自己修正のループを回させる
  • 用途で使い分け: Playwright MCP = CI / test、Chrome DevTools MCP = debug / perf。2026 は両方併用が定番
  • push してから直すサイクルは遅い。kramdown バグのような描画事故はローカルで先に出す

4. Iteration（見て、言葉で直す）

  • スクリーンショットを Claude に渡す → 不満を 1 文 → CSS / markup を直す → 再スクショ
  • これを 3〜5 周
  • Figma を使うなら公式 Figma Dev Mode MCP の Code to Canvas で双方向 sync、デザイナーレビューに戻せる

5. 品質ゲート（push 前）

  • Design Review サブエージェントを立てる: Playwright で撮影 → WCAG 2.1 AA + ヒューリスティック自動監査 → 修正提案
  • Argos などで PR レベルの screenshot diff、Applitools Visual AI で意味的 diff（3px ズレが意味あるか判定）
  • /grill の視覚版として最後に通す

6. Storybook / カタログ（design system がある場合のみ）

  • @storybook/addon-mcp で components / stories を MCP 経由で AI に exposure
  • TS props → argTypes mapping で CSF3 story を自動生成
  • til のような単発 repo では不要、design system 持ちの本格プロジェクト向け

7. 失敗パターン

  • 「いい感じに」と言って投げる → reference の質ガチャになる
  • push してから見る → 描画事故に気づくのが遅い
  • 1 案で進める → 比較がないので妥協ラインがわからない
  • Specification 段で Anthropic 公式 cookbook を無視する → 紫グラデ・Inter・大量絵文字の典型 AI 出力に戻る
  • Visual MCP を入れずに「コードだけで」レビューする → レンダリングバグを見落とす

参考・引用元

2026-05-14

関連ノート