code-map-visualization

Code Map Visualization Best Practices

How to render and visually navigate a codebase that has been projected and geohashed into a 2D map — making it honest, fast, legible, interactive, animated, and accessible. This is the rendering and perception craft on top of the spatial structure: it draws on decades of information-visualisation, cartography, computer-graphics, and nature-/biology-inspired layout knowledge so a code map reads correctly and runs at interactive rates. Contains 47 rules across 9 categories, prioritised by impact.

When to Apply

Reference these guidelines when:

• Deciding what code attribute to put on which visual channel (position, size, colour) and which colour scale tells the truth
• Drawing tens of thousands to millions of cells on the web with Canvas2D, WebGL, or deck.gl, and keeping the render loop inside the frame budget
• Placing and decluttering region/file labels, and rendering legible text over a busy map
• Wiring up interaction — hover, picking, selection, a camera/view-state model, deep links, keyboard control
• Animating camera moves, level-of-detail transitions, and data updates without disorienting the viewer
• Making the canvas accessible to color-vision-deficient, motion-sensitive, keyboard-only, and screen-reader users

A note on scope

This skill is the rendering and perception layer. The companion skill geohash-spatial-code-maps owns the spatial math — geohash encoding, the code→plane projection, bbox/covering-set queries, tiling, and the precision↔zoom navigation model. Rules here cross-link into that skill (e.g. map-deterministic-projection, nav-level-of-detail-aggregation) rather than re-deriving it. Examples target TypeScript with Canvas2D + WebGL/deck.gl and d3-scale/d3-color; the perceptual reasoning generalises to any rendering stack.

Rule Categories by Priority

Priority	Category	Impact	Prefix	Rules
1	Visual Encoding & Perceptual Channels	CRITICAL	encode-	6
2	Color & Perceptual Color Scales	CRITICAL	color-	5
3	GPU Render Pipeline (Canvas2D + WebGL)	HIGH	gpu-	6
4	Render Performance & Frame Budget	HIGH	perf-	5
5	Labels & Text Rendering	MEDIUM-HIGH	text-	5
6	Interaction, Picking & Camera	MEDIUM-HIGH	interact-	5
7	Animation & Transitions	MEDIUM	anim-	4
8	Accessibility & Inclusive Rendering	MEDIUM	access-	4
9	Nature- & Cell-Inspired Layout & Rendering	MEDIUM	bio-	7

Quick Reference

1. Visual Encoding & Perceptual Channels (CRITICAL)

• encode-rank-channels-by-perceptual-accuracy — Put the decision metric on position/length, not hue
• encode-let-projection-own-position — The geohash projection owns x/y; don't re-layout
• encode-size-by-area-not-radius — Map value to area; take the square root for radius
• encode-separate-categorical-from-quantitative — Hue for category, ordered channels for magnitude
• encode-redundant-encoding-for-key-signals — Double-encode the few signals that must never be missed
• encode-maximize-data-ink-drop-chartjunk — Strip shadows, bevels, heavy grids that fight the data

2. Color & Perceptual Color Scales (CRITICAL)

• color-perceptually-uniform-sequential-ramp — Viridis/OKLCH, never rainbow/jet
• color-match-scale-type-to-data — Sequential vs diverging vs categorical, matched to the data
• color-design-for-color-vision-deficiency — CVD-safe palettes, verified by simulation
• color-limit-categorical-hues — Cap at ~8–12 hues; bucket the long tail
• color-control-contrast-against-basemap — Keep cells legible on light or dark backgrounds

3. GPU Render Pipeline — Canvas2D + WebGL (HIGH)

• gpu-layer-canvas2d-over-webgl — Bulk cells in GL, crisp labels/overlays in Canvas2D
• gpu-instance-cells-not-per-quad-draw — One instanced draw call, not one per cell
• gpu-batch-to-cut-draw-calls-and-state-changes — Group by program/texture to avoid pipeline flushes
• gpu-pack-attributes-into-typed-arrays — A reusable Float32Array, zero per-frame allocation
• gpu-atlas-tiles-and-glyphs — One atlas bound once, addressed by UV offset
• gpu-size-canvas-to-devicepixelratio — Size the backing store to DPR for crisp, non-overdrawn output

4. Render Performance & Frame Budget (HIGH)

