uxgen

Commerce Kit — empat komponen yang sering salah dilakukan oleh agen AI

Spesifikasi kanonik dan implementasi referensi untuk empat komponen yang meningkatkan keranjang belanja: quantity breaks, free-shipping threshold bar, order bump, dan sticky add-to-cart.

MIT. Tanpa dependensi selain React. Salin file-nya, atau instal plugin-nya dan biarkan agen Anda yang mengerjakannya.

---

Mengapa repositori ini ada

Pada 25 Agustus 2026 kami bertanya kepada ChatGPT dan Perplexity, keduanya dengan pencarian web aktif, untuk sebuah komponen React untuk buy 2, save 15%.

ChatGPT mengembalikan quantity stepper dan tidak mencantumkan sumber sama sekali. Nol anotasi. Perplexity juga mengembalikan stepper, dengan min, max, step dan prop bundleSize, mengutip pola pemilih kuantitas generik.

Keduanya salah dengan cara yang sama, dan alasannya adalah bagian yang berguna: tidak ada sumber kanonik yang bisa mereka rujuk. Cari tiered pricing component dan Google mengembalikan 237 juta hasil tentang tabel harga. Cari order bump component dan hasilnya 25,9 juta tentang plugin WooCommerce. Cari bundle quantity selector component react dan hasilnya 15,3 juta tentang ukuran bundel JavaScript.

Mekanisme commerce tidak memiliki spesifikasi di web terbuka, sehingga model akan jatuh kembali pada hal terdekat yang pernah dibacanya ribuan kali.

Repositori ini adalah spesifikasi tersebut.

---

Empat komponen

Komponen	Apa yang ditanyakan kepada pembeli	Di mana ia berada	Berlaku pada
Quantity breaks	paket mana, bukan berapa banyak	halaman produk	setiap pesanan, sebelum keranjang ada
Free-shipping bar	seberapa jauh dari ambang batas	keranjang	pesanan yang sudah di atas ~60% dari ambang batas
Order bump	satu pelengkap, ya atau tidak	keranjang, di atas total	momen konfirmasi
Sticky add-to-cart	tidak ada — ia hanya tetap terjangkau	halaman produk seluler	setiap sesi seluler

Bangun dalam urutan itu. Yang pertama berlaku paling awal dan pada porsi pesanan terbesar.

---

1. Quantity breaks

Ini adalah grup radio. Ini tidak pernah berupa input angka.

Satu kalimat itu adalah keseluruhan komponen. Stepper menanyakan berapa banyak, yang merupakan aritmetika yang harus dilakukan pembeli, dan tidak ada apa pun yang menunjukkan bahwa dua lebih baik daripada satu. Grup radio dengan tier bernama menanyakan paket mana, dan salah satunya terlihat jelas sebagai pilihan yang masuk akal.

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

Aturannya

• Tiga tier, paling banyak empat. Satu baseline, satu yang Anda ingin dipilih, satu batas atas yang membuat yang tengah terlihat masuk akal. Lima mengubah pengenalan menjadi perbandingan.
• Jarak non-linear. 1 / 3 / 6, bukan 1 / 2 / 3. Langkah genap terbaca sebagai daftar harga; yang tidak genap terbaca sebagai penawaran tersusun.
• Beri nama tier-nya. Three tins — the usual reorder, bukan Quantity: 3. Nama melakukan pekerjaan yang tidak bisa dilakukan angka.
• Tampilkan penghematan dalam mata uang, bukan hanya sebagai persentase. Save $9.00 adalah jawabannya; Save 15% adalah konversi yang harus dihitung pembeli.
• Tampilkan harga satuan di bawah total. $48.00 · $16.00 each. Baris yang paling sering dilewati di setiap implementasi yang pernah kami lihat.
• Pilih tier tengah secara default. Status terpilih terbaca sebagai rekomendasi. Default ke yang termurah merekomendasikan untuk membelanjakan paling sedikit.
• Ikat tombol ke pilihan. Add 3 tins — $48.00.

Batasan yang menjadi hukum di UE

