Koala UIArchitecture
The house style for building Koala UI - a pragmatic distillation of modern React design-system patterns, taking what scales and dropping what's clever-but-fragile.
The stack#
| Styling / variants | tailwind-variants (tv) with slots |
| Class merge | tailwind-merge, extended for Koala tokens |
| Behavior & a11y | Radix UI primitives |
| Polymorphism (asChild) | Radix Slot |
| Cross-part state | React Context (typed helper) |
| Theming | CSS variables + semantic tokens + class strategy |
What we reject#
recursiveCloneChildren-style prop distribution (matching children by displayName to inject props) is elegant in a demo and a liability at scale: it breaks under minification, breaks when a part is wrapped, and clones the subtree each render. We use React Context for cross-part state - what Radix, React Aria, Ark, MUI, and Chakra all do internally.
Full reference#
The complete writeup lives in docs/ARCHITECTURE.md in the repo.