# Système de design SumUp Circuit

## Aperçu de l’interface du système de design SumUp Circuit

Essayez des montants mal formés, modifiez le nom de l’article, activez ou désactivez le champ de note et consultez un aperçu local.

## Référence de conception du système de design SumUp Circuit

@sumup/circuit-ui 8.15.0 natif avec le thème clair CSS de @sumup/design-tokens 7.3.1 ; éditeur d’article local original.

### Surfaces claires et texte pour les commerçants

| Nom / règle | Valeur / configuration | Utilisation |
| --- | --- | --- |
| --cui-bg-normal | #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-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. |
### Unités d’espacement

| Nom / règle | Valeur / configuration | Utilisation |
| --- | --- | --- |
| --cui-spacings-bit | 4px | Valeurs d’espacement nommées, reprises de l’export CSS verrouillé. |
| --cui-spacings-byte | 8px | Valeurs d’espacement nommées, reprises de l’export CSS verrouillé. |
| --cui-spacings-kilo | 12px | Valeurs d’espacement nommées, reprises de l’export CSS verrouillé. |
| --cui-spacings-mega | 16px | Valeurs d’espacement nommées, reprises de l’export CSS verrouillé. |
| --cui-spacings-giga | 24px | Valeurs d’espacement nommées, reprises de l’export CSS verrouillé. |
| --cui-spacings-tera | 32px | Valeurs d’espacement nommées, reprises de l’export CSS verrouillé. |
| --cui-spacings-peta | 40px | Valeurs d’espacement nommées, reprises de l’export CSS verrouillé. |
| --cui-spacings-exa | 48px | Valeurs d’espacement nommées, reprises de l’export CSS verrouillé. |
| --cui-spacings-zetta | 56px | Valeurs d’espacement nommées, reprises de l’export CSS verrouillé. |
### Rayons des angles

| Nom / règle | Valeur / configuration | Utilisation |
| --- | --- | --- |
| --cui-border-radius-bit | 4px | Choisissez la forme selon le rôle du contrôle ou de la surface. |
| --cui-border-radius-byte | 8px | Choisissez la forme selon le rôle du contrôle ou de la surface. |
| --cui-border-radius-kilo | 12px | Choisissez la forme selon le rôle du contrôle ou de la surface. |
| --cui-border-radius-mega | 16px | Choisissez la forme selon le rôle du contrôle ou de la surface. |
| --cui-border-radius-circle | 100% | Choisissez la forme selon le rôle du contrôle ou de la surface. |
| --cui-border-radius-pill | 999999px | Choisissez la forme selon le rôle du contrôle ou de la surface. |
### Familles et graisses de polices

| Nom / règle | Valeur / configuration | Utilisation |
| --- | --- | --- |
| --cui-font-stack-default | aktiv-grotesk, Helvetica, Arial, system-ui, sans-serif, "Segoe UI", Roboto, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol" | L’exemple utilise les polices de remplacement disponibles ; il ne charge pas Aktiv Grotesk. |
| --cui-font-stack-mono | Menlo, Consolas, Monaco, Liberation Mono, Lucida Console, monospace | L’exemple utilise les polices de remplacement disponibles ; il ne charge pas Aktiv Grotesk. |
| --cui-font-weight-regular | 400 | L’exemple utilise les polices de remplacement disponibles ; il ne charge pas Aktiv Grotesk. |
| --cui-font-weight-bold | 700 | L’exemple utilise les polices de remplacement disponibles ; il ne charge pas Aktiv Grotesk. |
### États de l’action principale

| Nom / règle | Valeur / configuration | Utilisation |
| --- | --- | --- |
| --cui-bg-accent-strong | #0f131a | Conservez des états distincts pour le mode normal, le survol, l’activation et la désactivation. |
| --cui-bg-accent-strong-hovered | #3b3f46 | Conservez des états distincts pour le mode normal, le survol, l’activation et la désactivation. |
| --cui-bg-accent-strong-pressed | #6a737c | Conservez des états distincts pour le mode normal, le survol, l’activation et la désactivation. |
| --cui-bg-accent-strong-disabled | rgba(15, 19, 26, .4) | Conservez des états distincts pour le mode normal, le survol, l’activation et la désactivation. |
### Props publiques des champs et boutons

