# Дизайн-система SumUp Circuit

## Предварительный просмотр интерфейса дизайн-системы SumUp Circuit

Попробуйте ввести некорректные суммы, изменить название товара, переключить поле для примечания и просмотреть локальный снимок.

## Дизайн-система SumUp Circuit: справочник по дизайну

Нативный @sumup/circuit-ui 8.15.0 со светлой темой CSS из @sumup/design-tokens 7.3.1; оригинальный локальный редактор товара.

### Светлые поверхности и текст для продавца

| Название / правило | Значение / конфигурация | Применение |
| --- | --- | --- |
| --cui-bg-normal | #fff | Справочник семантических цветов для светлой темы продавца; не используйте цвет поверхности для текста, не проверив, с каким цветом текста он предназначен сочетаться. |
| --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 | Справочник семантических цветов для светлой темы продавца; не используйте цвет поверхности для текста, не проверив, с каким цветом текста он предназначен сочетаться. |
### Шаги отступов

| Название / правило | Значение / конфигурация | Применение |
| --- | --- | --- |
| --cui-spacings-bit | 4px | Именованные значения отступов из зафиксированного экспорта CSS. |
| --cui-spacings-byte | 8px | Именованные значения отступов из зафиксированного экспорта CSS. |
| --cui-spacings-kilo | 12px | Именованные значения отступов из зафиксированного экспорта CSS. |
| --cui-spacings-mega | 16px | Именованные значения отступов из зафиксированного экспорта CSS. |
| --cui-spacings-giga | 24px | Именованные значения отступов из зафиксированного экспорта CSS. |
| --cui-spacings-tera | 32px | Именованные значения отступов из зафиксированного экспорта CSS. |
| --cui-spacings-peta | 40px | Именованные значения отступов из зафиксированного экспорта CSS. |
| --cui-spacings-exa | 48px | Именованные значения отступов из зафиксированного экспорта CSS. |
| --cui-spacings-zetta | 56px | Именованные значения отступов из зафиксированного экспорта CSS. |
### Радиусы скругления

| Название / правило | Значение / конфигурация | Применение |
| --- | --- | --- |
| --cui-border-radius-bit | 4px | Выбирайте форму с учётом роли элемента управления или поверхности. |
| --cui-border-radius-byte | 8px | Выбирайте форму с учётом роли элемента управления или поверхности. |
| --cui-border-radius-kilo | 12px | Выбирайте форму с учётом роли элемента управления или поверхности. |
| --cui-border-radius-mega | 16px | Выбирайте форму с учётом роли элемента управления или поверхности. |
| --cui-border-radius-circle | 100% | Выбирайте форму с учётом роли элемента управления или поверхности. |
| --cui-border-radius-pill | 999999px | Выбирайте форму с учётом роли элемента управления или поверхности. |
### Семейства и начертания шрифтов

| Название / правило | Значение / конфигурация | Применение |
| --- | --- | --- |
| --cui-font-stack-default | aktiv-grotesk, Helvetica, Arial, system-ui, sans-serif, "Segoe UI", Roboto, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol" | В примере используются доступные резервные шрифты; Aktiv Grotesk не загружается. |
| --cui-font-stack-mono | Menlo, Consolas, Monaco, Liberation Mono, Lucida Console, monospace | В примере используются доступные резервные шрифты; Aktiv Grotesk не загружается. |
| --cui-font-weight-regular | 400 | В примере используются доступные резервные шрифты; Aktiv Grotesk не загружается. |
| --cui-font-weight-bold | 700 | В примере используются доступные резервные шрифты; Aktiv Grotesk не загружается. |
### Состояния основного действия

| Название / правило | Значение / конфигурация | Применение |
| --- | --- | --- |
| --cui-bg-accent-strong | #0f131a | Сохраняйте отдельные состояния: обычное, при наведении, при нажатии и неактивное. |
| --cui-bg-accent-strong-hovered | #3b3f46 | Сохраняйте отдельные состояния: обычное, при наведении, при нажатии и неактивное. |
| --cui-bg-accent-strong-pressed | #6a737c | Сохраняйте отдельные состояния: обычное, при наведении, при нажатии и неактивное. |
| --cui-bg-accent-strong-disabled | rgba(15, 19, 26, .4) | Сохраняйте отдельные состояния: обычное, при наведении, при нажатии и неактивное. |
### Публичные свойства полей и кнопок

