🚀

画面設計書を Markdown で書く文化を浸透させたい

に公開7件
Excel
Markdown
architecture
idea

1. はじめに

実務では、画面設計書が Excel や PowerPoint、Word で管理されていることが多いです。
それ自体は珍しくありませんし、提出物としては都合が良い場面もあります。

ただ、開発の現場で実際に使う設計資料として見ると、つらいことが多いです。

  • どこが変わったのか差分が追いづらい
  • レビューで変更点に集中しづらい
  • 実装と設計書の同期が崩れやすい
  • コピー運用で古い記述が残る
  • 画面ごとに表現がばらつきやすい

その結果、画面設計書が「あるけど信用されない文書」になってしまうことがあります。

自分は最近、画面設計書をもっとドキュメントベース、できれば Markdown ベースで書く文化を浸透させたいと考えています。
今回はその理由を整理してみます。

2. なぜ今の画面設計書運用がつらいのか

画面設計書は、多くの現場で Excel / Word / PowerPoint などの Office 文書で管理されています。
これはこれで自然な流れだと思います。社内外に共有しやすく、見た目も整えやすく、非エンジニアにも扱いやすいからです。

ただ、開発の中で継続的に使う設計資料として見ると、どうしてもつらさが出てきます。

差分が追いづらい

一番大きいのはここです。

画面設計書は、開発の途中で何度も変わります。

  • 項目名が変わる
  • 必須条件が変わる
  • 活性条件が追加される
  • ボタン押下時の挙動が変わる
  • エラー表示の文言が変わる

こうした変更は、実装にとってはかなり重要です。
しかし Office 文書だと、どこがどう変わったのかを追いづらいことが多いです。

もちろん変更履歴機能はありますが、Git のように差分を自然に確認する文化とは相性があまりよくありません。
結果として、レビュー時には「最新版を見てください」という運用になりやすく、変更点に集中した確認がしづらくなります。

実装と設計書が分離しやすい

開発現場では、コードは Git で管理されていても、設計書は別の共有フォルダや文書管理基盤に置かれていることがよくあります。

この構成だと、

  • コードは更新されたが設計書は更新されていない
  • 設計書は修正されたが実装に反映されていない
  • どのリリース時点でどの設計だったのか追いにくい

というズレが起きやすくなります。

特につらいのは、仕様変更が小さいときほどこのズレが放置されやすいことです。
軽微な文言変更、入力条件の変更、表示制御の追加などは、実装では重要でも、設計書側では後回しにされがちです。

その結果、設計書が徐々に現実から離れていきます。

3. なぜ Markdown ベースにしたいのか

前章で挙げたつらさの多くは、「設計書がコードと同じライフサイクルで管理されていない」ことに起因しています。
Markdown ベースにすることで、この構造的なズレを小さくできると考えています。

Git で差分管理できる

Markdown はプレーンテキストなので、Git との相性が非常に良いです。

  • 変更箇所が diff で一目でわかる
  • プルリクエストで設計変更のレビューができる
  • 「いつ・誰が・何を変えたか」が履歴として残る

Office 文書では難しかった「変更点に集中したレビュー」が、自然にできるようになります。
設計変更とコード変更を同じプルリクエストに含めれば、レビュアーは仕様と実装の整合性をその場で確認できます。

設計書とコードを同じリポジトリで管理できる

Markdown ファイルをリポジトリの docs/ などに置けば、コードと設計書が同じバージョン管理の中に入ります。

  • コードと設計書のブランチが一致する
  • リリースタグを打てば、その時点の設計書もセットで残る
  • 設計書だけ更新が漏れる、という状況が起きにくくなる

「設計書は SharePoint、コードは GitHub」という分離がなくなるだけで、同期のコストは大幅に下がります。

構造化しやすく、テンプレート運用に向いている

Markdown は見出し・リスト・テーブルといった基本的な構造を持っています。
これを活かして、画面設計書のテンプレートを定義しやすいです。

例えば、以下のような構成をテンプレートとして用意しておけば、画面ごとの記述のばらつきを抑えられます。

## 画面名: ユーザー登録
### 概要
### 画面レイアウト
### 項目定義
### バリデーション
### 画面遷移
### 備考

テンプレートがあることで、書く側も「何を書けばいいか」が明確になり、レビューする側も「何が書かれていないか」に気づきやすくなります。

軽量で、書くハードルが低い

