---
description: 
globs: 
alwaysApply: false
---
---
description: "Comprehensive shadcn/ui component guidelines with Tailwind CSS v4 best practices. Enforces modern CSS-first configuration, dynamic utilities, proper component usage, and v4-specific patterns while avoiding deprecated v3 syntax."
globs: "*.tsx,*.jsx,components/**/*.ts,components/**/*.tsx,src/components/**/*.tsx,app/**/*.tsx,pages/**/*.tsx"
alwaysApply: false
---

# Shadcn UI Components with Tailwind CSS v4

This project uses @shadcn/ui for UI components. These are beautifully designed, accessible components that you can copy and paste into your apps.

## Tailwind CSS v4 Principles

**IMPORTANT**: This project uses Tailwind CSS v4, NOT v3. Follow these modern principles:

### CSS-First Configuration
- Use `@import "tailwindcss"` instead of `@tailwind` directives
- Configure themes using `@theme` blocks in CSS, not `tailwind.config.js`
- Leverage CSS variables and modern CSS features

### Modern CSS Features
- Utilize OKLCH color space for more vivid colors
- Use `color-mix()` for opacity adjustments (e.g., `bg-blue-500/50`)
- Take advantage of cascade layers and logical properties
- Use modern selectors and CSS functions

### Dynamic Utilities
- Use dynamic values without configuration (e.g., `grid-cols-15`, `w-17`)
- Leverage data attributes directly (e.g., `data-current:opacity-100`)
- Use container queries with `@container` and `@sm:`, `@lg:` prefixes

### Avoid v3 Patterns
- Don't use deprecated utilities like `bg-opacity-*` (use `bg-blue-500/50` instead)
- Don't rely on `tailwind.config.js` for basic customization
- Avoid the old `@tailwind base;` `@tailwind components;` `@tailwind utilities;` directives

## Finding and Using Components

Components are available in the `src/components/ui` directory, following the aliases configured in `components.json`

## Using Components

Import components from the ui directory using the configured aliases:

```tsx
import { Button } from "@/components/ui/button"
import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"
import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "@/components/ui/card"
```

Example usage with Tailwind v4 features:

```tsx
<Button variant="outline" className="bg-blue-500/50 hover:bg-blue-600/60">
  Click me
</Button>

<Card className="shadow-lg text-shadow-sm">
  <CardHeader>
    <CardTitle className="text-xl @container-normal:text-2xl">Card Title</CardTitle>
    <CardDescription className="text-gray-600/80">Card Description</CardDescription>
  </CardHeader>
  <CardContent className="space-y-4">
    <p className="wrap-break-word">Card Content with proper text wrapping</p>
  </CardContent>
  <CardFooter className="border-t border-gray-200/50">
    <p className="text-sm opacity-75">Card Footer</p>
  </CardFooter>
</Card>
```

## Tailwind v4 Styling Best Practices

### Color Usage
- Use opacity modifiers: `text-blue-500/75` instead of `text-opacity-75`
- Leverage OKLCH colors for better vibrancy
- Use `color-mix()` through opacity modifiers

### Container Queries
```tsx
<div className="@container">
  <div className="grid grid-cols-1 @sm:grid-cols-2 @lg:grid-cols-3">
    {/* Responsive based on container size, not viewport */}
  </div>
</div>
```

### Dynamic Values
```tsx
// These work without configuration in v4
<div className="grid grid-cols-15 gap-7 w-23">
  {/* Dynamic grid columns and spacing */}
</div>
```

### Text Shadows (New in v4.1)
```tsx
<h1 className="text-3xl font-bold text-shadow-lg text-shadow-gray-800/30">
  Beautiful heading with shadow
</h1>
```

### Modern Variants
```tsx
// Input device detection
<button className="p-2 pointer-coarse:p-4 hover:bg-blue-100">
  Touch-friendly button
</button>

// Data attributes
<div data-state="active" className="opacity-50 data-[state=active]:opacity-100">
  State-driven styling
</div>
```

## Installing Additional Components

Many more components are available but not currently installed. You can view the complete list at https://ui.shadcn.com/

**IMPORTANT**: Before installing new components, always check the `~/components/ui/` folder first to see if the component already exists. This prevents duplicating components or accidentally overwriting existing customizations.

To install additional components, use the Shadcn CLI:

```bash
# First, check if the component already exists
ls ~/components/ui/

# Then install if needed
npx shadcn@latest add [component-name]
```

For example, to add the Accordion component:

```bash
# Check if accordion.tsx already exists
ls ~/components/ui/accordion.tsx

# If it doesn't exist, then install
npx shadcn@latest add accordion
```

Note: `npx shadcn-ui@latest` is deprecated, use `npx shadcn@latest` instead

Some commonly used components are:
- Accordion
- Alert
- AlertDialog
- AspectRatio
- Avatar
- Calendar  
- Checkbox
- Collapsible
- Command
- ContextMenu
- DataTable
- DatePicker
- Dropdown Menu
- Form
- Hover Card
- Menubar
- Navigation Menu
- Popover
- Progress
- Radio Group
- ScrollArea
- Select
- Separator
- Sheet
- Skeleton
- Slider
- Switch
- Table
- Textarea
- Toast
- Toggle
- Tooltip

## Component Styling

This project uses the "new-york" style variant with the "neutral" base color and CSS variables for theming, as configured in `components.json`.

## Custom Theme Configuration

If you need to customize the theme, use the CSS-first approach in your main CSS file:

```css
@import "tailwindcss";

@theme {
  --font-sans: "Inter", "system-ui", "sans-serif";
  --color-primary-50: oklch(0.98 0.01 264.052);
  --color-primary-500: oklch(0.50 0.15 264.052);
  --color-primary-900: oklch(0.20 0.08 264.052);
  --radius-md: 0.5rem;
  --shadow-brand: 0 4px 6px -1px color-mix(in oklab, var(--color-primary-500) 25%, transparent);
}
```

## Browser Compatibility

Tailwind CSS v4 requires modern browsers:
- Safari 16.4+
- Chrome 111+ 
- Firefox 128+

If you need to support older browsers, consider staying with Tailwind v3 until your browser support requirements change.