ADR-002 — Vanilla JS, no framework

Status · Superseded by ADR-011 (TypeScript) + ADR-012 (SvelteKit) Date · 2026-04-01 · Superseded April 2026 TA anchor · §stack · §constraints

Context

The project needs a consistent approach to UI and component structure. The primary rendering targets are Three.js and Canvas 2D — both imperative APIs. A declarative component framework would add abstraction on top of imperative rendering without clear benefit.

Decision

Vanilla JavaScript throughout. No React, Vue, Svelte, or any component framework.

Rationale

The rendering surfaces are inherently imperative — Three.js scenes, Canvas 2D draw calls. Wrapping them in a reactive component system adds complexity without benefit. The six screens are distinct enough that shared component logic is limited to the nav bar and detail panel — both manageable as vanilla JS modules.

Alternatives considered

• React — good for data-driven UI; poor fit for canvas/WebGL-heavy screens. Adds significant bundle size.
• Svelte — smaller than React; still adds compilation step and abstraction layer not needed here.
• Lit — lightweight web components; reasonable alternative but adds a dependency without clear gain.

Consequences

Positive: zero framework overhead; all code directly readable; no framework upgrade risk. Negative: shared component patterns require discipline without framework enforcement.