cs-build-ui-mockup

プランからクリック可能なモックアップを作成する

書かれたプランでは、注目ポイントを表現できません。 画面の順序、配置、階層、選択肢が揃っているかどうかも表現できません。問題が起きるのはまさにこうした点です。メモを何度読み返しても見つけられません。クライアントは言葉には同意した後、画面を見て、まったく違うことを言います。

このスキルでは、プランを実際に見られるものにし、食い違いを明らかにするレビューを実施して、見つかった内容を CodeSpring に書き戻します。

一連の流れの中での位置付け：

cs-build-plan-app  or  cs-build-import-codebase        (map + notes exist)
        │
        ▼
   cs-build-ui-mockup   ← you are here
        │            build it, show it, feed corrections back
        ▼
  cs-build-create-prd → cs-build-create-tasks → cs-build-feature

PRD より先に実行してください。 誰も確認していないプランから生成した PRD は、誤解をより詳細に記述するだけで、修正にかかるコストを増やします。

次を読んでください：codespring スキルの references/project-state.md、references/pitfalls.md、およびこのスキル独自のリファレンス —

リファレンス	読むタイミング
references/design-system.md	CSS を書く前に。 トークンアーキテクチャ、各種スケール、角丸の関係、ブランドの差し替え、ライト／ダークについて説明します。
references/review-method.md	誰かに見せる前に。レビューの先入観を防ぐ進め方、モックアップで確実に見つかる問題、修正内容を書き戻す方法について説明します。

実行環境が対応している場合は、Anthropic の frontend-design スキルも読み込んでください（https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md）。テンプレート的なものではなく、独自性のあるものを作るための手法です。このスキルの design-system.md は、その手法を支える構造です。この環境でスキルをインストールできない場合は、その URL を開いて直接内容に従ってください。

---

0. プランの準備ができているか確認する

bash ../codespring/scripts/fetch-project.sh --out /tmp/cs-state
node ../codespring/scripts/state.mjs       /tmp/cs-state

メモ付きのコア機能が必要です。メモがなければ描くものがありません。メモには、画面のコンテンツ、状態、ルールが記されています。

• マップがない → 別のスキルを使います。まず cs-build-plan-app（コードなし）または cs-build-import-codebase（既存コードあり）を実行してください。
• マップはあるが、メモが不十分またはない → そのことを伝え、先にメモを修正してください。カードのタイトルだけをもとに作ったモックアップでは、すべてを勝手に作り上げてしまい、何も検証できません。
• PRD をすでに生成している → それでも実施する価値はありますが、修正によって PRD の再生成が必要になることを明確に伝えてください。

1. 描き始める前に要件を明確にする

メモと利用者から、次の点を確認してください。これらがあらゆる視覚的な判断の土台になります。

• 誰が使うのか、そしてそれによって何が制約されるのか — 年齢、能力、利用環境、デバイス、どれくらい辛抱強く使えるか。
• メイン画面の単一の役割。
• このプロダクトが記憶に残る、たった一つの瞬間。 大胆な表現はここに使い、それ以外は控えめにします。
• すでに存在するブランド — 色、書体、ロゴ、またはデザインを合わせる既存のプロダクト。
• クライアントから提供された参考資料。 デザインの方向性が指定されている場合は、そのとおりに正確に従ってください — あらゆる既定の方針よりも、クライアントの意向を優先します。
• ライト、ダーク、または両方、およびデフォルトのテーマ。

参考画像が提供されている場合は、明示的に要素を抽出し、その内容を記録してください：名前を付けた 16 進数でのカラーパレット、角丸のスケール、書体の組み合わせ、余白のリズム、参考にする価値のある構造パターンを 2、3 個。次に、あえて取り入れない要素と、その理由を説明してください。参考画像は相手が気に入ったものを示す証拠であって、丸ごと複製するための仕様ではありません。参考画像が想定する利用者と、相手の利用者は異なることがよくあります。

2. すぐに破棄できる最小構成を選ぶ

これは数日で寿命を終えるコミュニケーション用の手段です。アプリそのものではありませんし、誤ってアプリそのものになってしまうことがあってはなりません。