| Nom / règle | Valeur / configuration | Utilisation |
| --- | --- | --- |
| Input.label | required string | Objectif visible du champ. |
| Input.invalid | boolean | Style natif d’erreur et état d’accessibilité. |
| Input.validationHint | string | Affichez une instruction précise sous le contrôle. |
| Button.variant | primary / secondary / tertiary | Hiérarchie des actions dans cette version verrouillée. |
| Button.size | s / m | Valeurs de taille actuelles dans la version 8.15.0. |
| Button.stretch | boolean | Étendez l’action de vérification locale à toute la largeur du conteneur parent. |
## Guide complet du système de design SumUp Circuit

Un guide pratique pour choisir, appliquer et évaluer ce système dans une interface réelle.

Des conseils complets, un point de départ pour la mise en œuvre et des liens vers les sources.

## 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

Intl.NumberFormat formate en euros le montant local validé. Le prix ressort davantage que la description de l’article et reste visible dans l’aperçu client. Si le brouillon est mal formé, un tiret cadratin s’affiche plutôt qu’un zéro trompeur ou un montant partiellement analysé.

## 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.

1. Effacez le nom et envoyez le formulaire pour examiner l’erreur du premier champ.

2. Essayez 24abc ou zéro, puis corrigez le montant en saisissant 24.50.

3. 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

Un parcours de paiement en production nécessite sa propre intégration à un service autorisé, une gestion validée des devises et des réponses du serveur. Cet exemple s’arrête volontairement à l’examen d’une présentation locale. Conservez cette formulation lorsque vous réutilisez l’exemple, tant qu’un véritable parcours de transaction n’est pas en place.

## 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.

```
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 />);
```

Référence du code

- Créez un projet Vite React, conservez <div id="root"></div> et chargez ce fichier comme src/main.jsx.

### circuit.css — composition responsive d’origine

Mise en page de l’application construite autour des composants natifs.

