# Sistema de diseño SumUp Circuit

## Vista previa de la interfaz del sistema de diseño SumUp Circuit

Prueba importes no válidos, cambia el nombre del artículo, muestra u oculta el campo de nota y revisa una vista previa local.

## Referencia de diseño del sistema de diseño SumUp Circuit

@sumup/circuit-ui 8.15.0 nativo con el tema claro de @sumup/design-tokens 7.3.1 CSS; editor de artículos local original.

### Superficies claras y texto para comerciantes

| Nombre / Regla | Valor / Configuración | Uso |
| --- | --- | --- |
| --cui-bg-normal | #fff | Referencia semántica para el tema claro de comerciantes; no uses un color de superficie como primer plano sin comprobar la combinación prevista. |
| --cui-bg-subtle | #f0f1f5 | Referencia semántica para el tema claro de comerciantes; no uses un color de superficie como primer plano sin comprobar la combinación prevista. |
| --cui-bg-strong | #000 | Referencia semántica para el tema claro de comerciantes; no uses un color de superficie como primer plano sin comprobar la combinación prevista. |
| --cui-bg-accent-strong | #0f131a | Referencia semántica para el tema claro de comerciantes; no uses un color de superficie como primer plano sin comprobar la combinación prevista. |
| --cui-fg-normal | #0f131a | Referencia semántica para el tema claro de comerciantes; no uses un color de superficie como primer plano sin comprobar la combinación prevista. |
| --cui-fg-subtle | #6a737c | Referencia semántica para el tema claro de comerciantes; no uses un color de superficie como primer plano sin comprobar la combinación prevista. |
| --cui-fg-on-strong | #fff | Referencia semántica para el tema claro de comerciantes; no uses un color de superficie como primer plano sin comprobar la combinación prevista. |
| --cui-fg-success | #018850 | Referencia semántica para el tema claro de comerciantes; no uses un color de superficie como primer plano sin comprobar la combinación prevista. |
| --cui-fg-danger | #de331d | Referencia semántica para el tema claro de comerciantes; no uses un color de superficie como primer plano sin comprobar la combinación prevista. |
| --cui-border-normal | #aeb6be | Referencia semántica para el tema claro de comerciantes; no uses un color de superficie como primer plano sin comprobar la combinación prevista. |
### Unidades de espaciado

| Nombre / Regla | Valor / Configuración | Uso |
| --- | --- | --- |
| --cui-spacings-bit | 4px | Pasos de espaciado con nombre, copiados de la exportación fijada de CSS. |
| --cui-spacings-byte | 8px | Pasos de espaciado con nombre, copiados de la exportación fijada de CSS. |
| --cui-spacings-kilo | 12px | Pasos de espaciado con nombre, copiados de la exportación fijada de CSS. |
| --cui-spacings-mega | 16px | Pasos de espaciado con nombre, copiados de la exportación fijada de CSS. |
| --cui-spacings-giga | 24px | Pasos de espaciado con nombre, copiados de la exportación fijada de CSS. |
| --cui-spacings-tera | 32px | Pasos de espaciado con nombre, copiados de la exportación fijada de CSS. |
| --cui-spacings-peta | 40px | Pasos de espaciado con nombre, copiados de la exportación fijada de CSS. |
| --cui-spacings-exa | 48px | Pasos de espaciado con nombre, copiados de la exportación fijada de CSS. |
| --cui-spacings-zetta | 56px | Pasos de espaciado con nombre, copiados de la exportación fijada de CSS. |
### Radios de esquina

| Nombre / Regla | Valor / Configuración | Uso |
| --- | --- | --- |
| --cui-border-radius-bit | 4px | Usa la forma adecuada según la función del control o la superficie. |
| --cui-border-radius-byte | 8px | Usa la forma adecuada según la función del control o la superficie. |
| --cui-border-radius-kilo | 12px | Usa la forma adecuada según la función del control o la superficie. |
| --cui-border-radius-mega | 16px | Usa la forma adecuada según la función del control o la superficie. |
| --cui-border-radius-circle | 100% | Usa la forma adecuada según la función del control o la superficie. |
| --cui-border-radius-pill | 999999px | Usa la forma adecuada según la función del control o la superficie. |
### Familias tipográficas y grosores

