diff --git a/docs/adr/0001-base-ui-over-radix.md b/docs/adr/0001-base-ui-over-radix.md new file mode 100644 index 0000000..def03fa --- /dev/null +++ b/docs/adr/0001-base-ui-over-radix.md @@ -0,0 +1,34 @@ +# 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 +}>… + +// ❌ wrong — asChild does not exist on @base-ui/react primitives + +``` + +## 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.