画面遷移図の書き方と例｜Mermaidで作る手順と画面一覧テンプレート

画面遷移図とは、システムにどんな画面があり、どの操作でどの画面へ移るかを、箱と矢印で1枚にまとめた図です。 先に「画面一覧」という表を作り、その表から図を起こすと、画面の抜けや行き止まりを早い段階で見つけられます。

この記事では、画面ID・画面名・種別・遷移元・遷移先・認証要否を持つ画面一覧のテンプレートをMarkdownとCSVで用意し、架空の会員サイト12画面で記入します。さらに、その画面一覧CSVからMermaidのflowchartコードを作るPythonコードを載せ、分岐・エラー画面・モーダル・ログイン要否の書き分けまで、生成されたコードと一緒に示します。1画面の中の項目定義には触れず、画面と画面のつながりと一覧の管理に絞ります。

確認環境：Ubuntu 24.04、Python 3.11.15、@mermaid-js/mermaid-cli 11.14.0（同梱の Mermaid 11.14.0、Chromium で描画）。掲載した Mermaid のコードはすべてこの環境で SVG に描画できたものです。

画面遷移図の書き方の早見表

画面遷移図を作る5つの手順

図を先に描き始めず、表から始めるのが、あとで直しやすい作り方です。

手順4と5をコードに任せると、表を直すだけで図も同じ内容に変わります。図と表を別々に手で直す作業がなくなり、レビューでは「流れが正しいか」に集中できます。

画面一覧のテンプレート（MarkdownとCSV）

列は6つです。まずは空のテンプレートです。

| 画面ID | 画面名 | 種別 | 遷移元 | 遷移先 | 認証要否 |
|---|---|---|---|---|---|
| SCR-000 | （画面名） | 通常 | （遷移元の画面ID） | （遷移先ID:操作） | 不要 |

表計算ソフトで管理するときは、次のCSVを貼り付けて使います。

画面ID,画面名,種別,遷移元,遷移先,認証要否
SCR-000,（画面名）,通常,（遷移元の画面ID）,（遷移先ID:操作）,不要

各列の書き方は次のとおりです。

番号帯の例です。間を空けて振ると、あとから画面を足しても並びが保てます。

遷移元と遷移先は同じ情報を両側から書いたものです。両方を書いておくと、表の1行を読むだけで「この画面にどこから来て、どこへ行くか」がわかり、テストで確認する経路も数えやすくなります。食い違いはこのあとのコードで検査します。

記入例：会員サイト12画面の画面一覧

架空の会員サイトを題材に、12画面を記入しました。

同じ内容のCSVです。screens.csv という名前で保存します。

画面ID,画面名,種別,遷移元,遷移先,認証要否
SCR-001,トップ,通常,SCR-022;SCR-121;SCR-900,SCR-010:ログインへ;SCR-020:新規登録へ,不要
SCR-010,ログイン,通常,SCR-001;SCR-010;SCR-011,SCR-100:ログイン?認証OK;SCR-010:ログイン?入力エラー;SCR-900:ログイン?システムエラー;SCR-011:パスワードを忘れた,不要
SCR-011,パスワード再設定,通常,SCR-010,SCR-010:再設定メール送信,不要
SCR-020,会員登録入力,通常,SCR-001;SCR-020;SCR-021,SCR-021:確認へ?入力OK;SCR-020:確認へ?入力エラー,不要
SCR-021,会員登録確認,通常,SCR-020,SCR-022:登録する?登録OK;SCR-900:登録する?システムエラー;SCR-020:修正する,不要
SCR-022,会員登録完了,完了,SCR-021,SCR-001:トップへ,不要
SCR-100,マイページ,通常,SCR-010;SCR-110;SCR-111;SCR-120,SCR-110:会員情報を編集;SCR-120:退会する,要
SCR-110,会員情報編集,通常,SCR-100;SCR-111,SCR-111:保存;SCR-100:キャンセル,要
SCR-111,保存確認モーダル,モーダル,SCR-110,SCR-100:はい;SCR-110:いいえ,要
SCR-120,退会確認モーダル,モーダル,SCR-100,SCR-121:退会する;SCR-100:やめる,要
SCR-121,退会完了,完了,SCR-120,SCR-001:トップへ,不要
SCR-900,エラー,エラー,SCR-010;SCR-021,SCR-001:トップへ,不要

