Ein Circuit-Leitfaden mit exakten semantischen Tokens, nativen Validierungs-Props, einem vollständigen Editor für Händlerartikel und einer illustrierten Vorschau aus Kundensicht.
Zusammenstellung des Händlereditors für das SumUp Circuit-Designsystem
Händlereingabe und Kundendarstellung trennen
Der Artikeleditor und die kassenbonartige Vorschau zeigen zwei Ansichten desselben Zustands. In einem kurzen Formular wird der Artikel benannt, ein beispielhafter Betrag festgelegt und ausgewählt, ob ein Notizfeld für Kunden angezeigt wird. Die Vorschau veranschaulicht die Wirkung, ohne einen Bezahlvorgang zu starten oder Zahlungsinformationen anzufordern.
Eine eigene Produktillustration verwenden
Die geometrische Druckgrafik ist eine eigens erstellte Illustration von CSS mit einer barrierefreien Beschreibung. Sie zeigt in der Kundenvorschau ein erkennbares Objekt statt eines leeren Bildrahmens und vermeidet zugleich ein vorgetäuschtes Händlerfoto oder ein kopiertes SumUp-Produktbild.
SumUp Circuit Designsystem: semantisches Theme und Paketumfang
Das exakt angeheftete Theme verwenden
Dieses Beispiel verwendet @sumup/circuit-ui 8.15.0 mit @sumup/design-tokens 7.3.1. Die Referenztabelle wird aus light.css dieses Pakets ausgelesen. Die aktuelle Upstream-Dokumentation ist inzwischen auf den Namespace @sumup-oss umgestellt; dies ist eine reproduzierbare Integration mit angehefteten Versionen und keine Behauptung, dass der ältere Namespace die neueste Version ist.
Komponentenstile und Tokenstile laden
Der Einstiegspunkt React importiert sowohl das Stylesheet der Komponenten als auch die helle Token-Datei. Die Klassennamen der Komponenten reichen nicht aus, wenn ihre benutzerdefinierten Eigenschaften CSS nicht definiert wurden. Eine abgegrenzte dunkle Palette benötigt außerdem ein vollständiges Basistheme, das gemeinsame Werte außerhalb der Farben bereitstellt.
Neutrale Oberflächen und Aktionskontrast im SumUp Circuit-Designsystem
Den Artikel als Blickfang beibehalten
Der Editor verwendet eine weiße Oberfläche und einen dunklen Vordergrund, während die Kundenvorschau auf einem dezenten neutralen Hintergrund liegt. Die eigene Illustration bringt gezielt Farbe in das Artikelbild und lässt die native primäre Aktion gut lesbar und leicht auffindbar.
Die Aktion in der Vorschau eindeutig als nicht interaktiv kennzeichnen
Die Fußzeile aus Kundensicht ist ein Textblock mit der Kennzeichnung „Nur Vorschau“ und keine deaktivierte Schaltfläche „Bezahlen“, die einen fast funktionierenden Bezahlvorgang suggeriert. Die einzige echte Aktion zum Absenden gehört zum Editor und prüft einen Artikel lokal. So verstehen Nutzer, wo die Interaktionsmöglichkeiten dieses Beispiels enden.
Typografie und Fallbacks im SumUp Circuit-Designsystem
Die Schriftarten des Themes transparent angeben
Der veröffentlichte Schriftartenstapel beginnt mit Aktiv Grotesk und umfasst Helvetica, Arial sowie System-Fallbacks. Dieses Offline-Beispiel lädt die zuerst genannte Schriftart nicht herunter. Die nativen Headline- und Body-Komponenten sorgen dennoch für die vorgesehene Hierarchie; die verfügbaren Schriftarten bestimmen die endgültige Form der Zeichen.
Betrag und Währung zusammenhalten
Abstände und abgerundete Oberflächen im SumUp Circuit-Designsystem
Die benannte Abstufung verwenden
Die Token-Skala verwendet die Bezeichnungen bit, byte, kilo, mega und weitere größere Stufen. Dabei handelt es sich um Designbezeichnungen, nicht um Zweierpotenzen. Die Tabelle enthält die exakten Pixelwerte, damit Entwickler keine Skala aus der Namensmetapher ableiten müssen.
Steuerungselemente bündig ausrichten, ohne die Hierarchie aufzuheben
Das Formular verwendet einen einheitlichen vertikalen Abstand und eine primäre Aktion über die gesamte Breite. Die Vorschau besteht aus einer größeren, abgerundeten Außenfläche und einem kleineren Kassenbon-Innenbereich. Auf dem Smartphone folgt die Vorschau auf das Formular; die Abstände werden verringert, bevor die Steuerelemente zusammengeschoben werden.
Artikelvalidierung und Entwurfszustand im SumUp Circuit-Designsystem
Vor der Formatierung die vollständige Zeichenfolge validieren
Die Anwendung akzeptiert ein bis fünf Ziffern vor dem Komma und bis zu zwei Nachkommastellen, sofern der Zahlenwert positiv ist. Dies ist eine eigens festgelegte Beispielregel. So wird verhindert, dass parseFloat Teilzeichenfolgen wie 24abc akzeptiert. Nach dem Absenden wird das erste ungültige native Input fokussiert.
Bei jeder Änderung die veraltete Prüfung verwerfen
Änderungen am Namen, Betrag oder der Sichtbarkeit der Notiz machen die vorherige Momentaufnahme ungültig. Der Erfolgszustand enthält den geprüften Artikelnamen und Betrag und ist damit an einen konkreten Entwurf gebunden. Der Code speichert dieses Ergebnis weder in einem Backend noch erstellt er eine Zahlungsanforderung.
Fehlerkorrektur und Bedeutung der Vorschau im SumUp Circuit-Designsystem
Beide Feldfehler ausprobieren
Für Artikelname und Preis werden native Pflichtfeldkennzeichnungen, der ungültige Zustand und validationHint verwendet. Im Quellcode bleiben Referenzen auf die Eingabefelder erhalten, damit der Fokus zum ersten fehlerhaften Feld zurückkehrt. Die Fehlerbehandlung lässt sich testen, ohne echte Kunden- oder Kartendaten einzugeben.
Leere den Namen und sende das Formular ab, um den ersten Feldfehler zu sehen.
Probiere 24abc oder null aus und korrigiere den Betrag anschließend auf 24.50.
Prüfe den Eintrag lokal und bearbeite ein Feld, um die veraltete Momentaufnahme zu verwerfen.
Illustration und statische Vorschau eindeutig kennzeichnen
Das Motiv hat eine kurze Beschreibung seiner Bildfunktion. Der Kundenhinweis ist ein erläuternder Platzhalter in einer ausdrücklich gekennzeichneten Vorschau, kein vorgetäuschtes bearbeitbares Eingabefeld. Die echte Checkbox zum Aktivieren des Hinweises befindet sich im Händlerformular und steuert, ob dieser Vorschauabschnitt angezeigt wird.
SumUp Circuit-Designsystem React und CSS-Integration
Die öffentlichen Peer-Abhängigkeiten und beide Stylesheets einbinden
Der Eintrag verwendet React 18 und die festgelegten Circuit-Komponenten. Token-, Icon-, Internationalisierungs- und Emotion-Peer-Abhängigkeiten entsprechen den Paketvorgaben. Der Code bindet light.css und styles.css explizit ein. Er setzt weder einen undokumentierten Provider noch eine verborgene Theme-Konfiguration auf Projektebene voraus.
Komponentenstile von @sumup/circuit-ui 8.15.0.
Vollständiges helles Theme von @sumup/design-tokens 7.3.1.
React 18 und die deklarierten Peer-Abhängigkeiten des Komponentenpakets.
Zahlungsdienste nur in einer echten Anwendung hinzufügen
SumUp Circuit-Designsystem: Komponentenbeispiele
main.jsx — vollständiges, funktionsfähiges Beispiel
Bearbeite einen Artikel und prüfe die Vorschau aus Kundensicht. Der folgende Quelltext enthält den vollständigen React-Eintrag einschließlich aller Zustände und Validierungen.
jsx
import React, { useState, useRef } from "react";
import { createRoot } from "react-dom/client";
import { Input, Checkbox, Button, Headline, Body } from "@sumup/circuit-ui";
import "@sumup/design-tokens/light.css";
import "@sumup/circuit-ui/styles.css";
import "./circuit.css";
function App() {
const [name, setName] = useState("Studio print"),
[price, setPrice] = useState("24.00"),
[note, setNote] = useState(true),
[errors, setErrors] = useState({}),
[review, setReview] = useState(null);
const nameRef = useRef(),
priceRef = useRef();
const valid = /^\d{1,5}(\.\d{1,2})?$/.test(price) && Number(price) > 0;
const amount = valid
? new Intl.NumberFormat("en-IE", {
style: "currency",
currency: "EUR",
}).format(Number(price))
: "—";
function change(fn) {
fn();
setReview(null);
setErrors({});
}
function submit(e) {
e.preventDefault();
const next = {};
if (!name.trim()) next.name = "Enter an item name.";
if (!valid)
next.price = "Use a positive amount with up to two decimal places.";
setErrors(next);
if (next.name) {
nameRef.current.focus();
return;
}
if (next.price) {
priceRef.current.focus();
return;
}
setReview({ name: name.trim(), amount, note });
}
return (
<main className="circuit-example">
<header>
<p className="eyebrow">MERCHANT TOOLS / LOCAL SPECIMEN</p>
<Headline as="h1">Prepare a simple item</Headline>
<Body>
Review how an item could appear to a customer. This example never
creates a payment link.
</Body>
</header>
<div className="circuit-grid">
<form onSubmit={submit} noValidate>
<h2>Item details</h2>
<Input
ref={nameRef}
label="Item name"
required
value={name}
maxLength={80}
invalid={!!errors.name}
validationHint={
errors.name || "Use a short name the customer can recognize."
}
onChange={(e) => change(() => setName(e.target.value))}
/>
<Input
ref={priceRef}
label="Price in EUR"
required
inputMode="decimal"
value={price}
invalid={!!errors.price}
validationHint={
errors.price || "Example amount only; no charge will be made."
}
onChange={(e) => change(() => setPrice(e.target.value))}
/>
<Checkbox
label="Show a customer note field"
checked={note}
onChange={(e) => change(() => setNote(e.target.checked))}
/>
<Button variant="primary" type="submit" stretch>
Review item locally
</Button>
{review && (
<div className="review" role="status">
<strong>Item reviewed</strong>
<p>
{review.name} · {review.amount}
</p>
<small>
Local snapshot only. No payment link or charge created.
</small>
</div>
)}
</form>
<section className="preview-surface" aria-labelledby="preview-heading">
<h2 id="preview-heading">Customer-side preview</h2>
<div className="receipt">
<div className="shop-mark" aria-hidden="true">
N
</div>
<p className="shop-name">Northstar Studio</p>
<div
className="print-art"
role="img"
aria-label="Original geometric print illustration"
>
<i></i>
<b></b>
<span></span>
</div>
<h3>{name.trim() || "Your item name"}</h3>
<p className="receipt-price">{amount}</p>
{note && (
<div className="note-placeholder">
<span>Customer note</span>
<p>A note field would appear here.</p>
</div>
)}
<div className="preview-action">
Preview only · checkout unavailable
</div>
</div>
</section>
</div>
<footer>
Native Circuit UI 8.15.0 components and design tokens 7.3.1. Original
item editor and illustration by OpenDesign.
</footer>
</main>
);
}
createRoot(document.getElementById("root")).render(<App />);
Speichern Sie die Datei neben main.jsx. Diese benutzerdefinierten Layoutregeln sind von der Token-Referenz der Bibliothek getrennt.
04
SumUp Circuit-Designsystem: Einrichtung des Agents
Ausgangspunkt für die Implementierung
Das Beispiel mit den festgelegten nativen Komponenten wurde gebündelt und lokal im Browser geprüft. Das Beispiel verwendet ausschließlich den lokalen Anwendungszustand.
sh
npm create vite@latest circuit-item -- --template react
cd circuit-item
npm install
npm install [email protected][email protected] @sumup/[email protected] @sumup/[email protected] @sumup/icons @sumup/intl@1 @emotion/react @emotion/styled @emotion/is-prop-valid
# Replace src/main.jsx and add src/circuit.css.
npm run dev
Ein Prompt für dein Projekt
Agenten-Prompt
Erstelle einen Circuit-Artikeleditor mit den festgelegten nativen Steuerelementen und beiden erforderlichen Stylesheets. Validiere vollständige Betragsangaben, behalte die Währungsformatierung bei, setze nach Änderungen eine veraltete lokale Prüfung zurück und halte die Kundenvorschau klar von einem echten Bezahlvorgang getrennt. Verwende die ursprüngliche Illustration und die exakten semantischen Token-Rollen.
05
SumUp Circuit-Designsystem: Quellen und Geltungsbereich
OpenDesign-Anwendungsleitfaden für eine festgelegte Generation des Circuit-Pakets. Illustration, Betrag und Artikel sind Beispiele. Dieser lokale Editor erstellt weder einen Zahlungslink noch eine Belastung oder eine Aktion für ein SumUp-Konto. Aktuelle Upstream-Pakete verwenden den neueren Namespace @sumup-oss.
