Una guía de Circuit con tokens semánticos exactos, propiedades de validación nativas, un editor completo de artículos para comerciantes y una vista previa ilustrada para clientes.
@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. · Referencia de implementación
02
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.
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
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.
Borra el nombre y envía el formulario para ver el error del primer campo.
Prueba con 24abc o con cero y, después, corrige el importe a 24.50.
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
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.
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 />);
Guárdalo junto a main.jsx. Estas reglas de composición personalizadas se distinguen de la referencia de tokens de la biblioteca.
04
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.
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
Una instrucción para tu proyecto
Instrucción para el agente
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.
05
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.
