code-map-visualization

Code Map Visualization Best Practices

2D マップに投影され、ジオハッシュ化されたコードベースを、正直で、高速で、読みやすく、インタラクティブで、アニメーション対応かつアクセシブルに描画し、視覚的にナビゲートする方法です。空間構造の上に構築される、描画と知覚に関する技術です。情報可視化、地図製作、コンピューターグラフィックス、自然・生物に着想を得たレイアウトの数十年にわたる知見を活用し、コードマップを正しく読み取れるようにするとともに、インタラクティブなフレームレートで動作させます。9つのカテゴリにわたる47のルールを、影響度順にまとめています。

適用する場面

次のような場合に、これらのガイドラインを参照してください。

• どのコード属性をどの視覚チャネル（位置、サイズ、色）に割り当てるか、また、どのカラースケールが正確に情報を伝えるかを決めるとき
• Canvas2D、WebGL、またはdeck.glを使って、数万から数百万のセルをウェブ上に描画し、レンダーループをフレーム予算内に収めるとき
• 領域やファイルのラベルを配置して重なりを整理し、情報量の多いマップ上に読みやすいテキストを描画するとき
• ホバー、ピッキング、選択、カメラ／ビュー状態モデル、ディープリンク、キーボード操作などのインタラクションを実装するとき
• 閲覧者を戸惑わせることなく、カメラの移動、詳細度の遷移、データ更新をアニメーション化するとき
• 色覚特性のある方、動きに敏感な方、キーボードのみを使う方、スクリーンリーダーを使う方がキャンバスを利用できるようにするとき

対象範囲について

このスキルは描画と知覚のレイヤーを対象とします。関連スキルのgeohash-spatial-code-mapsは、ジオハッシュのエンコード、コードから平面への投影、bbox／被覆集合クエリ、タイル分割、精度とズームのナビゲーションモデルといった空間計算を担当します。ここに記載するルールでは、これらを改めて説明するのではなく、関連スキルへのリンクを示します（例： map-deterministic-projection、 nav-level-of-detail-aggregation）。例では、Canvas2D + WebGL/deck.gl、d3-scale/d3-colorを使ったTypeScriptを対象としていますが、知覚に関する考え方はあらゆる描画スタックに応用できます。

優先度別ルールカテゴリ

優先度	カテゴリ	影響度	接頭辞	ルール数
1	視覚的エンコーディングと知覚チャネル	重大	encode-	6
2	色と知覚的カラースケール	重大	color-	5
3	GPU描画パイプライン（Canvas2D + WebGL）	高	gpu-	6
4	描画パフォーマンスとフレーム予算	高	perf-	5
5	ラベルとテキスト描画	中～高	text-	5
6	インタラクション、ピッキング、カメラ	中～高	interact-	5
7	アニメーションとトランジション	中	anim-	4
8	アクセシビリティとインクルーシブな描画	中	access-	4
9	自然・細胞に着想を得たレイアウトと描画	中	bio-	7

クイックリファレンス

1. 視覚的エンコーディングと知覚チャネル（重大）

• encode-rank-channels-by-perceptual-accuracy — 判断指標は色相ではなく、位置や長さで表す
• encode-let-projection-own-position — x/y座標はジオハッシュ投影に任せ、レイアウトを変更しない
• encode-size-by-area-not-radius — 値は面積に対応させ、半径には平方根を使う
• encode-separate-categorical-from-quantitative — カテゴリには色相、量には順序のあるチャネルを使う
• encode-redundant-encoding-for-key-signals — 見落としてはならない少数の信号は、二重にエンコードする
• encode-maximize-data-ink-drop-chartjunk — データの妨げになる影、ベベル、濃いグリッドを取り除く

2. 色と知覚的に均一なカラースケール（重要）

• color-perceptually-uniform-sequential-ramp — Viridis／OKLCHを使用し、レインボー／jetは使用しません
• color-match-scale-type-to-data — データに合わせて、順次・発散・カテゴリ別のスケールを使い分けます
• color-design-for-color-vision-deficiency — CVDに配慮したパレットを使い、シミュレーションで検証します
• color-limit-categorical-hues — 色相は約8～12色に抑え、残りはまとめます
• color-control-contrast-against-basemap — 明るい背景でも暗い背景でも、セルを判読できるようにします

3. GPU レンダリングパイプライン — Canvas2D + WebGL（高）

• gpu-layer-canvas2d-over-webgl — 大量のセルはGLで、鮮明なラベルやオーバーレイはCanvas2Dで描画します
• gpu-instance-cells-not-per-quad-draw — セルごとに描画するのではなく、インスタンス化した描画呼び出しを1回行います
• gpu-batch-to-cut-draw-calls-and-state-changes — プログラム／テクスチャごとにグループ化し、パイプラインのフラッシュを避けます
• gpu-pack-attributes-into-typed-arrays — 再利用可能なFloat32Arrayを使い、フレームごとの割り当てをなくします
• gpu-atlas-tiles-and-glyphs — 1つのアトラスを一度だけバインドし、UVオフセットで参照します
• gpu-size-canvas-to-devicepixelratio — 鮮明で過剰描画のない出力になるよう、バッキングストアのサイズをDPRに合わせます

4. 描画パフォーマンスとフレーム予算（高）

