Руководство по Circuit с точными семантическими токенами, встроенными свойствами валидации, полноценным редактором товаров для продавцов и иллюстрированным пользовательским интерфейсом.
Руководство OpenDesign8 глав39 справочных записейАвторское руководство по приложению
01
Предварительный просмотр интерфейса дизайн-системы SumUp Circuit
Попробуйте ввести некорректные суммы, изменить название товара, переключить поле для примечания и просмотреть локальный снимок.
Измените товар и проверьте его предварительный просмотр для покупателяОткрыть полный пример
Нативный @sumup/circuit-ui 8.15.0 со светлой темой CSS из @sumup/design-tokens 7.3.1; оригинальный локальный редактор товара. · Справочник по реализации
02
Дизайн-система SumUp Circuit: справочник по дизайну
Нативный @sumup/circuit-ui 8.15.0 со светлой темой CSS из @sumup/design-tokens 7.3.1; оригинальный локальный редактор товара.
Справочник семантических цветов для светлой темы продавца; не используйте цвет поверхности для текста, не проверив, с каким цветом текста он предназначен сочетаться.
--cui-bg-subtle
#f0f1f5
Справочник семантических цветов для светлой темы продавца; не используйте цвет поверхности для текста, не проверив, с каким цветом текста он предназначен сочетаться.
--cui-bg-strong
#000
Справочник семантических цветов для светлой темы продавца; не используйте цвет поверхности для текста, не проверив, с каким цветом текста он предназначен сочетаться.
--cui-bg-accent-strong
#0f131a
Справочник семантических цветов для светлой темы продавца; не используйте цвет поверхности для текста, не проверив, с каким цветом текста он предназначен сочетаться.
--cui-fg-normal
#0f131a
Справочник семантических цветов для светлой темы продавца; не используйте цвет поверхности для текста, не проверив, с каким цветом текста он предназначен сочетаться.
--cui-fg-subtle
#6a737c
Справочник семантических цветов для светлой темы продавца; не используйте цвет поверхности для текста, не проверив, с каким цветом текста он предназначен сочетаться.
--cui-fg-on-strong
#fff
Справочник семантических цветов для светлой темы продавца; не используйте цвет поверхности для текста, не проверив, с каким цветом текста он предназначен сочетаться.
--cui-fg-success
#018850
Справочник семантических цветов для светлой темы продавца; не используйте цвет поверхности для текста, не проверив, с каким цветом текста он предназначен сочетаться.
--cui-fg-danger
#de331d
Справочник семантических цветов для светлой темы продавца; не используйте цвет поверхности для текста, не проверив, с каким цветом текста он предназначен сочетаться.
--cui-border-normal
#aeb6be
Справочник семантических цветов для светлой темы продавца; не используйте цвет поверхности для текста, не проверив, с каким цветом текста он предназначен сочетаться.
Отделите ввод данных продавцом от представления для покупателя
Редактор товара и предварительный просмотр в виде чека показывают одно и то же состояние с двух сторон. В короткой форме задают название товара и примерную сумму, а также выбирают, нужно ли показывать поле для примечания покупателя. Предварительный просмотр демонстрирует результат, не создавая оформление заказа и не запрашивая платёжные данные.
Используйте оригинальную иллюстрацию товара
Геометрическая иллюстрация создана специально для CSS и снабжена доступным описанием. Она даёт покупателю узнаваемое изображение товара вместо пустого прямоугольника и не имитирует фотографию товара продавца и не копирует продуктовый ресурс SumUp.
Семантическая тема дизайн-системы SumUp Circuit и область применения пакета
Используйте точную зафиксированную тему
В примере используются @sumup/circuit-ui 8.15.0 и @sumup/design-tokens 7.3.1. Таблица справочных значений составлена по light.css из этого пакета. В актуальной документации постепенно переходят к пространству имён @sumup-oss; здесь показана воспроизводимая интеграция с зафиксированными версиями, а не утверждается, что старое пространство имён соответствует новейшему выпуску.
Подключите стили компонентов и токенов
Точка входа React импортирует и таблицу стилей компонентов, и файл токенов для светлой темы. Одних имён классов компонентов недостаточно, если не определены их пользовательские свойства CSS. Для палитры тёмной темы в отдельной области также потребуется полная базовая тема, задающая общие значения, не связанные с цветом.
Дизайн-система SumUp Circuit: нейтральные поверхности и контраст действий
Сохраняйте визуальный акцент на товаре
В редакторе используется белая поверхность с тёмным текстом, а предварительный просмотр для покупателя размещён на неброском нейтральном фоне. Оригинальная иллюстрация добавляет товару сдержанный цвет, не снижая читаемость нативного основного действия и не отвлекая от него.
Ясно обозначьте, что действие в предварительном просмотре не работает
В нижней части интерфейса покупателя расположен текстовый блок с пометкой «Только предварительный просмотр», а не неактивная кнопка «Оплатить», которая создаёт впечатление почти готового оформления заказа. Единственное настоящее действие отправки находится в редакторе и позволяет проверить локальный товар. Так пользователям проще понять фактические границы взаимодействия в этом примере.
Дизайн-система SumUp Circuit: типографика и резервные шрифты
Корректно указывайте стек темы
Опубликованный стек начинается с Aktiv Grotesk, за которым следуют Helvetica, Arial и системные резервные шрифты. Этот автономный пример не загружает первый шрифт. Нативные компоненты Headline и Body по-прежнему задают нужную иерархию, а начертания букв зависят от доступных шрифтов.
Не разделяйте сумму и валюту
Дизайн-система SumUp Circuit: отступы и скруглённые поверхности
В шкале токенов используются названия bit, byte, kilo, mega и далее. Это названия дизайн-значений, а не степени двойки. В таблице сохранены точные значения в пикселях, чтобы разработчики не выводили шкалу из метафорических названий.
Выравнивайте края элементов управления, сохраняя иерархию
В форме выдержан единый вертикальный отступ, а основное действие занимает всю ширину. Предварительный просмотр оформлен как крупная внешняя поверхность со скруглёнными углами и меньшей внутренней областью в стиле чека. На телефоне предварительный просмотр следует за формой; перед тем как сжимать элементы управления, уменьшают внутренние отступы.
Дизайн-система SumUp Circuit: проверка товара и состояние черновика
Проверяйте всю строку перед форматированием
Приложение принимает от одной до пяти цифр в целой части и до двух знаков после запятой; значение должно быть положительным. Это правило задано специально для примера. Оно не позволяет parseFloat принять неполную строку, например 24abc, и переводит фокус на первое некорректное нативное поле Input после отправки формы.
Сбрасывать устаревший результат проверки при любом изменении
Изменение названия, суммы или видимости примечания аннулирует предыдущий снимок состояния. Успешное состояние содержит проверенные название позиции и сумму, поэтому оно относится к конкретному черновику. Этот код не сохраняет результат на сервере и не создаёт платёжный запрос.
SumUp Circuit — дизайн-система: восстановление после ошибок и семантика предпросмотра Input
Проверьте ошибки в обоих полях
Для названия позиции и цены используются нативные атрибуты required, состояние invalid и подсказка validationHint. В исходном коде сохраняются ссылки на поля ввода, чтобы вернуть фокус на первое поле с ошибкой. Восстановление после ошибки можно проверить без ввода настоящих данных клиента или карты.
Очистите название и отправьте форму, чтобы посмотреть ошибку первого поля.
Введите 24abc или ноль, а затем исправьте сумму на 24.50.
Проверьте данные локально, затем измените поле, чтобы скрыть устаревший снимок состояния.
Точно обозначьте иллюстрацию и статический предпросмотр
Для изображения указано краткое описание его роли. Область примечания клиента — поясняющая заглушка в явно обозначенном предпросмотре, а не фиктивное редактируемое поле. Настоящий флажок настройки примечания находится в форме продавца и определяет, отображается ли эта область предпросмотра.
SumUp Circuit — дизайн-система: интеграция React и CSS
Подключите публичные peer-зависимости и обе таблицы стилей
Точка входа использует React 18 и закреплённую версию Circuit components, а также зависимости от токенов, иконок, интернационализации и Emotion в соответствии с требованиями пакета. В коде явно импортируются light.css и styles.css. Решение не зависит от недокументированного провайдера или скрытой настройки темы на уровне проекта.
Стили компонентов @sumup/circuit-ui 8.15.0.
Полная светлая тема @sumup/design-tokens 7.3.1.
React 18 и объявленные peer-зависимости пакета компонентов.
Добавляйте платёжные сервисы только в настоящее приложение
Измените позицию и посмотрите предпросмотр со стороны клиента. Приведённый ниже исходный код — полная точка входа React, включая всё состояние и валидацию.
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 />);
Сохраните рядом с main.jsx. Эти собственные правила композиции отделены от справочника токенов библиотеки.
04
SumUp Circuit — настройка агента для дизайн-системы
Отправная точка для реализации
Пример с закреплёнными версиями нативных компонентов собран и проверен в браузере локально. В образце используется только локальное состояние приложения.
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
Запрос для вашего проекта
Промпт для AI-агента
Создайте редактор позиций Circuit на основе закреплённых нативных элементов управления и подключите обе обязательные таблицы стилей. Проверяйте сумму целиком, сохраняйте форматирование валюты, сбрасывайте устаревший локальный результат проверки после изменений и отделяйте предпросмотр со стороны клиента от настоящего оформления заказа. Используйте исходную иллюстрацию и точные семантические роли токенов.
05
SumUp Circuit — источники и область применения дизайн-системы
Руководство по приложению OpenDesign для закреплённой версии Circuit. Иллюстрация, сумма и позиция приведены в качестве примеров. Этот локальный редактор не создаёт платёжную ссылку или списание и не выполняет действий с учётной записью SumUp; в актуальных версиях пакетов используется новое пространство имён @sumup-oss.