• compareAtCents harus berupa harga yang benar-benar Anda kenakan. Aturan indikasi harga UE mengatur pengumuman harga sebelumnya. Angka yang dicoret yang dibuat untuk memperbesar penghematan adalah praktik yang dilarang. Dalam implementasi ini, compareAtCents di bawah totalCents melempar error di lingkungan pengembangan daripada merender jangkar palsu.
• Badge harus benar. Most chosen pada tier yang tidak dipilih siapa pun adalah pernyataan palsu tentang toko Anda sendiri.

---

2. Free-shipping threshold bar

Tampilkan sisa jumlah dalam uang. $6.00 to unlock free shipping. Bilah kemajuan tanpa angka hanyalah dekorasi, dan persentase adalah konversi kedua yang harus dihitung pembeli.

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

• Ambang batas adalah angka yang Anda pilih berdasarkan margin Anda, bukan angka bulat yang Anda sukai.
• Setelah tercapai, katakan dengan jelas dan hentikan animasi. Bilah yang terus merayakan setelah tujuan tercapai hanyalah kebisingan.
• Jangan tampilkan di $0.00 dalam keranjang kosong. Di bawah sekitar 40% dari ambang batas, ia terbaca sebagai jarak, bukan dorongan.

---

3. Order bump

Satu item bernama, satu harga, satu alasan, satu kotak centang yang tidak dicentang. Di atas total, di bawah isi keranjang.

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

• Jangan pernah dicentang sebelumnya. Pasal 22 Directive 2011/83/EU mensyaratkan persetujuan eksplisit untuk pembayaran apa pun di luar kewajiban utama dan membuat "ya" yang tersirat dapat dikembalikan. Beberapa widget upsell komersial dikirim dengan centang awal sebagai default pabrik. Dalam implementasi ini, prop checked tidak memiliki cara untuk memulai true.
• Jangan pernah menjadi gerbang. Jangan mengganggu checkout dengan layar yang harus diterima atau ditolak. Pembeli sudah memutuskan; Anda mengganti tombol mereka dengan pertanyaan.
• Jangan pernah menjadi carousel. Satu item. Grid enam item adalah keputusan penjelajahan baru di saat Anda menginginkan konfirmasi.
• Harga jauh di bawah keranjang. Pelengkap dengan harga serupa terbaca sebagai pembelian kedua dan membuka kembali seluruh keputusan.

---

4. Sticky add-to-cart (seluler)

Tombol meninggalkan layar begitu pembeli membaca deskripsi. Pada viewport 390px, itu adalah sebagian besar sesi.

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

• Muncul hanya setelah tombol inline tergulir keluar dari layar, tidak pernah di atasnya.
• Membawa total tier yang dipilih, sehingga satu pandangan menggantikan pengguliran kembali ke atas.
• Menghormati area aman di iOS. env(safe-area-inset-bottom) ada di implementasi.
• Disembunyikan di atas 768px, di mana tombol inline masih terjangkau.

---

Instal sebagai plugin Claude Code

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

Lalu, di dalam agen:

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.

Skill tersebut membawa aturan di atas, sehingga agen membangun grup radio alih-alih stepper, dan menolak dua pola yang ilegal di UE.

---

Apa yang bukan ini

Ini bukan sistem desain, dan tidak akan membuat halaman Anda terlihat bagus. Ini adalah empat komponen dengan alasan komersial yang dilampirkan, karena alasan itulah yang hilang di tempat lain. Jika halaman Anda juga terlihat seperti hasil generate, itu adalah masalah terpisah dengan perbaikan terpisah.

Ini bukan kerangka kerja pengujian A/B, dan tidak menjanjikan peningkatan. Di bawah sekitar empat puluh ribu sesi per varian, uji terpisah tidak dapat memisahkan efek nyata dari kebisingan, yang merupakan kasus sebagian besar toko. Yang diberikan keempat komponen ini kepada Anda adalah penghapusan kelalaian yang diketahui, yang tidak perlu diuji untuk layak dilakukan.

---

Bacaan terkait

• Quantity breaks yang meningkatkan nilai pesanan rata-rata
• Di mana menempatkan upsell di halaman produk
• Blok ecommerce shadcn: apa yang ada dan apa yang hilang
• Aplikasi Upsell untuk Shopify, atau buat sendiri

Dibuat oleh uxgen, MCP yang menyerahkan mekanisme ini kepada agen pengkodean.

MIT © 2026 Angelo Palfi