Excel や PowerPoint で設計書を書くとき、体裁を整える作業に時間を取られることがあります。
セルの結合、罫線の調整、フォントサイズの統一など、内容とは関係ない作業です。

Markdown はそうした装飾の手間がほぼありません。
書く人が内容に集中できるため、設計書の更新が億劫になりにくいです。

「更新が面倒だから放置される」という問題に対して、書くコスト自体を下げることは地味ですが効果的です。

CI/CD やツールとの連携がしやすい

プレーンテキストであることのもうひとつの利点は、自動化との相性です。

  • テンプレートの必須セクションが埋まっているかを CI でチェックできる
  • Markdown から HTML や PDF に変換して、非エンジニア向けの閲覧用ドキュメントを自動生成できる
  • 静的サイトジェネレーター（MkDocs、Docusaurus など）で社内ポータル化できる

設計書を「書いたら終わり」ではなく、「書いたら自動で検証・配信される」仕組みに載せられるのは大きなメリットです。

4. Markdown で画面レイアウトをどう表現するか

「Markdown で画面設計書を書く」と言うと、最初に出てくる疑問がこれだと思います。

Excel や PowerPoint なら画面のレイアウトを視覚的に表現できるけど、Markdown でどうやるの？

正直に言えば、Markdown 単体で画面レイアウトをピクセル単位で表現するのは無理です。
しかし、画面設計書に求められるのは「完成イメージの再現」ではなく、「実装者が迷わない程度の構造の伝達」だと思います。

ここでは、いくつかのアプローチを紹介します。

アプローチ 1: ASCII ベースの簡易レイアウト

もっともシンプルな方法です。コードブロックの中にテキストベースでレイアウトを表現します。

+--------------------------------------------------+
| ヘッダー                                          |
+--------------------------------------------------+
| ユーザー登録                                      |
|                                                    |
|  氏名:       [___________________]                |
|  メール:     [___________________]                |
|  パスワード: [___________________]                |
|                                                    |
|  [登録する]  [キャンセル]                          |
+--------------------------------------------------+
| フッター                                          |
+--------------------------------------------------+

見た目は素朴ですが、Git diff との相性は抜群です。
項目が追加されたのか、並び順が変わったのか、一目でわかります。

簡単な画面やモーダルダイアログの構造を伝えるには十分なことが多いです。

アプローチ 2: Mermaid でフローや構造を図示する

GitHub や多くの Markdown ビューアが対応している Mermaid を使えば、画面遷移図やコンポーネントの関係を図として埋め込めます。

レイアウトそのものを描くよりも、画面間の遷移やコンポーネントの構造を示すのに向いています。
テキストベースなので diff も取れますし、プルリクエスト上でプレビューもできます。

アプローチ 3: Figma / デザインツールへのリンクを埋め込む

画面の見た目を正確に伝えたい場合は、無理に Markdown で描くよりも、Figma などのデザインツールに任せるのが現実的です。

