shadcn 컴포넌트 시각적 어댑터

# shadcn 컴포넌트 시각적 어댑터 ## 목표 `${component_file_path}`에 위치한 기존 `${component_name}` 컴포넌트를 다음 위치에서 확인 가능한 참조 컴포넌트의 시각적 디자인, 구조, 동작에 맞게 리팩터링합니다: > ${install_command:bunx --bun shadcn@latest add accordion} ${reference_url:} ← 선택 사항; 문서 페이지가 없으면 비워 둠 비즈니스 로직, 기존 props 인터페이스, 데이터 페칭 패턴은 교체하지 마십시오. 이를 유지하십시오. 시각적 레이어(마크업 구조, 클래스 이름, 애니메이션, 접근성 속성)만 적용하십시오. ## 1단계 - 기존 컴포넌트 분석 코드를 작성하기 전에: 1. `${component_file_path}`의 전체 소스를 읽습니다. 2. 다음을 매핑합니다: - 모든 props 및 해당 유형(TypeScript 인터페이스 또는 PropTypes) - 내부 상태 변수(`useState`, `useReducer`, Zustand 슬라이스 등) - 사용된 Context 제공자 또는 커스텀 훅 - 렌더링된 하위 컴포넌트 및 해당 위치 - 부모에 노출된 이벤트 핸들러 및 콜백 3. 모든 import를 나열하고 shadcn 프리미티브와 충돌하거나 대체 가능한 항목을 표시합니다. 코드를 건드리기 전에 간단한 감사 테이블을 출력합니다: | 항목 | 현재 값 | 작업 | |------|--------------|--------| | Props | ... | 유지 / 이름 변경 / 제거 | | 상태 | ... | 유지 / 마이그레이션 | | Context/훅 | ... | 유지 / 교체 | | 하위 컴포넌트 | ... | 유지 / 교체 | | 의존성 | ... | 유지 / 설치 / 제거 | ## 2단계 - 의존성 해결 설치 명령을 직접 실행합니다: ${install_command} 명령이 완료되면 생성된 파일이 ${components_dir:components/ui}/에 나타납니다. 해당 파일을 사용하여 3단계를 진행합니다. ## 3단계 - 참조 컴포넌트 검토 ${reference_url}이 제공된 경우 → 이전과 같이 가져와서 시각적 사양을 추출합니다. ${reference_url}이 비어 있는 경우 → 2단계에서 CLI 명령으로 다운로드한 파일을 읽고 소스 코드에서 직접 동일한 정보를 추출합니다: - cva 변형 스키마 - data-state / data-disabled 속성 - 애니메이션/전환 클래스 - ARIA 역할 및 props - cn() 사용 패턴 ## 4단계 - 컴포넌트 리팩터링 1단계의 기존 컴포넌트에 3단계의 시각적 구조를 적용합니다. ### 규칙: - ✅ 직접적인 shadcn 대응이 없는 한 모든 기존 prop 이름과 유형을 유지합니다. - ✅ 모든 데이터 페칭, 비즈니스 로직, 콜백을 유지합니다. - ✅ Radix 프리미티브를 `forwardRef`로 래핑하고 `...props`를 펼쳐 유연성을 보존합니다. - ✅ 모든 className 병합에 `cn()`을 사용합니다 - 문자열 연결은 절대 사용하지 않습니다. - ✅ 참조 컴포넌트가 복합 하위 컴포넌트를 사용하는 경우 명명된 복합 하위 컴포넌트를 내보냅니다(예: `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`). - ❌ 생성된 shadcn 파일을 import하여 재-export하지 마십시오 - 로직을 함께 유지하기 위해 리팩터링된 파일에 프리미티브를 인라인으로 구축합니다. - ❌ 명시적 지시 없이 참조 컴포넌트에 없는 Tailwind 클래스를 추가하지 마십시오. ### 반응형 동작 (`${responsive_breakpoints:sm md lg}`): 모바일 우선 반응형 클래스를 적용합니다. `tailwind.config.ts`의 현재 중단점이 프로젝트 규칙과 일치하는지 확인합니다. 참조가 컨테이너 쿼리를 사용하는 경우 `@tailwindcss/container-queries`를 설치합니다. ## 5단계 - Context 제공자 및 훅 참조 컴포넌트에 Context 제공자(예: `ToastProvider`, `TooltipProvider`)가 필요한 경우: 1. `${provider_file:app/layout.tsx}` 또는 `${provider_file:app/providers.tsx}`에 이미 마운트되어 있는지 확인합니다. 2. 그렇지 않은 경우 적절한 레이아웃 파일에 추가합니다. 정확한 diff를 제공합니다. 3. 커스텀 훅이 필요한 경우(예: `useToast`, `useDialog`), `${hooks_dir:hooks/}`에 배치하고そこ에서 import합니다. ## 6단계 - 명확화 질문 (알 수 없는 경우 생성 전에 질문) 다음 중 기존 코드에서 결정할 수 없는 것이 있으면 작성 전에 질문합니다: 1. **데이터/props**: 전달될 데이터의 형태는 무엇입니까? (도움이 된다면 샘플 객체를 제공하십시오.) 2. **상태 관리**: 컴포넌트 상태는 로컬입니까, 아니면 외부에서 관리됩니까 (Zustand, Redux, React Query)? 3. **에셋**: lucide-react로 처리되지 않는 필수 이미지, 로고 또는 커스텀 아이콘이 있습니까? 4. **반응형**: `${responsive_breakpoints:sm md lg}` 중단점에서 예상 레이아웃은 무엇입니까? 5. **배치**: 이 컴포넌트는 앱 라우팅/레이아웃 트리의 어디에 위치합니까? (Context 제공자 배치에 중요합니다.) ## 7단계 - 출력 형식 결과를 다음으로 제공합니다: 1. **`${component_file_path}`** - 전체 리팩터링된 컴포넌트 파일. 2. **`${components_dir:components/ui}/${shadcn_component_slug}.tsx`** - shadcn 프리미티브 (필요하고 CLI에서 생성되지 않은 경우에만). 3. **`lib/utils.ts`** - 생성 또는 업데이트가 필요한 경우에만. 4. **레이아웃/제공자 diff** - 제공자를 추가해야 하는 경우에만. 5. 간단한 **마이그레이션 노트** 섹션: - 제거된 의존성 - 이름이 변경된 props (있는 경우) - 수동 단계 (예: `globals.css`에 CSS 변수 추가) ## Tailwind CSS 변수 (shadcn 디자인 토큰) `globals.css`에 필요한 CSS 커스텀 속성이 포함되어 있는지 확인합니다. 참조 컴포넌트가 `--radius`, `--background`, `--foreground`, `--primary`, `--ring`과 같은 토큰을 사용하는 경우 누락된 변수를 추가합니다. 프로젝트가 이미 커스텀 테마를 정의하지 않는 한 `${color_theme:zinc}`에 대한 shadcn 기본 토큰 세트를 사용합니다. ## 제약 조건 - 프레임워크: **${framework:Next.js 14+ App Router}** - 스타일링: **Tailwind CSS ${tailwind_version:3}**만 사용 - 인라인 스타일, CSS 모듈, styled-components 금지. - TypeScript: **strict 모드**. 모든 새 코드는 완전히 타입이 지정되어야 합니다. - 직접적인 피어 충돌이 없는 한 기존 의존성 버전을 업그레이드하거나 다운그레이드하지 마십시오.