種別ごとの内訳は、通常7、モーダル2、完了2、エラー1です。ログイン画面の遷移先に SCR-010 自身があるのは、入力エラーのときに同じ画面へ戻ってメッセージを出すためです。

画面一覧CSVからMermaidのコードを作るPythonコード

標準ライブラリだけで動きます。csv2mermaid.py として screens.csv と同じフォルダに保存してください。

"""画面一覧CSVから Mermaid の flowchart と Markdown の表を作る。
使い方: python3 csv2mermaid.py screens.csv            （Mermaid を標準出力へ）
        python3 csv2mermaid.py screens.csv --table    （Markdown の表を標準出力へ）
"""
import csv
import sys

# 種別ごとのノードの形（Mermaid の括弧）とクラス名
SHAPES = {
    "通常": ('["', '"]', "normal"),
    "モーダル": ('[["', '"]]', "modal"),
    "完了": ('(["', '"])', "done"),
    "エラー": ('{{"', '"}}', "error"),
}
GROUPS = {"不要": ("PUBLIC", "ログイン不要"), "要": ("MEMBER", "ログイン必要")}


def nid(screen_id):
    """SCR-010 → SCR010（ノードIDにハイフンを入れない）"""
    return screen_id.replace("-", "")


def parse_targets(cell):
    """「SCR-100:ログイン?認証OK;SCR-011:パスワードを忘れた」を
    [(遷移先ID, 操作, 条件), ...] にする。条件が無ければ空文字。"""
    result = []
    for part in filter(None, (p.strip() for p in cell.split(";"))):
        target, _, label = part.partition(":")
        action, _, cond = label.partition("?")
        result.append((target.strip(), action.strip(), cond.strip()))
    return result


def load(path):
    with open(path, encoding="utf-8-sig", newline="") as f:
        return list(csv.DictReader(f))


def check(rows):
    """画面一覧の矛盾を文字列のリストで返す。空なら問題なし。"""
    errors = []
    ids = [r["画面ID"] for r in rows]
    for i in sorted({i for i in ids if ids.count(i) > 1}):
        errors.append(f"{i}: 画面IDが重複しています")
    incoming = {i: set() for i in ids}
    for r in rows:
        if r["種別"] not in SHAPES:
            errors.append(f"{r['画面ID']}: 種別「{r['種別']}」は定義されていません")
        if r["認証要否"] not in GROUPS:
            errors.append(f"{r['画面ID']}: 認証要否「{r['認証要否']}」は 要／不要 で書きます")
        for target, _, _ in parse_targets(r["遷移先"]):
            if target not in incoming:
                errors.append(f"{r['画面ID']}: 遷移先 {target} が画面一覧にありません")
            else:
                incoming[target].add(r["画面ID"])
    for r in rows:
        written = set(filter(None, (s.strip() for s in r["遷移元"].split(";"))))
        actual = incoming.get(r["画面ID"], set())
        for s in sorted(actual - written):
            errors.append(f"{r['画面ID']}: 遷移元に {s} が書かれていません")
        for s in sorted(written - actual):
            errors.append(f"{r['画面ID']}: 遷移元 {s} からの遷移が {s} の遷移先にありません")
        if not actual and r["画面ID"] != rows[0]["画面ID"]:
            errors.append(f"{r['画面ID']}: どの画面からも遷移できません")
    return errors


