調査メモ: 図・グラフのガイドライン(issue #113 の artifacts 要約) #
issue #113「図やグラフ用のガイドラインを作りたい」に添付された
HTML artifacts(issue artifacts で gh api repos/.../issues/113/artifacts から取れる)を読んでまとめたもの。
添付は 3 件だが #2 と #3 は同一ファイルなので実質 2 本ある。
- **#1
claude-figure-guideline(Claude 作)**: 「図解ガイドライン — 開発者向けの図の設計システム」。 章立て・必須記載表・チャートカタログ・チェックリストまで揃った規約書型。 - **#3
chatgpt-visual-communication-design-guideline.html(ChatGPT 作)**: 「Visual Communication Design System」。 原則(FOUNDATION/GRAMMAR/STAT のルール ID 付き)と検証モデルを中心に据えた原則書型。
どちらも「バックエンドエンジニア向けの、フロントエンドのデザインシステムに相当する図の規約」という同じ依頼から作られている。 以下は両者の骨格と、このリポジトリ(write-slops / tools/svg-gen)にどう効くかの整理。
2 つの文書で共通する核 #
- **最初の分岐は「図にしない」**。Markdown の文・表・リスト・コードブロックで同じ速さで読めるなら図にしない。 数値 1〜3 個、6 行以下の比較、一本道の手順、2 段までの階層などは表形式で閾値つきで列挙されている。 図にすべきサインは「位置の言葉が要る」「関係を頭で組み立て直す必要がある」「5 個以上の値の大小・推移・分布が論点」など。
- **問いから始める**。図の種類はデータの形ではなく「何を知りたいか」で決める。タイトルは結論文 (「v2.3 で p99 が 38% 改善」)、サブタイトルは条件(環境・期間・n・集計単位)。
- **抽象とは何を残し何を捨てたかの宣言**。捨てたもの(除外データ、省略したコンポーネント、比喩の破綻点)を書かない図は嘘になる。
- **視覚要素は暗黙の主張を持つ**。位置・長さ・面積・色・線・矢印・囲み・重なりは、書かなくても関係・序列・包含を主張する。 矢印は図ごとに意味を 1 つ宣言する。列挙に A → B → C を使うと順序・因果を勝手に主張する。
- **必須記載は props のように必須にする**。n、期間、集計単位・ビン幅、単位つき軸、区間・誤差の種類、除外条件、 出典と生成コード(パス @ コミット)。脚注テンプレートまで用意されている。
- **検査は 2 段**。lint が拾えるのは機械的な半分(viewBox 内か、禁止構文か、両端矢頭か)だけで、 意味的・認知的な妥当性(軸の向き、模式図が実測に見える、そもそも図にする必要があったか)は人がチェックリストで見る。
相違点と互いの補完 #
Claude 版(規約カタログ型)が強いところ #
- **3 つの表現の区別**:テキスト表現 / 統計的可視化 / 概念図解を分け、1 枚で混ぜない。前者は「値を歪めない」、後者は「何を捨てたかを明示」が中心。
- **抽象レベル L0〜L4**:実物(スクショ・ログ)→ 写像(統計全般)→ 構造(実名の構成図・シーケンス図)→ モデル(レイヤー図・パターン図)→ 概念(2x2・比喩図)。 1 枚 1 レベル、L3・L4 は具体例(L1・L2)と結ぶ。統計内にも集計の抽象度があり、開発者向けは 1 段低い集計(平均の棒より点を重ねた箱ひげ)を選ぶ。
- **保存する関係 6 種**:量・順序・接続・包含・状態・対比から 1〜2 個だけ保存し残りを捨てる、という決め方。 「書き込みは必ずキューを経由する」なら保存するのは接続だけ、時刻まで描きたくなったら別の図、という運用。
- **チャート選択フローとカタログ**:問い(分布・比較・時系列・関係・構成・モデル評価)→ 第一選択 → 切り替え条件。 各チャートに「典型領域・効果・制約」を持つ。開発者向けの第一選択は ECDF、横棒は 0 起点 + 値順ソート、円グラフは原則禁止。
- **svg-gen 分割案(付録 B)**:概念図キット(現 svg.ts)とデータ図キット(現 hbars を切り出して育てる)に分け、 lint(check.ts)は共通、という提案。「図にするか」「抽象レベル」の判断はツールで強制できないので write-slops 側の文章に置く。
ChatGPT 版(原則書型)が強いところ #
- **認知タスク × 情報型の表**:「正確な値を読む」「傾向を追う」「相関を探索」などのタスクから表現候補を引く。 チャート名ではなく目的を先行させる構造になっている。
- **視覚文法の一覧**:位置・長さ・面積・色・線・矢印・囲み・重なり・サイズの 9 要素それぞれに「典型的に伝えること」と「誤読のリスク」。 「書かれていないことも主張する」というフレーミングは Claude 版より明示的。
- **証拠レベルの分離(FOUNDATION-005)**:実験的知見・一般的慣習・局所的な設計判断・検証待ちの仮説を区別する。 規約の各行がどの根拠を持つかを記録し、例外承認と更新を容易にする。
- **コンポーネント仕様の形(
id: temporal.line)**:purpose / abstraction / representation / fidelity_target / input / effects(emphasizes + obscures)/ rules(severity つき)/ metadata(required_when_applicable)という YAML 風の仕様単位。描画ライブラリを交換しても設計判断を再利用できる形。 - **3 段階の検証**:構文的妥当性(static lint)→ 意味的妥当性(semantic review)→ 認知的妥当性(cognitive review)。 Claude 版の「lint で機械的半分 + チェックリストで人」と対応するが、意味的と認知的を分けている。
両者に共通する弱めの点 #
- どちらも統計的可視化側は「何を記載すべきか」までは具体的だが、描画パラメータ(ビン幅の決め方、縮尺、 どの程度のサンプル数で何が見えるか)は経験則の列挙止まり。
- ルール ID や章番号はどちらも「提案規約」であり、外部標準ではない(両文書とも自分でそう断っている)。
このリポジトリへの落とし込み #
現状の tools/svg-gen は概念図向け(Canvas・anchor・配置ヘルパー)+ 唯一のデータ図 hbars + lint check.ts。
ガイドラインの観点では以下のギャップがある。
- **軸がない**。hbars はラベルと値を並べるだけで、目盛り・軸タイトル・単位を出す仕組みがない。 統計的可視化の必須記載(軸と単位、n、集計単位、イベント線、出典)を図に載せるには軸と ticks が要る。
- **系列が 1 種**。折れ線・散布図・ECDF のような L1 の図を出すには scale の写像と系列描画が要る。
- **必須記載の強制がない**。ガイドライン 15 章の「必須記載を必須引数に」を真似るなら、 データ図側のヘルパーは title(結論)・subtitle(条件)・footnote(出典・期間・n・生成コード)を必須引数にできる。
- 「図にするか」「どの抽象レベルか」はツールで強制できないので、write-slops の SKILL.md か このドキュメント群の側に判断を置く(Claude 版付録 B と同じ結論)。
次のステップとして、仮想データ(seed 固定の疑似乱数で作る、それっぽい計測値)から ECDF・折れ線・散布図を描く小さなデータ図キット(chart.ts + examples/fig-chart-*.ts)を svg-gen 内で試し、 結果を slops 記事にする。うまくいけば「データ図キット」分割の実績になる。
出典 #
- issue #113 の artifacts(
gh api repos/podhmo/html-sandbox/issues/113/artifacts/{1,3})。 Claude 版は Cleveland & McGill (1984) を記憶ベースで引用、ChatGPT 版は同書に加えて Munzner (2014)・FT Visual Vocabulary・W3C Images Tutorial を参考文献として挙げている(原典の内容は未確認)。 - tools/svg-gen/README.md、slops/2026-10-31-svg-gen-figures.md(このリポジトリ内)。