UI Components
Comprehensive patterns for building accessible UI component libraries with shadcn/ui and Radix Primitives. Covers CVA variants, OKLCH theming, cn() utility, component extension, asChild composition, dialog/menu patterns, and data-attribute styling. Each category has individual rule files in rules/ loaded on-demand.
Quick Reference
| Category |
Rules |
Impact |
When to Use |
| shadcn/ui |
3 |
HIGH |
CVA variants, component customization, form patterns, data tables |
| Radix Primitives |
3 |
HIGH |
Dialogs, polymorphic composition, data-attribute styling |
| Design System Tokens |
1 |
HIGH |
W3C tokens, OKLCH theming, Tailwind @theme, spacing scales |
| Design System Components |
1 |
HIGH |
Atomic design, CVA variants, accessibility, Storybook |
| Forms |
2 |
HIGH |
React Hook Form v7, Zod validation, Server Actions |
Total: 10 rules across 4 categories
Quick Start
// CVA variant system with cn() utility
import { cva, type VariantProps } from 'class-variance-authority'
import { cn } from '@/lib/utils'
const buttonVariants = cva(
'inline-flex items-center justify-center rounded-md font-medium transition-colors',
{
variants: {
variant: {
default: 'bg-primary text-primary-foreground hover:bg-primary/90',
destructive: 'bg-destructive text-destructive-foreground',
outline: 'border border-input bg-background hover:bg-accent',
ghost: 'hover:bg-accent hover:text-accent-foreground',
},
size: {
default: 'h-10 px-4 py-2',
sm: 'h-9 px-3',
lg: 'h-11 px-8',
},
},
defaultVariants: { variant: 'default', size: 'default' },
}
)
// Radix Dialog with asChild composition
import { Dialog } from 'radix-ui'
<Dialog.Root>
<Dialog.Trigger asChild>
<Button>Open</Button>
</Dialog.Trigger>
<Dialog.Portal>
<Dialog.Overlay className="fixed inset-0 bg-black/50" />
<Dialog.Content className="data-[state=open]:animate-in">
<Dialog.Title>Title</Dialog.Title>
<Dialog.Description>Description</Dialog.Description>
<Dialog.Close>Close</Dialog.Close>
</Dialog.Content>
</Dialog.Portal>
</Dialog.Root>
shadcn/ui
Beautifully designed, accessible components built on CVA variants, cn() utility, and OKLCH theming.
| Rule |
File |
Key Pattern |
| Customization |
rules/shadcn-customization.md |
CVA variants, cn() utility, OKLCH theming, component extension |
| Forms |
rules/shadcn-forms.md |
Form field wrappers, react-hook-form integration, validation |
| Data Table |
rules/shadcn-data-table.md |
TanStack Table integration, column definitions, sorting/filtering |
Radix Primitives
Unstyled, accessible React primitives for building high-quality design systems.
| Rule |
File |
Key Pattern |
| Dialog |
rules/radix-dialog.md |
Dialog, AlertDialog, controlled state, animations |
| Composition |
rules/radix-composition.md |
asChild, Slot, nested triggers, polymorphic rendering |
| Styling |
rules/radix-styling.md |
Data attributes, Tailwind arbitrary variants, focus management |
Key Decisions
| Decision |
Recommendation |
| Color format |
OKLCH for perceptually uniform theming |
| Class merging |
Always use cn() for Tailwind conflicts |
| Extending components |
Wrap, don't modify source files |
| Variants |
Use CVA for type-safe multi-axis variants |
| Styling approach |
Data attributes + Tailwind arbitrary variants |
| Composition |
Use asChild to avoid wrapper divs |
| Animation |
CSS-only with data-state selectors |
| Form components |
Combine with react-hook-form |
Anti-Patterns (FORBIDDEN)
- Modifying shadcn source: Wrap and extend instead of editing generated files
- Skipping cn(): Direct string concatenation causes Tailwind class conflicts
- Inline styles over CVA: Use CVA for type-safe, reusable variants
- Wrapper divs: Use
asChild to avoid extra DOM elements
- Missing Dialog.Title: Every dialog must have an accessible title
- Positive tabindex: Using
tabindex > 0 disrupts natural tab order
- Color-only states: Use data attributes + multiple indicators
- Manual focus management: Use Radix built-in focus trapping
Detailed Documentation
| Resource |
Description |
| scripts/ |
Templates: CVA component, extended button, dialog, dropdown |
| checklists/ |
shadcn setup, accessibility audit checklists |
| references/ |
CVA system, OKLCH theming, cn() utility, focus management |
Design System Tokens
Design token architecture for consistent theming and visual identity.
| Rule |
File |
Key Pattern |
| Token Architecture |
rules/design-system-tokens.md |
W3C tokens, OKLCH colors, Tailwind @theme, spacing scales |
Design System Components
Component architecture patterns with atomic design and accessibility.
| Rule |
File |
Key Pattern |
| Component Architecture |
rules/design-system-components.md |
Atomic design, CVA variants, WCAG 2.1 AA, Storybook |
Forms
React Hook Form v7 with Zod validation and React 19 Server Actions.
| Rule |
File |
Key Pattern |
| React Hook Form |
rules/forms-react-hook-form.md |
useForm, field arrays, Controller, wizards, file uploads |
| Zod & Server Actions |
rules/forms-validation-zod.md |
Zod schemas, Server Actions, useActionState, async validation |
Related Skills
accessibility - WCAG compliance and React Aria patternstesting-patterns - Component testing patterns
1---2name: ui-components3description: UI component library patterns for shadcn/ui and Radix Primitives. Use when building accessible component libraries, customizing shadcn components, using Radix unstyled primitives, or creating design system foundations.4license: MIT5---67# UI Components89Comprehensive patterns for building accessible UI component libraries with shadcn/ui and Radix Primitives. Covers CVA variants, OKLCH theming, cn() utility, component extension, asChild composition, dialog/menu patterns, and data-attribute styling. Each category has individual rule files in `rules/` loaded on-demand.1011## Quick Reference1213| Category | Rules | Impact | When to Use |14|----------|-------|--------|-------------|15| [shadcn/ui](#shadcnui) | 3 | HIGH | CVA variants, component customization, form patterns, data tables |16| [Radix Primitives](#radix-primitives) | 3 | HIGH | Dialogs, polymorphic composition, data-attribute styling |17| [Design System Tokens](#design-system-tokens) | 1 | HIGH | W3C tokens, OKLCH theming, Tailwind @theme, spacing scales |18| [Design System Components](#design-system-components) | 1 | HIGH | Atomic design, CVA variants, accessibility, Storybook |19| [Forms](#forms) | 2 | HIGH | React Hook Form v7, Zod validation, Server Actions |2021**Total: 10 rules across 4 categories**2223## Quick Start2425```tsx26// CVA variant system with cn() utility27import { cva, type VariantProps } from 'class-variance-authority'28import { cn } from '@/lib/utils'2930const buttonVariants = cva(31 'inline-flex items-center justify-center rounded-md font-medium transition-colors',32 {33 variants: {34 variant: {35 default: 'bg-primary text-primary-foreground hover:bg-primary/90',36 destructive: 'bg-destructive text-destructive-foreground',37 outline: 'border border-input bg-background hover:bg-accent',38 ghost: 'hover:bg-accent hover:text-accent-foreground',39 },40 size: {41 default: 'h-10 px-4 py-2',42 sm: 'h-9 px-3',43 lg: 'h-11 px-8',44 },45 },46 defaultVariants: { variant: 'default', size: 'default' },47 }48)49```5051```tsx52// Radix Dialog with asChild composition53import { Dialog } from 'radix-ui'5455<Dialog.Root>56 <Dialog.Trigger asChild>57 <Button>Open</Button>58 </Dialog.Trigger>59 <Dialog.Portal>60 <Dialog.Overlay className="fixed inset-0 bg-black/50" />61 <Dialog.Content className="data-[state=open]:animate-in">62 <Dialog.Title>Title</Dialog.Title>63 <Dialog.Description>Description</Dialog.Description>64 <Dialog.Close>Close</Dialog.Close>65 </Dialog.Content>66 </Dialog.Portal>67</Dialog.Root>68```6970## shadcn/ui7172Beautifully designed, accessible components built on CVA variants, cn() utility, and OKLCH theming.7374| Rule | File | Key Pattern |75|------|------|-------------|76| Customization | `rules/shadcn-customization.md` | CVA variants, cn() utility, OKLCH theming, component extension |77| Forms | `rules/shadcn-forms.md` | Form field wrappers, react-hook-form integration, validation |78| Data Table | `rules/shadcn-data-table.md` | TanStack Table integration, column definitions, sorting/filtering |7980## Radix Primitives8182Unstyled, accessible React primitives for building high-quality design systems.8384| Rule | File | Key Pattern |85|------|------|-------------|86| Dialog | `rules/radix-dialog.md` | Dialog, AlertDialog, controlled state, animations |87| Composition | `rules/radix-composition.md` | asChild, Slot, nested triggers, polymorphic rendering |88| Styling | `rules/radix-styling.md` | Data attributes, Tailwind arbitrary variants, focus management |8990## Key Decisions9192| Decision | Recommendation |93|----------|----------------|94| Color format | OKLCH for perceptually uniform theming |95| Class merging | Always use cn() for Tailwind conflicts |96| Extending components | Wrap, don't modify source files |97| Variants | Use CVA for type-safe multi-axis variants |98| Styling approach | Data attributes + Tailwind arbitrary variants |99| Composition | Use `asChild` to avoid wrapper divs |100| Animation | CSS-only with data-state selectors |101| Form components | Combine with react-hook-form |102103## Anti-Patterns (FORBIDDEN)104105- **Modifying shadcn source**: Wrap and extend instead of editing generated files106- **Skipping cn()**: Direct string concatenation causes Tailwind class conflicts107- **Inline styles over CVA**: Use CVA for type-safe, reusable variants108- **Wrapper divs**: Use `asChild` to avoid extra DOM elements109- **Missing Dialog.Title**: Every dialog must have an accessible title110- **Positive tabindex**: Using `tabindex > 0` disrupts natural tab order111- **Color-only states**: Use data attributes + multiple indicators112- **Manual focus management**: Use Radix built-in focus trapping113114## Detailed Documentation115116| Resource | Description |117|----------|-------------|118| [scripts/](scripts/) | Templates: CVA component, extended button, dialog, dropdown |119| [checklists/](checklists/) | shadcn setup, accessibility audit checklists |120| [references/](references/) | CVA system, OKLCH theming, cn() utility, focus management |121122## Design System Tokens123124Design token architecture for consistent theming and visual identity.125126| Rule | File | Key Pattern |127|------|------|-------------|128| Token Architecture | `rules/design-system-tokens.md` | W3C tokens, OKLCH colors, Tailwind @theme, spacing scales |129130## Design System Components131132Component architecture patterns with atomic design and accessibility.133134| Rule | File | Key Pattern |135|------|------|-------------|136| Component Architecture | `rules/design-system-components.md` | Atomic design, CVA variants, WCAG 2.1 AA, Storybook |137138## Forms139140React Hook Form v7 with Zod validation and React 19 Server Actions.141142| Rule | File | Key Pattern |143|------|------|-------------|144| React Hook Form | `rules/forms-react-hook-form.md` | useForm, field arrays, Controller, wizards, file uploads |145| Zod & Server Actions | `rules/forms-validation-zod.md` | Zod schemas, Server Actions, useActionState, async validation |146147## Related Skills148149- `accessibility` - WCAG compliance and React Aria patterns150- `testing-patterns` - Component testing patterns
diegosouzapw