| Nombre / Regla | Valor / Configuración | 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" | El ejemplo usa fuentes alternativas disponibles; no descarga Aktiv Grotesk. |
| --cui-font-stack-mono | Menlo, Consolas, Monaco, Liberation Mono, Lucida Console, monospace | El ejemplo usa fuentes alternativas disponibles; no descarga Aktiv Grotesk. |
| --cui-font-weight-regular | 400 | El ejemplo usa fuentes alternativas disponibles; no descarga Aktiv Grotesk. |
| --cui-font-weight-bold | 700 | El ejemplo usa fuentes alternativas disponibles; no descarga Aktiv Grotesk. |
### Estados de la acción principal

| Nombre / Regla | Valor / Configuración | Uso |
| --- | --- | --- |
| --cui-bg-accent-strong | #0f131a | Mantén separados los estados normal, al pasar el cursor, pulsado y deshabilitado. |
| --cui-bg-accent-strong-hovered | #3b3f46 | Mantén separados los estados normal, al pasar el cursor, pulsado y deshabilitado. |
| --cui-bg-accent-strong-pressed | #6a737c | Mantén separados los estados normal, al pasar el cursor, pulsado y deshabilitado. |
| --cui-bg-accent-strong-disabled | rgba(15, 19, 26, .4) | Mantén separados los estados normal, al pasar el cursor, pulsado y deshabilitado. |
### Propiedades públicas de campos y botones

| Nombre / Regla | Valor / Configuración | Uso |
| --- | --- | --- |
| Input.label | required string | Finalidad visible del campo. |
| Input.invalid | boolean | Estilo de error nativo y estado de accesibilidad. |
| Input.validationHint | string | Muestra una instrucción específica debajo del control. |
| Button.variant | primary / secondary / tertiary | Jerarquía de acciones en esta versión fijada. |
| Button.size | s / m | Valores de tamaño actuales en la versión 8.15.0. |
| Button.stretch | boolean | Ocupa todo el ancho del elemento principal para la acción de revisión local. |
## Guía completa del sistema de diseño SumUp Circuit

Una guía práctica para elegir, aplicar y revisar este sistema en una interfaz real.

Orientación completa, un punto de partida para la implementación y enlaces al código fuente.

## Composición del editor de comerciantes del sistema de diseño SumUp Circuit

### Separa la entrada del comerciante de la presentación para el cliente

> El editor de artículos y la vista previa, similar a un recibo, muestran dos vistas del mismo estado. Un formulario breve permite asignar un nombre al artículo, establecer un importe ilustrativo y elegir si se muestra un campo para notas del cliente. La vista previa muestra el efecto sin crear un proceso de pago ni solicitar información de pago.

### Usa una ilustración de producto original

La imagen de impresión geométrica es una obra original de CSS con una descripción accesible. Da a la vista previa para el cliente un objeto reconocible en lugar de un rectángulo de imagen vacío, y evita usar una foto falsa de un comerciante o un recurso de producto copiado de SumUp.

## Alcance del tema semántico y del paquete del sistema de diseño SumUp Circuit

### Usa exactamente el tema fijado

Este ejemplo utiliza @sumup/circuit-ui 8.15.0 con @sumup/design-tokens 7.3.1. La tabla de referencia se obtiene de light.css de ese paquete. La documentación actual del proyecto ha empezado a usar el espacio de nombres @sumup-oss; esta es una integración reproducible con versiones fijadas, no una afirmación de que el espacio de nombres anterior corresponda a la versión más reciente.

### Carga los estilos de los componentes y los tokens

La entrada de React importa tanto la hoja de estilos de los componentes como el archivo de tokens light. Los nombres de clase de los componentes no bastan si no se han definido sus propiedades personalizadas CSS. Una paleta oscura con ámbito propio también necesitaría un tema base completo para proporcionar los valores compartidos que no dependen del color.

## Superficies neutras y contraste de acciones del sistema de diseño SumUp Circuit

### Mantén el artículo como foco visual