def to_mermaid(rows):
    kind = {r["画面ID"]: r["種別"] for r in rows}
    out = ["flowchart TD"]
    # 1) 認証要否ごとにサブグラフへ入れる。条件つきの操作は判定のひし形も同じ枠に置く
    judges = {}
    for key, (gid, title) in GROUPS.items():
        out.append(f'    subgraph {gid}["{title}"]')
        for r in rows:
            if r["認証要否"] != key:
                continue
            src = nid(r["画面ID"])
            left, right, cls = SHAPES[r["種別"]]
            label = f"{r['画面ID']}<br/>{r['画面名']}"
            out.append(f"        {src}{left}{label}{right}:::{cls}")
            for _, action, cond in parse_targets(r["遷移先"]):
                if cond and (src, action) not in judges:
                    count = sum(1 for s, _ in judges if s == src)
                    judges[(src, action)] = f"{src}_J{count + 1}"
                    out.append(f'        {judges[(src, action)]}{{"{action}"}}:::judge')
        out.append("    end")
    # 2) 遷移。エラー画面への線だけ点線にする
    for r in rows:
        src = nid(r["画面ID"])
        linked = set()
        for target, action, cond in parse_targets(r["遷移先"]):
            arrow = "-.->" if kind[target] == "エラー" else "-->"
            if not cond:
                out.append(f'    {src} {arrow}|"{action}"| {nid(target)}')
                continue
            judge = judges[(src, action)]
            if judge not in linked:
                linked.add(judge)
                out.append(f"    {src} --> {judge}")
            out.append(f'    {judge} {arrow}|"{cond}"| {nid(target)}')
    # 3) 種別ごとの色
    out += [
        "    classDef normal fill:#ffffff,stroke:#333333,color:#111111",
        "    classDef modal fill:#fff4d6,stroke:#b8860b,color:#111111",
        "    classDef done fill:#e3f4e1,stroke:#2e7d32,color:#111111",
        "    classDef error fill:#fde2e2,stroke:#c62828,color:#111111",
        "    classDef judge fill:#e8f0fe,stroke:#1a56b0,color:#111111",
    ]
    return "\n".join(out)


def to_table(rows):
    cols = list(rows[0].keys())
    lines = ["| " + " | ".join(cols) + " |", "|" + "---|" * len(cols)]
    for r in rows:
        cells = [r[c].replace(";", "、") for c in cols]
        lines.append("| " + " | ".join(cells) + " |")
    return "\n".join(lines)


if __name__ == "__main__":
    rows = load(sys.argv[1])
    problems = check(rows)
    if problems:
        print("\n".join(problems), file=sys.stderr)
        sys.exit(1)
    print(to_table(rows) if "--table" in sys.argv else to_mermaid(rows))

実行コマンドです。

python3 csv2mermaid.py screens.csv > flow.mmd

生成された flow.mmd の全文です（51行）。

flowchart TD
    subgraph PUBLIC["ログイン不要"]
        SCR001["SCR-001<br/>トップ"]:::normal
        SCR010["SCR-010<br/>ログイン"]:::normal
        SCR010_J1{"ログイン"}:::judge
        SCR011["SCR-011<br/>パスワード再設定"]:::normal
        SCR020["SCR-020<br/>会員登録入力"]:::normal
        SCR020_J1{"確認へ"}:::judge
        SCR021["SCR-021<br/>会員登録確認"]:::normal
        SCR021_J1{"登録する"}:::judge
        SCR022(["SCR-022<br/>会員登録完了"]):::done
        SCR121(["SCR-121<br/>退会完了"]):::done
        SCR900{{"SCR-900<br/>エラー"}}:::error
    end
    subgraph MEMBER["ログイン必要"]
        SCR100["SCR-100<br/>マイページ"]:::normal
        SCR110["SCR-110<br/>会員情報編集"]:::normal
        SCR111[["SCR-111<br/>保存確認モーダル"]]:::modal
        SCR120[["SCR-120<br/>退会確認モーダル"]]:::modal
    end
    SCR001 -->|"ログインへ"| SCR010
    SCR001 -->|"新規登録へ"| SCR020
    SCR010 --> SCR010_J1
    SCR010_J1 -->|"認証OK"| SCR100
    SCR010_J1 -->|"入力エラー"| SCR010
    SCR010_J1 -.->|"システムエラー"| SCR900
    SCR010 -->|"パスワードを忘れた"| SCR011
    SCR011 -->|"再設定メール送信"| SCR010
    SCR020 --> SCR020_J1
    SCR020_J1 -->|"入力OK"| SCR021
    SCR020_J1 -->|"入力エラー"| SCR020
    SCR021 --> SCR021_J1
    SCR021_J1 -->|"登録OK"| SCR022
    SCR021_J1 -.->|"システムエラー"| SCR900
    SCR021 -->|"修正する"| SCR020
    SCR022 -->|"トップへ"| SCR001
    SCR100 -->|"会員情報を編集"| SCR110
    SCR100 -->|"退会する"| SCR120
    SCR110 -->|"保存"| SCR111
    SCR110 -->|"キャンセル"| SCR100
    SCR111 -->|"はい"| SCR100
    SCR111 -->|"いいえ"| SCR110
    SCR120 -->|"退会する"| SCR121
    SCR120 -->|"やめる"| SCR100
    SCR121 -->|"トップへ"| SCR001
    SCR900 -->|"トップへ"| SCR001
    classDef normal fill:#ffffff,stroke:#333333,color:#111111
    classDef modal fill:#fff4d6,stroke:#b8860b,color:#111111
    classDef done fill:#e3f4e1,stroke:#2e7d32,color:#111111
    classDef error fill:#fde2e2,stroke:#c62828,color:#111111
    classDef judge fill:#e8f0fe,stroke:#1a56b0,color:#111111

