shadcn/ui — Framework Patterns

Framework-specific conventions for shadcn/ui. For general shadcn/ui usage (component APIs, installation), use the CLI: npx shadcn@latest add <component>.

Scope: This skill covers framework conventions that differ from stock shadcn/ui. For design intelligence, see ui-ux-pro-max. For layout patterns, see standards/reference/layout-patterns.md. For theme details, see standards/reference/themes.md.

Critical: Shadcnblocks Premium First

Policy: Check Premium Blocks before building ANY custom UI.

We own Shadcnblocks Premium (lifetime). Before designing a new component or page:

1. Browse https://www.shadcnblocks.com/blocks
2. Filter by group: Marketing (878), App (190), Ecommerce (122), Portfolio (111), Background (50)
3. If match found, use as-is or with minimal config changes (colors, copy, icons)
4. If no match, document the gap and get human approval before building custom

See standards/reference/premium-blocks.md for full policy, gap documentation template, and approved exceptions.

Unified Radix UI Imports

The framework uses the unified radix-ui package, NOT scoped @radix-ui/react-* packages.

// CORRECT — unified package
import { Slot } from "radix-ui"
import { Dialog as DialogPrimitive } from "radix-ui"
import { Tooltip as TooltipPrimitive } from "radix-ui"

// WRONG — scoped packages (legacy)
import { Slot } from "@radix-ui/react-slot"
import * as DialogPrimitive from "@radix-ui/react-dialog"

When the shadcn CLI generates a component, it may use scoped imports. Always convert to unified imports after installation.

Import Patterns by Component

Component	Import
Button (Slot)	import { Slot } from "radix-ui"
Dialog	import { Dialog as DialogPrimitive } from "radix-ui"
Sheet	import { Dialog as SheetPrimitive } from "radix-ui"
AlertDialog	import { AlertDialog as AlertDialogPrimitive } from "radix-ui"
Select	import { Select as SelectPrimitive } from "radix-ui"
DropdownMenu	import { DropdownMenu as DropdownMenuPrimitive } from "radix-ui"
Tooltip	import { Tooltip as TooltipPrimitive } from "radix-ui"
Label	import { Label as LabelPrimitive } from "radix-ui"
Separator	import { Separator as SeparatorPrimitive } from "radix-ui"
Progress	import { Progress as ProgressPrimitive } from "radix-ui"
RadioGroup	import { RadioGroup as RadioGroupPrimitive } from "radix-ui"
ScrollArea	import { ScrollArea as ScrollAreaPrimitive } from "radix-ui"
Switch	import { Switch as SwitchPrimitive } from "radix-ui"
Tabs	import { Tabs as TabsPrimitive } from "radix-ui"
Toggle	import { Toggle as TogglePrimitive } from "radix-ui"
Collapsible	import { Collapsible as CollapsiblePrimitive } from "radix-ui"
Popover	import { Popover as PopoverPrimitive } from "radix-ui"
Command	Uses cmdk directly, not Radix
Sonner	Uses sonner directly, not Radix

Tailwind v4 Theme Configuration

The framework uses Tailwind CSS v4 with CSS-based configuration (not tailwind.config.js/.ts).

Reference: Read references/tailwind-v4-config.md for the full CSS theme block, v3-to-v4 migration table, oklch color format details, components.json config, and the cn() utility function.

43-Theme System

The framework includes 43 color themes from tweakcn, synced via tools/scripts/sync-tweakcn-themes.ts. Themes are defined as CSS variable sets. See standards/reference/themes.md for the full theme catalog and switching guide.

Reference: Read references/component-inventory.md for the full list of 31 installed components and the add-component checklist.

Reference: Read references/form-patterns.md for React Hook Form + Zod form patterns, Sonner toast usage, and Server Component integration.

Common Pitfalls

Pitfall	Fix
Using scoped @radix-ui/react-* imports	Use unified radix-ui package
tailwind.config.ts for theme config	Use @theme blocks in CSS (v4)
hsl() color values	Use oklch() format
Building custom UI before checking Premium	Check Shadcnblocks first
Raw sonner import for toasts	Use shadcn sonner component
tailwindcss-animate plugin	Use tw-animate-css import
@tailwind base/components/utilities	Use @import "tailwindcss"
Missing "use client" on interactive pages	Add directive where event handlers/hooks are used

References

• Component APIs: npx shadcn@latest add --help or https://ui.shadcn.com
• Theme catalog: standards/reference/themes.md
• Component inventory: standards/reference/component-maintenance.md
• Premium blocks: standards/reference/premium-blocks.md
• Layout patterns: standards/reference/layout-patterns.md