diagram-designとは｜Claude Codeで27種の図を自己完結HTMLで作るスキル

「アーキテクチャ図を描いて」とAIに頼むと、たいてい角丸の四角が均等に並んだ、どこの資料にも属さない図が返ってくる。cathrynlavery/diagram-design（MIT・2026-08-14時点★16,028）は、この問題を汎用の作図AIではなく 27種の型と機械強制されたスタイル規約 で解こうとしたエージェントスキルだ。Claude Code／Codex／Pi のいずれにもプラグインとして入る。運用の全体像はClaude Code｜2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引きにまとめてある。

diagram-designとは——類似の作図スキルとの棲み分け

2026年4月16日作成のリポジトリで、Internet Archive のスナップショットでは 2026-08-13 05:53 UTC でスター11,497・フォーク728・ウォッチャー43、約28時間後の 2026-08-14 09:32 UTC でスター16,028・フォーク961・ウォッチャー64 と、1日で4,500以上増えていた。.claude-plugin/plugin.json のバージョンは 2.3.3。

中身は素朴で、スキル本体はMarkdownの集合体だ。SKILL.md が振る舞いと選定ルールを、references/ が型ごとの仕様書を持ち、描くのはエージェント自身でレンダラは介在しない。だから規約を言葉で決め、機械で検査する構成になる。

oh-my-mermaid は「コードから図を起こす」、Archify は「言葉から手早く1枚」、diagram-design は 「出した図をそのまま公開できる版面にする」 に重心がある。本文に埋め込むだけなら素のMermaidで足りるが、提案書の図を毎回Figmaで整えているなら置き換えの候補になる。

「27」という単位——数え方と、型を増やさない工夫

references/type-*.md は ちょうど27ファイルで、README本文の3か所も「27 visual types」、verify-semantic-motion.py も「7つの意味パターンが27種の視覚型へ独立にルーティングされる」ことを検査する。数え方による違いは次のとおり。

references/ には注釈・アイコン・手描き風・ターミナル装飾の primitive が4種 あり、型を増やさず既存の型に重ねる装飾として扱われる。v2.3で入った 意味パターン も同じ発想で、ファンインするキュー、ステージ枠、非構造入力の変換、対になるポリシートレース、安全な舗装道路（paved road）、ガバナンスのカタログ、多層の防御の7つは「振る舞い」として semantic-patterns.md に定義され、発火条件・部品・要素数の予算・アンチパターン・最も近い視覚型が決まっている。キューを描くときも型を新設せず既存の型へ寄せる。

モーションも none／reveal／step／loop の4モードで 既定は none。静止first frameを必ず持ち、タイミングは決定論的で、OSの「視差効果を減らす」が有効なら静止フレームだけを見せる。許されるスクリプトは template-motion.html の正規コントローラのみだ。

diagram-designの主張は実測に耐えるか——自己完結性・CI・異常系

規約がREADMEのポエムで終わっていないかを、2026-08-14時点の main で実際に走らせて確かめた。

同梱103枚——外部依存は書体1本だけ

