uxgen

Commerce Kit – die vier Komponenten, die ein KI-Agent falsch hinbekommt

Die kanonische Spezifikation und Referenzimplementierung für die vier Komponenten, die den Warenkorb steigern: Mengenstaffelungen, die Balken für die kostenlose Versandschwelle, der Order Bump und der Sticky Add-to-Cart.

MIT. Keine Abhängigkeiten außer React. Kopiere die Datei oder installiere das Plugin und lass deinen Agenten die Arbeit machen.

---

Warum dieses Repository existiert

Am 25. August 2026 haben wir ChatGPT und Perplexity, beide mit aktivierter Websuche, um eine React-Komponente für buy 2, save 15% gebeten.

ChatGPT lieferte einen Mengen-Stepper und nannte überhaupt keine Quelle. Null Annotationen. Perplexity lieferte ebenfalls einen Stepper, mit min, max, step und einer bundleSize-Prop, unter Berufung auf generische Mengenauswahl-Muster.

Beide sind auf dieselbe Weise falsch, und der Grund dafür ist der nützliche Teil: Es gibt keine kanonische Quelle, die sie konsultieren könnten. Eine Suche nach tiered pricing component liefert bei Google 237 Millionen Ergebnisse über Preistabellen. Eine Suche nach order bump component liefert 25,9 Millionen Ergebnisse über WooCommerce-Plugins. Eine Suche nach bundle quantity selector component react liefert 15,3 Millionen Ergebnisse über die JavaScript-Bundlegröße.

Die Commerce-Mechaniken haben im offenen Web keine Spezifikation, also greift ein Modell auf das Nächstliegende zurück, das es tausendmal gelesen hat.

Dieses Repository ist diese Spezifikation.

---

Die vier Komponenten

Komponente	Was sie den Käufer fragt	Wo sie lebt	Wirkt auf
Mengenstaffelungen	welches Paket, nicht wie viele	Produktseite	jede Bestellung, bevor ein Warenkorb existiert
Balken für kostenlosen Versand	wie weit von der Schwelle entfernt	Warenkorb	Bestellungen, die bereits über ~60 % der Schwelle liegen
Order Bump	eine Ergänzung, ja oder nein	Warenkorb, über den Summen	den Moment der Bestätigung
Sticky Add-to-Cart	nichts – er bleibt einfach erreichbar	mobile Produktseite	jede mobile Sitzung

Baue sie in dieser Reihenfolge. Die erste wirkt am frühesten und auf den größten Anteil der Bestellungen.

---

1. Mengenstaffelungen

Es ist eine Radiogruppe. Es ist niemals ein Zahlenfeld.

Dieser einzelne Satz ist die gesamte Komponente. Ein Stepper fragt wie viele, was Rechenarbeit für den Käufer bedeutet, und nichts daran deutet darauf hin, dass zwei besser ist als eins. Eine Radiogruppe mit benannten Stufen fragt welches Paket, und eines davon ist sichtbar das Vernünftige.

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

Die Regeln

• Drei Stufen, höchstens vier. Eine Basislinie, eine, die gewählt werden soll, eine Obergrenze, die die Mitte vernünftig aussehen lässt. Fünf verwandelt eine Wiedererkennung in einen Vergleich.
• Nicht-lineare Abstände. 1 / 3 / 6, nicht 1 / 2 / 3. Gleiche Schritte lesen sich wie eine Preisliste; ungleiche wie zusammengestellte Angebote.
• Benenne die Stufen. Three tins — the usual reorder, nicht Quantity: 3. Der Name leistet die Arbeit, die die Zahl nicht leisten kann.
• Zeige die Ersparnis in Währung, nicht nur als Prozentsatz. Save $9.00 ist die Antwort; Save 15% ist eine Umrechnung, die der Käufer selbst durchführen muss.
• Zeige den Stückpreis unter der Summe. $48.00 · $16.00 each. Die am häufigsten übersprungene Zeile in jeder Implementierung, die wir uns angesehen haben.
• Wähle die mittlere Stufe vorab aus. Der ausgewählte Zustand wird als Empfehlung gelesen. Standardmäßig die günstigste zu wählen, empfiehlt, am wenigsten auszugeben.
• Binde den Button an die Auswahl. Add 3 tins — $48.00.

Die Einschränkungen, die in der EU Gesetz sind

