このサイトは、Claudeのデザイン機能で作ったHTML/CSS/JSのプロトタイプを、Astro + TypeScript + MDX + Tailwind CSS v4 の構成で実装し直し、Cloudflare Pagesに載せたものです。デザインから実装への「ハンドオフ」で意識したことをまとめます。

チャットの履歴こそが仕様書

ハンドオフバンドルには、完成したプロトタイプのコードだけでなく、デザイン中の対話履歴が丸ごと含まれていました。最初はコードだけ読めば十分だと思っていましたが、実際には逆でした。

「見出しが大きすぎるので抑えたい」「ホバーでカーソルがズレるのを直した」「アイコンが浮いているので描き直した」——最終形のコードには、こうした試行錯誤の結果だけが残っていて、なぜそうなっているのかは履歴にしか書かれていません。仕様書のないデザインでは、対話の記録が仕様書の代わりになります。

ピクセルを合わせ、構造は合わせない

プロトタイプはあくまで描画結果のモックです。見た目は忠実に再現しつつ、内部構造は実装先の流儀に合わせて組み直しました。

  • 1枚の長いHTMLは、セクションごとのAstroコンポーネントに分割
  • 繰り返し要素（スキルカード、実績、記事一覧）はデータ配列から生成し、記事はMDXのコンテンツコレクションへ
  • 即時実行関数で書かれたスクリプトは、TypeScriptの型を付けてモジュールに分離

「見た目はコピー、構造は翻訳」と捉えると、判断に迷いがなくなります。

プロトタイプ専用の機能を見極める

バンドルには、配色や書体をその場で切り替えるデザイン検討用のReact製パネルも含まれていました。これは制作中の比較検討のための道具であって、公開サイトの機能ではありません。何を移植して何を捨てるかの線引きも、ハンドオフの大事な仕事です。おかげで本番のクライアントJSはモード切替と演出だけの数KBに収まりました。

まとめ

  • 最終形のコードは「結果」、対話履歴は「理由」。両方読む
  • 見た目はピクセル単位で合わせ、構造は実装先に最適化する
  • 検討用の機能は移植しない勇気を持つ

デザインツールと実装の距離は年々縮まっていますが、「意図を読み取って翻訳する」工程は、まだ人間とエージェントの腕の見せどころだと感じます。