# Sistema di design SumUp Circuit

## Anteprima dell’interfaccia del sistema di design SumUp Circuit

Prova importi non validi, modifica il nome dell’articolo, attiva o disattiva il campo delle note e controlla un’istantanea locale.

## Riferimento di design del sistema sistema di design SumUp Circuit

@sumup/circuit-ui 8.15.0 nativo con il tema chiaro CSS di @sumup/design-tokens 7.3.1; editor di articoli locale originale.

### Superfici chiare e testo per esercenti

| Nome / regola | Valore / configurazione | Utilizzo |
| --- | --- | --- |
| --cui-bg-normal | #fff | Riferimento semantico chiaro per esercenti; non usare un colore di superficie come primo piano senza verificarne l’abbinamento previsto. |
| --cui-bg-subtle | #f0f1f5 | Riferimento semantico chiaro per esercenti; non usare un colore di superficie come primo piano senza verificarne l’abbinamento previsto. |
| --cui-bg-strong | #000 | Riferimento semantico chiaro per esercenti; non usare un colore di superficie come primo piano senza verificarne l’abbinamento previsto. |
| --cui-bg-accent-strong | #0f131a | Riferimento semantico chiaro per esercenti; non usare un colore di superficie come primo piano senza verificarne l’abbinamento previsto. |
| --cui-fg-normal | #0f131a | Riferimento semantico chiaro per esercenti; non usare un colore di superficie come primo piano senza verificarne l’abbinamento previsto. |
| --cui-fg-subtle | #6a737c | Riferimento semantico chiaro per esercenti; non usare un colore di superficie come primo piano senza verificarne l’abbinamento previsto. |
| --cui-fg-on-strong | #fff | Riferimento semantico chiaro per esercenti; non usare un colore di superficie come primo piano senza verificarne l’abbinamento previsto. |
| --cui-fg-success | #018850 | Riferimento semantico chiaro per esercenti; non usare un colore di superficie come primo piano senza verificarne l’abbinamento previsto. |
| --cui-fg-danger | #de331d | Riferimento semantico chiaro per esercenti; non usare un colore di superficie come primo piano senza verificarne l’abbinamento previsto. |
| --cui-border-normal | #aeb6be | Riferimento semantico chiaro per esercenti; non usare un colore di superficie come primo piano senza verificarne l’abbinamento previsto. |
### Unità di spaziatura

| Nome / regola | Valore / configurazione | Utilizzo |
| --- | --- | --- |
| --cui-spacings-bit | 4px | Valori di spaziatura con nome, ripresi dall’export bloccato a una versione specifica di CSS. |
| --cui-spacings-byte | 8px | Valori di spaziatura con nome, ripresi dall’export bloccato a una versione specifica di CSS. |
| --cui-spacings-kilo | 12px | Valori di spaziatura con nome, ripresi dall’export bloccato a una versione specifica di CSS. |
| --cui-spacings-mega | 16px | Valori di spaziatura con nome, ripresi dall’export bloccato a una versione specifica di CSS. |
| --cui-spacings-giga | 24px | Valori di spaziatura con nome, ripresi dall’export bloccato a una versione specifica di CSS. |
| --cui-spacings-tera | 32px | Valori di spaziatura con nome, ripresi dall’export bloccato a una versione specifica di CSS. |
| --cui-spacings-peta | 40px | Valori di spaziatura con nome, ripresi dall’export bloccato a una versione specifica di CSS. |
| --cui-spacings-exa | 48px | Valori di spaziatura con nome, ripresi dall’export bloccato a una versione specifica di CSS. |
| --cui-spacings-zetta | 56px | Valori di spaziatura con nome, ripresi dall’export bloccato a una versione specifica di CSS. |
### Raggi degli angoli

| Nome / regola | Valore / configurazione | Utilizzo |
| --- | --- | --- |
| --cui-border-radius-bit | 4px | Scegli la forma in base al ruolo del controllo o della superficie. |
| --cui-border-radius-byte | 8px | Scegli la forma in base al ruolo del controllo o della superficie. |
| --cui-border-radius-kilo | 12px | Scegli la forma in base al ruolo del controllo o della superficie. |
| --cui-border-radius-mega | 16px | Scegli la forma in base al ruolo del controllo o della superficie. |
| --cui-border-radius-circle | 100% | Scegli la forma in base al ruolo del controllo o della superficie. |
| --cui-border-radius-pill | 999999px | Scegli la forma in base al ruolo del controllo o della superficie. |
### Famiglie e pesi dei font

