ADR 0005: Radix UI over MUI and Headless UI

Decision: Replace MUI with Radix UI unstyled primitives. Why: MUI’s theme system couldn’t be overridden cleanly enough to produce a distinctive visual identity; Radix gives full style ownership with accessibility and portal handling included.

Context

Vektory started on MUI. It got me moving fast, but as the design took shape I hit a wall: I couldn’t make the app look like Vektory. Every override fought the theme system, and the result still read as “a MUI app in a custom skin”, recognisable at a glance. I wanted the opposite: a distinctive dark-purple-and-gold surface where nothing shouted its origin library, where the visual identity was mine.

That meant switching to an unstyled primitives library. The choice came down to Radix UI versus Headless UI.

Options considered

MUI (incumbent) Ships with a complete design system and styling engine. Great for shipping fast on a conventional visual. Overrides are possible but adversarial, I found myself fighting specificity wars and theme tokens I didn’t need. The app kept looking like MUI no matter what I did.

Radix UI Unstyled, accessible primitives. Each primitive ships as a separate npm package, installed independently. Good portal/focus/ARIA handling out of the box. Visual layer is 100% my responsibility.

Headless UI Similar philosophy, unstyled primitives, accessibility built in. Distributed as a single monolithic package. Smaller primitive surface than Radix.

Decision

Radix UI. The per-primitive package boundary and the richer primitive set made it the better fit for Vektory.

Rationale

Consequences

Positive

Negative, the discipline tax

Follow-up