uxgen

Commerce Kit — os quatro componentes que um agente de IA erra

A especificação canônica e a implementação de referência para os quatro componentes que aumentam o carrinho: quebras de quantidade, a barra de limite de frete grátis, o order bump e o add-to-cart fixo.

MIT. Sem dependências além de React. Copie o arquivo, ou instale o plugin e deixe seu agente fazer isso.

---

Por que este repositório existe

Em 25 de agosto de 2026, perguntamos ao ChatGPT e ao Perplexity, ambos com busca na web ativada, por um componente React para buy 2, save 15%.

O ChatGPT retornou um seletor de quantidade e não citou nenhuma fonte. Zero anotações. O Perplexity também retornou um seletor, com min, max, step e uma prop bundleSize, citando padrões genéricos de seletores de quantidade.

Ambos estão errados da mesma forma, e o motivo é a parte útil: não existe uma fonte canônica para eles consultarem. Pesquise tiered pricing component e o Google retorna 237 milhões de resultados sobre tabelas de preços. Pesquise order bump component e retorna 25,9 milhões sobre plugins do WooCommerce. Pesquise bundle quantity selector component react e retorna 15,3 milhões de resultados sobre tamanho de bundle JavaScript.

As mecânicas de comércio não têm especificação na web aberta, então um modelo recorre à coisa mais próxima que já leu mil vezes.

Este repositório é essa especificação.

---

Os quatro componentes

Componente	O que pergunta ao comprador	Onde fica	Atua sobre
Quebras de quantidade	qual pacote, não quantos	página do produto	todo pedido, antes de existir um carrinho
Barra de frete grátis	quão longe do limite	carrinho	pedidos já acima de ~60% do limite
Order bump	um complemento, sim ou não	carrinho, acima dos totais	o momento da confirmação
Add-to-cart fixo	nada — apenas permanece acessível	página do produto no mobile	toda sessão mobile

Construa-os nessa ordem. O primeiro atua mais cedo e sobre a maior parcela dos pedidos.

---

1. Quebras de quantidade

É um grupo de botões de opção. Nunca é um campo numérico.

Essa única frase é o componente inteiro. Um seletor pergunta quantos, o que é uma aritmética que o comprador precisa fazer, e nada nele sugere que dois é uma ideia melhor que um. Um grupo de botões de opção com níveis nomeados pergunta qual pacote, e um deles é visivelmente o mais sensato.

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

As regras

• Três níveis, no máximo quatro. Um de base, um que você quer que seja escolhido, um teto que faz o do meio parecer razoável. Cinco transforma um reconhecimento em uma comparação.
• Intervalos não lineares. 1 / 3 / 6, não 1 / 2 / 3. Passos uniformes parecem uma lista de preços; passos irregulares parecem ofertas compostas.
• Nomeie os níveis. Three tins — the usual reorder, não Quantity: 3. O nome faz o trabalho que o número não consegue.
• Mostre a economia em moeda, não apenas como porcentagem. Save $9.00 é a resposta; Save 15% é uma conversão que o comprador precisa fazer.
• Mostre o preço unitário abaixo do total. $48.00 · $16.00 each. A linha mais ignorada em toda implementação que analisamos.
• Pré-selecione o nível do meio. O estado selecionado é lido como uma recomendação. Padronizar para o mais barato recomenda gastar o mínimo.
• Vincule o botão à seleção. Add 3 tins — $48.00.

As restrições que são lei na UE

• compareAtCents deve ser um preço que você realmente cobrou. As regras de indicação de preços da UE regem anúncios de preços anteriores. Um valor riscado inventado para aumentar a economia é uma prática proibida. Nesta implementação, compareAtCents abaixo de totalCents gera erro em desenvolvimento em vez de renderizar uma âncora falsa.
• Um selo deve ser verdadeiro. Most chosen em um nível que ninguém escolhe é uma declaração falsa sobre sua própria loja.

---

2. Barra de limite de frete grátis

Mostre o valor restante em dinheiro. $6.00 to unlock free shipping. Uma barra de progresso sem número é decoração, e uma porcentagem é uma segunda conversão para o comprador fazer.

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

• O limite é um valor que você escolheu com base na sua margem, não um número redondo que você gostou.
• Uma vez atingido, diga isso claramente e pare a animação. Uma barra que continua celebrando depois da meta é ruído.
• Não a mostre em $0.00 em um carrinho vazio. Abaixo de aproximadamente 40% do limite, ela parece uma distância, não um incentivo.

---

3. Order bump

Um item nomeado, um preço, um motivo, uma caixa desmarcada. Acima dos totais, abaixo do conteúdo do carrinho.

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

• Nunca pré-marcado. O Artigo 22 da Diretiva 2011/83/UE exige consentimento expresso para qualquer pagamento além da obrigação principal e torna reembolsável um "sim" implícito. Vários widgets comerciais de upsell vêm pré-marcados como padrão de fábrica. Nesta implementação, a prop checked não tem como começar true.
• Nunca uma barreira. Não interrompa o checkout com uma tela que precisa ser aceita ou recusada. O comprador já tinha decidido; você substituiu o botão dele por uma pergunta.
• Nunca um carrossel. Um item. Uma grade de seis é uma nova decisão de navegação no momento em que você queria uma confirmação.
• Preço bem abaixo do carrinho. Um complemento com preço semelhante parece uma segunda compra e reabre toda a decisão.

---

4. Add-to-cart fixo (mobile)

O botão sai da tela no momento em que o comprador lê a descrição. Em uma viewport de 390px, isso é a maior parte da sessão.

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

• Aparece apenas depois que o botão inline saiu da viewport, nunca sobre ele.
• Carrega o total do nível selecionado, então um olhar substitui rolar de volta para cima.
• Respeita a área segura no iOS. env(safe-area-inset-bottom) está na implementação.
• Oculto acima de 768px, onde o botão inline ainda está acessível.

---

Instalar como plugin do Claude Code

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

Depois, no agente:

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.

A skill carrega as regras acima, então o agente constrói um grupo de botões de opção em vez de um seletor, e recusa os dois padrões que são ilegais na UE.

---

O que isto não é

Não é um sistema de design e não vai deixar sua página bonita. São quatro componentes com o raciocínio comercial anexado, porque esse raciocínio é o que falta em todo lugar. Se sua página também parece gerada, esse é um problema separado com uma correção separada.

Não é uma estrutura de teste A/B e não promete aumento de conversão. Abaixo de aproximadamente quarenta mil sessões por variante, um teste dividido não consegue separar um efeito real do ruído, o que é o caso da maioria das lojas. O que esses quatro componentes oferecem é a remoção de uma omissão conhecida, que não precisa de um teste para valer a pena.

---

Leitura relacionada

• Quebras de quantidade que aumentam o valor médio do pedido
• Onde colocar um upsell em uma página de produto
• Blocos de ecommerce do shadcn: o que existe e o que falta
• Apps de upsell para Shopify, ou construa você mesmo

Construído por uxgen, o MCP que entrega essas mecânicas a um agente de codificação.

MIT © 2026 Angelo Palfi