In the modern web development landscape, UI libraries often fall into two categories: high-abstraction "black boxes" that are difficult to customize, or low-level utility collections that require significant boilerplate. When I started building @srcroot/ui, the goal was to find the "Goldilocks zone"—a design system that provides a robust, accessible foundation without ever getting in the developer's way.
The result is what I call "The Invisible UI": a system built on the core principle of Deep Polymorphism.
What is Deep Polymorphism?
Traditional React components often limit you to a specific HTML element. A <Button> is always a <button>. If you need it to be a link, you often have to use a different component or a hacky prop.
In @srcroot/ui, every core component supports the asChild pattern (via Radix UI) or a direct as prop. This means:
- A
Button can be an <a> tag for navigation.
- A
Card can be a <section> or an <article> for better SEO.
- A
Heading can be any level from h1 to h6 while maintaining consistent visual styling.
This approach ensures that the visual identity of the design system is decoupled from the semantic structure of the document.
The Power of CVA (Class Variance Authority)
Consistency is the soul of a design system. However, hardcoding styles into components makes them rigid. To solve this, @srcroot/ui leverages Class Variance Authority (CVA).
CVA allows us to define component variants (like primary, outline, ghost) and sizes (sm, md, lg) in a type-safe, declarative way.
const buttonVariants = cva(
"inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors...",
{
variants: {
variant: {
default: "bg-primary text-primary-foreground hover:bg-primary/90",
destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
outline: "border border-input hover:bg-accent hover:text-accent-foreground",
// ...
},
size: {
default: "h-10 py-2 px-4",
sm: "h-9 px-3 rounded-md",
lg: "h-11 px-8 rounded-md",
},
},
defaultVariants: {
variant: "default",
size: "default",
},
}
)
By using CVA, we ensure that every instance of a "Primary Large Button" looks exactly the same across every project in the SrcRoot ecosystem.
Accessibility as a First-Class Citizen
A design system is only as good as its accessibility. @srcroot/ui is built on top of Radix UI primitives, which handle the heavy lifting of WAI-ARIA compliance. This includes:
- Keyboard Navigation: Full support for Tab, Arrow keys, and Enter/Space interactions.
- Focus Management: Automatic focus trapping in modals and popovers.
- Screen Reader Support: Proper aria-labels, roles, and states are managed automatically.
By embedding these patterns into the foundation, developers using the library don't have to "remember" to make their apps accessible—it happens by default.
The Copy-and-Paste Philosophy
Inspired by the success of shadcn/ui, @srcroot/ui promotes a "copy-and-paste" philosophy for components. Instead of installing a massive npm package that includes 50 components you don't need, you pull in only the source code for what you use.
This gives you:
- Zero Bloat: Only the code you need enters your bundle.
- Full Ownership: If you need to change a specific interaction for one project, you can edit the component file directly.
- Maximum Customizability: Since it's just code in your
components/ui folder, it integrates perfectly with your project's Tailwind config.
Real-World Impact
Today, @srcroot/ui powers the entire SrcRoot and ExpressITLab software suite, including:
- CalQuick: The complex commerce dashboard.
- SrcRoot PM: The high-fidelity Kanban board.
- Hisabi: The retail POS interface.
It has reduced our frontend development time by roughly 40%, allowing us to focus on business logic rather than re-centering divs or debugging ARIA attributes.
Conclusion
The goal of @srcroot/ui isn't to be a "UI Kit." It's to be a UI Foundation. By prioritizing polymorphism, type-safety, and accessibility, we've built a system that empowers developers to create stunning, accessible interfaces with unprecedented speed.
The UI should be invisible—it should just work, so your content can shine.
Check out @srcroot/ui on NPM and start building your next project with a robust foundation.