READMEの「ビルド手順も、JavaScriptも、外部画像への依存も無い」を、skills/diagram-design/assets/*.html 103枚で数えた。

103枚すべてが https://fonts.googleapis.com/css2?... を1本読むが、原文は “no build step, JavaScript, or external image dependency” で、README自身もSVGエクスポート時のGoogle Fonts注入を明記している。--font-sans は 'Geist', system-ui, sans-serif のようにフォールバックを持つので、エアギャップ環境では書体が差し替わるだけで版面は崩れない。

CIのゲート8本を回す

ci.yml がPythonスクリプトを走らせるステップは19本あり、図の品質に直接効く8本をローカルで再実行した（verify-semantic-motion.py だけは、CIが --markdown-only と --example-only に分けて呼ぶところを引数なしで通した。他の7本はCIと同じ引数）。

git clone --depth 1 https://github.com/cathrynlavery/diagram-design.git
cd diagram-design

python3 scripts/verify-docs-sync.py           # 説明文・ギャラリー到達性・READMEツリーの同期
python3 scripts/verify-geometry.py --all      # 4pxグリッド等の幾何検査
python3 scripts/lint-skin.py --all --baseline # 配色・外部資源・a11y契約
python3 scripts/verify-motion.py --shipped    # 出荷済みモーションHTML
python3 scripts/verify-semantic-motion.py     # 意味パターン→型のルーティング
python3 scripts/verify-mermaid-import.py      # Mermaid取り込みの文法・上限・異常系
python3 scripts/verify-drawio-import.py       # draw.io取り込み（DTD拒否含む）
python3 scripts/verify-sequence-oauth.py      # シーケンス型のALT構造

8本すべて終了コード0。verify-geometry.py --all は103ファイルで指摘0、lint-skin.py は101検査20除外で指摘0、verify-mermaid-import.py は敵対的ラベルの不活性化や文書化されたexit 2経路の発火まで見ている。lint-skin は配色以外に、純黒 rgb(0,0,0)、CSS @import、外部HTTP(S)の <link>／src、フラグメント以外の CSS url()、<svg> 上の実行可能属性を拒否し、<svg> の先頭子要素に非空の <title> と <desc>、それを順に指す aria-labelledby、図ごとに接頭辞のあるID（id="title" のような裸のIDは不可）を要求する。モーションのコントローラは template-motion.html と完全一致でないと通らない。

ただし --baseline を外すと終了コード1で46件——「パレットに無い色」36件と「許可色から派生していない色」10件で、指摘は11ファイル。scripts/lint-skin-baseline.txt には20ファイル名が並び、指摘の無い9ファイルも含む。教科書的なbaseline運用で欠陥ではないが、「全アセットがトークンだけで塗られている」とまでは言えない。取り込む前に一度外して見ておきたい。

壊した図を6通り食わせる

エージェントが自分の出力を検査する縮小版が scripts/self_check.py として同梱されている。無改変の example-architecture.html を対照群に、6通りの改ざんを食わせた。

cp skills/diagram-design/assets/example-architecture.html clean.html
python3 skills/diagram-design/scripts/self_check.py clean.html   # → OK / exit 0

# 遠隔画像を注入
sed 's|<svg |<img src="https://evil.example.com/t.png"><svg |' clean.html > a.html
python3 skills/diagram-design/scripts/self_check.py a.html       # → FAIL / exit 1

許可ホストはホスト名の完全一致で判定され、類似ドメインでは抜けられない。HTMLの <head> の <title> を消しても exit 0 で通るのは、守る対象がSVGのアクセシブル名であってページタイトルではないからだ。

導入と運用——3系統への配布、常駐コスト、ブランド取り込み

配布は3系統のマーケットプレース経由で、いずれも skills/diagram-design/ を読む。

# Claude Code（マーケットプレース追加 → インストール）
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design

# Codex
codex plugin marketplace add cathrynlavery/diagram-design
codex plugin add diagram-design@diagram-design

# Pi（Gitからの非固定インストール）
pi install https://github.com/cathrynlavery/diagram-design

Claude Codeはサードパーティ製マーケットプレースの自動更新を既定で無効にしており、/plugin → Marketplaces → diagram-design → Enable auto-update を一度有効にしないと更新が来ない。Piは自動更新が無く pi update --extensions を手で叩く。スタイルガイドを編集するなら、更新で references/style-guide.md が上書きされうるのでクローンしてシンボリックリンクを張る「editable install」が案内されている。組織のGitHubマーケットプレース（Cowork）はprivate/internalリポジトリを要求するので自組織へミラーする。リリースタグが未作成（plugin.json の 2.3.3 のみ、Releasesは空）なので、版の固定はコミットSHA頼みだ。

初回だけゲートがあり、style-guide.md が既定のままなら「オンボーディングを走らせるか、トークンを手で貼るか、既定で進めるか」を聞いて止まる。既定配色は「白（white-smoke）の紙・ジェットブラックの文字・アトミックタンジェリンのアクセント・ブルースレートの副次テキスト」。PNG書き出しは pip install playwright && playwright install chromium が前提（既定倍率2×）で、書き出したSVG/PNGは図だけで -full 版の編集カードやヘッダは含まない。

references/ 全体は429,282バイトだが、全部が載ることはまず無い。最大の primitive-icons.md（106,768バイト、全体の約4分の1）もアイコンを明示的に使うときしか読まれない。測り方はClaude Skillsとは｜「スキル=フォルダ」の仕組みと作り方・使い方を徹底解説の構造をそのまま当てはめればよい。

「onboard diagram-design to https://yoursite.com」と頼むと、トップページのパレットとフォントスタックを役割に割り当てる。<body> の背景が paper、主な文字色が ink、副次テキストが muted、カード類が paper-2、最も使われるブランド色が accent。フォントは <h1> が title、<body> が node-name、<code> が sublabel だ。書き込み前に ink と paper のコントラストをWCAG AAで検査し、9〜12pxの図中サイズで基準を割る色は調整値と理由を出す。適用後は、サンプリングしたURL・色の対応・フォントと配信元・フォールバックの有無を並べた「忠実度レシート」が出る。以降の図は #eb6c36 のような生の値ではなく accent を参照するので、スタイルガイドの表を書き換えれば27種すべてに反映される。

既存資産の取り込み——日本語のMermaidで試した

既存資産は「変換」ではなく「描き直し」で、引き継ぐのは コンポーネント・関係・グルーピング・方向 だけ。元の座標・配色・フォント・draw.ioの斜め線・Mermaidの自動レイアウトは捨てる。当て先は4つのダイヤルで決まる。フォーマット（html／svg／png／html+png）、サイズ（doc-inline〜slide-16x9〜print-a4-landscape など9種、文字サイズのランプも変わる）、詳細度（faithful ≤24ノード／balanced ≤12／simplified ≤7）、読み手（engineer／mixed／executive。語彙が変わり、Auth Service / JWT · RS256 · :8443 が Sign-in になる）。詳細度の上限が実質の制約で、大きな図は必ずどこかを落とすが、何を統合し何を落としたかは「忠実度台帳」に出る。

前段の scripts/mermaid_extract.py は実行可能なパーサだ。当サイトの既存記事の日本語フローチャート——全角の判断ノード、<br/> の改行、style ... fill:#4CAF50 を含む実物——を投げた。

python3 skills/diagram-design/scripts/mermaid_extract.py jp-decision.mmd
# 1 diagram(s): [0] flowchart (11n/11e)
# - shapes: {'rect': 7, 'rhombus': 4}
# - budget: nodes OVER (max 9), edges ok (max 12)
# - discarded: 5 style directives, 0 click handlers

日本語ラベルはそのまま保持され、<br/> は digest 上で ⏎ になる（--json のIR側では \n のまま）。rect 7・rhombus 4で判断ノードを正しく識別し、budget: nodes OVER (max 9) で上限超過を描き直す前に警告し、discarded: 5 style directives で捨てた色指定の数を黙らずに出す。digest には「ハブ（注目候補）」「入口ノード」「終端ノード」も出て、当サイトの図では「チームで運用するか？」が次数4で最大のハブ、つまりアクセント色を当てる候補と判定された。draw.io側も .drawio / .drawio.xml / .drawio.png（埋め込み図）/ .drawio.svg と圧縮ペイロードに対応し、verify-drawio-import.py はDTD拒否・PNG境界・資源上限まで検査していた。

効くのは型の数より、その27を崩さないための検査が走るコードとして同梱されている点だ。一方で、baselineを外せば配色の逸脱が46件見え、詳細度の上限は大きな既存図を削り、版の固定はコミットSHA頼みになる。どれも「規約を機械で守る」設計と地続きの制約で、把握して使えば見積もりを外さない。

参照ソース

・cathrynlavery/diagram-design — GitHubリポジトリ（README・SKILL.md・scripts/・skills/diagram-design/）
・diagram-design 公式ギャラリー（cathrynlavery.github.io/diagram-design）
・Agent Skills — Anthropic 公式ドキュメント
・本稿の実測: 2026-08-14 時点のツリー（コミット e1d47bb0、plugin.json v2.3.3）を対象に検証した。同梱アセット103枚の集計、ci.yml が呼ぶゲート8本の再実行、self_check.py への異常系入力6件、mermaid_extract.py への日本語Mermaid入力（当サイトのプロンプトエンジニアリングとハーネスエンジニアリングの違いに載せている11ノードのフローチャート）はいずれも本稿のために実施した。本文の引用文字列・ファイル名・数値は2026-09-10に同ツリーへ再度突き合わせ済み。リポジトリのスター数等は Internet Archive のスナップショットで確認した