Um guia do Circuit com tokens semânticos exatos, propriedades nativas de validação, um editor completo de itens para lojistas e uma prévia ilustrada do lado do cliente.
Composição do editor de comerciantes do sistema de design SumUp Circuit
Separe os dados inseridos pelo comerciante da apresentação para o cliente
O editor de itens e a prévia no estilo de recibo mostram duas visualizações do mesmo estado. Um formulário curto dá nome ao item, define um valor ilustrativo e permite escolher se o campo de observações do cliente será exibido. A prévia demonstra o efeito sem criar um checkout nem solicitar informações de pagamento.
Use uma ilustração original do produto
A imagem com formas geométricas é uma arte original de CSS com descrição acessível. Ela apresenta um objeto reconhecível na prévia do cliente, em vez de um retângulo de imagem vazio, sem recorrer a uma foto falsa de comerciante ou a um recurso de produto copiado da SumUp.
SumUp Circuit Tema semântico e escopo do pacote do sistema de design
Use o tema exato da versão fixada
Este exemplo usa @sumup/circuit-ui 8.15.0 com @sumup/design-tokens 7.3.1. A tabela de referência é lida de light.css desse pacote. A documentação upstream atual passou a usar o namespace @sumup-oss; esta é uma integração reproduzível com versões fixadas, não uma afirmação de que o namespace antigo corresponde à versão mais recente.
Carregue os estilos dos componentes e dos tokens
A entrada de React importa tanto a folha de estilos dos componentes quanto o arquivo de tokens do tema claro. Os nomes de classe dos componentes não bastam quando suas propriedades personalizadas de CSS ainda não foram definidas. Uma paleta escura com escopo próprio também exigiria um tema base completo para fornecer os valores compartilhados que não são de cor.
Superfícies neutras e contraste das ações no sistema de design SumUp Circuit
Mantenha o item como foco visual
O editor usa uma superfície branca e um primeiro plano escuro, enquanto a prévia do cliente fica sobre um fundo neutro sutil. A arte original acrescenta cor controlada à imagem do item, sem prejudicar a legibilidade nem a visibilidade da ação principal nativa.
Deixe claro que a ação da prévia não é interativa
O rodapé voltado ao cliente é um bloco de texto identificado como Somente prévia, não um botão Pagar desativado que dê a impressão de que o checkout está quase funcionando. A única ação real de envio pertence ao editor e serve para revisar um item local. Isso ajuda as pessoas a entender os limites reais de interação deste exemplo.
Tipografia e fontes alternativas do sistema de design SumUp Circuit
Represente a pilha de fontes do tema com precisão
A pilha publicada começa com Aktiv Grotesk e inclui Helvetica, Arial e fontes alternativas do sistema. Este exemplo offline não baixa a primeira fonte. Os componentes nativos Headline e Body ainda oferecem a hierarquia pretendida, enquanto as fontes disponíveis determinam o formato final das letras.
Mantenha o valor e a moeda juntos
Espaçamento e superfícies arredondadas do sistema de design SumUp Circuit
Use a sequência de etapas nomeadas
A escala de tokens usa os nomes bit, byte, quilo, mega e outros maiores. São rótulos de design, não potências de dois. A tabela preserva os valores exatos em pixels para evitar que desenvolvedores inventem uma escala com base nessa metáfora de nomenclatura.
Alinhe as bordas dos controles sem nivelar a hierarquia
O formulário usa um espaçamento vertical consistente e uma ação principal que ocupa toda a largura. A prévia usa uma superfície externa maior e arredondada e um interior menor, no estilo de recibo. Em um celular, a prévia aparece após o formulário, com o espaçamento interno reduzido antes de comprimir os controles.
Validação de itens e estado de rascunho no sistema de design SumUp Circuit
Valide a string completa antes de formatar
O aplicativo aceita de um a cinco dígitos inteiros e até duas casas decimais, com um valor numérico positivo. Esta é uma regra definida para o exemplo. Ela evita que parseFloat aceite uma string parcial, como 24abc, e direciona o foco para o primeiro Input nativo inválido após o envio.
Limpe a revisão desatualizada sempre que houver uma edição
O nome, o valor e a visibilidade das observações invalidam a revisão anterior. O estado de sucesso inclui o nome e o valor do item revisado, ficando assim vinculado a um rascunho concreto. O código não armazena esse resultado em um backend nem cria uma solicitação de pagamento.
Recuperação de erros de campos e semântica da prévia no sistema de design SumUp Circuit
Teste os erros dos dois campos
O nome e o preço do item usam rótulos obrigatórios nativos, estado inválido e validationHint. O código mantém referências aos campos de entrada para devolver o foco ao primeiro campo com erro. É possível testar a recuperação de erros sem inserir dados reais de clientes ou cartões.
Apague o nome e envie para conferir o erro do primeiro campo.
Experimente 24abc ou zero e, em seguida, corrija o valor para 24.50.
Faça a revisão local e edite um campo para descartar o instantâneo desatualizado.
Descreva a ilustração e identifique a prévia estática com precisão
A arte tem uma breve descrição de sua função como imagem. A área de observações do cliente é um texto explicativo dentro de uma prévia identificada explicitamente, não um campo editável falso. A caixa de seleção real para as observações permanece no formulário do comerciante e controla se essa área aparece na prévia.
Integração de SumUp Circuit React e CSS no sistema de design
Inclua as dependências peer públicas e as duas folhas de estilo
A entrada usa React 18 e os componentes Circuit fixados, com dependências peer de tokens, ícones, internacionalização e Emotion que correspondem aos requisitos do pacote. O código importa light.css e styles.css explicitamente. Não depende de um provedor não documentado nem de uma configuração de tema oculta no projeto.
Estilos dos componentes de @sumup/circuit-ui 8.15.0.
Tema claro completo de @sumup/design-tokens 7.3.1.
React 18 e dependências peer declaradas pelo pacote de componentes.
Adicione serviços de pagamento somente em um aplicativo real
Exemplos de componentes do sistema de design SumUp Circuit
main.jsx — exemplo funcional completo
Edite um item e confira a prévia para o cliente. O código abaixo é a entrada completa de React, incluindo todos os estados e validações.
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 />);
Salve junto de main.jsx. Estas regras de composição personalizadas são distintas da referência de tokens da biblioteca.
04
Configuração do agente de IA do sistema de design SumUp Circuit
Ponto de partida para implementação
O exemplo nativo com versões fixadas foi empacotado e verificado localmente no navegador. O exemplo usa apenas o estado local da aplicação.
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
Um prompt para seu projeto
Prompt para agente de IA
Crie um editor de itens do Circuit usando os controles nativos fixados e as duas folhas de estilo obrigatórias. Valide strings de valor completas, preserve a formatação da moeda, limpe a revisão local desatualizada após edições e mantenha a prévia do cliente distinta de um checkout real. Use a ilustração original e as funções semânticas exatas dos tokens.
05
Fontes e escopo do sistema de design SumUp Circuit
Guia da aplicação OpenDesign para uma geração específica do pacote Circuit. A ilustração, o valor e o item são exemplos. Este editor local não cria links de pagamento nem cobranças, e não realiza ações na conta SumUp; os pacotes upstream atuais usam o namespace mais recente @sumup-oss.