基本方針：対象プラットフォーム本来の流儀で、スタイルが適用され、ルーティングされ、クリックできるページを最速で作れるものを選びます。通常は、ユーティリティ CSS レイヤーを備えたスキャフォールド済みのウェブアプリです。無理なく合わせられるなら最終的な技術スタックに合わせますが、スタックの忠実度を理由にモックアップを遅らせてはいけません。 ネイティブアプリのウェブモックアップも問題ありませんし、一般的です。重要なのは画面です。

バックエンドなし。データベースなし。認証なし。実際の API 呼び出しなし。 すべてハードコードしたサンプルデータを使います。

独立したディレクトリに配置し、名前は明確に mockup/ とします。また、使い捨てであることを1行で明記します。

3. まずデザインシステムを構築する

トークンを用意する前に画面を書いてはいけません。仕様は references/design-system.md にあります。要点は次のとおりです。

• すべての値を一か所にまとめます。 コンポーネント内に16進数のカラーコード、ピクセル値、角丸、フォントスタックを記述してはいけません。例外はありません。リブランド全体を1つのファイルで完了できるようにします。
• ライトモードとダークモードを最初から両方構築し、後付けにしません。 ダークモードを後付けすると、すべての画面を見直すことになります。
• スペーシング、文字サイズ、角丸は、それぞれ1つのスケールを使います。 角丸は意図的な関係性に基づいて選びます。詳細はリファレンスを参照してください。よくある失敗は、理由を誰にも説明できないまま、カードを28、ボタンを6、入力欄を12にすることです。
• 色は具体的な色名ではなく、意味に基づいて定義します。 --surface、--ink、--accent のようにします。--blue は使いません。意味に基づく名前を使うことで、ブランドの差し替えが可能になります。

次に、Anthropic の frontend-design スキルにある2段階のプロセスを実行します。トークンセットを計画し（名前付きカラー4～6色、見出し用と本文用のフォント、レイアウトのコンセプト、そして特徴となる要素を1つ）、その計画を要件に照らして批評し、汎用的なデフォルトに見える部分を修正してから、コードを書き始めます。

4. 画面を構築する

主要な機能ごとに1画面と、最も重要なフローを1つだけ作ります。 すべてのサブ機能を作る必要はありません。プロダクトの全体像が分かるだけのものを作ります。

実際のレビューで問題になったことがあるため、以下は必須です。

• 実際の文言を使います。 lorem ipsum は使いません。不適切な文言を見つけることも目的の1つであり、プレースホルダーテキストではその問題が完全に隠れてしまいます。
• 現実味のあるサンプルデータを使います。 実在しそうな名前と数値を使います。「アイテム1」では見つからない問題も、「椅子からの立ち上がり筋力・10分・レベル2」なら見つかります。
• コントロールは目に見える反応を返すようにします。 クリックしても何も起きないチップは、静的ではなく壊れているように見えます。そのせいでレビューの時間を無駄にすることになります。クリックで変化するハードコードされた状態で十分です。
• 空の状態と初回起動時の状態を描きます。 これらは最も見落とされやすい画面であり、技術に詳しくないユーザーに「壊れている」と最も誤解されやすい画面です。
• 詳細画面があるリスト項目は、すべて開けるようにします。 開けないリストは誰にも信頼されません。また、「クリックして詳細を見るだろう」という想定こそ、モックアップで明らかにするべきことです。
• 選択肢を列挙する場合は、セットが本当に固定されているのでない限り、必ず「その他」や「カスタム」といった選択肢を用意します。 固定リストは実際のユーザーに触れた途端に使い物にならなくなります。

5. スタイルガイドのページを追加する

デザインシステムを、クライアントが実物を見て意見を出せる形で示す /styleguide ルートを作成します。名前と値を添えたカラーパレット、適用例を含む文字サイズのスケール、スペーシングと角丸のスケール、すべての状態を含むボタンと入力欄、カード、ライトモード／ダークモード切り替えを表示します。

これは実際に役立ちます。クライアントがトークン単位で具体的な案を承認または却下できるため、画面を1つずつ見ながら議論するより、はるかに低コストで話し合えます。また、実際のものを構築する担当者にとっても、システムのドキュメントになります。

6. 誰かに見せる前に自分で確認する

