uxgen

Commerce Kit — bốn thành phần mà một AI agent thường làm sai

Bản đặc tả chuẩn và triển khai tham chiếu cho bốn thành phần giúp tăng giá trị giỏ hàng: chiết khấu theo số lượng, thanh tiến trình miễn phí vận chuyển, đề xuất bổ sung đơn hàng, và nút thêm vào giỏ hàng cố định.

MIT. Không phụ thuộc gì ngoài React. Sao chép tệp, hoặc cài plugin và để agent của bạn tự làm.

---

Vì sao repository này tồn tại

Vào ngày 25 tháng 8 năm 2026, chúng tôi đã hỏi ChatGPT và Perplexity, cả hai đều bật tìm kiếm web, về một thành phần React cho buy 2, save 15%.

ChatGPT trả về một bộ chọn số lượng và không trích dẫn nguồn nào cả. Không một chú thích nào. Perplexity cũng trả về một bộ chọn số lượng, với min, max, step và một prop bundleSize, trích dẫn các mẫu chọn số lượng chung chung.

Cả hai đều sai theo cùng một cách, và lý do chính là phần hữu ích: không có nguồn chuẩn nào để chúng tham khảo. Tìm kiếm tiered pricing component và Google trả về 237 triệu kết quả về bảng giá. Tìm kiếm order bump component và nó trả về 25,9 triệu kết quả về plugin WooCommerce. Tìm kiếm bundle quantity selector component react và nó trả về 15,3 triệu kết quả về kích thước bundle JavaScript.

Các cơ chế thương mại không có đặc tả trên web mở, vì vậy một mô hình sẽ quay lại với thứ gần nhất mà nó đã đọc hàng nghìn lần.

Repository này chính là đặc tả đó.

---

Bốn thành phần

Thành phần	Nó hỏi người mua điều gì	Nó nằm ở đâu	Tác động lên
Chiết khấu theo số lượng	chọn gói nào, không phải chọn bao nhiêu	trang sản phẩm	mọi đơn hàng, trước khi giỏ hàng tồn tại
Thanh miễn phí vận chuyển	còn cách ngưỡng bao xa	giỏ hàng	các đơn hàng đã trên ~60% ngưỡng
Đề xuất bổ sung đơn hàng	một sản phẩm bổ sung, có hoặc không	giỏ hàng, phía trên tổng tiền	thời điểm xác nhận
Nút thêm vào giỏ hàng cố định	không hỏi gì — nó chỉ luôn hiển thị	trang sản phẩm trên di động	mọi phiên di động

Xây dựng chúng theo thứ tự đó. Thành phần đầu tiên tác động sớm nhất và lên phần lớn nhất của đơn hàng.

---

1. Chiết khấu theo số lượng

Đây là một nhóm radio. Nó không bao giờ là một ô nhập số.

Một câu duy nhất đó là toàn bộ thành phần. Một bộ chọn số lượng hỏi bao nhiêu, đó là phép toán mà người mua phải tự thực hiện, và không có gì trong đó gợi ý rằng hai là lựa chọn tốt hơn một. Một nhóm radio với các gói có tên hỏi chọn gói nào, và một trong số đó hiển nhiên là lựa chọn hợp lý.

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)}
/>

Các quy tắc

• Ba gói, tối đa bốn. Một gói cơ bản, một gói bạn muốn được chọn, một gói trần khiến gói giữa trông hợp lý. Năm gói biến sự nhận diện thành sự so sánh.
• Khoảng cách không tuyến tính. 1 / 3 / 6, không phải 1 / 2 / 3. Các bước đều nhau đọc như một bảng giá; các bước không đều đọc như các ưu đãi được thiết kế.
• Đặt tên cho các gói. Three tins — the usual reorder, không phải Quantity: 3. Tên gọi làm công việc mà con số không thể.
• Hiển thị số tiền tiết kiệm bằng tiền tệ, không chỉ là phần trăm. Save $9.00 là câu trả lời; Save 15% là một phép quy đổi mà người mua phải tự thực hiện.
• Hiển thị đơn giá dưới tổng tiền. $48.00 · $16.00 each. Dòng bị bỏ qua nhiều nhất trong mọi triển khai mà chúng tôi đã xem xét.
• Chọn trước gói giữa. Trạng thái được chọn được đọc như một khuyến nghị. Mặc định chọn gói rẻ nhất khuyến nghị chi tiêu ít nhất.
• Gắn nút với lựa chọn. Add 3 tins — $48.00.

Các ràng buộc là luật tại EU