### 画面レイアウト
[Figma: ユーザー登録画面](https://www.figma.com/file/xxxxx)

![ユーザー登録画面](./images/user-registration.png)

ポイントは、Markdown 側に画像やリンクとして埋め込むことで、設計書の中から直接参照できるようにすることです。
スクリーンショットを images/ ディレクトリに入れてリポジトリで管理すれば、バージョンとの紐付けも維持できます。

どのアプローチを選ぶか

大事なのは、「画面設計書の目的はレイアウトの再現ではない」という割り切りだと思います。

目的 適したアプローチ
画面の構造をざっくり伝えたい ASCII レイアウト / テーブル
画面遷移や状態の流れを示したい Mermaid
正確なビジュアルを共有したい Figma リンク / スクリーンショット

実務では、これらを組み合わせるのが自然だとおもいます。
Markdown で構造と仕様を書き、見た目の確認が必要な部分だけデザインツールを参照する。
この使い分けができれば、Markdown ベースでも画面設計書として十分に機能します。

5. 導入のハードルとどう向き合うか

ここまで Markdown ベースのメリットを書いてきましたが、実際に現場で導入しようとすると壁にぶつかります。
技術的な問題よりも、チームや組織の文化に関わる部分が大きいです。

「Markdown が書けない人がいる」問題

一番多く聞く反論がこれです。

確かに、非エンジニアのメンバー（PMやビジネスサイドの担当者など）にとって、Markdown は馴染みがないかもしれません。
ただ、実際に画面設計書で使う Markdown の記法はごく限られています。

  • 見出し（##）
  • 箇条書き（-）
  • テーブル（| ... |）

この 3 つが書ければ、画面設計書の大半はカバーできます。
「Markdown を完全に習得してもらう」のではなく、「この 3 つだけ覚えてもらう」というハードルの下げ方が現実的です。

また、どうしても Markdown を直接触ってもらうのが難しい場合は、HackMD や Notion のようなリッチエディタ付きのツールを挟むという選択肢もあります。

あと、最近はAIに聞けばこの程度のことはすぐ教えてくれるのでハードルは低いと思います。

「Excel じゃないと納品できない」問題

SIer やクライアントワークでは、納品物のフォーマットが指定されていることがあります。
「画面設計書は Excel で」と契約や慣習で決まっている場合、Markdown に完全移行するのは難しいです。

まず検討すべきは、Markdown のまま納品を認めてもらう交渉です。

  • GitHub 上でレンダリングされた状態を見せれば、十分に読みやすいことが伝わる場合が多い
  • MkDocs などで静的サイト化すれば、閲覧用としての品質は Excel と遜色ない
  • 「差分管理ができる」「設計とコードが同期する」といったメリットはクライアントにとっても利点になる

ここは上層部にぜひとも頑張っていただきたいです。

契約上どうしても Excel が求められる場合は、「開発中は Markdown で書き、納品時に変換する」という二段構えで対応します。

  • 日常の開発・レビューは Markdown ベースで行う
  • 納品や報告のタイミングで、ツールで Excel / Word / PDF に変換する
  • 変換テンプレートを用意しておけば、手作業は最小限に抑えられるはず...

「今ある設計書をどうするか」問題

既存プロジェクトには、すでに大量の Excel 設計書が存在していることがほとんどです。
これをすべて Markdown に移行するのは、コストに見合わないことが多いです。

現実的な進め方としては、

  • 新規画面や大きな改修が入るタイミングで、その画面から Markdown に切り替える
  • 既存の設計書はそのまま残し、参照はできる状態を維持する
  • 徐々に Markdown 側の資産が増えていく形を目指す

一気に切り替えるのではなく、「新しく書くものから Markdown にする」というルールにするだけで、自然に移行が進みます。

「テキストだと見づらい」という心理的な壁

Excel の設計書は、色やセル結合で視覚的に整理されているため、「見やすい」と感じる人が多いです。
一方、Markdown のプレーンテキストは「素っ気ない」「情報が整理されていないように見える」と感じられることがあります。

これに対しては、

  • GitHub や GitLab 上ではレンダリングされるので、実際にはそれなりに見やすい
  • MkDocs や Docusaurus で静的サイト化すれば、閲覧体験は大きく改善できる
  • 「見た目の整え方」ではなく「情報の探しやすさ」で評価基準を切り替える

という対応が有効です。

最終的には、「きれいな見た目の設計書」よりも「信頼できる設計書」のほうが開発にとって価値があるという共通認識をチーム内で持てるかどうかをポイントとしておきたいです。

6. 具体例: Markdown で書く画面設計書

ここまでの内容を踏まえて、実際に Markdown で画面設計書を書くとどうなるか、具体例を示します。
題材は、よくある「ユーザー登録画面」です。

SCR-001: ユーザー登録画面（クリックで展開）
# SCR-001: ユーザー登録画面


## 概要
新規ユーザーがアカウントを作成するための画面。  
姓、名、メールアドレス、パスワード、確認用パスワードを入力し、利用規約に同意した上で登録を行う。

## 画面目的
- 新規ユーザーを登録する
- 入力不備を画面上で検知し、正しい形式で登録させる
- 登録成功後、登録完了画面へ遷移させる

## アクセス制御
- 未ログインユーザーのみアクセス可能
- ログイン済みユーザーが本画面へアクセスした場合は、ダッシュボードへリダイレクトする

## 画面レイアウト
※実際の画面があるなら差し替えやURLを記載する
+--------------------------------------------+
| ヘッダー（ロゴ / ナビゲーション）           |
+--------------------------------------------+
|                                            |
|         ユーザー登録                        |
|                                            |
|  姓:          [_______________]            |
|  名:          [_______________]            |
|  メール:      [_______________]            |
|  パスワード:  [_______________]            |
|  確認用:      [_______________]            |
|                                            |
|  [ ] 利用規約に同意する                    |
|                                            |
|  [  登録する  ]    キャンセル               |
|                                            |
+--------------------------------------------+
| フッター                                   |
+--------------------------------------------+

## 項目定義

| #   | 項目名             | 項目ID          | 種別             | 必須 | 最大長 | 初期値     | 備考                       |
| --- | ------------------ | --------------- | ---------------- | ---- | ------ | ---------- | -------------------------- |
| 1   | 姓                 | lastName        | テキスト         | ○    | 50     | 空         | 前後空白は送信時に trim    |
| 2   | 名                 | firstName       | テキスト         | ○    | 50     | 空         | 前後空白は送信時に trim    |
| 3   | メールアドレス     | email           | テキスト         | ○    | 256    | 空         | 前後空白は送信時に trim    |
| 4   | パスワード         | password        | パスワード       | ○    | 128    | 空         | 入力文字はマスク表示       |
| 5   | パスワード（確認） | passwordConfirm | パスワード       | ○    | 128    | 空         | 入力文字はマスク表示       |
| 6   | 利用規約同意       | agreeTerms      | チェックボックス | ○    | -      | 未チェック | チェック時のみ同意とみなす |

## 入力仕様

### メールアドレス
- 半角で入力する
- `local-part@domain` 形式であること
- 前後空白は除去して判定する

### パスワード
- 8文字以上 128文字以下
- 英大文字を1文字以上含む
- 英小文字を1文字以上含む
- 数字を1文字以上含む
- ASCII記号を1文字以上含む
- 全角文字・空白文字は不可

## バリデーション

| #   | 対象項目           | 実施タイミング | ルール                          | エラーメッセージ                                                               |
| --- | ------------------ | -------------- | ------------------------------- | ------------------------------------------------------------------------------ |
| 1   | 姓                 | blur / 送信時  | 未入力チェック                  | 「姓を入力してください」                                                       |
| 2   | 名                 | blur / 送信時  | 未入力チェック                  | 「名を入力してください」                                                       |
| 3   | メールアドレス     | blur / 送信時  | 未入力チェック                  | 「メールアドレスを入力してください」                                           |
| 4   | メールアドレス     | blur / 送信時  | 形式チェック                    | 「メールアドレスの形式が正しくありません」                                     |
| 5   | パスワード         | blur / 送信時  | 未入力チェック                  | 「パスワードを入力してください」                                               |
| 6   | パスワード         | blur / 送信時  | 複雑性チェック                  | 「パスワードは英大文字・小文字・数字・記号を含む8〜128文字で入力してください」 |
| 7   | パスワード（確認） | blur / 送信時  | 未入力チェック                  | 「確認用パスワードを入力してください」                                         |
| 8   | パスワード（確認） | blur / 送信時  | 一致チェック（password と比較） | 「パスワードが一致しません」                                                   |
| 9   | 利用規約同意       | 送信時         | チェック必須                    | 「利用規約に同意してください」                                                 |
| 10  | メールアドレス     | 送信時         | 重複チェック（API）             | 「このメールアドレスは既に登録されています」                                   |

### バリデーション実施ルール
- 各入力項目のフロントバリデーションは blur 時に実施する
- 送信ボタン押下時は全項目を再検証する
- メールアドレス重複チェックは送信時に API 応答で判定する
- 複数エラーがある場合は、各項目ごとに同時表示する

## エラー表示仕様
- 項目単位のエラーは、対象入力欄の直下にインライン表示する
- API によるメール重複エラーは、メールアドレス欄の直下に表示する
- 送信時にエラーがある場合は、先頭エラー項目へフォーカスを移動する
- 通信障害などの業務外エラーは画面上部にメッセージを表示する  
  - 表示文言: 「登録に失敗しました。時間をおいて再度お試しください」

## ボタン仕様

| ボタン     | 項目ID       | 動作                                        | 活性条件                                                                                 |
| ---------- | ------------ | ------------------------------------------- | ---------------------------------------------------------------------------------------- |
| 登録する   | submitButton | フォーム送信 → `POST /api/users`            | 必須入力済み、メール形式正常、パスワード形式正常、確認用一致、利用規約同意済みのとき活性 |
| キャンセル | cancelButton | 確認ダイアログ表示 → OK時にトップ画面へ遷移 | 常時活性                                                                                 |

### 登録するボタン押下時の動作
1. フロント側バリデーションを全件実施する
2. エラーがある場合は API を呼び出さず、エラー表示のみ行う
3. エラーがない場合、`POST /api/users` を実行する
4. 成功時は登録完了画面（SCR-002）へ遷移する
5. 409 エラー時はメールアドレス欄に重複エラーを表示する
6. それ以外のエラー時は画面上部にシステムエラーメッセージを表示する

### 二重送信防止
- API 通信中は「登録する」ボタンを非活性にする
- API 通信中はローディング表示を行う
- API 応答完了後、失敗時のみ再度活性化する

## 確認ダイアログ仕様（キャンセル押下時）
- 表示文言: 「入力内容は破棄されます。よろしいですか？」
- OK押下: トップ画面（SCR-000）へ遷移
- キャンセル押下: 本画面に留まる

## 画面遷移

| 遷移元                  | 操作                           | 遷移先                  |
| ----------------------- | ------------------------------ | ----------------------- |
| ログイン画面（SCR-003） | 「新規登録はこちら」リンク押下 | 本画面                  |
| 本画面                  | 登録成功                       | 登録完了画面（SCR-002） |
| 本画面                  | キャンセルダイアログでOK押下   | トップ画面（SCR-000）   |
| 本画面                  | ログイン済み状態でアクセス     | ダッシュボード          |

## API

| メソッド | エンドポイント | 用途         |
| -------- | -------------- | ------------ |
| POST     | `/api/users`   | ユーザー登録 |

### リクエスト

```json
{
  "lastName": "山田",
  "firstName": "太郎",
  "email": "yamada@example.com",
  "password": "P@ssw0rd123"
}
### レスポンス（成功: 201）

{
  "id": "usr_xxxxxxxx",
  "email": "yamada@example.com",
  "createdAt": "2026-03-25T10:00:00Z"
}

### レスポンス（エラー: 409）

{
  "error": {
    "code": "EMAIL_ALREADY_EXISTS",
    "message": "このメールアドレスは既に登録されています"
  }
}

## 非機能要件・補足

- パスワードはフロントから平文で送信し、API 側で bcrypt ハッシュ化する
- 通信は TLS 必須
- 登録完了時に確認メールを非同期送信する
- 画面の主要操作はキーボード操作に対応する
- Tab キーで各入力項目およびボタンへ移動可能であること
- スマートフォン表示時も入力・送信が可能であること

この例のポイントは以下の通りです。

  • 画面 ID（SCR-001） を付けることで、画面間の参照がしやすくなる
  • 項目定義とバリデーションを分離 することで、それぞれの変更が diff で追いやすくなる
  • API の仕様もセットで書く ことで、フロントとバックエンドの認識ズレを防げる
  • 遷移先に画面 ID を記載 することで、画面遷移の全体像を機械的にも追える

Excel で同じ内容を書くこともできますが、この形式なら Git で差分管理でき、プルリクエストでレビューでき、コードと同じリポジトリに置けます。

実務ではこのテンプレートをチームで共有し、画面ごとに 1 ファイル（docs/screens/SCR-001.md）として管理する運用をおすすめをしたいです。

Discussion

とまとみとまとみ

要件をgit管理できるといいですよね
ASCII以外の選択肢がないかなあ、Figmaは操作難易度が少々高いしなあ、と悩まされています(笑)

salvoxsalvox

まったく同感です。エクセル、ワードの立ち上がりの遅さにイラっとする人いないのだろうか。Markdownなら、PDFにだってできる。もっと広めるべきです

1
poissonpoisson

設計書をコード化するのはいいです。 画面設計書に限らず、markdownやPlantUMLを使って設計書を作ります。更に、対応する評価項目や評価用プログラム（／スクリプト）もコード化します。 これがEverything-As-Codeの考え方ですね

fu3norifu3nori

AAで書く、というのは目から鱗でした。ただ込み入った画面を書くとき大変かも……。
かといってほかの方がおっしゃる通りfigmaを使うのが手間なので簡単に画面設計ができる
デファクトスタンダードなツールや手法が出てくるといいのですけれども

VANVAN

mdはAIとの相性がいいです。
いつも、美味しそうに食べてくれます

1
horie-thorie-t

アプローチ 1: ASCII ベースの簡易レイアウト

PlantUMLのサブプロジェクトのSaltなら簡単に画面のモックが書けますよ。

くーちゃんくーちゃん

マークダウンの箇条書き記述が
−=　マイナス　イコール　と成ってしまった際、EXCELで読み込んだ時に、バリュー表示で扱い難いのが、難点だな。と感じてる。今日この頃