| Название / правило | Значение / конфигурация | Применение |
| --- | --- | --- |
| Input.label | required string | Назначение поля, видимое пользователю. |
| Input.invalid | boolean | Нативное оформление и состояние доступности для некорректного значения. |
| Input.validationHint | string | Показывайте под элементом управления конкретную инструкцию. |
| Button.variant | primary / secondary / tertiary | Иерархия действий в этой зафиксированной версии. |
| Button.size | s / m | Текущие значения размеров в версии 8.15.0. |
| Button.stretch | boolean | Растяните локальную кнопку проверки на всю ширину родительского элемента. |
## Полное руководство по дизайн-системе SumUp Circuit

Практическое руководство по выбору, применению и оценке этой системы для реального интерфейса.

Подробные рекомендации, отправная точка для реализации и ссылки на источники.

## Дизайн-система SumUp Circuit: композиция редактора продавца

### Отделите ввод данных продавцом от представления для покупателя

> Редактор товара и предварительный просмотр в виде чека показывают одно и то же состояние с двух сторон. В короткой форме задают название товара и примерную сумму, а также выбирают, нужно ли показывать поле для примечания покупателя. Предварительный просмотр демонстрирует результат, не создавая оформление заказа и не запрашивая платёжные данные.

### Используйте оригинальную иллюстрацию товара

Геометрическая иллюстрация создана специально для 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 по-прежнему задают нужную иерархию, а начертания букв зависят от доступных шрифтов.

### Не разделяйте сумму и валюту

Intl.NumberFormat форматирует проверенную локальную сумму в евро. Цена заметнее описания товара и остаётся в предварительном просмотре для покупателя. Для некорректного чернового значения показывается длинное тире, а не вводящий в заблуждение ноль или частично разобранная сумма.

## Дизайн-система SumUp Circuit: отступы и скруглённые поверхности

### Используйте последовательность именованных значений

В шкале токенов используются названия bit, byte, kilo, mega и далее. Это названия дизайн-значений, а не степени двойки. В таблице сохранены точные значения в пикселях, чтобы разработчики не выводили шкалу из метафорических названий.

### Выравнивайте края элементов управления, сохраняя иерархию

В форме выдержан единый вертикальный отступ, а основное действие занимает всю ширину. Предварительный просмотр оформлен как крупная внешняя поверхность со скруглёнными углами и меньшей внутренней областью в стиле чека. На телефоне предварительный просмотр следует за формой; перед тем как сжимать элементы управления, уменьшают внутренние отступы.

## Дизайн-система SumUp Circuit: проверка товара и состояние черновика

### Проверяйте всю строку перед форматированием

Приложение принимает от одной до пяти цифр в целой части и до двух знаков после запятой; значение должно быть положительным. Это правило задано специально для примера. Оно не позволяет parseFloat принять неполную строку, например 24abc, и переводит фокус на первое некорректное нативное поле Input после отправки формы.

### Сбрасывать устаревший результат проверки при любом изменении

Изменение названия, суммы или видимости примечания аннулирует предыдущий снимок состояния. Успешное состояние содержит проверенные название позиции и сумму, поэтому оно относится к конкретному черновику. Этот код не сохраняет результат на сервере и не создаёт платёжный запрос.

## SumUp Circuit — дизайн-система: восстановление после ошибок и семантика предпросмотра Input

### Проверьте ошибки в обоих полях

Для названия позиции и цены используются нативные атрибуты required, состояние invalid и подсказка validationHint. В исходном коде сохраняются ссылки на поля ввода, чтобы вернуть фокус на первое поле с ошибкой. Восстановление после ошибки можно проверить без ввода настоящих данных клиента или карты.

1. Очистите название и отправьте форму, чтобы посмотреть ошибку первого поля.

2. Введите 24abc или ноль, а затем исправьте сумму на 24.50.

3. Проверьте данные локально, затем измените поле, чтобы скрыть устаревший снимок состояния.

