Una guida Circuit con token semantici esatti, proprietà di convalida native, un editor completo degli articoli del venditore e un’anteprima illustrata dal lato cliente.
@sumup/circuit-ui 8.15.0 nativo con il tema chiaro CSS di @sumup/design-tokens 7.3.1; editor di articoli locale originale. · Riferimento per l’implementazione
02
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.
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
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.
Cancella il nome e invia il modulo per esaminare l'errore del primo campo.
Prova 24abc o zero, poi correggi l'importo in 24.50.
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
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.
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 />);
Salva il file accanto a main.jsx. Queste regole di composizione personalizzate sono distinte dal riferimento ai token della libreria.
04
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.
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 per il tuo progetto
Prompt per l’agente
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.
05
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.
