UI Components Skill | Agent Skills

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

Agent Skills: UI Components

Install this agent skill to your local

Skill Files