### Точно обозначьте иллюстрацию и статический предпросмотр

Для изображения указано краткое описание его роли. Область примечания клиента — поясняющая заглушка в явно обозначенном предпросмотре, а не фиктивное редактируемое поле. Настоящий флажок настройки примечания находится в форме продавца и определяет, отображается ли эта область предпросмотра.

## 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-зависимости пакета компонентов.

### Добавляйте платёжные сервисы только в настоящее приложение

Для рабочего платёжного процесса необходима отдельная авторизованная интеграция с сервисом, проверка обработки валюты и ответы сервера. Этот образец намеренно ограничивается локальным просмотром оформления. При повторном использовании примера сохраняйте эту формулировку, пока не будет реализован настоящий платёжный процесс.

## SumUp Circuit — примеры компонентов дизайн-системы

### main.jsx — полный рабочий образец

Измените позицию и посмотрите предпросмотр со стороны клиента. Приведённый ниже исходный код — полная точка входа React, включая всё состояние и валидацию.

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

Справочник по коду

- Создайте проект React на Vite, сохраните <div id="root"></div> и загрузите этот код как src/main.jsx.

### circuit.css — исходная адаптивная композиция

Слой компоновки приложения поверх нативных компонентов.

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

Справочник по коду

- Сохраните рядом с main.jsx. Эти собственные правила композиции отделены от справочника токенов библиотеки.

## SumUp Circuit — настройка агента для дизайн-системы

### Отправная точка для реализации

Пример с закреплёнными версиями нативных компонентов собран и проверен в браузере локально. В образце используется только локальное состояние приложения.

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

### Запрос для вашего проекта

```
Создайте редактор позиций Circuit на основе закреплённых нативных элементов управления и подключите обе обязательные таблицы стилей. Проверяйте сумму целиком, сохраняйте форматирование валюты, сбрасывайте устаревший локальный результат проверки после изменений и отделяйте предпросмотр со стороны клиента от настоящего оформления заказа. Используйте исходную иллюстрацию и точные семантические роли токенов.
```

## SumUp Circuit — источники и область применения дизайн-системы

Руководство по приложению OpenDesign для закреплённой версии Circuit. Иллюстрация, сумма и позиция приведены в качестве примеров. Этот локальный редактор не создаёт платёжную ссылку или списание и не выполняет действий с учётной записью SumUp; в актуальных версиях пакетов используется новое пространство имён @sumup-oss.

- Документация Circuit Актуальные рекомендации по компонентам и интеграции.

- Закреплённые токены светлой темы Точные значения, использованные в этом образце.

- Источник Circuit Версии пакетов, свойства компонентов и актуальное пространство имён.

## SumUp Circuit — дополнительные ресурсы по дизайн-системе

### TDesign

Создайте компактный редактор политики API на основе TDesign React: конкретные роли тем, двухпиксельная шкала размеров, регистрация полей Form и типизированная композиция Table.

### Thumbtack Thumbprint

Создайте интерфейс для поиска услуг на основе документированных примитивов Thumbprint v2: компактные карточки поставщиков, понятные сведения для сравнения, наглядные состояния выбора и постоянно видимый список избранного.

### Twilio Paste

Подготовьте черновик уведомления с темой и правилами использования кнопок Paste, проверенной шкалой интервалов и чётким разграничением редактирования, просмотра и фактической отправки сообщения.


- [Справочник по реализации](https://circuit.sumup.com/)
- [Источник](https://cdn.jsdelivr.net/npm/@sumup/design-tokens@7.3.1/light.css)
- [Источник](https://github.com/sumup-oss/circuit-ui)
- [Справочник по коду](https://circuit.sumup.com/)
- [Документация Circuit Актуальные рекомендации по компонентам и интеграции.](https://circuit.sumup.com/)
- [Закреплённые токены светлой темы Точные значения, использованные в этом образце.](https://cdn.jsdelivr.net/npm/@sumup/design-tokens@7.3.1/light.css)
- [Источник Circuit Версии пакетов, свойства компонентов и актуальное пространство имён.](https://github.com/sumup-oss/circuit-ui)