| Nome / regola | Valore / configurazione | Utilizzo |
| --- | --- | --- |
| --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’esempio usa i fallback disponibili; non scarica Aktiv Grotesk. |
| --cui-font-stack-mono | Menlo, Consolas, Monaco, Liberation Mono, Lucida Console, monospace | L’esempio usa i fallback disponibili; non scarica Aktiv Grotesk. |
| --cui-font-weight-regular | 400 | L’esempio usa i fallback disponibili; non scarica Aktiv Grotesk. |
| --cui-font-weight-bold | 700 | L’esempio usa i fallback disponibili; non scarica Aktiv Grotesk. |
### Stati dell’azione primaria

| Nome / regola | Valore / configurazione | Utilizzo |
| --- | --- | --- |
| --cui-bg-accent-strong | #0f131a | Mantieni distinti gli stati normale, hover, premuto e disabilitato. |
| --cui-bg-accent-strong-hovered | #3b3f46 | Mantieni distinti gli stati normale, hover, premuto e disabilitato. |
| --cui-bg-accent-strong-pressed | #6a737c | Mantieni distinti gli stati normale, hover, premuto e disabilitato. |
| --cui-bg-accent-strong-disabled | rgba(15, 19, 26, .4) | Mantieni distinti gli stati normale, hover, premuto e disabilitato. |
### Props pubbliche per campi di input e pulsanti

| Nome / regola | Valore / configurazione | Utilizzo |
| --- | --- | --- |
| Input.label | required string | Scopo visibile del campo. |
| Input.invalid | boolean | Stile nativo di errore e stato di accessibilità. |
| Input.validationHint | string | Mostra un’istruzione specifica sotto il controllo. |
| Button.variant | primary / secondary / tertiary | Gerarchia delle azioni in questa versione bloccata a una versione specifica. |
| Button.size | s / m | Valori delle dimensioni attuali nella versione 8.15.0. |
| Button.stretch | boolean | Estendi l’azione di revisione locale a tutta la larghezza del contenitore. |
## Guida completa al sistema di design SumUp Circuit

Una guida pratica per scegliere, applicare e valutare questo sistema in un’interfaccia reale.

Indicazioni complete, un punto di partenza per l’implementazione e link alle fonti.

## Composizione dell’editor per esercenti del sistema di design SumUp Circuit

### Separa l’input per l’esercente dalla presentazione al cliente

> L’editor dell’articolo e l’anteprima simile a una ricevuta mostrano due viste dello stesso stato. Un modulo breve assegna un nome all’articolo, imposta un importo illustrativo e consente di scegliere se mostrare un campo per le note del cliente. L’anteprima illustra il risultato senza avviare un checkout né richiedere informazioni di pagamento.

### Usa un’illustrazione originale del prodotto

L’immagine della stampa geometrica è un’opera originale realizzata con CSS e accompagnata da una descrizione accessibile. Rende riconoscibile l’oggetto nell’anteprima cliente invece di lasciare un rettangolo vuoto, evitando al contempo finte fotografie dell’esercente o risorse di prodotto SumUp copiate.

## Tema semantico e ambito dei pacchetti del sistema di design SumUp Circuit

### Usa il tema esatto bloccato a una versione specifica

Questo esempio usa @sumup/circuit-ui 8.15.0 con @sumup/design-tokens 7.3.1. La tabella di riferimento è ricavata da light.css di quel pacchetto. La documentazione upstream attuale si è spostata verso lo spazio dei nomi @sumup-oss; questa è un’integrazione riproducibile con versioni bloccate, non un’affermazione che lo spazio dei nomi precedente sia quello della versione più recente.

### Carica gli stili dei componenti e i token

L’entry React importa sia il foglio di stile dei componenti sia il file dei token chiari. I soli nomi delle classi dei componenti non bastano se le relative proprietà personalizzate CSS non sono definite. Anche una palette scura con ambito limitato richiederebbe un tema di base completo, per fornire i valori condivisi non legati al colore.

## Superfici neutre e contrasto delle azioni nel sistema di design SumUp Circuit

### Mantieni l’articolo al centro dell’attenzione visiva

