with-canvas
with-canvas
Canvas work fails in two different ways: visual code that is pretty but janky, and optimized code that is unmaintainable or inaccessible. Treat every task as a rendering architecture decision before writing draw calls. Load only the reference named by the current phase; do not preload all references.
Phase 1 - Classify the Canvas Job
Identify the dominant workload before choosing APIs:
- Reject canvas: prefer DOM/CSS/SVG/video when the scene is mostly text, accessible controls, document layout, simple iconography, CSS animation, media playback, or a small number of scalable vector shapes.
- Decorative animation: non-interactive ambience, background particles, stars, birds, procedural loops.
- Data rendering: charts, maps, heatmaps, large point clouds, frequently updated measurements.
- Generative art: seeded/random drawing, creative sketches, procedural systems, exportable images.
- Interactive tool: pointer/keyboard input, selection, drag, editable objects, hit testing.
- Game/simulation: fixed update loop, dynamic entities, collision/physics, layered scene.
- WebGL/engine canvas: Three.js/Babylon.js/other renderer owning GPU resources.
MANDATORY READ: if the workload is decorative animation or generative art, read references/visual-quality.md — for those two jobs, looking good is the task, and perf/a11y hygiene alone ships generic output. Do NOT load it for data rendering, tools, games, or engine canvases.
Exit condition: state the workload, why canvas is the right primitive, target frame rate, expected object count, interaction model, and whether the canvas is decorative or semantically meaningful.