---
description:
globs:
alwaysApply: false
---
# Tailwind CSS v4 + Shadcn UI 호환성 규칙

## **CSS 설정 (src/index.css)**

- **@theme 레이어 사용**
  ```css
  @theme {
    --radius: 0.5rem;
  }
  ```

- **CSS 변수 정의**
  - `:root`에 라이트 모드 색상 변수 정의
  - `.dark`에 다크 모드 색상 변수 정의
  - `hsl(var(--foreground))` 형태로 색상 사용

## **cn 함수 (src/lib/utils.ts)**

- **에러 핸들링 필수**
  ```typescript
  // ✅ DO: fallback 로직 포함
  export function cn(...inputs: ClassValue[]) {
    try {
      return twMerge(clsx(inputs));
    } catch (error) {
      console.warn("tailwind-merge fallback:", error);
      return clsx(inputs);
    }
  }
  
  // ❌ DON'T: 에러 핸들링 없이 사용
  export function cn(...inputs: ClassValue[]) {
    return twMerge(clsx(inputs));
  }
  ```

## **컴포넌트 스타일링**

- **CSS 변수 활용**
  ```typescript
  // ✅ DO: CSS 변수 기반 스타일링
  className="bg-background text-foreground border-border"
  
  // ✅ DO: cn 함수로 조건부 스타일링
  className={cn(
    "base-styles",
    condition && "conditional-styles"
  )}
  ```

- **색상 시스템 준수**
  - `background`, `foreground`, `primary`, `secondary` 등 정의된 변수 사용
  - 직접 색상 값 대신 변수 사용

## **패키지 관리**

- **필수 패키지**
  ```json
  {
    "@tailwindcss/cli": "^4.1.10",
    "@tailwindcss/vite": "^4.1.10",
    "tailwind-merge": "latest",
    "clsx": "^2.1.1",
    "class-variance-authority": "^0.7.1"
  }
  ```

- **제거해야 할 파일**
  - `tailwind.config.js` (v4는 CSS-first 방식)
  - `postcss.config.js` (v4는 PostCSS 불필요)

## **Vite 설정**

- **플러그인 설정**
  ```typescript
  // vite.config.ts
  import tailwindcss from "@tailwindcss/vite";
  
  export default defineConfig({
    plugins: [react(), tailwindcss()],
  });
  ```

## **문제 해결**

- **tailwind-merge 오류 시**
  - 최신 버전으로 업데이트
  - cn 함수에 fallback 로직 구현

- **스타일이 적용되지 않을 때**
  - CSS 변수가 올바르게 정의되었는지 확인
  - @theme 레이어가 포함되었는지 확인

- **빌드 오류 시**
  - node_modules 캐시 삭제 후 재설치
  - package-lock.json 삭제 후 재설치

## **모범 사례**

- **컴포넌트 개발 시**
  - 항상 CSS 변수 사용
  - cn 함수로 클래스 조합
  - 조건부 스타일링에 적절한 패턴 적용

- **테마 관리**
  - 라이트/다크 모드 변수 동시 정의
  - 일관된 색상 시스템 유지

- **성능 최적화**
  - 불필요한 클래스 중복 방지
  - cn 함수 사용으로 클래스 충돌 해결

## **참고 자료**

- [Tailwind CSS v4 공식 문서](https://tailwindcss.com/docs/v4-beta)
- [Shadcn UI + Tailwind v4 가이드](https://www.luisball.com/blog/shadcn-ui-with-tailwind-v4)
- [Shadcn UI 공식 설치 가이드](https://ui.shadcn.com/docs/installation/manual)