Un guide Circuit avec des tokens sémantiques exacts, des propriétés natives de validation, un éditeur complet de fiches marchand et un aperçu illustré côté client.
Référence sémantique du thème clair marchand ; n’utilisez pas une couleur de surface comme couleur de premier plan sans vérifier la combinaison prévue.
--cui-bg-subtle
#f0f1f5
Référence sémantique du thème clair marchand ; n’utilisez pas une couleur de surface comme couleur de premier plan sans vérifier la combinaison prévue.
--cui-bg-strong
#000
Référence sémantique du thème clair marchand ; n’utilisez pas une couleur de surface comme couleur de premier plan sans vérifier la combinaison prévue.
--cui-bg-accent-strong
#0f131a
Référence sémantique du thème clair marchand ; n’utilisez pas une couleur de surface comme couleur de premier plan sans vérifier la combinaison prévue.
--cui-fg-normal
#0f131a
Référence sémantique du thème clair marchand ; n’utilisez pas une couleur de surface comme couleur de premier plan sans vérifier la combinaison prévue.
--cui-fg-subtle
#6a737c
Référence sémantique du thème clair marchand ; n’utilisez pas une couleur de surface comme couleur de premier plan sans vérifier la combinaison prévue.
--cui-fg-on-strong
#fff
Référence sémantique du thème clair marchand ; n’utilisez pas une couleur de surface comme couleur de premier plan sans vérifier la combinaison prévue.
--cui-fg-success
#018850
Référence sémantique du thème clair marchand ; n’utilisez pas une couleur de surface comme couleur de premier plan sans vérifier la combinaison prévue.
--cui-fg-danger
#de331d
Référence sémantique du thème clair marchand ; n’utilisez pas une couleur de surface comme couleur de premier plan sans vérifier la combinaison prévue.
--cui-border-normal
#aeb6be
Référence sémantique du thème clair marchand ; n’utilisez pas une couleur de surface comme couleur de premier plan sans vérifier la combinaison prévue.
Composition de l’éditeur marchand du système de design SumUp Circuit
Séparez la saisie du commerçant de la présentation au client
L’éditeur d’article et l’aperçu de type reçu présentent deux vues du même état. Un formulaire concis permet de nommer l’article, de définir un montant indicatif et de choisir si un champ de note destiné au client s’affiche. L’aperçu montre le résultat sans créer de processus de paiement ni demander d’informations de paiement.
Utilisez une illustration de produit originale
L’illustration géométrique est une création originale CSS accompagnée d’une description accessible. Elle donne à l’aperçu client un objet reconnaissable plutôt qu’un rectangle d’image vide, sans recourir à une fausse photo de commerçant ni à un visuel de produit SumUp copié.
Thème sémantique et périmètre du package du système de design SumUp Circuit
Utilisez exactement le thème verrouillé
Cet exemple utilise @sumup/circuit-ui 8.15.0 avec @sumup/design-tokens 7.3.1. Le tableau de référence est extrait du fichier light.css de ce package. La documentation actuelle en amont privilégie désormais l’espace de noms @sumup-oss ; il s’agit d’une intégration reproductible sur des versions verrouillées, et non d’une affirmation selon laquelle l’ancien espace de noms serait la version la plus récente.
Chargez les styles des composants et des jetons
L’entrée React importe à la fois la feuille de styles des composants et le fichier de tokens clairs. Les noms de classes des composants ne suffisent pas si leurs propriétés personnalisées CSS n’ont pas été définies. Une palette sombre à portée limitée nécessiterait également un thème de base complet pour fournir les valeurs partagées autres que les couleurs.
Surfaces neutres et contraste des actions du système de design SumUp Circuit
Gardez l’article au centre de l’attention visuelle
L’éditeur utilise une surface blanche et un premier plan sombre, tandis que l’aperçu client repose sur un fond neutre discret. L’illustration d’origine apporte une touche de couleur maîtrisée à l’image de l’article, sans nuire à la lisibilité de l’action principale native, qui reste facile à repérer.
Montrez clairement que l’action de l’aperçu n’est pas interactive
Le pied de page côté client est un bloc de texte intitulé « Aperçu uniquement », et non un bouton de paiement désactivé qui laisserait croire que le paiement est presque prêt. La seule véritable action d’envoi appartient à l’éditeur et sert à examiner un article local. Cela aide les utilisateurs à comprendre les limites réelles des interactions de cet exemple.
Typographie et polices de remplacement du système de design SumUp Circuit
Utilisez honnêtement la pile de polices du thème
La pile publiée commence par Aktiv Grotesk, puis comprend Helvetica, Arial et les polices système de remplacement. Cet exemple hors ligne ne télécharge pas la première police. Ses composants natifs Headline et Body assurent tout de même la hiérarchie prévue, tandis que les polices disponibles déterminent la forme finale des caractères.
Gardez le montant et sa devise ensemble
Espacement et surfaces arrondies du système de design SumUp Circuit
Utilisez la séquence d’étapes nommée
L’échelle des tokens utilise les noms bit, byte, kilo, mega et les suivants. Il s’agit de libellés de design, et non de puissances de deux. Le tableau conserve les valeurs exactes en pixels afin que les développeurs n’inventent pas une échelle à partir de cette métaphore.
Alignez les bords des contrôles sans aplatir la hiérarchie
Le formulaire utilise un espacement vertical uniforme et une action principale sur toute la largeur. L’aperçu présente une grande surface extérieure arrondie et un reçu intérieur plus petit. Sur téléphone, l’aperçu suit le formulaire, et les marges intérieures sont réduites avant de comprimer les contrôles.
Validation des articles et état de brouillon du système de design SumUp Circuit
Validez la chaîne complète avant de la formater
L’application accepte un à cinq chiffres entiers, jusqu’à deux décimales et une valeur numérique positive. Il s’agit d’une règle propre à cet exemple. Elle évite que parseFloat accepte une chaîne partielle telle que 24abc et place le curseur dans le premier champ Input natif invalide après l’envoi.
Effacez l’examen précédent à chaque modification
Toute modification du nom, du montant ou de l’affichage de la note invalide l’instantané précédent. L’état de réussite inclut le nom et le montant de l’article examiné : il est donc lié à un brouillon précis. Le code n’enregistre pas ce résultat dans un serveur dorsal et ne crée pas de demande de paiement.
Récupération après erreur de saisie et sémantique de l’aperçu du système de design SumUp Circuit
Testez les erreurs des deux champs
Le nom et le prix de l’article utilisent les libellés natifs required, l’état invalid et validationHint. Le code conserve des références aux champs de saisie afin de replacer le curseur dans le premier champ en erreur. Il est possible de tester la récupération après erreur sans saisir de véritables données client ou de carte bancaire.
Effacez le nom et envoyez le formulaire pour examiner l’erreur du premier champ.
Essayez 24abc ou zéro, puis corrigez le montant en saisissant 24.50.
Examinez l’article localement, puis modifiez un champ pour fermer l’instantané obsolète.
Décrivez honnêtement l’illustration et l’aperçu statique
L’illustration est accompagnée d’une courte description de son rôle. La zone de note client est un texte indicatif explicatif dans un aperçu clairement signalé, et non un faux champ modifiable. La véritable case à cocher qui règle l’affichage de la note reste dans le formulaire marchand et détermine si cette zone de l’aperçu apparaît.
Intégration de React et CSS au système de design SumUp Circuit
Incluez les dépendances publiques et les deux feuilles de styles
L’entrée utilise React 18 et les composants Circuit épinglés, ainsi que les dépendances de tokens, d’icônes, d’internationalisation et d’Emotion requises par le package. Le code importe explicitement light.css et styles.css. Il ne dépend ni d’un fournisseur non documenté ni d’une configuration de thème masquée à l’échelle du projet.
Styles des composants @sumup/circuit-ui 8.15.0.
Thème clair complet @sumup/design-tokens 7.3.1.
React 18 et les dépendances déclarées par le package de composants.
N’ajoutez des services de paiement que dans une véritable application
Exemples de composants du système de design SumUp Circuit
main.jsx — exemple complet fonctionnel
Modifiez un article et examinez son aperçu côté client. Le code source ci-dessous correspond à l’entrée React complète, avec tous les états et la validation.
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 />);
Enregistrez ce fichier à côté de main.jsx. Ces règles de composition personnalisées se distinguent de la référence des jetons de la bibliothèque.
04
Configuration de l’agent IA pour le système de design SumUp Circuit
Point de départ de l’implémentation
L’exemple natif épinglé a été assemblé et vérifié localement dans un navigateur. Cet exemple utilise uniquement l’état local de l’application.
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
Un prompt pour votre projet
Prompt pour l’agent IA
Créez un éditeur d’articles Circuit avec les contrôles natifs épinglés et les deux feuilles de styles requises. Validez les chaînes de montant complètes, préservez le formatage des devises, effacez l’examen local obsolète après toute modification et distinguez clairement l’aperçu côté client d’un véritable paiement. Utilisez l’illustration d’origine et les rôles exacts des tokens sémantiques.
05
Sources et périmètre du système de design SumUp Circuit
Guide d’application OpenDesign pour une version épinglée du package Circuit. L’illustration, le montant et l’article sont des exemples. Cet éditeur local ne crée ni lien de paiement, ni prélèvement, ni action sur un compte SumUp ; les packages amont actuels utilisent le nouvel espace de noms @sumup-oss.