El editor usa una superficie blanca y un primer plano oscuro, mientras que la vista previa para el cliente aparece sobre un fondo neutro y sutil. La ilustración original añade color controlado a la imagen del artículo, de modo que la acción principal nativa siga siendo legible y fácil de localizar.

### Deja claro que la acción de la vista previa no es interactiva

El pie de la vista para el cliente es un bloque de texto etiquetado «Solo vista previa», no un botón «Pagar» deshabilitado que sugiera un proceso de pago casi funcional. La única acción real de envío pertenece al editor y revisa un artículo local. Así, los usuarios entienden los límites reales de interacción de este ejemplo.

## Tipografía y fuentes alternativas del sistema de diseño SumUp Circuit

### Usa con transparencia la pila tipográfica del tema

La pila publicada empieza con Aktiv Grotesk e incluye Helvetica, Arial y fuentes del sistema como alternativas. Este ejemplo sin conexión no descarga la primera fuente. Sus componentes nativos Headline y Body siguen proporcionando la jerarquía prevista, mientras que las fuentes disponibles determinan las formas finales de las letras.

### Mantén juntos el importe y la moneda

Intl.NumberFormat genera la representación en euros del importe local validado. El precio destaca visualmente más que la descripción del artículo y permanece en la vista previa para el cliente. Un borrador no válido muestra una raya en lugar de un cero engañoso o un importe analizado parcialmente.

## Espaciado y superficies redondeadas del sistema de diseño SumUp Circuit

### Usa la secuencia de pasos con nombre

La escala de tokens utiliza nombres como bit, byte, kilo, mega y otros de mayor magnitud. Son etiquetas de diseño, no potencias de dos. La tabla conserva los valores exactos en píxeles para que los desarrolladores no deduzcan una escala a partir de la metáfora de los nombres.

### Alinea los bordes de los controles sin aplanar la jerarquía

El formulario mantiene un espaciado vertical uniforme y una acción principal de ancho completo. La vista previa tiene una superficie exterior más grande y redondeada, y un interior más pequeño con formato de recibo. En un teléfono, la vista previa aparece después del formulario y se reduce el espaciado antes de comprimir los controles.

## Sistema de diseño de SumUp Circuit: validación del artículo y estado del borrador

### Valida la cadena completa antes de darle formato

La aplicación acepta de uno a cinco dígitos enteros y hasta dos decimales, siempre que el valor numérico sea positivo. Esta es una regla de ejemplo definida aquí. Evita que parseFloat acepte cadenas parciales como 24abc y enfoca el primer Input nativo no válido después del envío.

### Borra la revisión anterior ante cualquier cambio

Cualquier cambio en el nombre, el importe o la visibilidad de la nota invalida la instantánea anterior. El estado correcto incluye el nombre y el importe del artículo revisado, por lo que queda vinculado a un borrador concreto. El código no guarda este resultado en un backend ni crea una solicitud de pago.

## Sistema de diseño de SumUp Circuit: recuperación de errores de entrada y semántica de la vista previa

### Prueba los errores de ambos campos

El nombre y el precio del artículo usan las etiquetas required nativas, el estado invalid y validationHint. El código conserva referencias a los campos de entrada para devolver el foco al primero que tenga un error. Puedes probar la recuperación de errores sin introducir datos reales de clientes ni tarjetas.

1. Borra el nombre y envía el formulario para ver el error del primer campo.

2. Prueba con 24abc o con cero y, después, corrige el importe a 24.50.

3. Revisa el contenido de forma local y modifica un campo para descartar la instantánea obsoleta.

### Describe con honestidad la ilustración y la vista previa estática

La ilustración tiene una breve descripción de su función como imagen. El área de la nota para el cliente es un texto explicativo dentro de una vista previa identificada claramente, no un campo de entrada editable ficticio. La casilla real para configurar la nota permanece en el formulario del comercio y controla si aparece esa zona de la vista previa.

## Integración de SumUp Circuit, el sistema de diseño, con React y CSS

### Incluye las dependencias peer públicas y ambas hojas de estilos