L’editor usa una superficie bianca e un primo piano scuro, mentre l’anteprima cliente si trova su uno sfondo neutro discreto. L’opera originale aggiunge colore controllato all’immagine dell’articolo, lasciando l’azione primaria nativa leggibile e facile da individuare.

### Rendi chiaramente non interattiva l’azione dell’anteprima

Il piè di pagina lato cliente è un blocco di testo con l’etichetta «Solo anteprima», non un pulsante «Paga» disabilitato che suggerisce un checkout quasi funzionante. L’unica vera azione di invio appartiene all’editor e serve a rivedere un articolo in locale. In questo modo è più chiaro quali siano i limiti effettivi di interazione dell’esempio.

## Tipografia e fallback del sistema di design SumUp Circuit

### Usa con trasparenza lo stack del tema

Lo stack pubblicato inizia con Aktiv Grotesk e include Helvetica, Arial e i fallback di sistema. Questo esempio offline non scarica il primo font. I componenti nativi Headline e Body mantengono comunque la gerarchia prevista, mentre i font disponibili determinano la forma finale dei caratteri.

### Mantieni uniti l’importo e la relativa valuta

Intl.NumberFormat formatta in euro l’importo locale convalidato. Il prezzo ha maggiore risalto visivo rispetto alla descrizione dell’articolo e rimane nell’anteprima cliente. Una bozza non valida mostra un trattino lungo, anziché uno zero fuorviante o un importo interpretato solo in parte.

## Spaziatura e superfici arrotondate del sistema di design SumUp Circuit

### Usa la sequenza dei valori nominali

La scala dei token usa i nomi bit, byte, kilo, mega e altri di valore superiore. Sono etichette di design, non potenze di due. La tabella mantiene i valori esatti in pixel, così gli sviluppatori non devono dedurre una scala dalla metafora dei nomi.

### Allinea i bordi dei controlli senza appiattire la gerarchia

Il modulo usa una spaziatura verticale costante e un’azione primaria a tutta larghezza. L’anteprima presenta una superficie esterna più grande e arrotondata e un interno più piccolo simile a una ricevuta. Sul telefono, l’anteprima segue il modulo; la spaziatura si riduce prima di comprimere i controlli.

## Convalida degli articoli e stato delle bozze nel sistema di design SumUp Circuit

### Convalida l’intera stringa prima di formattarla

L'applicazione accetta da una a cinque cifre intere e fino a due decimali, con un valore numerico positivo. Questa è una regola di esempio definita appositamente. Evita che parseFloat accetti stringhe parziali come 24abc e, dopo l'invio, porta il focus sul primo Input nativo non valido.

### Cancella la revisione non aggiornata a ogni modifica

La visibilità del nome, dell'importo e della nota invalida lo snapshot precedente. Lo stato di operazione riuscita include il nome e l'importo dell'articolo revisionato, quindi è associato a una bozza specifica. Il codice non salva questo risultato in un backend né crea una richiesta di pagamento.

## Semantica di recupero e anteprima di Input nel sistema di design SumUp Circuit

### Verifica gli errori di entrambi i campi

Il nome dell'articolo e il prezzo usano le proprietà native required, invalid e validationHint. Il codice conserva i riferimenti agli input per riportare il focus sul primo campo non valido. È possibile verificare il recupero dagli errori senza inserire dati reali di clienti o carte.

1. Cancella il nome e invia il modulo per esaminare l'errore del primo campo.

2. Prova 24abc o zero, poi correggi l'importo in 24.50.

3. Esegui la revisione in locale e modifica un campo per eliminare lo snapshot non aggiornato.

### Descrivi con precisione l'illustrazione e l'anteprima statica

L'illustrazione ha una breve descrizione del suo ruolo di immagine. L'area della nota del cliente è un testo segnaposto esplicativo all'interno di un'anteprima chiaramente identificata, non un falso campo modificabile. La casella di controllo per impostare la nota rimane nel modulo dell'esercente e determina se l'area corrispondente compare nell'anteprima.

## Integrazione con sistema di design SumUp Circuit React e CSS

### Includi le peer dependency pubbliche e entrambi i fogli di stile

Il progetto usa React 18 e i componenti Circuit con versione fissata, insieme alle peer dependency per token, icone, internazionalizzazione ed Emotion richieste dal pacchetto. Il codice importa esplicitamente light.css e styles.css. Non si affida a provider non documentati né a configurazioni di tema nascoste a livello di progetto.

