Storefront Best Practices

• 이커머스 스토어프론트 구축 또는 확장 — 모든 프레임워크(Next.js, SvelteKit, TanStack Start, React, Vue): 상품 페이지, 상품 목록, 장바구니, 결제, 네비게이션, 홈페이지, 검색, 계정 페이지 또는 주문 확인.
• 백엔드 통합(Medusa 포함) — SDK 설정, 상품/카테고리/지역 불러오기, 가격 표시, 결제 수단 선택, 장바구니 관리.
• 기존 스토어 최적화 — 전환율 개선, 모바일 경험 문제 수정, SEO 구조화 데이터 추가, 또는 쇼핑 흐름의 접근성 개선.
• 스토어프론트 구현 계획 수립 — 코드 작성 전에 올바른 참조 파일을 참고하고 알려진 함정을 피하는 단계별 구축 계획 생성.

• 비전자상거래 프로젝트 — 관리자 대시보드, SaaS 앱, 블로그, 또는 쇼핑/구매 흐름이 없는 사이트는 이 스킬의 패턴을 활용할 필요가 없습니다.
• 순수 백엔드 또는 API 작업 — 프론트엔드 스토어프론트 컴포넌트 없이 서버 측 커머스 로직만 작업하는 경우, 이 스킬은 거의 가치를 제공하지 않습니다.

백엔드 API 또는 SDK를 호출하는 코드를 작성하기 전에, 이 스킬은 5단계 워크플로우를 강제합니다: 일시 중지, 문서 또는 MCP 서버 쿼리, 사용자와 함께 메서드 검증, 코드 작성, 그런 다음 TypeScript 오류 확인. 이를 통해 추측성 메서드 이름, 오래된 예제, 그리고 자동으로 발생하는 런타임 오류를 방지합니다.

이 스킬은 모든 스토어프론트 작업(결제, 상품 목록, 내비게이션, SEO, 모바일, Medusa 통합 등)을 특정 참조 파일(예: reference/layouts/checkout.md, reference/medusa.md)에 매핑합니다. 각 기능을 구현하기 전에 로드해야 할 파일을 정확히 지정하여 패턴이 일관되게 적용되도록 보장합니다.

스토어프론트에 특화된 높은 영향력의 규칙을 다룹니다: 스크린 리더를 위한 장바구니 수량의 aria-live="polite", iOS 고정 버튼을 위한 env(safe-area-inset-bottom), 최소 44px 터치 타겟, 스크롤 하단 상품 이미지에 필수적인 loading="lazy", 그리고 Storefront Best Practices UI에서의 이모지 사용 금지.

Next.js(App 및 Pages Router), SvelteKit, TanStack Start, Remix에 대한 상품 및 카테고리 페이지의 올바른 동적 라우트 패턴을 제공합니다. 확장성이 없는 정적 개별 항목 라우트에 대해 명시적으로 경고합니다.

Medusa SDK 초기화(공개 API 키 필요), 올바른 가격 표시(100으로 나누지 않음), 상품 조회 시 region_id 요구사항, CORS 포트 규칙(8000), Vite SSR 설정, 커스텀 타입 대신 @medusajs/types 사용, 그리고 주문 완료 후 장바구니 상태 초기화에 대해 다룹니다.

장바구니/네비게이션, 상품 탐색, 결제, 모바일, SEO, 성능, 디자인 일관성, 백엔드 통합 등 다양한 카테고리에 걸쳐 30개 이상의 안티패턴을 정리한 목록 — 구현 전후로 확인할 수 있도록 각 항목이 구체적인 ❌ 규칙 형태로 구성되어 있습니다.

이 스킬은 디스커버리(design.md 로드)부터 파운데이션, 핵심 컴포넌트, 쇼핑 플로우, 최적화에 이르기까지 10단계 순차 워크플로우를 제공합니다. 각 단계는 구현 전에 로드해야 할 정확한 파일을 참조하여, 누락되는 항목 없이 스타일의 일관성을 유지할 수 있도록 합니다.

결제 아키텍처 결정(단일 페이지 vs. 다단계)을 안내하고, 결제 수단을 하드코딩하는 대신 백엔드에서 가져오도록 강제하며, 비회원 결제 요구 사항을 표시하고, reference/layouts/checkout.md 및 reference/medusa.md를 통해 Medusa 전용 결제 통합 단계를 제공합니다.

SDK 설정, 지역 및 가격 책정 패턴, region_id를 활용한 상품 불러오기, 장바구니 지역에 맞춘 국가 목록 범위 지정, Vite SSR 구성, 그리고 메서드 검증을 위한 Medusa MCP 서버 활용 방법을 다룹니다 — 가장 흔한 Medusa 스토어프론트 통합 오류를 예방합니다.

개발자에게 터치 타겟 크기, 안전 영역 인세트(safe-area insets), 이미지 최적화에 대해서는 reference/mobile-responsiveness.md를, 제품 JSON-LD 스키마, 메타 태그, Open Graph, PageSpeed Insights를 통한 Core Web Vitals 측정에 대해서는 reference/seo.md를 참조하도록 안내합니다.