# 調査メモ: 図・グラフのガイドライン（issue #113 の artifacts 要約）

[issue #113](https://github.com/podhmo/html-sandbox/issues/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（このリポジトリ内）。
