# Sistema de design SumUp Circuit

## Prévia da interface do sistema de design SumUp Circuit

Teste valores inválidos, altere o nome do item, ative ou desative o campo de observações e confira um instantâneo local.

## Referência de design do sistema de design SumUp Circuit

@sumup/circuit-ui 8.15.0 nativo com tema claro CSS de @sumup/design-tokens 7.3.1; editor de itens local original.

### Superfícies claras e texto para comerciantes

| Nome / Regra | Valor / Configuração | Uso |
| --- | --- | --- |
| --cui-bg-normal | #fff | Referência semântica para o tema claro de comerciantes; não use uma cor de superfície como primeiro plano sem confirmar o par previsto para ela. |
| --cui-bg-subtle | #f0f1f5 | Referência semântica para o tema claro de comerciantes; não use uma cor de superfície como primeiro plano sem confirmar o par previsto para ela. |
| --cui-bg-strong | #000 | Referência semântica para o tema claro de comerciantes; não use uma cor de superfície como primeiro plano sem confirmar o par previsto para ela. |
| --cui-bg-accent-strong | #0f131a | Referência semântica para o tema claro de comerciantes; não use uma cor de superfície como primeiro plano sem confirmar o par previsto para ela. |
| --cui-fg-normal | #0f131a | Referência semântica para o tema claro de comerciantes; não use uma cor de superfície como primeiro plano sem confirmar o par previsto para ela. |
| --cui-fg-subtle | #6a737c | Referência semântica para o tema claro de comerciantes; não use uma cor de superfície como primeiro plano sem confirmar o par previsto para ela. |
| --cui-fg-on-strong | #fff | Referência semântica para o tema claro de comerciantes; não use uma cor de superfície como primeiro plano sem confirmar o par previsto para ela. |
| --cui-fg-success | #018850 | Referência semântica para o tema claro de comerciantes; não use uma cor de superfície como primeiro plano sem confirmar o par previsto para ela. |
| --cui-fg-danger | #de331d | Referência semântica para o tema claro de comerciantes; não use uma cor de superfície como primeiro plano sem confirmar o par previsto para ela. |
| --cui-border-normal | #aeb6be | Referência semântica para o tema claro de comerciantes; não use uma cor de superfície como primeiro plano sem confirmar o par previsto para ela. |
### Unidades de espaçamento

| Nome / Regra | Valor / Configuração | Uso |
| --- | --- | --- |
| --cui-spacings-bit | 4px | Etapas de espaçamento nomeadas, copiadas da exportação fixada de CSS. |
| --cui-spacings-byte | 8px | Etapas de espaçamento nomeadas, copiadas da exportação fixada de CSS. |
| --cui-spacings-kilo | 12px | Etapas de espaçamento nomeadas, copiadas da exportação fixada de CSS. |
| --cui-spacings-mega | 16px | Etapas de espaçamento nomeadas, copiadas da exportação fixada de CSS. |
| --cui-spacings-giga | 24px | Etapas de espaçamento nomeadas, copiadas da exportação fixada de CSS. |
| --cui-spacings-tera | 32px | Etapas de espaçamento nomeadas, copiadas da exportação fixada de CSS. |
| --cui-spacings-peta | 40px | Etapas de espaçamento nomeadas, copiadas da exportação fixada de CSS. |
| --cui-spacings-exa | 48px | Etapas de espaçamento nomeadas, copiadas da exportação fixada de CSS. |
| --cui-spacings-zetta | 56px | Etapas de espaçamento nomeadas, copiadas da exportação fixada de CSS. |
### Raios dos cantos

| Nome / Regra | Valor / Configuração | Uso |
| --- | --- | --- |
| --cui-border-radius-bit | 4px | Use as formas de acordo com a função do controle ou da superfície. |
| --cui-border-radius-byte | 8px | Use as formas de acordo com a função do controle ou da superfície. |
| --cui-border-radius-kilo | 12px | Use as formas de acordo com a função do controle ou da superfície. |
| --cui-border-radius-mega | 16px | Use as formas de acordo com a função do controle ou da superfície. |
| --cui-border-radius-circle | 100% | Use as formas de acordo com a função do controle ou da superfície. |
| --cui-border-radius-pill | 999999px | Use as formas de acordo com a função do controle ou da superfície. |
### Famílias e pesos de fontes

