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 | 4 | HIGH | CVA variants, component customization, form patterns, data tables, v4 styles |
| Radix Primitives | 3 | HIGH | Dialogs, polymorphic composition, data-attribute styling |
| Design System | 5 | HIGH | W3C tokens, OKLCH theming, spacing scales, typography, component states, animation |
| Design System Components | 1 | HIGH | Atomic design, CVA variants, accessibility, Storybook |
| Forms | 2 | HIGH | React Hook Form v7, Zod validation, Server Actions |
| Modern CSS & Tooling | 3 | HIGH | CSS cascade layers, Tailwind v4, Storybook CSF3 |
| UX Foundations | 4 | HIGH | Visual hierarchy, typography thresholds, color system, empty states |
Total: 22 rules across 7 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 |
| v4 Styles | rules/shadcn-v4-styles.md | 6 styles (Vega→Luma), preset codes, style detection, class mapping |
v4 Style System
shadcn CLI v4 ships 6 visual styles. Each rewrites component class names — not just CSS variables.
| Style | Character | Best For |
|---|---|---|
| Vega | Balanced radius, clean lines | General purpose (successor to New York) |
| Nova | Compact padding, reduced margins | Dense dashboards, admin panels |
| Maia | Soft, rounded, generous spacing | Consumer-facing, friendly apps |
| Lyra | Sharp, zero radius, monospace pairs | Editorial, developer tools |
| Mira | Ultra-compact, minimal chrome | Spreadsheets, data-heavy interfaces |
| Luma | Extreme rounding (rounded-4xl), soft elevation (shadow-md + ring), breathable layouts | Polished native-app feel, macOS Tahoe-inspired |
Configure visually at ui.shadcn.com/create → pick style, theme, fonts, icons, then copy the generated command. Do not hardcode preset codes in docs — they're tied to a specific style snapshot and can drift.
shadcn CLI v4 (Apr 2026) — new commands
| Command | Purpose |
|---|---|
npx shadcn@latest apply <style> | Apply a published style (e.g. luma, nova, lyra) to the current project — re-skins existing components without re-adding them |
npx shadcn@latest info | Show resolved config: registry, style, tokens, components present, Tailwind version |
npx shadcn@latest skills | List the shadcn/skills registry — Claude Code- and Cursor-ready skill packs that bundle CLI commands with agent guidance |
npx shadcn@latest build | Build a custom registry (already-documented) — pair with apply to ship a private style |
Detection: Read components.json → "style" field (e.g., "radix-luma", "base-nova"). Old "new-york" and "default" styles are superseded by Vega.
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
asChildto avoid extra DOM elements - Missing Dialog.Title: Every dialog must have an accessible title
- Positive tabindex: Using
tabindex > 0disrupts 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
Design token architecture, spacing, typography, and interactive component states.
| Rule | File | Key Pattern |
|---|---|---|
| Token Architecture | rules/design-system-tokens.md | W3C tokens, OKLCH colors, Tailwind @theme |
| Spacing Scale | rules/design-system-spacing.md | 8px grid, Tailwind space-1 to space-12 |
| Typography Scale | rules/design-system-typography.md | Font sizes, weights, line heights |
| Component States | rules/design-system-states.md | Hover, focus, active, disabled, loading, animation presets |
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 |
Modern CSS & Tooling
Modern CSS patterns, Tailwind v4, and component documentation tooling for 2026.
| Rule | File | Key Pattern |
|---|---|---|
| CSS Cascade Layers | rules/css-cascade-layers.md | @layer ordering, specificity-free overrides, third-party isolation |
| Tailwind v4 | rules/tailwind-v4-patterns.md | CSS-first @theme, native container queries, @max-* variants |
| Storybook Docs | rules/storybook-component-docs.md | CSF3 stories, play() interaction tests, Chromatic visual regression |
UX Foundations
Cognitive-science-grounded UI/UX principles with specific numeric thresholds for production-quality interfaces.
| Rule | File | Key Pattern |
|---|---|---|
| Visual Hierarchy | rules/visual-hierarchy.md | Button tiers, de-emphasis, F/Z scan, Von Restorff, proximity, max-width |
| Typography Thresholds | rules/typography-thresholds.md | 65ch line length, 1.4–1.6 line height, rem units, modular type scale |
| Color System | rules/color-system.md | OKLCH 9-shade scales, semantic categories, no true black, brand-tinted neutrals |
| Empty States | rules/empty-states.md | Skeleton-first, icon + headline + description + CTA, cause-specific tone |
Related Skills
ork:accessibility- WCAG compliance and React Aria patternsork:testing-unit- Component testing patterns