Using Headless Components in Design Systems
What You'll Learn
You'll learn how to wrap headless primitives (like Radix or React Aria) in your own styled components to create a consistent, accessible design system for your entire application.
The Core Idea
Headless libraries give you behavior and accessibility, but no styles. Your design system needs to enforce your brand's look and feel. The solution? Create a thin wrapper layer where you import headless primitives, apply your design tokens (colors, spacing, typography), and export them as your own components.
Think of it like buying a car chassis with all the safety features and mechanical systems (headless primitive), then adding your custom paint job, upholstery, and trim (your design system styling). Every car in your fleet looks consistent, but they all have the same reliable internals.
The Pattern
// In your design system: Button.tsx
import * as RadixButton from '@radix-ui/react-button';
import { styled } from './your-styling-solution';
const StyledButton = styled(RadixButton.Root, {
backgroundColor: 'var(--color-primary)',
padding: 'var(--space-2) var(--space-4)',
borderRadius: 'var(--radius-md)',
'&:hover': {
backgroundColor: 'var(--color-primary-dark)',
}
});
export const Button = StyledButton;
Now everywhere in your app imports Button from your design system—not Radix directly. Accessibility is guaranteed, styling is consistent, and future design changes happen in one place.
This works identically with React Aria hooks—wrap the hook call and styling in your custom component, then export that.
Why This Matters
Your team never touches the underlying primitive directly. They use your components, which means:
- No styling inconsistencies
- Accessibility baked in everywhere
- Easy global design updates
Key Takeaway: Headless components become design system building blocks by wrapping them with your styling layer—giving you both accessibility guarantees and visual consistency across your entire application.