Mermaid.jsのスマホ崩れを解決！Astro専用図解コンポーネント3種自作とAI執筆CLI高速化

Mermaid図解がスマホとAI執筆で抱える4つの限界

Mermaid はテキストから複雑なネットワーク図やシーケンス図を描ける素晴らしいライブラリですが、「Web 記事の本文中で誰にでも読みやすく見せる」という用途に限ると、SVG 固定座標レンダリングゆえの構造的な弱点があります。

パソコンの大きな画面で作っとるときは「おお、カッコいい図ができた！」と満足しとるんじゃけど、あとから iPhone で自分の記事を開いてみたら、米粒みたいな文字になっとって愕然とするんよね。

まさにそこが一番の盲点なんです！複雑な網目状のグラフなら Mermaid の出番ですが、記事で伝えたい「手順の流れ」「A と B の違い」「3 階層の仕組み」なら、CSS グリッドとコンテナクエリで組んだ Astro コンポーネント に置き換えるだけで劇的に読みやすくなりますよ！

クライアントJSゼロのAstro専用図解3種の設計

display:contentsとコンテナクエリの妙技

自作したのは FlowDiagram（手順・因果フロー）、CompareDiagram（2 列／3 列の対比カード）、LayerDiagram（上下階層のアーキテクチャ図） の 3 種類です。特に工夫した CSS 設計の急所が 2 つあります。

1 つ目は、横並びフロー図における 「カード幅の完全 1:1 均等配分」 です。各ステップ部品（FlowStep）の中に「カード本体」と「右向き矢印コネクタ」をセットで入れ、最後のステップだけ CSS の :last-child .flow-connector { display: none; } で矢印を消すと、そのままでは最後のステップだけが矢印のぶん狭くなってカード幅が不揃いになります。

そこで横並び時は親ラッパーに display: contents を指定して DOM の箱をレイアウト上透過させ、全カード本体に直接 flex: 1 1 0%; min-width: 0; を効かせることで、矢印の幅を除いた残りスペースが全カードへ寸分違わず均等配分されるようにしました。

/* FlowDiagram.astro（抜粋：ラッパーを透過して全カード幅を1:1均等化） */
.flow-diagram {
  container-type: inline-size;
}
.flow-diagram.is-horizontal .flow-track > :global(.flow-step-unit) {
  display: contents;
}
.flow-diagram.is-horizontal .flow-track > :global(.flow-step-unit .flow-card) {
  flex: 1 1 0%;
  min-width: 0;
}
.flow-track > :global(.flow-step-unit:last-child .flow-connector) {
  display: none;
}

/* コンテナ幅600px以下（または4ステップ以上で760px以下）なら自動で縦積み＋矢印90度回転 */
@container (max-width: 600px) {
  .flow-diagram.is-horizontal .flow-track {
    flex-direction: column;
  }
  .flow-diagram.is-horizontal .flow-track > :global(.flow-step-unit) {
    display: flex;
    flex-direction: column;
  }
  .flow-diagram.is-horizontal .flow-track > :global(.flow-step-unit .flow-arrow-svg) {
    transform: rotate(90deg);
  }
}

2 つ目は、画面全体の幅（@media）だけでなく図解自身の横幅を見る CSS コンテナクエリ（container-type: inline-size） と :has(> :nth-child(4)) の併用です。これにより、ステップ数が 4 つあって横幅が窮屈になったときだけ、PC の狭いウィンドウでも自動的に縦積みレイアウトへ美しく切り替わります。

実演！フロー図・比較図・階層図の3パターン

実際にこのページ上で 3 つのコンポーネントを動かしている実演サンプルをご覧ください（スマホでご覧の方は縦積み＋下向き矢印に、PC でご覧の方は横並びやマルチカラムに自動最適化されています）。

まずは ① FlowDiagram ＋ FlowStep です。tone 属性（default / accent / danger / success）と矢印ラベル（arrow）を渡すだけで、視線が自然に流れるステップ図になります。

次に ② CompareDiagram ＋ CompareCard です。従来品との比較や「NG 例 vs OK 例」を色分けバッジ付きで並べるのに最適です。

そして 3 つ目が ③ LayerDiagram ＋ LayerBox です。システム構成や優先順位の階層を表現でき、中間レイヤーだけを columns={2} で横 2 分割するといった柔軟なレイアウトにも対応しています。

AIの無駄な往復をゼロにする執筆CLIツールキット

ミリ秒単位の書式検査とアフィリエイト自動登録

美しい図解コンポーネントを作っただけでは、まだ半分です。AI エディタと一緒に何十本もの記事を執筆していると、AI が毎回「既存の記事はどう書いているかな？」と過去の .mdx を 5〜10 ファイルも読みに行ったり、手作業でアフィリエイト定義ファイルを編集してカンマ抜けを起こしたりといった 「非本質的な往復コスト」 が発生します。

そこで当サイトでは、templates/ フォルダにマスター原型を置いた上で、定型作業をすべて 1 コマンドで片付ける Node.js 製 CLI scripts/article_toolkit.mjs を整備しました。

AI さんに「気をつけて書いてね！」と毎回お願いするより、0.01 秒で見つけ出してくれる検査道具を渡してあげるほうが 100 倍確実でちね！

まさにその通りです！AI は人間のような「なんとなくの空気読み」は苦手ですが、明確な型（コンポーネント）と機械的な検査コマンド（check） を用意してあげると、驚くほど正確に一発で美しい記事を仕上げてくれるようになります。

まとめ：AIが迷わず書ける『型と道具』を先に作る

個人メディアや技術ブログを長く心地よく続けていく秘訣は、毎回の執筆で気合や手作業に頼らないことです。「スマホでも 5K でも絶対に崩れない Astro 図解コンポーネント 3 種」と「0.01 秒でミスを弾くスキャフォールド CLI」 という土台を一度作ってしまえば、あとは中身の一次検証と読者への価値提供だけに 100% 集中できるようになります。

ご自身の Astro ブログにも同様の専用図解コンポーネントと執筆 CLI ツールキットを取り入れたい方は、以下のプロンプトを最上位モデルの AI エディタへ渡してカスタマイズしてみてください。

以下の記事の設計を参考に、私の Astro プロジェクトへ「クライアントJSゼロの専用図解コンポーネント3種（FlowDiagram / CompareDiagram / LayerDiagram）」と「記事スキャフォールド＆高速プリフライト検査CLI」を導入してください。
参照URL: https://lab.chihouzakki.com/blog/review/astro-custom-diagrams-mermaid-alternative-scaffold/

【作業ルール（厳守）】
1. まず私のサイトの既存カラースキーム（ライト／ダークモードのCSS変数）と MDX ディレクトリ構造・フロントマター定義（src/content.config.ts 等）を確認し、デザインに自然に馴染む実装計画を提示して合意を得てください。
2. FlowDiagram は横並び時に display: contents と flex: 1 1 0% で全カード幅が均等になるようにし、スマホ幅や狭幅コンテナ（@container）では自動で縦積み＋矢印90度回転するレスポンシブ設計にしてください。
3. プリフライト検査CLI（checkサブコマンド）には、見出し文字数チェック、未閉じタグ検出、画像ファイルの存在確認を含め、数ミリ秒で実行できるようにしてください。

「崩れない図解の器」と「迷わない道具箱」を揃えて、毎日の執筆をもっと楽しくクリエイティブな時間にしていきましょう！

▲ 図解の崩れ直しから解放されれば、夜はぐっすり眠れます