La entrada usa React 18 y los componentes de Circuit fijados, con dependencias peer de tokens, iconos, internacionalización y Emotion que cumplen los requisitos del paquete. El código importa explícitamente light.css y styles.css. No depende de un proveedor sin documentar ni de una configuración de tema oculta a nivel de proyecto.

- Estilos de los componentes de @sumup/circuit-ui 8.15.0.

- Tema claro completo de @sumup/design-tokens 7.3.1.

- React 18 y las dependencias peer declaradas por el paquete de componentes.

### Añade servicios de pago solo en una aplicación real

Un flujo de pago en producción requiere su propia integración con servicios autorizados, un manejo validado de la moneda y respuestas del servidor. Este ejemplo se limita deliberadamente a revisar una presentación local. Conserva esa descripción al reutilizarlo hasta que exista un flujo de transacción real.

## Ejemplos de componentes del sistema de diseño SumUp Circuit

### main.jsx — ejemplo completo y funcional

Edita un artículo y revisa la vista previa para el cliente. El código siguiente es la entrada completa de React e incluye todo el estado y la validación.

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

Referencia de código

- Crea un proyecto Vite React, conserva <div id="root"></div> y cárgalo como src/main.jsx.

### circuit.css — composición adaptable original

Diseño de la aplicación con capas alrededor de los 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;
  }
}
```

Referencia de código

- Guárdalo junto a main.jsx. Estas reglas de composición personalizadas se distinguen de la referencia de tokens de la biblioteca.

## Configuración del agente para el sistema de diseño SumUp Circuit

### Punto de partida para la implementación

El ejemplo nativo fijado se empaquetó y se comprobó localmente en el navegador. El ejemplo utiliza únicamente el estado local de la aplicación.

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

### Una instrucción para tu proyecto

```
Crea un editor de artículos de Circuit con los controles nativos fijados y las dos hojas de estilos requeridas. Valida las cadenas completas de los importes, conserva el formato de moneda, borra las revisiones locales obsoletas después de los cambios y distingue la vista previa para el cliente de un proceso de pago real. Usa la ilustración original y los roles semánticos de tokens exactos.
```

## Fuentes y alcance del sistema de diseño SumUp Circuit

Guía de la aplicación OpenDesign para una generación fijada del paquete Circuit. La ilustración, el importe y el artículo son ejemplos. Este editor local no crea enlaces de pago, cargos ni acciones en una cuenta de SumUp; las versiones actuales de los paquetes usan el espacio de nombres @sumup-oss.

- Documentación de Circuit Guía actual de componentes e integración.

- Tokens claros fijados Valores exactos usados en este ejemplo.

- Código fuente de Circuit Generaciones de paquetes, propiedades de componentes y espacio de nombres actual.

## Recursos relacionados con el sistema de diseño SumUp Circuit

### TDesign

Crea un editor compacto de políticas de API con TDesign React: roles de tema concretos, su escala de tamaños de dos píxeles, registro de campos Form y una composición tipada de Table.

### Thumbtack Thumbprint

Crea una interfaz de descubrimiento de servicios con las primitivas documentadas de Thumbprint v2: tarjetas compactas de proveedores, detalles comparativos fáciles de leer, estados de selección claros y una lista de preselección persistente.

### Twilio Paste

Redacta una notificación con el tema y los contratos de botones de Paste, una escala de espaciado verificada y una distinción clara entre editar, revisar y enviar un mensaje.


- [Referencia de implementación](https://circuit.sumup.com/)
- [Fuente](https://cdn.jsdelivr.net/npm/@sumup/design-tokens@7.3.1/light.css)
- [Fuente](https://github.com/sumup-oss/circuit-ui)
- [Referencia de código](https://circuit.sumup.com/)
- [Documentación de Circuit Guía actual de componentes e integración.](https://circuit.sumup.com/)
- [Tokens claros fijados Valores exactos usados en este ejemplo.](https://cdn.jsdelivr.net/npm/@sumup/design-tokens@7.3.1/light.css)
- [Código fuente de Circuit Generaciones de paquetes, propiedades de componentes y espacio de nombres actual.](https://github.com/sumup-oss/circuit-ui)