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

• ork:accessibility - WCAG compliance and React Aria patterns
• ork:testing-patterns - Component testing patterns