| Nome / Regra | Valor / Configuração | Uso |
| --- | --- | --- |
| --cui-font-stack-default | aktiv-grotesk, Helvetica, Arial, system-ui, sans-serif, "Segoe UI", Roboto, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol" | O exemplo usa fontes alternativas disponíveis; não carrega Aktiv Grotesk. |
| --cui-font-stack-mono | Menlo, Consolas, Monaco, Liberation Mono, Lucida Console, monospace | O exemplo usa fontes alternativas disponíveis; não carrega Aktiv Grotesk. |
| --cui-font-weight-regular | 400 | O exemplo usa fontes alternativas disponíveis; não carrega Aktiv Grotesk. |
| --cui-font-weight-bold | 700 | O exemplo usa fontes alternativas disponíveis; não carrega Aktiv Grotesk. |
### Estados da ação principal

| Nome / Regra | Valor / Configuração | Uso |
| --- | --- | --- |
| --cui-bg-accent-strong | #0f131a | Mantenha estados distintos para normal, ao passar o cursor, pressionado e desativado. |
| --cui-bg-accent-strong-hovered | #3b3f46 | Mantenha estados distintos para normal, ao passar o cursor, pressionado e desativado. |
| --cui-bg-accent-strong-pressed | #6a737c | Mantenha estados distintos para normal, ao passar o cursor, pressionado e desativado. |
| --cui-bg-accent-strong-disabled | rgba(15, 19, 26, .4) | Mantenha estados distintos para normal, ao passar o cursor, pressionado e desativado. |
### Propriedades públicas de campos e botões

| Nome / Regra | Valor / Configuração | Uso |
| --- | --- | --- |
| Input.label | required string | Finalidade visível do campo. |
| Input.invalid | boolean | Estilo nativo de estado inválido e estado de acessibilidade. |
| Input.validationHint | string | Exiba uma instrução específica abaixo do controle. |
| Button.variant | primary / secondary / tertiary | Hierarquia de ações nesta versão fixada. |
| Button.size | s / m | Valores de tamanho atuais na versão 8.15.0. |
| Button.stretch | boolean | Use toda a largura do elemento pai para a ação de revisão local. |
## Guia completo do sistema de design SumUp Circuit

Um guia prático para escolher, aplicar e avaliar este sistema em uma interface real.

Orientações completas, um ponto de partida para a implementação e links para o código-fonte.

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

Intl.NumberFormat gera a representação em euros para o valor local validado. O preço tem mais destaque visual que a descrição do item e permanece na prévia do cliente. Um rascunho inválido mostra um travessão, em vez de um zero enganoso ou de um valor parcialmente interpretado.

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

1. Apague o nome e envie para conferir o erro do primeiro campo.

2. Experimente 24abc ou zero e, em seguida, corrija o valor para 24.50.

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

Um fluxo de pagamento de produção precisa de sua própria integração autorizada com serviços, tratamento validado de moedas e respostas do servidor. Este exemplo se limita intencionalmente à revisão de uma apresentação local. Mantenha essa descrição ao reutilizar o exemplo, até que exista um fluxo de transação 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.

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

Referência de código

- Crie um projeto Vite React, mantenha <div id="root"></div> e carregue este arquivo como src/main.jsx.

### circuit.css — composição responsiva original

Layout da aplicação organizado em torno dos componentes nativos.

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

Referência de código

- Salve junto de main.jsx. Estas regras de composição personalizadas são distintas da referência de tokens da biblioteca.

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

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

### Um prompt para seu projeto

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

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

- Documentação do Circuit Orientações atuais sobre componentes e integrações.

- Tokens claros fixados Valores exatos usados neste exemplo.

- Fonte do Circuit Gerações de pacotes, propriedades de componentes e namespace atual.

## Recursos relacionados ao sistema de design SumUp Circuit

### TDesign

Crie um editor compacto de políticas API com TDesign React: funções concretas do tema, escala de tamanhos de dois pixels, registro de campos do Form e composição tipada de Table.

### Thumbtack Thumbprint

Crie uma interface de descoberta de serviços com os elementos primitivos documentados da v2 do Thumbprint: cartões compactos de prestadores, detalhes de comparação fáceis de ler, estados de seleção claros e uma lista de favoritos persistente.

### Twilio Paste

Crie um rascunho de notificação com o tema e os contratos de botões do Paste, uma escala de espaçamento verificada e uma distinção clara entre editar, revisar e realmente enviar uma mensagem.


- [Referência de implementação](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)
- [Referência de código](https://circuit.sumup.com/)
- [Documentação do Circuit Orientações atuais sobre componentes e integrações.](https://circuit.sumup.com/)
- [Tokens claros fixados Valores exatos usados neste exemplo.](https://cdn.jsdelivr.net/npm/@sumup/design-tokens@7.3.1/light.css)
- [Fonte do Circuit Gerações de pacotes, propriedades de componentes e namespace atual.](https://github.com/sumup-oss/circuit-ui)