uxgen

Commerce Kit — AI 에이전트가 틀리기 쉬운 네 가지 구성 요소

바구니 금액을 높이는 네 가지 구성 요소에 대한 표준 명세 및 참조 구현: 수량 구간(quantity breaks), 무료 배송 임계값 바(free-shipping threshold bar), 주문 추가 상품(order bump), 고정 장바구니 담기(sticky add-to-cart).

MIT 라이선스. React 외 의존성 없음. 파일을 복사하거나 플러그인을 설치해 에이전트가 처리하도록 하세요.

---

이 저장소가 존재하는 이유

2026년 8월 25일, 우리는 웹 검색을 활성화한 ChatGPT와 Perplexity에게 buy 2, save 15%용 React 컴포넌트를 요청했습니다.

ChatGPT는 수량 스테퍼(quantity stepper)를 반환했고 출처를 전혀 인용하지 않았습니다. 주석이 전혀 없었습니다. Perplexity도 스테퍼를 반환했으며, min, max, step 및 bundleSize prop을 포함해 일반적인 수량 선택기 패턴을 인용했습니다.

둘 다 같은 방식으로 틀렸고, 그 이유가 바로 유용한 부분입니다. 참고할 표준 소스가 없기 때문입니다. tiered pricing component을 검색하면 Google은 가격표에 관한 2억 3,700만 개의 결과를 반환합니다. order bump component을 검색하면 WooCommerce 플러그인에 관한 2,590만 개의 결과를 반환합니다. bundle quantity selector component react을 검색하면 JavaScript 번들 크기에 관한 1,530만 개의 결과를 반환합니다.

커머스 메커니즘에 대한 명세가 공개 웹에 없으므로, 모델은 수천 번 읽은 가장 가까운 것으로 대체하게 됩니다.

이 저장소가 바로 그 명세입니다.

---

네 가지 구성 요소

구성 요소	구매자에게 묻는 것	위치	적용 대상
수량 구간	몇 개가 아니라 어떤 패키지인지	상품 페이지	장바구니가 생기기 전의 모든 주문
무료 배송 바	임계값까지 얼마나 남았는지	장바구니	이미 임계값의 약 60% 이상인 주문
주문 추가 상품	보완 상품 하나, 예 또는 아니오	장바구니, 합계 위	확인 순간
고정 장바구니 담기	아무것도 묻지 않음 — 계속 접근 가능하게 유지	모바일 상품 페이지	모든 모바일 세션

이 순서대로 구축하세요. 첫 번째가 가장 먼저, 그리고 가장 많은 주문 비율에 적용됩니다.

---

1. 수량 구간

라디오 그룹입니다. 숫자 입력이 절대 아닙니다.

이 한 문장이 전체 구성 요소입니다. 스테퍼는 몇 개를 묻는데, 이는 구매자가 수행해야 하는 산수이며, 1개보다 2개가 더 낫다는 것을 암시하는 요소가 전혀 없습니다. 이름이 지정된 티어의 라디오 그룹은 어떤 패키지를 묻고, 그중 하나가 눈에 띄게 합리적으로 보입니다.

import { QuantityBreaks } from "./src/quantity-breaks"

<QuantityBreaks
  tiers={[
    { units: 1, name: "One tin",   totalCents: 1900, compareAtCents: 1900 },
    { units: 3, name: "Three tins — the usual reorder",
      totalCents: 4800, compareAtCents: 5700, badge: "Most chosen", preselected: true },
    { units: 6, name: "Six tins — the year",
      totalCents: 9000, compareAtCents: 11400 },
  ]}
  currency="USD"
  onChange={(tier) => setSelected(tier)}
/>

규칙

• 세 개 티어, 최대 네 개. 기준선 하나, 선택되길 원하는 것 하나, 중간이 합리적으로 보이게 만드는 상한선 하나. 다섯 개는 인식을 비교로 바꿉니다.
• 비선형 간격. 1 / 3 / 6, 1 / 2 / 3이 아님. 균등한 단계는 가격표처럼 읽히고, 불균등한 단계는 구성된 제안처럼 읽힙니다.
• 티어에 이름을 지정하세요. Three tins — the usual reorder, Quantity: 3이 아님. 이름이 숫자가 할 수 없는 역할을 합니다.
• 할인 금액을 통화로 표시하고, 백분율로만 표시하지 마세요. Save $9.00이 답이고, Save 15%은 구매자가 계산해야 하는 변환입니다.
• 총액 아래에 단가를 표시하세요. $48.00 · $16.00 each. 우리가 살펴본 모든 구현에서 가장 많이 건너뛰는 줄입니다.
• 중간 티어를 미리 선택하세요. 선택된 상태는 추천으로 읽힙니다. 가장 저렴한 것을 기본값으로 하면 가장 적게 지출하도록 권장하는 것입니다.
• 버튼을 선택에 바인딩하세요. Add 3 tins — $48.00.

EU에서 법으로 정한 제약 사항