• perf-render-in-a-single-raf-loop — Coalesce input into one redraw per frame
• perf-redraw-only-dirty-regions — Repaint the overlay, not the static cell layer
• perf-debounce-viewport-recompute — Throttle the covering-set recompute; draw every frame
• perf-offload-to-worker-and-offscreencanvas — Heavy projection/packing off the main thread
• perf-bound-the-tile-cache — LRU-cap the tile cache; free GPU buffers on eviction

5. Labels & Text Rendering (MEDIUM-HIGH)

• text-place-and-declutter-labels-greedily — Greedy collision placement by priority
• text-show-labels-by-level-of-detail — Domain labels low-zoom, file labels only when big
• text-render-glyphs-on-canvas2d-not-per-glyph-textures — Native fillText, not GL glyph uploads
• text-add-halo-for-legibility — A halo keeps labels readable over any fill
• text-anchor-region-labels-at-centroid — Pole of inaccessibility, not the bbox centre

6. Interaction, Picking & Camera (MEDIUM-HIGH)

• interact-pick-with-gpu-color-id-or-spatial-index — O(1)/O(log n) picking, not a linear scan
• interact-keep-hover-feedback-under-one-frame — Instant overlay highlight, async details
• interact-model-the-camera-not-the-dom — One view-state object as the source of truth
• interact-sync-view-state-to-the-url — Deep-linkable, shareable views
• interact-support-keyboard-pan-zoom-and-focus — Arrow and +/- keys drive the camera

7. Animation & Transitions (MEDIUM)

• anim-ease-camera-transitions-not-jumps — Ease centre and zoom so the eye can follow
• anim-crossfade-between-lod-levels — Dissolve aggregates into points, don't pop
• anim-preserve-object-constancy-on-data-update — Key by geohash; animate only real changes
• anim-keep-transitions-interruptible-and-budgeted — Cancel and retarget in-flight tweens

8. Accessibility & Inclusive Rendering (MEDIUM)

• access-encode-redundantly-never-color-alone — Pair colour with shape or label (WCAG 1.4.1)
• access-honor-prefers-reduced-motion — Collapse animation for motion-sensitive users
• access-make-the-map-keyboard-operable — Focusable, focus-visible, no keyboard trap
• access-provide-a-text-alternative-for-the-canvas — A synced DOM/ARIA outline for screen readers

9. Nature- & Cell-Inspired Layout & Rendering (MEDIUM)

A situational toolbox for rendering the map organically; two of these were invented for software visualisation.

• bio-voronoi-regions-for-space-filling-tessellation — Gapless Voronoi cells seeded by projected points
• bio-relax-weights-for-even-cell-areas — Lloyd/CVT on weights; keep seed positions fixed
• bio-circle-packing-for-nested-counts — Packed circles for hierarchy and counts
• bio-phyllotaxis-packing-for-even-point-spread — Golden-angle spiral for dense, even fills
• bio-metaball-hulls-for-region-membranes — Marching-squares organic region outlines
• bio-edge-bundling-for-dependency-overlays — Holten bundling vs a straight-line hairball
• bio-flow-fields-for-animated-dependency-load — Physarum/boids flow when motion encodes load

How to Use

Read individual reference files for detailed explanations, code examples, and "when NOT to apply" guidance:

• Section definitions — Category structure and impact levels
• Rule template — Template for adding new rules

Rules cross-link via [[other-rule-slug]]; follow them when a related pattern is referenced. Cross-links to enc-, prec-, dec-, qry-, nbr-, idx-, map-, and nav- rules point into the companion geohash-spatial-code-maps skill — read them there for the spatial math.

To build a renderer end to end, the spine is: decide the encoding (category 1) → choose colour (category 2) → stand up the GPU pipeline (category 3) → hold the frame budget (category 4) → add labels, interaction, animation, and accessibility (categories 5–8); reach for organic, cell-based rendering — Voronoi regions, packing, membranes, edge bundling — when it suits the map (category 9). The upstream projection and tiling come from geohash-spatial-code-maps.

Reference Files

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information
AGENTS.md	Auto-built TOC navigation

Related Skills

• geohash-spatial-code-maps — The spatial layer this renders: geohash encoding, the code→plane projection, tiling, and the precision↔zoom navigation model
• computer-science-algorithms — The spatial-index, sorting, and complexity primitives behind fast picking, declutter, and the render loop