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.