• compareAtCents은 실제로 청구한 가격이어야 합니다. EU 가격 표시 규칙은 이전 가격 공지를 규율합니다. 할인 폭을 키우기 위해 만들어낸 취소선 가격은 금지된 관행입니다. 이 구현에서 compareAtCents이 totalCents 아래에 있으면 잘못된 앵커를 렌더링하는 대신 개발 중에 예외를 던집니다.
• 배지는 사실이어야 합니다. 아무도 선택하지 않는 티어에 Most chosen을 붙이는 것은 자신의 상점에 대한 거짓 진술입니다.

---

2. 무료 배송 임계값 바

남은 금액을 화폐 단위로 표시하세요. $6.00 to unlock free shipping. 숫자가 없는 진행 바는 장식일 뿐이고, 백분율은 구매자가 계산해야 하는 두 번째 변환입니다.

<FreeShippingBar subtotalCents={4400} thresholdCents={5000} currency="USD" />

• 임계값은 마음에 드는 둥근 숫자가 아니라 마진을 고려해 선택한 수치입니다.
• 도달하면 간단히 알리고 애니메이션을 중지하세요. 목표 달성 후에도 계속 축하하는 바는 소음일 뿐입니다.
• 빈 장바구니에서 $0.00에 표시하지 마세요. 임계값의 약 40% 미만에서는 부드러운 유도가 아니라 거리로 읽힙니다.

---

3. 주문 추가 상품

이름이 지정된 항목 하나, 가격 하나, 이유 하나, 체크되지 않은 상자 하나. 합계 위, 장바구니 내용물 아래.

<OrderBump
  item={{ name: "Steel scoop", priceCents: 600, reason: "Measures one serving exactly." }}
  onToggle={(added) => setBump(added)}
/>

• 절대 미리 체크하지 마세요. Directive 2011/83/EU 제22조는 주요 의무를 넘어선 모든 지불에 명시적 동의를 요구하며, 묵시적 동의는 환불 가능하게 만듭니다. 여러 상용 업셀 위젯이 공장 기본값으로 미리 체크된 상태로 배송됩니다. 이 구현에서 checked prop은 true로 시작할 방법이 없습니다.
• 절대 게이트가 되지 마세요. 수락하거나 거부해야 하는 화면으로 체크아웃을 중단하지 마세요. 구매자는 이미 결정했는데, 당신이 그들의 버튼을 질문으로 바꿨습니다.
• 절대 캐러셀이 되지 마세요. 항목 하나. 여섯 개의 그리드는 확인을 원했던 순간에 새로운 탐색 결정입니다.
• 장바구니보다 훨씬 낮은 가격으로 책정하세요. 비슷한 가격의 보완 상품은 두 번째 구매로 읽히고 전체 결정을 다시 열게 됩니다.

---

4. 고정 장바구니 담기(모바일)

구매자가 설명을 읽는 순간 버튼이 화면에서 사라집니다. 390px 뷰포트에서는 세션의 대부분이 그렇습니다.

<StickyAddToCart label="Add 3 tins" totalCents={4800} currency="USD" onAdd={add} />

• 인라인 버튼이 화면 밖으로 스크롤된 후에만 나타나며, 절대 그 위에 나타나지 않습니다.
• 선택한 티어의 총액을 표시하므로 한 번의 응시로 위로 스크롤할 필요가 없습니다.
• iOS의 안전 영역을 존중합니다. env(safe-area-inset-bottom)이 구현에 포함되어 있습니다.
• 인라인 버튼이 여전히 접근 가능한 768px 이상에서는 숨겨집니다.

---

Claude Code 플러그인으로 설치

/plugin marketplace add kinerette/uxgen-commerce-kit
/plugin install commerce-kit@uxgen

그런 다음 에이전트에서:

Use the commerce-kit skill. Add quantity breaks to this product page:
three tiers at 1 / 3 / 6, the middle one marked and preselected,
saving shown in currency, and bind the add-to-cart button to the selection.

이 스킬은 위의 규칙을 포함하므로 에이전트는 스테퍼 대신 라디오 그룹을 구축하고 EU에서 불법인 두 가지 패턴을 거부합니다.

---

이것이 아닌 것

디자인 시스템이 아니며, 페이지를 보기 좋게 만들지 않습니다. 상업적 근거가 첨부된 네 가지 구성 요소입니다. 그 근거가 다른 모든 곳에서 빠져 있기 때문입니다. 페이지가 생성된 것처럼 보인다면, 그것은 별도의 문제이며 별도의 해결책이 있습니다.

A/B 테스트 프레임워크가 아니며, 상승을 약속하지 않습니다. 변형당 약 4만 세션 미만에서는 분할 테스트가 실제 효과와 노이즈를 구분할 수 없으며, 대부분의 상점이 그렇습니다. 이 네 가지 구성 요소가 제공하는 것은 알려진 누락의 제거이며, 테스트 없이도 수행할 가치가 있습니다.

---

관련 자료

• 평균 주문 금액을 높이는 수량 구간
• 상품 페이지에서 업셀을 배치할 위치
• shadcn 이커머스 블록: 존재하는 것과 빠진 것
• Shopify용 업셀 앱 또는 직접 구축

uxgen이 구축 — 이러한 메커니즘을 코딩 에이전트에 전달하는 MCP.

MIT © 2026 Angelo Palfi