- Stili dei componenti di @sumup/circuit-ui 8.15.0.

- Tema chiaro completo di @sumup/design-tokens 7.3.1.

- React 18 e le peer dependency dichiarate dal pacchetto dei componenti.

### Aggiungi servizi di pagamento solo in un'applicazione reale

Un flusso di pagamento per la produzione richiede un'integrazione autorizzata con un servizio dedicato, la gestione convalidata della valuta e le risposte del server. Questo esempio si limita intenzionalmente alla revisione di una presentazione locale. Mantieni questa formulazione quando riutilizzi l'esempio, finché non esiste un vero flusso di transazione.

## Esempi di componenti del sistema di design SumUp Circuit

### main.jsx — esempio completo funzionante

Modifica un articolo ed esamina l'anteprima per il cliente. Il codice sorgente qui sotto è l'entry point completo di React e include tutto lo stato e la convalida.

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

Riferimento del codice

- Crea un progetto React con Vite, mantieni <div id="root"></div> e salva questo codice come src/main.jsx.

### circuit.css — composizione originale adattiva

Impaginazione dell’applicazione costruita intorno ai componenti nativi.

```
* {
  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;
  }
}
```

Riferimento del codice

- Salva il file accanto a main.jsx. Queste regole di composizione personalizzate sono distinte dal riferimento ai token della libreria.

## Configurazione dell'agent per il sistema di design SumUp Circuit

### Punto di partenza per l’implementazione

L’esempio nativo bloccato è stato incluso nel bundle e verificato localmente nel browser. L’esempio usa solo lo stato locale dell’applicazione.

```
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 per il tuo progetto

```
Crea un editor di articoli Circuit usando i controlli nativi con versione fissata ed entrambi i fogli di stile richiesti. Convalida gli importi completi, mantieni la formattazione della valuta, cancella la revisione locale non aggiornata dopo ogni modifica e distingui l'anteprima per il cliente da un vero checkout. Usa l'illustrazione originale e gli esatti ruoli semantici dei token.
```

## Fonti e ambito del sistema di design SumUp Circuit

Guida applicativa di OpenDesign per una versione specifica del pacchetto Circuit. L'illustrazione, l'importo e l'articolo sono esempi. Questo editor locale non crea link di pagamento né addebiti e non esegue operazioni su account SumUp; i pacchetti upstream attuali usano il nuovo namespace @sumup-oss.

- Documentazione di Circuit Indicazioni aggiornate sui componenti e sulle integrazioni.

- Token chiari con versione fissata Valori esatti usati in questo esempio.

- Source di Circuit Versioni dei pacchetti, proprietà dei componenti e namespace attuale.

## Risorse correlate al sistema di design SumUp Circuit

### TDesign

Crea un editor compatto di criteri API con TDesign React: ruoli concreti del tema, scala delle dimensioni di due pixel, registrazione dei campi Form e composizione tipizzata di Table.

### Thumbtack Thumbprint

Crea un’interfaccia per scoprire servizi con le primitive v2 documentate di Thumbprint: schede compatte dei fornitori, dettagli di confronto leggibili, stati di selezione chiari e una selezione ristretta sempre visibile.

### Twilio Paste

Componi una bozza di notifica con il tema e le convenzioni dei pulsanti di Paste, una scala di spaziatura verificata e una distinzione chiara tra la modifica, la revisione e l’invio effettivo di un messaggio.


- [Riferimento per l’implementazione](https://circuit.sumup.com/)
- [Fonte](https://cdn.jsdelivr.net/npm/@sumup/design-tokens@7.3.1/light.css)
- [Fonte](https://github.com/sumup-oss/circuit-ui)
- [Riferimento del codice](https://circuit.sumup.com/)
- [Documentazione di Circuit Indicazioni aggiornate sui componenti e sulle integrazioni.](https://circuit.sumup.com/)
- [Token chiari con versione fissata Valori esatti usati in questo esempio.](https://cdn.jsdelivr.net/npm/@sumup/design-tokens@7.3.1/light.css)
- [Source di Circuit Versioni dei pacchetti, proprietà dei componenti e namespace attuale.](https://github.com/sumup-oss/circuit-ui)