使い方ガイドの画面図は、1枚もスクショを撮っていない ── ui-sketch で作れるもの

まず現物を見てほしい

soroe の使い方ガイドと wa/ri の使い方ガイドに載っている画面図は、1枚もスクリーンショットを撮っていない。

Claude に UI のコードを読ませて画面構造の JSON に起こさせ、それをスクリプトで SVG に描いている。ui-sketch というスキルにまとめて公開しているものだ。

出てくるのはこういう図になる。

3画面ぶんの流れが1枚に入っていて、番号バッジが要素を指している。左上の青いバッジが画面番号、引き出し線でつながっているのが注釈番号だ。

もう1枚、別のアプリのもの。

同じスクリプトで描いているが、アプリのブランドカラー（soroe は青、wa/ri は紫とオレンジ）はそのまま出る。意味のある色は再現するが、影やグラデーションは再現しないという線引きになっている。

---

番号バッジの色には意味がある

図をよく見ると、バッジに赤い丸と緑の四角の2種類がある。

バッジ	意味
赤い丸	タップしても画面は変わらない（入力欄、表示、トグルなど）
緑の四角	タップすると別の画面・シート・ダイアログへ移る

JSON 側では、注釈に to（遷移先）を書いたものが自動的に緑の四角になる。

{ "n": 1, "target": "amount", "text": "数値のみ。3桁ごとに区切る。" }
{ "n": 2, "target": "submit", "to": "確認ダイアログ", "text": "押すと確認へ。" }

これが効くのは、図を見ただけで「どこを押すと話が進むのか」が分かるからだ。手順書を書いていると「ここをタップ」という文が延々と続くが、緑の四角を追えばいいと分かっていれば読む側の負荷が下がる。

上の soroe の図でいうと、1・2・4・6 が緑の四角で、3・5 が赤い丸になっている。

---

同じ画面の「状態の変化」も描ける

画面遷移だけでなく、1つの画面が入力によってどう変わるかも1枚にできる。

これは soroe の「連続入力」の説明図で、3枚とも同じ画面だ。日付が 7/3 → 7/4 → 完了と進み、下部の「編集中: 7/3（3 / 15）」というカウンタと、上部のマスの色が変わっていく。

スクリーンショットでこれをやると、3回同じ画面を撮って、余計な部分をトリミングして、矢印を後から足すことになる。ラフ画なら JSON を3つ書くだけで済む。

---

なぜスクリーンショットをやめたのか

理由は4つあった。

1. 実装前に描ける。 これが一番大きい。仕様を詰める段階で図が出せるので、「この画面にこのボタンは要らないのでは」という話が作る前にできる。スクショは動くものが無いと撮れない。

2. 文言を直すたびに撮り直さなくていい。 ボタンのラベルを1つ変えただけで、ガイドの図が全部古くなる。ラフ画なら JSON の1行を直して再生成するだけだ。

3. ダミーデータが写り込まない。 スクショには開発中のテストデータが入る。「テスト太郎」「あああ」「¥99999999」が公開ドキュメントに載る事故は、撮る運用をやめると起きない。

4. 端末やOSで見た目が揺れない。 iPhone で撮った図と Android で撮った図が混ざると、同じアプリの説明に見えなくなる。

---

図には文言を焼き込まない

ui-sketch には --md というオプションがあって、これを付けると図には画面と番号バッジだけが残り、見出し・説明文は同名の Markdown に分離される。

out/form.svg   ← 画面 ＋ ①②③ の番号バッジのみ
out/form.md    ← 見出し・番号と説明の対応表

ガイド側は、こう組み立てている。

![はじめての割り勘（3ステップ）](/images/guide/wa-ri/f01-flow-first-warikan.svg)

ルームを作る → 支払いを記録する → 割り勘結果を見る。この3つだけで精算できる。

| No. | 場所 | 説明 |
|---|---|---|
| 1 | クイックスタート | ONにすると人数分のメンバー（自分・A・B…）が自動で登録されるので、メンバー登録の手間が省ける。 |
| 2 | 「作成」ボタン | 作成するとそのままルームトップへ移動する。 |
| 3 | 誰が払った？ | 立て替えた人を1人選ぶ。 |

説明文が画像の外にあるので、文言だけ直したいときに図を作り直さずに済む。検索にも引っかかるし、読み上げにも乗る。画像の中に文章を焼き込むと、このどれもができなくなる。

---

作り方は「Claude が読む、スクリプトが描く」

Dart や Swift の UI は条件分岐・テーマ参照・別ファイルの子ウィジェットに散っているので、構文解析で図にするのは無理がある。

なので分担をこうしている。

1. Claude がコードを読んで、画面構造の JSON に要約する
2. スクリプトがその JSON を決定論的に SVG に描く

JSON が中間成果物として残るので、Claude の読み違いは手で直せるし、次に画面を変えたときも差分だけ直せる。

{
  "title": "支払い登録画面",
  "device": "phone",
  "screens": [
    {
      "appbar": { "leading": "chevron-left", "title": "支払いを登録" },
      "body": [
        { "type": "segmented", "items": ["立替", "共同", "個人"], "active": 0, "id": "kind" },
        { "type": "field", "label": "金額", "placeholder": "0", "trailing": "円", "id": "amount" }
      ]
    }
  ]
}

描画は Python の標準ライブラリだけで動く。PNG にしたいときだけ Chrome のヘッドレスを使う。

---

向かないこと

デザインレビューには使えない。 影・グラデーション・カスタムフォント・実画像は再現しないので、配色や余白の議論には向かない。狙っているのは「ワイヤーフレームより上、モックより下」で、どこに何があるかが一目で分かることだけだ。

だから図の近くには必ず「ラフ画である」と書くようにしている。実装済み画面のモックと誤読されると、配色の指摘が仕様レビューに混ざってくる。

コードに無い要素は足させない。 ここはスキルの本文に強く書いてある。「あった方が自然」で描き足されると、仕様書が嘘になる。図が信用できなくなった時点で、この方法の価値は全部無くなる。

---

使ってみる

スキルの SKILL.md 全文とインストール手順は ui-sketch のページに載せてある。

git clone https://github.com/yuuint/claude-skills.git
cp -r claude-skills/skills/ui-sketch ~/.claude/skills/

examples/ に4種類（フォーム・ダッシュボード・画面遷移・長い画面）のサンプル JSON が入っているので、コピーして中身を差し替えるのが一番早い。

上に貼った図はすべて実際に公開しているものなので、soroe のガイド・wa/ri のガイドで、図と説明表がどう組み合わさっているかも見てもらえます。