ui-components

$27

// 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

v4 Styles

rules/shadcn-v4-styles.md

6 styles (Vega→Luma), preset codes, style detection, class mapping

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

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