til/…/better-ui-ux-workflow
better-ui-ux-workflow.mdupdated 2026-08-012,455 chars

Claude Code で​美しい​ UI/UX を​引き出すワークフロー

この​tilリポジトリを​雑に​組み立てたあと、​考え直して​2026年5月時点の​エコシステムを​調査し、​この​推奨ワークフローを​整理した。

1. 仕様固め​（言葉で​先に​決める）

  • 参照したい​サイト3〜5件​（例：​「Stripeの​ドキュメントのような​感じ」）
  • 避けたい​サイト1〜2件​（例：​「こうは​したくない」）
  • 形容詞3語​（例：​「真面目・等幅・​落ち着いた」​「ブルータリズム​（＝コンクリート打ちっ放しのような​無骨な​建築様式に​着想を​得た​デザイン潮流）」​「レトロフューチャー」など）
  • 想定する​読者と​使用デバイス
  • Anthropic​（アンソロピック）​公式のFrontend Aesthetics Cookbookを​CLAUDE.mdに​取り込み、​「AIっぽさ」を​避ける​ルール​（Inter・Robotoなどの​既定フォント禁止、​紫の​グラデーション禁止、​過剰な​影の​禁止など）を​最初から​効かせる
  • 公式のfrontend-designスキルを​有効化すると、​CLAUDE.mdを​基点に​デザイン哲学が​自動で​注入される

ここを​先に​固める​ことで、​Claudeが​推測しなければならない​範囲が​大きく​狭まる。

2. 探索​（3案を​並列に​出す）

  • claude --worktree（＝独立した​作業ブランチを​複数同時に​持つ機能）で​3〜5個の​独立した​セッションを​立ち上げ、​worktree​（作業ツリー）​ごとに​異なる​方​向性の​デザインを​並列に​実装する

UI生成の​ための​MCP​（Model Context Protocol＝AIエージェントが​外部​ツールを​呼び出すための​標準規格）の​選び方は​次の​とおりである。

  • shadcnの​公式MCP —— 複数の​レジストリ​（部品の​配布元）から​コンポーネントを​導入する​デファクトスタンダード​（＝事実上の​標準）である。
  • 21st.dev Magic MCP —— 1つの​プロンプトから​複数の​バリエーションを​一括​生成し、​比較して​選ぶスタイルは​並列案の​検討に​向く。
  • v0 MCP —— 画像から​Reactコードへの​変換が​必要な​場合に​使う。

1案を​磨き込むよりも、​3案作って​2案を​捨てる方が​正解に​たどり着くのが​速い。

3. ローカルプレビューと​自己検証ループ

  • bundle exec jekyll serveのような​コマンドで​ローカル起動する。
  • Playwright MCP（microsoft/playwright-mcp）を​使い、​Claude自身に​ナビゲート→スクリーンショット→コンソール確認→自己修正と​いう​ループを​回させる。
  • 用途で​使い分ける。​Playwright MCPは​CI​（＝継続的インテグレーション。​コード変更の​たびに​自動で​ビルド・テストする​仕組み）​／テスト用途、​Chrome DevTools MCPは​デバッグ・パフォーマンス計測用途。​2026年時点では​両方の​併用が​標準である。
  • push​（＝変更を​リポジトリへ​送信する​こと）してから​直す​一往復は​遅い。​kramdownの​バグのような​描画上の​不具合は、​事前に​ローカルで​洗い出しておく。

4. イテレーション​（見てから​言葉で​直す）

  • スクリーンショットを​Claudeに​渡す→不満を​1文で​伝える​→CSS／マークアップを​修正する​→再度スクリーンショットを​撮る。
  • これを​3〜5回繰り返す。
  • Figma​（フィグマ）を​使う​場合は、​公式のFigma Dev Mode MCPの​Code to Canvas機能で​双方​向の​同期が​でき、​デザイナーの​レビューに​差し戻せる。

5. 品質ゲート​（pushの​前に）

  • Design Reviewサブエージェント（＝独立した​文脈で​動く​レビュー専用の​AI）を​立てる。​Playwrightで​キャプチャし、​WCAG 2.1 AA​（後述）と​ヒューリスティック​（＝経験則に​基づく​簡便な​判断法）に​よる​自動監査を​行い、​修正案を​得る。
  • PRレベル​（＝1回の​変更提案単位）の​スクリーンショット差分には​Argos、​意味的な​差分​（3pxの​ズレが​実際に​問題か​どうかの​判断）には​Applitools Visual AIを​使う。
  • /grill（＝コードの​視覚版に​あたる​厳格レビューコマンド）の​視覚版と​して​最後に​実行する。

6. Storybook / カタログ​（デザインシステムを​持つ​場合のみ）

  • @storybook/addon-mcpは、​コンポーネントや​ストーリー​（＝コンポーネントの​見本表示）を​MCP経由で​AIに​公開する。
  • TSの​props​（＝コンポーネントへ渡す設定値）から​argTypesへの​マッピングを​通じて​CSF3形式の​ストーリーを​自動生成する。
  • tilのような​一発物の​リポジトリには​不要で、​デザインシステムを​保有する​本格的な​プロジェクト向けである。

7. 失敗パターン

  • 「いい​感じに​して」と​丸投げする​→参照の​質次第の​運任せに​なる。
  • pushした​後に​しか​見ない​→描画上の​不具合に​気づくのが​遅れる。
  • 1案のみで​進める​→比較対象が​なく、​許容できる​線が​どこかを​判断できない。
  • 仕様固めの​段階で​Anthropic公式の​cookbookを​無視する​→紫の​グラデーション・Inter・絵文字の​氾濫と​いう​典型的な​AI出力に​逆戻りする。
  • 視覚系の​MCPを​使わず​「コードだけ」で​レビューする​→描画上の​不具合を​見逃す。

出典・参考

関連ノート

148 notestil