ADR-0001 UI framework

Context

Every product we build needs a UI layer. Standardizing on one UI framework means shared components, shared hiring profile, shared knowledge, and no per-project re-litigation. The choice constrains the app framework decision (ADR-0002) and the styling decision later.

Options considered

1. React

The incumbent. Largest ecosystem, largest hiring pool, every major app framework supports it first-class.

Pros

• Biggest ecosystem: component libraries, tooling, docs, answers exist for everything
• Largest hiring pool; most candidates need no ramp-up
• First-class support in every meta-framework (TanStack Start, Next.js, Remix, Astro)
• Mature concurrent features, server components knowledge transfers across frameworks

Cons

• No official full-stack story by itself — needs a meta-framework
• Ecosystem churn (though stabilizing)
• Verbose compared to compiled alternatives

2. Vue / Nuxt

Progressive framework with strong single-file-component DX.

Pros

• Gentle learning curve, excellent docs
• Nuxt is a coherent full-stack story
• Reactivity model is simple and explicit

Cons

• Smaller hiring pool and ecosystem than React
• TanStack Start is React-first — picking Vue would break the stack direction
• Fewer enterprise component libraries

3. Svelte / SvelteKit

Compiled components, minimal boilerplate.

Pros

• Least boilerplate, great DX
• Small bundles, fast runtime

Cons

• Smallest hiring pool of the three
• Ecosystem gaps for enterprise needs
• TanStack Start is React-first — breaks the stack direction

4. SolidJS / others (Angular, Qwik)

Fine frameworks, but niche hiring pools and ecosystem gaps make them poor company-wide defaults.

Decision

React is the company-standard UI framework for all new web apps.

It’s the safest foundation: the biggest ecosystem, the biggest hiring pool, and it’s the first-class target of TanStack Start (ADR-0002). The cost of React’s verbosity is more than paid back by never being blocked on a missing library or an unanswerable question.

Consequences

Easier: hiring, onboarding, component sharing across products, third-party integrations (analytics, auth UIs, payments all ship React SDKs first).

Harder: nothing meaningful — but we commit to keeping up with React’s evolution (compiler, server components) rather than freezing on old patterns.

Given up: the smaller bundle sizes of compiled frameworks (Svelte/Solid). Accepted — bundle size is not our bottleneck; team velocity is.