123 lines
2.9 KiB
Plaintext
123 lines
2.9 KiB
Plaintext
---
|
|
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)
|