```
* {
  box-sizing: border-box;
}
body {
  margin: 0;
  background: var(--cui-bg-normal);
  color: var(--cui-fg-normal);
  font: 16px/1.5 var(--cui-font-stack-default);
}
.circuit-example {
  padding: 32px;
}
.circuit-example header {
  max-width: 720px;
  margin-bottom: 32px;
}
.eyebrow {
  font-size: 12px;
  letter-spacing: 0.08em;
  margin-bottom: 12px;
  color: var(--cui-fg-subtle);
}
.circuit-grid {
  display: grid;
  grid-template-columns: minmax(0, 1fr) minmax(300px, 1fr);
  gap: 48px;
}
.circuit-example h2 {
  font-size: 20px;
  font-weight: 700;
  margin: 0 0 24px;
}
.circuit-example form {
  max-width: 540px;
  display: flex;
  flex-direction: column;
  gap: 24px;
}
.circuit-example form h2 {
  margin: 0;
}
.preview-surface {
  background: var(--cui-bg-subtle);
  padding: 28px;
  border-radius: 16px;
}
.preview-surface > h2 {
  font-size: 14px;
  color: var(--cui-fg-subtle);
  text-align: center;
}
.receipt {
  max-width: 340px;
  margin: auto;
  background: white;
  border-radius: 12px;
  box-shadow: 0 4px 20px #0000000d;
  padding: 24px;
}
.shop-mark {
  width: 40px;
  height: 40px;
  border-radius: 50%;
  background: #0f131a;
  color: #fff;
  display: grid;
  place-items: center;
  font-weight: 700;
  margin: auto;
}
.shop-name {
  text-align: center;
  font-size: 14px;
  margin: 12px 0 20px;
}
.print-art {
  height: 150px;
  background: #f5dfbb;
  position: relative;
  overflow: hidden;
  border-radius: 8px;
}
.print-art i {
  position: absolute;
  left: 24px;
  bottom: 0;
  width: 100px;
  height: 130px;
  border-radius: 60px 60px 0 0;
  background: #ce663d;
}
.print-art b {
  position: absolute;
  right: 20px;
  top: 20px;
  width: 90px;
  height: 90px;
  border-radius: 50%;
  background: #385d50;
}
.print-art span {
  position: absolute;
  left: 0;
  right: 0;
  bottom: 0;
  height: 24px;
  background: #202e2a;
}
.receipt h3 {
  font-size: 20px;
  line-height: 1.3;
  margin: 20px 0 8px;
  overflow-wrap: anywhere;
}
.receipt-price {
  font-size: 28px;
  font-weight: 700;
  margin: 0 0 24px;
}
.note-placeholder {
  padding: 12px;
  border: 1px solid #bfc6cf;
  border-radius: 8px;
  margin-bottom: 16px;
  font-size: 12px;
}
.note-placeholder span {
  font-weight: 700;
}
.note-placeholder p {
  margin: 4px 0 0;
  color: #4f5a65;
}
.preview-action {
  background: #e9edf2;
  text-align: center;
  border-radius: 999px;
  padding: 12px;
  font-size: 12px;
  color: #4f5a65;
}
.review {
  padding: 20px;
  background: #e7f5ef;
  border-radius: 8px;
}
.review p {
  margin: 8px 0;
}
.review small {
  font-size: 12px;
}
.circuit-example footer {
  font-size: 12px;
  color: var(--cui-fg-subtle);
  margin-top: 32px;
}
@media (max-width: 850px) {
  .circuit-grid {
    grid-template-columns: 1fr;
    gap: 32px;
  }
  .circuit-example form {
    max-width: none;
  }
}
@media (max-width: 550px) {
  .circuit-example {
    padding: 20px 16px;
  }
  .preview-surface {
    padding: 20px;
  }
  .receipt {
    padding: 20px;
  }
}
```

Référence du code

- 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.

## 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.

```
npm create vite@latest circuit-item -- --template react
cd circuit-item
npm install
npm install react@18.3.1 react-dom@18.3.1 @sumup/circuit-ui@8.15.0 @sumup/design-tokens@7.3.1 @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

```
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.
```

## 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.

- Documentation Circuit Documentation à jour sur les composants et leur intégration.

- Tokens clairs épinglés Valeurs exactes utilisées dans cet exemple.

- Code source Circuit Versions des packages, propriétés des composants et espace de noms actuel.

## Ressources connexes du système de design SumUp Circuit

### TDesign

Créez un éditeur de règles compact API avec TDesign React : des rôles de thème concrets, son échelle de tailles par incréments de deux pixels, l’enregistrement des champs Form et une composition Table typée.

### Thumbtack Thumbprint

Créez une interface de découverte de services avec les primitives documentées de Thumbprint v2 : des cartes de prestataires compactes, des détails de comparaison faciles à lire, des états de sélection clairs et une présélection toujours accessible.

### Twilio Paste

Rédigez une notification avec le thème et les conventions de boutons de Paste, une échelle d’espacement vérifiée et une distinction claire entre la modification, la révision et l’envoi effectif d’un message.


- [Référence de mise en œuvre](https://circuit.sumup.com/)
- [Source](https://cdn.jsdelivr.net/npm/@sumup/design-tokens@7.3.1/light.css)
- [Source](https://github.com/sumup-oss/circuit-ui)
- [Référence du code](https://circuit.sumup.com/)
- [Documentation Circuit Documentation à jour sur les composants et leur intégration.](https://circuit.sumup.com/)
- [Tokens clairs épinglés Valeurs exactes utilisées dans cet exemple.](https://cdn.jsdelivr.net/npm/@sumup/design-tokens@7.3.1/light.css)
- [Code source Circuit Versions des packages, propriétés des composants et espace de noms actuel.](https://github.com/sumup-oss/circuit-ui)