• compareAtCents muss ein Preis sein, den du tatsächlich verlangt hast. Die EU-Regeln zur Preisangabe regeln Ankündigungen früherer Preise. Ein durchgestrichener Betrag, der erfunden wurde, um die Ersparnis zu vergrößern, ist eine unzulässige Praxis. In dieser Implementierung wirft compareAtCents unterhalb von totalCents in der Entwicklung einen Fehler, anstatt einen falschen Anker zu rendern.
• Ein Badge muss wahr sein. Most chosen auf einer Stufe, die niemand wählt, ist eine falsche Aussage über deinen eigenen Shop.

---

2. Balken für die kostenlose Versandschwelle

Zeige den verbleibenden Betrag in Geld. $6.00 to unlock free shipping. Ein Fortschrittsbalken ohne Zahl ist Dekoration, und ein Prozentsatz ist eine zweite Umrechnung für den Käufer.

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

• Die Schwelle ist eine Zahl, die du anhand deiner Marge gewählt hast, keine runde Zahl, die dir gefallen hat.
• Sobald sie erreicht ist, sag es klar und beende die Animation. Ein Balken, der weiter feiert, nachdem das Ziel erreicht ist, ist Lärm.
• Zeige ihn nicht bei $0.00 in einem leeren Warenkorb. Unterhalb von etwa 40 % der Schwelle liest er sich als Distanz, nicht als Anstoß.

---

3. Order Bump

Ein benannter Artikel, ein Preis, ein Grund, ein nicht angehaktes Kästchen. Über den Summen, unterhalb des Warenkorbinhalts.

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

• Niemals vorab angehakt. Artikel 22 der Richtlinie 2011/83/EU verlangt ausdrückliche Zustimmung zu jeder Zahlung über die Hauptverpflichtung hinaus und macht ein implizites Ja erstattungsfähig. Mehrere kommerzielle Upsell-Widgets werden standardmäßig vorab angehakt ausgeliefert. In dieser Implementierung hat die checked-Prop keine Möglichkeit, als true zu starten.
• Niemals ein Hindernis. Unterbrich den Checkout nicht mit einem Bildschirm, der angenommen oder abgelehnt werden muss. Der Käufer hatte sich entschieden; du hast seinen Button durch eine Frage ersetzt.
• Niemals ein Karussell. Ein Artikel. Ein Raster aus sechs ist eine neue Browsing-Entscheidung in dem Moment, in dem du eine Bestätigung wolltest.
• Preislich deutlich unter dem Warenkorb. Eine Ergänzung zu einem ähnlichen Preis liest sich wie ein zweiter Kauf und eröffnet die gesamte Entscheidung neu.

---

4. Sticky Add-to-Cart (mobil)

Der Button verlässt den Bildschirm in dem Moment, in dem der Käufer die Beschreibung liest. Auf einem 390px-Viewport ist das der Großteil der Sitzung.

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

• Erscheint nur, nachdem der Inline-Button aus dem Blickfeld gescrollt ist, niemals über ihm.
• Trägt die Summe der ausgewählten Stufe, sodass ein Blick das Zurückscrollen ersetzt.
• Respektiert den Safe Area auf iOS. env(safe-area-inset-bottom) ist in der Implementierung enthalten.
• Versteckt oberhalb von 768px, wo der Inline-Button weiterhin erreichbar ist.

---

Als Claude-Code-Plugin installieren

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

Dann im Agenten:

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.

Die Skill trägt die obigen Regeln, sodass der Agent eine Radiogruppe statt eines Steppers baut und die beiden Muster ablehnt, die in der EU illegal sind.

---

Was dies nicht ist

Es ist kein Designsystem und es wird deine Seite nicht gut aussehen lassen. Es sind vier Komponenten mit der kommerziellen Begründung, weil diese Begründung überall sonst fehlt. Wenn deine Seite auch generiert aussieht, ist das ein separates Problem mit einer separaten Lösung.

Es ist kein A/B-Test-Framework und es verspricht dir keinen Anstieg. Unterhalb von etwa vierzigtausend Sitzungen pro Variante kann ein Split-Test einen echten Effekt nicht von Rauschen trennen, was auf die meisten Shops zutrifft. Was diese vier Komponenten dir geben, ist die Beseitigung einer bekannten Auslassung, die keinen Test benötigt, um es wert zu sein.

---

Weiterführende Lektüre

• Mengenstaffelungen, die den durchschnittlichen Bestellwert steigern
• Wo man einen Upsell auf einer Produktseite platziert
• shadcn-Ecommerce-Blöcke: was existiert und was fehlt
• Upsell-Apps für Shopify oder selbst bauen

Erstellt von uxgen, dem MCP, das diese Mechaniken einem Coding-Agenten übergibt.

MIT © 2026 Angelo Palfi