📝 Almond UI Library 협업 규칙 (v3)

1. 멤버십/일반 할인 데이터 구조

• 멤버십 할인 관련 필드는 반드시 membership 접두사를 붙입니다.
  • 예: membershipDiscountPrice, membershipDiscountRate, isMembershipDiscount
• 할인율은 number 타입으로 소수점 없이 표현하며, 퍼센트 기호는 UI에서 포맷합니다.
• 일반 할인 컬럼이 있을 경우, discountPrice, discountRate 등 구분해서 명시합니다.
• UI 컴포넌트는 숫자 데이터로 받아 포맷을 직접 처리해야 하며, 파싱된 문자열은 사용하지 않습니다.

2. Next.js 및 React SPA 호환 렌더링 전략

2-1. 이미지: ImageWrapper 사용

• Next.js 환경에서는 자동으로 next/image를 사용하고, 일반 React(CRA 등) 환경에서는 <img>로 fallback 됩니다.
• 사이즈, object-fit 등 레이아웃 스타일은 내부에서 통일되며, 외부에서는 src, alt 정도만 지정하면 됩니다.

<ImageWrapper
  src="/images/thumb.jpg"
  alt="썸네일"
  fill
  sizes="65px"
  className="object-cover"
/>

3. 공통 컴포넌트 설계 원칙 (WishCard, OrderCard 등)

• 링크는 반드시 productLink로 문자열 href만 전달합니다.
• 이미지는 반드시 imageSrc, imageAlt로 전달합니다.
• 내부에서는 ImageWrapper, LinkWrapper를 사용해 프레임워크 환경에 맞게 자동 대응합니다.

<WishCard
  productName="고속도로 꼬깔콘"
  originalPrice={37860}
  productLink="/product/123"
  imageSrc="/images/thumb.png"
  imageAlt="꼬깔콘 썸네일"
  onAddToCart={() => alert("장바구니 담기")}
  onDelete={() => alert("삭제")}
/>

4. 컴포넌트 스타일 규칙

• 컨테이너 컴포넌트는 padding, border 등 레이아웃을 책임집니다.
• 내부 요소는 spacing(gap, margin 등)을 적절히 관리합니다.
• 스타일은 내부 Tailwind CSS 기준으로 통일되며, 외부에서 className 덮어쓰는 방식은 지양합니다.
• 불필요한 중첩 DOM, 중복 스타일 선언은 피하고, 레이아웃 책임을 명확히 분리합니다.

5. 향후 확장 예정 규칙 항목

• ✅ 접근성(A11y): ARIA 속성, 키보드 포커스, role 대응 방식 정의 예정
• ✅ 다국어(i18n): 텍스트 전달 방식 및 언어 리소스 처리 규칙 추가 예정
• ✅ variant 기반 UI 분기: variant="sold-out" 등 UI 표현 제어 방식 도입 예정
• ✅ 디자인 토큰 적용 방식: Tailwind 커스텀 테마 적용 규칙 도입 예정

이 문서는 Almond UI 컴포넌트 라이브러리의 재사용성과 유지보수성을 높이기 위한 공식 규칙입니다.