ADR-0001: Use @base-ui/react instead of Radix UI

Status

accepted

Context

shadcn/ui ships visual components that are typically built on Radix UI primitives. When we bootstrapped Scrum4Me with shadcn, the component wrappers in components/ui/ were adapted to use @base-ui/react instead of the Radix packages. @base-ui/react exposes the same accessibility primitives but uses a render prop for composition instead of Radix's asChild pattern. Attempting to use asChild in our TypeScript-strict setup produced type errors because the prop is not declared in @base-ui/react's API surface.

Decision

We use @base-ui/react exclusively. No Radix UI package (@radix-ui/*) is imported anywhere in the codebase. Composition always uses the render prop:

// ✅ correct
<TooltipTrigger render={<button />}>…</TooltipTrigger>

// ❌ wrong — asChild does not exist on @base-ui/react primitives
<TooltipTrigger asChild><button>…</button></TooltipTrigger>

Consequences

Positive

TypeScript stays clean; no any casts or asChild workarounds.
@base-ui/react is actively maintained by the MUI team with React 19 support.
Composition pattern is explicit and grep-friendly.

Negative

AI agents trained on Radix-based shadcn documentation will default to asChild — they must be reminded of the render-prop pattern (this ADR exists for that reason).
shadcn CLI-generated components may need manual adjustment when installed.

1.5 KiB Raw Blame History