このコードを mermaid-cli で描画すると、上に「ログイン不要」、左下に「ログイン必要」の枠ができ、12個の画面と3個のひし形が矢印でつながった図になります。

Markdownの表も同じCSVから出力できます。上の記入例の表は、このコマンドの出力をそのまま貼ったものです。

python3 csv2mermaid.py screens.csv --table

画面一覧の矛盾を見つける（検査の出力）

check() は、図を作る前に次の5点を調べます。

わざと3か所を書き換えたCSV（トップの遷移元から SCR-900 を削る、マイページの遷移先を SCR-115 にする、エラー画面の種別を「異常」にする）で実行した結果です。

python3 csv2mermaid.py bad.csv; echo "exit=$?"

SCR-100: 遷移先 SCR-115 が画面一覧にありません
SCR-900: 種別「異常」は定義されていません
SCR-001: 遷移元に SCR-900 が書かれていません
SCR-110: 遷移元 SCR-100 からの遷移が SCR-100 の遷移先にありません
exit=1

3か所の書き換えに対して4行が出ています。遷移先を SCR-115 に変えたことで、「SCR-115 が一覧にない」と「SCR-110 の遷移元に書かれた SCR-100 から実際には来ていない」の2つが見つかったためです。終了コードが1になるので、CIに組み込めば、矛盾のある画面一覧がそのまま取り込まれることを防げます。

分岐・エラー画面・モーダル・ログイン要否の書き分け

生成されたコードのうち、書き分けの部分だけを小さな図にして説明します。4つとも単独で描画できます。

分岐：操作の結果で行き先が変わるとき

CSVの遷移先に SCR-100:ログイン?認証OK;SCR-010:ログイン?入力エラー のように「操作?条件」を書くと、同じ操作がひし形1つにまとまります。

flowchart TD
    SCR010["SCR-010<br/>ログイン"]
    SCR100["SCR-100<br/>マイページ"]
    SCR010 --> J1{"ログイン"}
    J1 -->|"認証OK"| SCR100
    J1 -->|"入力エラー"| SCR010

矢印のラベルには「条件」を、ひし形には「操作」を書きます。 ひし形を挟まずに画面から2本の矢印を出すと、「ログイン」というラベルが2本に付いて、どちらが成功時かが読み取りにくくなります。

エラー画面：点線でつなぐ

エラー画面は多くの画面から線が集まります。エラー画面へ向かう線だけ点線（-.->）にすると、通常の流れと見分けがつきます。

flowchart TD
    SCR021["SCR-021<br/>会員登録確認"]
    SCR022(["SCR-022<br/>会員登録完了"])
    SCR900{{"SCR-900<br/>エラー"}}:::error
    SCR021 -->|"登録OK"| SCR022
    SCR021 -.->|"システムエラー"| SCR900
    classDef error fill:#fde2e2,stroke:#c62828,color:#111111

どの画面でも起こりうるエラー（通信が切れた、など）まで全部の画面から線を引くと、図が線で埋まります。画面一覧には「そのエラー画面へ移ると決めた操作」だけを書き、共通のエラーは図の外に一文で書いておくと読みやすくなります。

モーダル：二重枠の箱にする

モーダルは、元の画面の上に重なって表示される確認用の小窓です。URLが変わらないことが多く、ブラウザの「戻る」での動きも通常の画面と違うため、種別を分けて形を変えておくと、実装とテストで扱いを分けやすくなります。

flowchart TD
    SCR110["SCR-110<br/>会員情報編集"]
    SCR111[["SCR-111<br/>保存確認モーダル"]]:::modal
    SCR100["SCR-100<br/>マイページ"]
    SCR110 -->|"保存"| SCR111
    SCR111 -->|"はい"| SCR100
    SCR111 -->|"いいえ"| SCR110
    classDef modal fill:#fff4d6,stroke:#b8860b,color:#111111

