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).

Detailed Documentation

Design System

Design token architecture, spacing, typography, and interactive component states.

Design System Components

Component architecture patterns with atomic design and accessibility.

Forms

React Hook Form v7 with Zod validation and React 19 Server Actions.

Modern CSS & Tooling

Modern CSS patterns, Tailwind v4, and component documentation tooling for 2026.

UX Foundations

Cognitive-science-grounded UI/UX principles with specific numeric thresholds for production-quality interfaces.

Related Skills

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