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 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: 21 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

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

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 patterns

• ork:testing-unit

• Component testing patterns