ログイン要否：サブグラフで領域を分ける

subgraph で囲むと、ログインが必要な画面がひと目でわかります。枠をまたぐ矢印が「ログイン状態が変わる場所」なので、認証のチェックを入れる場所の確認にも使えます。

flowchart TD
    subgraph PUBLIC["ログイン不要"]
        SCR010["SCR-010<br/>ログイン"]
    end
    subgraph MEMBER["ログイン必要"]
        SCR100["SCR-100<br/>マイページ"]
        SCR110["SCR-110<br/>会員情報編集"]
    end
    SCR010 -->|"認証OK"| SCR100
    SCR100 -->|"会員情報を編集"| SCR110

記入例の12画面では、枠をまたぐ矢印は「ログインの認証OK → マイページ」と「退会確認モーダル → 退会完了」の2本です。ログイン状態が変わるのはこの2か所だけ、と図から読み取れます。

図として描画する（mermaid-cli）

画像ファイルにしたいときは mermaid-cli の mmdc コマンドを使います。

npm install -g @mermaid-js/mermaid-cli
mmdc -i flow.mmd -o flow.svg

Generating single mermaid chart

コンテナなど、ブラウザを自分で指定する環境では、設定ファイルを -p で渡します。今回は次の内容で描画しました（executablePath は Chromium の場所に合わせます）。

{"executablePath": "/path/to/chrome", "args": ["--no-sandbox"]}

mmdc -p puppeteer-config.json -i flow.mmd -o flow.svg

画面が増えても読みやすく保つコツ

列を足したいとき

画面一覧は、列を足すほど他の資料の入口として使えます。足しやすい列の例です。

csv.DictReader は列名で値を取り出すので、列を足してもコードはそのまま動きます。

レビュー用チェックリスト

• [ ] 画面IDが重複していない
• [ ] 画面名が、画面に表示するタイトルと同じ言葉になっている
• [ ] すべての画面に、入ってくる矢印と出ていく矢印がある（入口の画面を除く）
• [ ] 入力がある画面に、入力エラーのときの行き先が書かれている
• [ ] 登録・更新・削除の前に、確認の画面かモーダルがある
• [ ] 完了画面から次に行ける先がある
• [ ] エラー画面から戻る先がある
• [ ] ログインが必要な画面が、すべて「ログイン必要」の枠に入っている
• [ ] 枠をまたぐ矢印が、ログインとログアウト（退会）に当たる操作だけになっている
• [ ] 検査のコードが終了コード0で終わる

よくある質問

Q. 画面遷移図と画面一覧は、どちらを先に作りますか？ A. 画面一覧を先に作ります。表は行を足すだけで画面を増やせて、抜けにも気づきやすいからです。図は、表から生成して流れを確かめるために使います。

Q. Mermaidではフローチャートと状態遷移図のどちらで書きますか？ A. この記事ではフローチャートを使いました。箱の形を種別ごとに変えられ、subgraph でログイン要否を囲めるので、画面一覧の列をそのまま図に写せます。

Q. モーダルやタブの切り替えも1画面として数えますか？ A. 利用者に確認や入力を求めるモーダルは、画面IDを振って一覧に入れると、遷移の抜けが減ります。同じ画面の中で表示が切り替わるだけのタブは、画面一覧には入れず、その画面の設計書で扱うと一覧が増えすぎません。

Q. 図をExcelや表計算ソフトの画面一覧と一緒に管理できますか？ A. できます。画面一覧をCSVで書き出し、この記事のコードに渡せば図になります。コードでは utf-8-sig で読んでいるので、先頭に BOM という目印が付いたCSVでも同じ結果になります。

まとめ

• 画面遷移図は、画面一覧（表）から作ると、画面の抜けと行き止まりを早く見つけられる
• 画面一覧の列は画面ID・画面名・種別・遷移元・遷移先・認証要否の6つから始める
• 遷移先は「遷移先ID:操作?条件」の形で書くと、分岐のひし形までコードで生成できる
• エラー画面は点線、モーダルは二重枠、完了は角丸、ログイン要否はサブグラフで書き分ける
• 遷移元と遷移先の食い違いは検査のコードで見つけ、終了コードでCIに知らせる
• 画面が増えたら、機能ごとにCSVを分けて機能別の図と全体の図を作る

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。