/ui-components

name: ui-components
license: MIT
compatibility: "Claude Code 2.1.277+."
description: 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.
user-invocable: false
disable-model-invocation: true
metadata:
  owner-agent: "frontend-ui-developer"
  category: document-asset-creation
  version: "2.1.0"
  author: "OrchestKit"
  complexity: "medium"
  tags: "ui-components, shadcn, radix, component-library, design-system, accessible-components, react-hook-form, zod, forms, validation, server-actions, field-arrays"
allowed-tools: "Read Glob Grep WebFetch WebSearch"

UI Components

Patterns for building accessible UI component libraries with shadcn/ui and Radix Primitives, as a thin wrap over the first-party docs: quick-start recipes, key decisions, anti-patterns, and the house delta. Vendor mechanics (CVA variants, cn() utility, component extension, asChild composition, dialog/menu patterns, data-attribute styling) are upstream's job; see [Upstream coverage (do not restate)](#upstream-coverage-do-not-restate). Each remaining category has individual rule files in `rules/` loaded on-demand.

Quick Reference

| Category | Rules | Impact | When to Use | |----------|-------|--------|-------------| | [shadcn/ui](#shadcnui) | 1 | HIGH | v4 styles, preset codes, style detection | | [Design System](#design-system) | 4 | HIGH | W3C tokens, OKLCH theming, spacing scales, typography, component states, animation | | [Design System Components](#design-system-components) | 1 | HIGH | Atomic design, CVA variants, accessibility, Storybook | | [Forms](#forms) | 2 | HIGH | React Hook Form v7, Zod validation, Server Actions | | [Modern CSS & Tooling](#modern-css--tooling) | 3 | HIGH | CSS cascade layers, Tailwind v4, Storybook CSF3 | | [UX Foundations](#ux-foundations) | 4 | HIGH | Visual hierarchy, typography thresholds, color system, empty states |

**Total: 15 rules across 6 categories.** Radix primitive mechanics and shadcn customization tutorials are first-party documented; see [Upstream coverage (do not restate)](#upstream-coverage-do-not-restate) and [references/ork-delta.md](references/ork-delta.md) for what stays ours.

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 | |------|------|-------------| | v4 Styles | `rules/shadcn-v4-styles.md` | 6 styles (Vega→Luma), preset codes, style detection, class mapping |

Customization, form, and data-table walkthroughs are upstream's job now; see [Upstream coverage (do not restate)](#upstream-coverage-do-not-restate). Our conventions on top of them live in [references/ork-delta.md](references/ork-delta.md).

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](https://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.

Key Decisions

| Decision | Recommendation | |