• perf-render-in-a-single-raf-loop — 入力をまとめ、フレームごとに1回だけ再描画します
• perf-redraw-only-dirty-regions — 静的なセルレイヤーではなく、オーバーレイを再描画します
• perf-debounce-viewport-recompute — カバー範囲の再計算はスロットルし、描画は毎フレーム行います
• perf-offload-to-worker-and-offscreencanvas — 負荷の高い投影／パッキング処理をメインスレッド以外で実行します
• perf-bound-the-tile-cache — タイルキャッシュの上限をLRU方式で設定し、追い出し時にGPUバッファを解放します

5. ラベルとテキストの描画（中～高）

• text-place-and-declutter-labels-greedily — 優先度に基づいて、貪欲法で衝突を避けながら配置します
• text-show-labels-by-level-of-detail — ズームが低いときはドメインラベルを表示し、ファイルラベルは十分に大きい場合のみ表示します
• text-render-glyphs-on-canvas2d-not-per-glyph-textures — GLでグリフをアップロードせず、ネイティブのfillTextを使います
• text-add-halo-for-legibility — ハローを付けることで、どのような塗りつぶしの上でもラベルを読みやすく保てます
• text-anchor-region-labels-at-centroid — bboxの中心ではなく、最大内接円の中心に配置します

6. インタラクション、ピッキング、カメラ（中～高）

• interact-pick-with-gpu-color-id-or-spatial-index — 線形走査ではなく、O(1)／O(log n)でピッキングします
• interact-keep-hover-feedback-under-one-frame — オーバーレイのハイライトは即時に表示し、詳細は非同期で取得します
• interact-model-the-camera-not-the-dom — 1つのビュー状態オブジェクトを信頼できる唯一の情報源にします
• interact-sync-view-state-to-the-url — ビューをディープリンク可能かつ共有可能にします
• interact-support-keyboard-pan-zoom-and-focus — 矢印キーと+／-キーでカメラを操作します

7. アニメーションとトランジション（中）

• anim-ease-camera-transitions-not-jumps — 中心位置とズームを滑らかに変化させ、視線で追えるようにします
• anim-crossfade-between-lod-levels — 集約表示をポイントへディゾルブし、突然切り替わらないようにします
• anim-preserve-object-constancy-on-data-update — ジオハッシュをキーにし、実際に変化したものだけをアニメーションさせます
• anim-keep-transitions-interruptible-and-budgeted — 実行中のトゥイーンをキャンセルし、目標を変更できるようにします

8. アクセシビリティとインクルーシブなレンダリング（中）

• access-encode-redundantly-never-color-alone — 色を形状やラベルと組み合わせます（WCAG 1.4.1）
• access-honor-prefers-reduced-motion — 動きに敏感なユーザー向けにアニメーションを抑制します
• access-make-the-map-keyboard-operable — フォーカス可能、フォーカス可視、キーボードトラップなしにします
• access-provide-a-text-alternative-for-the-canvas — スクリーンリーダー向けに、同期された DOM/ARIA のアウトラインを提供します

9. 自然・細胞に着想を得たレイアウトとレンダリング（中）

マップを有機的にレンダリングするための、状況に応じて使えるツールボックスです。このうち 2 つはソフトウェアの可視化向けに考案されました。

• bio-voronoi-regions-for-space-filling-tessellation — 投影されたポイントをシードとする、隙間のないボロノイセル
• bio-relax-weights-for-even-cell-areas — 重みに対する Lloyd/CVT を使用し、シード位置は固定します
• bio-circle-packing-for-nested-counts — 階層と件数を表す円パッキング
• bio-phyllotaxis-packing-for-even-point-spread — 密度が高く均一な塗りつぶしに使う黄金角スパイラル
• bio-metaball-hulls-for-region-membranes — マーチングスクエアによる有機的な領域の輪郭
• bio-edge-bundling-for-dependency-overlays — 直線が絡み合った表示に代わる Holten のバンドリング
• bio-flow-fields-for-animated-dependency-load — 動きで負荷を表現する場合の Physarum/boids フロー

使い方

詳しい説明、コード例、「適用すべきでない場合」のガイダンスについては、各リファレンスファイルを参照してください。

• セクション定義 — カテゴリー構造と影響レベル
• ルールテンプレート — 新しいルールを追加するためのテンプレート

ルールは [[other-rule-slug]] で相互リンクされています。関連するパターンが参照されている場合は、そのリンク先も確認してください。enc-、prec-、dec-、qry-、nbr-、idx-、map-、nav- ルールへの相互リンクは、コンパニオンの geohash-spatial-code-maps スキルを参照します。空間計算については、そちらを読んでください。

レンダラーを最初から最後まで構築する場合の基本的な流れは、エンコーディングを決め（カテゴリー 1）→ 色を選び（カテゴリー 2）→ GPU パイプラインを立ち上げ（カテゴリー 3）→ フレーム予算を守り（カテゴリー 4）→ ラベル、インタラクション、アニメーション、アクセシビリティを追加する（カテゴリー 5～8）ことです。マップに適している場合は、有機的な細胞ベースのレンダリング（ボロノイ領域、パッキング、膜、エッジバンドリング）を活用してください（カテゴリー 9）。上流の投影とタイル分割については、geohash-spatial-code-maps を参照してください。

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルールのテンプレート
metadata.json	バージョンとリファレンス情報
AGENTS.md	自動生成された目次ナビゲーション

関連スキル

• geohash-spatial-code-maps — この描画の基盤となる空間レイヤー：geohash エンコーディング、コード→平面への投影、タイル分割、精度↔ズームのナビゲーションモデル
• computer-science-algorithms — 高速なピッキング、表示の整理、レンダリングループを支える空間インデックス、ソート、計算量の基本要素