• compareAtCents phải là một mức giá bạn thực sự đã thu. Các quy tắc chỉ định giá của EU quản lý các thông báo giá trước đó. Một con số gạch ngang được bịa ra để phóng đại khoản tiết kiệm là một hành vi bị cấm. Trong triển khai này, compareAtCents dưới totalCents sẽ ném lỗi trong môi trường phát triển thay vì hiển thị một mức neo giả.
• Một huy hiệu phải đúng sự thật. Most chosen trên một gói không ai chọn là một tuyên bố sai về chính cửa hàng của bạn.

---

2. Thanh tiến trình miễn phí vận chuyển

Hiển thị số tiền còn thiếu bằng tiền tệ. $6.00 to unlock free shipping. Một thanh tiến trình không có con số chỉ là trang trí, và một phần trăm là một phép quy đổi thứ hai mà người mua phải tự thực hiện.

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

• Ngưỡng là một con số bạn chọn dựa trên biên lợi nhuận của mình, không phải một con số tròn bạn thích.
• Khi đã đạt ngưỡng, hãy nói rõ ràng và dừng hoạt ảnh. Một thanh cứ tiếp tục ăn mừng sau khi đã đạt mục tiêu chỉ là tiếng ồn.
• Không hiển thị nó ở $0.00 trong một giỏ hàng trống. Dưới khoảng 40% ngưỡng, nó đọc như một khoảng cách, không phải một cú huých.

---

3. Đề xuất bổ sung đơn hàng

Một sản phẩm có tên, một mức giá, một lý do, một ô chưa được chọn. Phía trên tổng tiền, dưới nội dung giỏ hàng.

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

• Không bao giờ được chọn trước. Điều 22 của Chỉ thị 2011/83/EU yêu cầu sự đồng ý rõ ràng cho bất kỳ khoản thanh toán nào ngoài nghĩa vụ chính và khiến một sự đồng ý ngầm phải được hoàn tiền. Nhiều widget bán hàng thương mại được giao với ô chọn trước làm mặc định nhà máy. Trong triển khai này, prop checked không có cách nào để bắt đầu true.
• Không bao giờ là một rào cản. Không làm gián đoạn thanh toán bằng một màn hình phải được chấp nhận hoặc từ chối. Người mua đã quyết định; bạn đã thay nút của họ bằng một câu hỏi.
• Không bao giờ là một băng chuyền. Một sản phẩm. Một lưới sáu sản phẩm là một quyết định duyệt mới vào đúng thời điểm bạn muốn một sự xác nhận.
• Giá thấp hơn hẳn giỏ hàng. Một sản phẩm bổ sung có giá tương tự đọc như một giao dịch mua thứ hai và mở lại toàn bộ quyết định.

---

4. Nút thêm vào giỏ hàng cố định (di động)

Nút rời khỏi màn hình ngay khi người mua đọc phần mô tả. Trên viewport 390px, đó là phần lớn phiên.

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

• Chỉ xuất hiện sau khi nút nội tuyến đã cuộn ra khỏi tầm nhìn, không bao giờ chồng lên nó.
• Mang tổng tiền của gói đã chọn, để một cái nhìn thay thế việc cuộn ngược lên.
• Tôn trọng vùng an toàn trên iOS. env(safe-area-inset-bottom) nằm trong triển khai.
• Ẩn trên 768px, nơi nút nội tuyến vẫn có thể truy cập được.

---

Cài đặt như một plugin Claude Code

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

Sau đó, trong agent:

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.

Kỹ năng này mang theo các quy tắc trên, để agent xây dựng một nhóm radio thay vì một bộ chọn số lượng, và từ chối hai mẫu bất hợp pháp tại EU.

---

Đây không phải là gì

Nó không phải là một hệ thống thiết kế, và nó sẽ không làm cho trang của bạn trông đẹp hơn. Nó là bốn thành phần kèm lý do thương mại, vì lý do đó là thứ đang thiếu ở mọi nơi khác. Nếu trang của bạn cũng trông như được tạo tự động, đó là một vấn đề riêng với một giải pháp riêng.

Nó không phải là một khung A/B testing, và nó không hứa hẹn một sự tăng trưởng. Dưới khoảng bốn mươi nghìn phiên mỗi biến thể, một thử nghiệm phân tách không thể tách biệt hiệu ứng thực khỏi nhiễu, điều này đúng với hầu hết các cửa hàng. Điều mà bốn thành phần này mang lại là loại bỏ một thiếu sót đã biết, điều này không cần một bài kiểm tra để biết là đáng làm.

---

Đọc thêm

• Chiết khấu theo số lượng giúp tăng giá trị đơn hàng trung bình
• Nơi đặt upsell trên trang sản phẩm
• shadcn ecommerce blocks: những gì tồn tại và những gì còn thiếu
• Ứng dụng Upsell cho Shopify, hoặc tự xây dựng

Được xây dựng bởi uxgen, MCP trao các cơ chế này cho một coding agent.

MIT © 2026 Angelo Palfi