UI Components

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). Each remaining category has individual rule files in rules/ loaded on-demand.

Quick Reference

Total: 15 rules across 6 categories. Radix primitive mechanics and shadcn customization tutorials are first-party documented; see Upstream coverage (do not restate) and 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.

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

v4 Style System

shadcn CLI v4 ships 6 visual styles. Each rewrites component class names — not just CSS variables.

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

Detection: Read components.json → "style" field (e.g., "radix-luma", "base-nova"). Old "new-york" and "default" styles are superseded by Vega.

Key Decisions

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

Upstream coverage (do not restate)

These topics were removed from this skill on 2026-07-31 because a first-party source owns them. Point sessions at the source; keep only floors, scars, and house decisions here (they live in references/ork-delta.md).