# 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:

```tsx
// ✅ 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.