apps/docs/content/blog/en/why-choose-heroui-for-your-design-system.mdx
Most React component libraries solve the same problem: stop rebuilding buttons. But design systems fail at a different stage — when the library you chose can't flex to your product's needs, when accessibility is an afterthought bolted on after launch, or when your AI coding assistant hallucinates props that don't exist.
HeroUI combines React Aria for accessibility, Tailwind CSS v4 for styling, and a compound component API that gives you structural control without prop sprawl. This post explains the concrete reasons to choose it as the foundation of your design system.
| Layer | Technology | Why |
|---|---|---|
| Accessibility | React Aria (Adobe) | Industry-leading WCAG primitives, actively maintained |
| Styling | Tailwind CSS v4 | Static CSS, zero runtime, design tokens via @theme |
| Component API | Compound components | Card.Header, Modal.Body — structural control without prop sprawl |
| Types | TypeScript | Full type coverage, generic props, strict mode compatible |
| AI tooling | MCP server, llms.txt, agent skills | AI assistants get current APIs, not stale training data |
| Cross-platform | HeroUI Native (React Native) | Same design system on web and mobile — no other open library does this |
Every HeroUI component is built on React Aria, Adobe's accessibility primitive library. This isn't a marketing checkbox — React Aria is the deepest accessibility foundation available for React, and it powers Adobe's own production design system (Spectrum) across Photoshop Web, Acrobat, and Lightroom.
What React Aria handles that most libraries don't:
This matters because accessibility compliance isn't optional in 2026. Government, healthcare, finance, and education all require WCAG conformance. HeroUI gives you that conformance as a default, not an upgrade.
Many popular libraries (shadcn/ui, Park UI) are built on Radix UI. Radix is solid, but the original team has shifted focus to Base UI, and the long-term maintenance of Radix primitives is an open question. React Aria is actively maintained by Adobe — a company that depends on it for their own products.
HeroUI doesn't use Tailwind as a compatibility layer — it's built for Tailwind CSS v4 from the ground up.
What this means in practice:
@theme directives, not JavaScript configuration objects. Change a token and every component updates.className — the same Tailwind workflow you use for everything else in your project.<Button variant="secondary" className="font-semibold tracking-wide">
Get Started
</Button>
<Card className="max-w-md shadow-lg">
<Card.Header className="pb-0">
<Card.Title className="text-xl font-bold">Dashboard</Card.Title>
</Card.Header>
<Card.Content className="py-4">
Your metrics here
</Card.Content>
</Card>
If your team already uses Tailwind, HeroUI integrates without introducing a second styling system. If you don't use Tailwind yet, adopting it is a separate decision — but one that most React teams in 2026 have already made.
HeroUI uses compound components — a pattern where parent components expose sub-components through dot notation. This is the same approach used by Radix UI, and it scales far better than prop-based APIs for complex UIs.
<Modal>
<Button>Open</Button>
<Modal.Backdrop>
<Modal.Container>
<Modal.Dialog>
<Modal.Header>
<Modal.Heading>Confirm</Modal.Heading>
</Modal.Header>
<Modal.Body>Are you sure?</Modal.Body>
<Modal.Footer>
<Button variant="ghost">Cancel</Button>
<Button>Confirm</Button>
</Modal.Footer>
</Modal.Dialog>
</Modal.Container>
</Modal.Backdrop>
</Modal>
Why this matters for design systems:
className to any sub-component independently. Style Card.Header differently from Card.Footer without CSS overrides.HeroUI ships <ComponentCount />+ components with <ExampleCount />+ documented examples. The library covers the full product UI surface:
Complex components like Calendar, DatePicker, ColorPicker, and Table are self-contained — they handle date math, locale formatting, keyboard navigation, and screen reader announcements internally. These are genuinely hard to build accessibly, and HeroUI ships them as maintained, tested primitives.
Most developers use AI coding assistants daily. The quality of generated code depends on whether the AI has accurate context for your component library — or is guessing from stale training data.
HeroUI ships four first-party integrations:
A Model Context Protocol server that AI agents can query for component documentation, APIs, source code, and design tokens. Connect it to Cursor, Claude Code, Windsurf, or any MCP-compatible editor.
When an AI assistant has access to the MCP server, it can look up the exact compound component structure, available props, and correct imports for any HeroUI component — instead of hallucinating.
Learn how to set up the MCP Server →
A structured reference file at heroui.com/llms.txt that gives LLMs a condensed, accurate reference for the entire library. This is a standardized format that AI tools consume to avoid generating deprecated patterns.
Pre-built skill files for Cursor, Claude Code, and other AI tools that teach agents HeroUI's conventions — correct imports, compound component patterns, styling approaches, and project scaffolding.
Learn how to install Agent Skills →
An AGENTS.md file that provides repository-level context for AI coding agents. It describes the project structure, coding conventions, and component patterns so agents understand your codebase from the first prompt.
The result: AI assistants generate correct HeroUI v3 code with the right compound component patterns, import paths, and Tailwind classes. This matters because incorrect AI output costs more time to debug than it saves to generate.
HeroUI Pro extends the base library with app-level components and templates:
Pro is a paid product — use it when you need app infrastructure, not just UI components.
<DocsImage src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/heroui-native-og-light-1.webp" darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/native/heroui-native-og-dark-1.webp" alt="HeroUI Native - React Native components" />
HeroUI is the only open design system that delivers the same component quality across both web and mobile. HeroUI Native brings the same design tokens, compound component API, and accessibility standards to React Native — leveraging each platform's native APIs instead of wrapping web views.
This means teams building cross-platform products can share a single design system across React (web) and React Native (mobile) without compromising on either platform. Same visual language, same component patterns, same theming tokens — but native rendering on each side.
No other open-source React component library offers this. MUI, shadcn/ui, Chakra UI, and Mantine are web-only. If your product ships on both web and mobile, HeroUI is the only design system that covers both from the same foundation.
<DocsImage src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/blog/community-figma-preview-light.png" darkSrc="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/blog/community-figma-preview-dark.png" alt="HeroUI Figma Kit" />
The HeroUI Figma Kit (v3) keeps design and code in sync. Components in Figma match the React implementation, so designers and developers work from the same source of truth.
Every component has Storybook stories showing all variants, states, and compositions. Use it for visual testing, design review, and documentation.
HeroUI isn't new — we've been building it for over 5 years, starting from v1 (originally NextUI). The community has grown steadily: 29.3K+ GitHub stars, 9K+ Discord members, and thousands of discussions, community answers, and issues resolved every week.
HeroUI is venture-backed, including Y Combinator. This means a dedicated full-time team, long-term maintenance commitments, and the resources to keep shipping. When you adopt a component library, you're betting on its future — HeroUI is built to be around for the long run.
HeroUI ships with refined defaults that look polished without custom theming:
The design token system uses CSS custom properties, so theming is standard CSS:
@theme {
--color-primary: oklch(0.6 0.25 260);
--radius-field: 0.5rem;
--shadow-surface: 0 1px 3px rgba(0, 0, 0, 0.08);
}
Change tokens globally and every component updates. No JavaScript theme objects, no provider wrappers, no runtime overhead.
Want to make HeroUI yours in a few clicks? The Theme Builder lets you customize colors, typography, radius, and spacing visually — then export a ready-to-use CSS theme for your project.
Most component libraries require configuration files, provider wrappers, theme objects, and plugin setup before you can render your first component. HeroUI doesn't. The entire setup is two steps:
1. Install:
npm i @heroui/styles @heroui/react
2. Add one line to your CSS:
@import "tailwindcss";
@import "@heroui/styles"; /* That's it */
Now use any component — no ThemeProvider, no ChakraProvider, no MantineProvider, no configuration objects:
import { Button, Card } from "@heroui/react";
export default function Page() {
return (
<Card>
<Card.Content>
<Button>Click me</Button>
</Card.Content>
</Card>
);
}
That's the entire setup. No wrapping your app in providers, no theme configuration files, no runtime setup. Install, import one CSS line, and start building. See the Quick Start guide to get running in under five minutes.
HeroUI is designed for the React Server Components model:
Card, Badge, Text, Separator, Avatar) stay in server component trees with zero client JavaScript.Button, Modal, Table, Select) use client boundaries — clearly documented per component.This means your pages ship less JavaScript by default. Static layouts render on the server. Interactive widgets hydrate only where needed.
HeroUI takes a focused approach: instead of shipping every possible component, we prioritize depth, accessibility, and quality for the components teams use most. For specialized needs like rich text editing, drag-and-drop, or charting, we recommend pairing HeroUI with dedicated libraries that excel at those specific problems — this gives you better results than relying on a single library to handle everything.
HeroUI is built for Tailwind CSS v4. If your team is already using Tailwind, adoption is seamless. If you're on a different styling approach, the switch to Tailwind is a separate but worthwhile investment in modern CSS tooling.
HeroUI is a strong fit if you're building:
npm install @heroui/styles @heroui/react