• ビルドが成功し、すべてのルートが読み込まれます。
• 実際に見てください。 各画面のスクリーンショットを撮り、実際に目を通します。HTTP 200 だけで確認したモックアップをリリースしてはいけません。
• すべての画面でライトモードとダークモードの両方が機能します。
• フレームワークのブランドを示すものは何も表示されません。開発用バッジ、エラーオーバーレイ、プレースホルダーのファビコンなどです。技術に詳しくないクライアントは、そうしたものを見て「壊れている」と受け取ります。
• 品質の最低ライン：キーボードフォーカスが見えること、見出しの順序が適切であること、動きを減らす設定が尊重されること、横スクロールがないこと。
• Chanelのルール：取り除けるものを1つ見つけてください。

7. レビューを実施する

詳しい方法は references/review-method.md にあります。その要点は次のとおりです。

相手に見せて、黙ってください。 説明したり、考えた理由を話したり、選択を先回りして弁護したりしてはいけません。画面について説明した瞬間、測っているのは画面ではなく、説明に説得力があるかどうかです。

自由回答式の質問だけをしてください。最初に何をするか見せてください、わかりにくいところはありますか、足りないものはありますか、Xを探すとしたらどこを見ますか。

フィードバックは文字どおりに受け止め、意味を別に考えてください。 「ぼんやりして見える」は具体的な改善につながる意見ではありませんが、相手が指しているものには実際に問題があります。「何を示しているのかわからない」は、グラフにタイトルがないという意味です。「これはクリックするものですか」は、1つの画面が何の案内もなく2つの役割を担っているという意味です。

2回のレビューを想定してください。 フィードバックが「これは違う」から「こちらのほうが好みだ」に変わったら、そこで止めます。その時点で必要な理解は得られており、残りはビルド中に決められる好みの問題です。

8. 修正内容を CodeSpring に反映する

このステップがあるからこそ、このスキルを実行する価値があります。 レビューの結果は UI のやることリストではなく、計画の修正内容です。ビルド時に参照される場所に反映してください。

1. 理由は機能のメモに記載します。 決定だけでなく、その理由もです。「ワークアウトを最初に表示します。何かを見せる前に2つ質問すると、何も見ていない段階で2つの判断を求めることになるためです。」 理由があれば、後任者がその変更を元に戻すのを防げます。
2. 影響を受けるタスクすべてに DESIGN REVIEW ブロックを追加します。 そうすれば、その画面を作る人は元の間違いを再発見するのではなく、修正内容を確認できます。
3. レビューで不足が明らかになったものは、新しいタスクにします。 ユーザーが行うことが本当に新しい機能であれば、新しいサブ機能も追加します。
4. メモにモックアップを合意済みの UI リファレンスとして記載し、実行方法も添えます。 同じ画面を説明する文章よりも、モックアップのほうが価値のあるものになりました。

codespring mindmap note <coreFeatureId> --title "How it works — X" --text "$(cat note.txt)"
codespring task update <taskId> --description "$(cat task.txt)"
codespring task create --title "0.x.y — ..." --description "..." --feature <id> --priority high

9. 引き継ぐ

計画がクライアントが実際に確認した内容を反映したら、→ cs-build-create-prd。 続いて cs-build-create-tasks、その後 cs-build-feature を実行します。

モックアップとその実行方法、スタイルガイド、レビューによって計画がどう変わったか、次に何をするかを、明確に伝えてください。

---

うまくいっている状態

• モックアップは PRD より前にできていました。
• デザインシステムを最初に構築し、すべての値が1か所にまとまり、ライトモードとダークモードの両方が機能します。
• /styleguide ルートがあり、ブランディングについてトークンのレベルで話し合えます。
• 実際の文言、もっともらしいデータ、反応するコントロールがあり、空の状態も描画されています。
• 詳細を確認できるすべてのリストが開き、列挙された選択肢にはすべて別の方法があります。
• 説明なしで提示され、自由回答式の質問が使われました。
• すべての修正が、理由付きのメモとタスクのブロックになっています。 個人的なやることリストにはなっていません。
• メモにモックアップが合意済みの UI リファレンスとして記載されています。
• 計画をいくら読んでも見つからなかったことが、少なくとも1つ明らかになりました。 何も見つからなかった場合、モックアップが役に立つほど具体的ではありませんでした。