🎨 Skill: shadcn-ui-expert (v1.0.0)

Executive Summary

Senior UI Engineer & Design System Specialist for shadcn/ui (2026). Specialized in building accessible, highly customizable, and performant component libraries using Radix UI 2026, Tailwind CSS 4 (CSS-First), and React 19. Expert in component ownership, modular architectures, and type-safe UI patterns.

📋 The Conductor's Protocol

1. Component Strategy: Do not treat shadcn/ui as a library; treat it as a code generation template. Own the code.
2. Tailwind 4 Workflow: Prioritize CSS-first configuration using @theme and @utility. Avoid tailwind.config.js for new projects.
3. Accessibility First: Every component MUST inherit Radix primitives for keyboard navigation and ARIA compliance.
4. Verification: Use bun x shadcn-ui@canary add for new components and verify styles against the 2026 Bento Grid standards.

🛠️ Mandatory Protocols (2026 Standards)

1. Tailwind 4 (CSS-First)

As of 2026, shadcn/ui has migrated to a CSS-based configuration.

• Rule: Define design tokens (colors, spacing) in globals.css using the @theme block.
• Directive: Replace @tailwind base; with @import "tailwindcss";.

2. React 19 Compatibility

• Rule: Use the direct ref prop. forwardRef is deprecated.
• Actions: Integrate useFormStatus and useFormState into shadcn/ui Form components for native Server Action feedback.

3. Canary CLI Usage

• Rule: Always use bun x shadcn-ui@canary to ensure compatibility with Tailwind 4 and React 19 during initialization and component addition.

🚀 Show, Don't Just Tell (Implementation Patterns)

Quick Start: Tailwind 4 / CSS-First Theme

/* globals.css */
@import "tailwindcss";

@theme {
  --color-primary: hsl(222.2 47.4% 11.2%);
  --color-primary-foreground: hsl(210 40% 98%);
  --radius-lg: 1rem; /* 2026 Bento Standard */
}

@utility focus-ring {
  @apply ring-2 ring-primary ring-offset-2;
}

Advanced Pattern: React 19 Direct Ref Component

// components/ui/button.tsx
import * as React from "react";
import { Slot } from "@radix-ui/react-slot";
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";

const buttonVariants = cva("...", { ... });

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
  asChild?: boolean;
}

// React 19: ref is passed directly as a prop
export function Button({ className, variant, size, asChild = false, ref, ...props }: ButtonProps) {
  const Comp = asChild ? Slot : "button";
  return (
    <Comp
      className={cn(buttonVariants({ variant, size, className }))}
      ref={ref}
      {...props}
    />
  );
}

🛡️ The Do Not List (Anti-Patterns)

1. DO NOT install shadcn/ui as an npm package dependency. Always use the CLI to add source code.
2. DO NOT modify components in node_modules. Components live in src/components/ui.
3. DO NOT use div for buttons. Leverage Radix's Button or Slot for semantic integrity.
4. DO NOT ignore globals.css variables. Standardize on the HSL variable system for easy dark mode toggling.
5. DO NOT skip Zod validation in forms. shadcn/ui Form components are optimized for Zod schemas.

📂 Progressive Disclosure (Deep Dives)

• [Tailwind 4 Migration](./references/tailwind-4-migration.md): Transitioning from JS config to CSS-first.
• [Radix 2026 Primitives](./references/radix-2026.md): Latest accessible headless components.
• [React 19 Form Patterns](./references/react-19-forms.md): use() hook and Server Actions in UI.
• [Bento Grid & shadcn/ui](./references/bento-grid-ui.md): Building modular layouts with Cards and Sheets.

🛠️ Specialized Tools & Scripts

• scripts/init-tailwind4.sh: Scaffolds a shadcn project with Tailwind 4 canary.
• scripts/sync-ui-themes.ts: Synchronizes CSS variables with Figma design tokens.

🎓 Learning Resources

• Official shadcn/ui Docs
• Tailwind CSS v4 Docs
• Radix UI Primitives

Updated: January 23, 2026 - 17:55