Fancy Components는 React를 기반으로 한 창의적인 애니메이션 컴포넌트와 마이크로 인터랙션을 제공하는 오픈소스 라이브러리입니다. 단순한 UI 요소를 넘어 웹사이트에 생동감을 불어넣는 시각적 경험을 목표로 합니다. 이 가이드는 개발자들이 프로젝트에 참여하여 새로운 컴포넌트를 추가하거나 기존 기능을 개선하는 과정을 상세히 설명합니다.

기술 스택 및 요구 사항

프로젝트에 기여하기 위해서는 다음과 같은 기술 사양을 준수해야 합니다.

• Framework: React 18 (현재 React 19는 지원하지 않음)
• Language: TypeScript
• Styling: Tailwind CSS v4
• Animation: Motion (구 framer-motion의 최신 버전)

개발 환경 구축

로컬 개발 환경을 설정하려면 저장소를 클론하고 의존성을 설치해야 합니다.

# 저장소 복제
git clone https://gitcode.com/gh_mirrors/fan/fancy

# 프로젝트 폴더 이동
cd fancy

# 패키지 설치
npm install

# 컴포넌트 레지스트리 빌드
npm run build:registry

컴포넌트 개발 프로세스

1. 소스 코드 구현

새로운 애니메이션 컴포넌트는 src/fancy/components 내의 적절한 카테고리(예: text, background, blocks) 폴더에 작성합니다.

// src/fancy/components/text/glitch-text.tsx
import { motion } from "motion/react";

interface GlitchProps {
  text: string;
  intensity?: number;
}

export const GlitchText = ({ text, intensity = 5 }: GlitchProps) => {
  return (
    <motion.span
      animate={{ x: [-intensity, intensity, 0] }}
      transition={{ repeat: Infinity, duration: 0.2 }}
    >
      {text}
    </motion.span>
  );
};

2. 컴포넌트 설정 파일 작성

추가 설정이 필요한 경우 컴포넌트와 동일한 이름의 .json 파일을 생성하여 의존성이나 CSS 변수를 정의합니다.

{
  "dependencies": ["motion"],
  "tailwind": {
    "config": {
      "theme": {
        "extend": {
          "colors": {
            "fancy-purple": "#8a2be2"
          }
        }
      }
    }
  }
}

3. 문서 및 예제 추가

사용자가 컴포넌트를 이해할 수 있도록 예제 파일과 MDX 문서를 작성해야 합니다.

• 데모 파일: src/fancy/examples 폴더에 컴포넌트명-demo.tsx 형식으로 작성합니다.
• 문서화: src/content/docs/components 경로에 MDX 파일을 생성하여 사용법, Props 사양, 설치 방법을 기술합니다.
• 네비게이션 등록: src/config/docs.ts 파일의 docsConfig 배열에 새 컴포넌트 경로를 추가합니다.

커밋 및 PR 규정

일관된 프로젝트 관리를 위해 Conventional Commits 규격을 준수해야 합니다.

# 신규 컴포넌트 추가 시
git checkout -b feat/new-animation-effect
git commit -m "feat(text): add glitch-text animation component"

# 버그 수정 시
git commit -m "fix(blocks): resolve z-index issue in stacking-cards"

Pull Request(PR)를 제출할 때는 다음 체크리스트를 확인하십시오.

• 코드 스타일 및 타입 체크 통과 여부
• 컴포넌트 작동 화면(GIF 또는 비디오) 첨부
• 접근성(Accessibility) 고려 여부 (aria-label, sr-only 등 활용)

품질 관리 기준

Fancy Components에 병합되는 모든 코드는 아래 기준을 충족해야 합니다.

• 독창성: 기존 라이브러리의 단순 복제가 아닌, 고유한 시각적 효과나 인터랙션을 포함해야 합니다.
• 성능 최적화: 불필요한 리렌더링을 방지하고 Motion 라이브러리의 최적화 기법을 활용합니다.
• 완결성: 명확한 Props 정의와 함께 다양한 시나리오에서의 데모가 포함되어야 합니다.