みなさん、こんにちは。
先日、Zennで公開されていた「画面設計書をMarkdownで書く文化を浸透させたい」という記事を読みました。
この記事では、Markdownで管理するメリット（差分管理のしやすさ、リポジトリへの同梱、テンプレート化など）がとても丁寧に整理されていて、私自身も「確かにその通り！」と強く共感する部分が多くありました。
ただ、読み進めながら自分の開発スタイルと照らし合わせてみたとき、一つ明確に見えてきたことがあります。それは、「Markdownで管理すべき領域」と「そうでない領域」をハッキリ分けるべきだ、という点です。
今回は、私が実践している、より効率的で「破綻しない」画面管理戦略についてお話ししてみたいと思います。
Markdownに「UIレイアウト」は書かない
元記事では、ASCIIアートやMermaid、あるいはFigmaへのリンクを使って画面レイアウトを表現する方法が紹介されていました。
確かにMarkdownで完結させるための工夫としてはアリなのですが、私はUIのレイアウト自体をMarkdownに書く必要はないと考えています。
理由は「再現性が低く、メンテナンスの手間が増えるだけだから」、です。
UIの唯一の真実は、実際に動く「コード」と、その結果である「スクリーンショット」だけです。MarkdownでUIを模倣しようとするのは、いわば本物のコピーを手作業で作るようなもの。すぐに中身が古くなり、ドキュメントとしての信頼性が失われてしまいます。
「じゃあ、Figmaできっちりデザインするの？」と思われるかもしれませんが、小規模な開発ではFigmaでの作り込みも極力避けたいのが本音です。結局、コードで再実装する二度手間が発生してしまうからです。
私のUI設計フロー – 「手書き → AI → コード → スクショ」
では、どうしているのか。私の現在のワークフローはこんな感じです。
- 手書きのラフ
Figmaなどのデザインツールは思考を収束させてしまいがちです。白紙にペンで書くのが、思考の拡散には最速です。 - AIでコード生成
そのラフをAIに読み込ませ、一気にUIコード（HTML/CSSやReactなど）を生成します。 - スクショを撮る
出来上がった画面のスクリーンショットを撮ります。 - 遷移図もAI任せ
画面遷移などの構造は、AIにMermaid形式などで出力させます。
この流れなら、UIの見た目や構造はすべて「コード」と「スクショ」に集約されます。わざわざMarkdownの中に文字でレイアウトを組む必要がなくなります。
Markdownに残すのは「仕様」だけでいい
「じゃあMarkdownは使わないの？」というと、そんなことはありません。むしろ、Markdownは「仕様の単一情報源」として非常に重要です。
コードやスクショだけでは表現しきれない「ロジック」の部分は、必ず存在するからです。
- 入力項目の必須／任意
- バリデーション条件やエラー文言
- ボタンの活性条件
- 複雑な画面遷移のトリガー
- APIのフィールド対応表
- ユーザー権限による表示制御
これらはコードの差分（diff）だけでは読み解くのが大変です。だからこそ、README.mdの延長として、これらをテキストベースで残しておくことに大きな価値があります。
「Markdownは絵を描くためではなく、仕様を定義するために使う」。これが私のスタンスです。
「世の中のシステムの大半」に最適なサイズ感
もちろん、画面数が数百を超えるような大規模システムや、多くのチームが関わるプロジェクトでは、Figmaなどの厳密なデザイン管理ツールが必要になるでしょう。
しかし現実には、世の中のシステムの多くはそこまで巨大ではありません。
- 画面数は20〜50程度
- 画面遷移はシンプル
- 少人数のチーム開発
こうした規模感であれば、「コード ＋ スクショ ＋ 遷移図 ＋ 最小限の仕様Markdown」の組み合わせが、最もコストパフォーマンス良く、スピード感を持って開発を進められます。
私の画面管理戦略（まとめ）
最後に、私の戦略を整理するとこんな感じです。
Markdownは仕様に徹するのがベスト
元記事が提唱する「Markdownで設計書を書く文化」のメリット（Gitでのレビューのしやすさや軽快さ）は、本当に素晴らしいものです。
ただ、その道具を「何に使うか」を絞り込むことで、開発効率はさらに上がると確信しています。
「UIはコードに任せ、Markdownは仕様に徹する」。
これが、記事をきっかけに改めて整理できた私の結論でした。
本日も最後までお読みいただきありがとうございました。
それでは、よいシステム開発を！
