03. UX/UI и дизайн-система

1. Принципы UX

1. Один экран — одно решение. Пользователь не выбирает между десятками настроек.
2. Результат важнее процесса. Показываем, что произойдёт, а не как устроено.
3. Честность. Цена, лимиты и риски видны до оплаты.
4. Обратимость. Можно вернуться, поставить на паузу, переподключить.
5. Понятная ошибка. Всегда: что случилось, почему, что сделать.
6. Минимум терминов. «Связка», «Подключение», «Запуск» вместо «транзакция», «нода», «маппинг».
7. Доступность. WCAG 2.1 AA, клавиатура, контраст, фокус, prefers-reduced-motion.

1.1. Тон коммуникации

• Дружелюбно, но без панибратства.
• Короткие предложения. Активный залог.
• Никакого «упс» и «ой». Вместо «Ошибка 403» — «Telegram не принял токен. Проверьте, что бот не удалён».
• В кнопках — глагол + объект: «Подключить Telegram», «Отправить тест», «Включить связку».

---

2. Карта экранов

Публичная часть

Кабинет

Админка

/admin — обзор; /admin/users; /admin/bundles; /admin/services; /admin/runs; /admin/payments; /admin/incidents; /admin/content; /admin/audit.

Документация проекта

/docs — опубликованное ТЗ (этот документ) с оглавлением и поиском.

---

3. Ключевые пользовательские потоки

3.1. Первая связка (главный flow)

Лендинг
  └─ «Выбрать связку» → Каталог
       └─ Карточка связки
            └─ «Подключить в один клик»
                 ├─ [не авторизован] Регистрация (email) → подтверждение
                 └─ Wizard
                      1. Обзор: что произойдёт, доступы, цена
                      2. Подключить источник (OAuth/токен)
                      3. Подключить приёмник (OAuth/токен)
                      4. Поля: авто-маппинг (до 5 правок)
                      5. Тест: отправить, увидеть результат
                      6. Активация: trial 7 дней → «Включить»
                          └─ Успех: «Связка работает» + пример события

Правила:

• Регистрация запрашивает только email и пароль; имя — опционально.
• Прогресс: 6 шагов, но экранов после регистрации — не более 5.
• Черновик сохраняется автоматически.
• Если сервис уже подключён — шаг пропускается.
• Кнопка «Назад» не теряет данные.
• Выход из wizard — с подтверждением «Черновик сохранён».

3.2. Ошибка и восстановление

Email «Связка остановлена» → Кабинет → Активация
  └─ Баннер: «Telegram отклонил токен»
       ├─ «Переподключить» → OAuth/токен → проверка → «Возобновить»
       └─ «Почему?» → статья/чат

3.3. Оплата

Конец trial → Email за 24 часа → Биллинг
  └─ «Оплатить 200 ₽» → ЮKassa → успех → чек на email
       └─ Ошибка → «Повторить» / «Другой способ» → grace 3 дня

3.4. Пауза и удаление

• Пауза: мгновенно, без потери настроек, с пояснением про тарификацию.
• Удаление: модалка с вводом названия связки (защита от случайности), предупреждение о удалении вебхука и истории через 90 дней.

---

4. Wireframes (низкая детализация)

4.1. Лендинг

┌──────────────────────────────────────────────────────────────┐
│ Logo   Каталог  Тарифы  Помощь            Войти  [Начать]   │
├──────────────────────────────────────────────────────────────┤
│  [badge] Готовые интеграции без конструктора                 │
│  Интеграции в один клик.            ┌──────────────────────┐ │
│  200 ₽ за связку.                   │  Tilda → Telegram    │ │
│  Одна связка — одна функция.        │  ● Подключено        │ │
│  [Выбрать связку] [Как это работает]│  ┌────┐   ┌────┐     │ │
│                                     │  │Tilda│ → │Telegram│ │
│  ✓ Без кода  ✓ Без транзакций       │  └────┘   └────┘     │ │
│                                     └──────────────────────┘ │
├──────────────────────────────────────────────────────────────┤
│  Логотипы сервисов (marquee)                                 │
├──────────────────────────────────────────────────────────────┤
│  3 шага: Выберите → Подключите → Включите                    │
├──────────────────────────────────────────────────────────────┤
│  Популярные связки (bento-сетка 6 карточек)                  │
├──────────────────────────────────────────────────────────────┤
│  Почему easy-connect (4 преимущества)                        │
├──────────────────────────────────────────────────────────────┤
│  Тариф: 200 ₽/мес за связку   [Попробовать 7 дней]           │
├──────────────────────────────────────────────────────────────┤
│  FAQ (accordion)                                             │
├──────────────────────────────────────────────────────────────┤
│  Footer: документы, контакты, статус                         │
└──────────────────────────────────────────────────────────────┘

4.2. Каталог

┌──────────────────────────────────────────────────────────────┐
│ Поиск: [заявка в телеграм____________________]               │
│ Категории: Все | CRM | Мессенджеры | Таблицы | Формы | ...   │
│ Фильтры: Источник ▾  Приёмник ▾  Сортировка ▾                │
├──────────────────────────────────────────────────────────────┤
│ ┌────────────┐ ┌────────────┐ ┌────────────┐                │
│ │ Tilda → TG │ │ Форма → amo│ │ Sheets → TG│                │
│ │ Заявка в TG│ │ Сделка в CRM│ │ Строка в TG│                │
│ │ 200 ₽/мес  │ │ 200 ₽/мес  │ │ 200 ₽/мес  │                │
│ └────────────┘ └────────────┘ └────────────┘                │
└──────────────────────────────────────────────────────────────┘

4.3. Wizard

┌──────────────────────────────────────────────────────────────┐
│ ← Назад    Шаг 2 из 5   ●●○○○                                │
│                                                              │
│  Подключите Telegram                                         │
│  Нужен бот и его токен. Мы покажем, где его взять.           │
│                                                              │
│  [Открыть инструкцию]                                        │
│  Токен: [____________________________________]  [Проверить]  │
│                                                              │
│  ✓ Бот @my_shop_bot подключён                                │
│                                                              │
│                                        [Продолжить →]        │
└──────────────────────────────────────────────────────────────┘

4.4. Обзор кабинета

┌────────────┬─────────────────────────────────────────────────┐
│ Logo       │  Обзор                          [ + Связка ]   │
│            │                                                 │
│ Обзор      │  ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│ Связки     │  │Активны 3│ │Запуски  │ │Успешно  │           │
│ Запуски    │  │         │ │ 1 234   │ │ 99,2 %  │           │
│ Подключения│  └─────────┘ └─────────┘ └─────────┘           │
│ Биллинг    │                                                 │
│ Настройки  │  ⚠ Требует внимания: Telegram отклонил токен   │
│            │    [Переподключить]                             │
│            │                                                 │
│            │  Мои связки                                     │
│            │  ● Tilda → Telegram   активна   12 мин назад    │
│            │  ● Форма → amoCRM     активна   1 час назад     │
│            │  ⏸ Sheets → SMS       пауза                    │
└────────────┴─────────────────────────────────────────────────┘

4.5. Детали запуска

┌──────────────────────────────────────────────────────────────┐
│ ← Запуски     #run_01HX...    Успешно · 1,2 с                │
├──────────────────────────────────────────────────────────────┤
│ 09:41:02  Получено событие (Tilda)                           │
│ 09:41:02  Валидация пройдена                                 │
│ 09:41:02  Фильтр: пропущено (нет телефона)? → нет            │
│ 09:41:03  Telegram: сообщение отправлено                     │
├──────────────────────────────────────────────────────────────┤
│ Вход (маскировано)          │ Результат                      │
│ name: Иван                  │ message_id: 12345              │
│ phone: +7••••••1234         │ chat_id: -100...               │
│ email: i•••@mail.ru         │                                │
├──────────────────────────────────────────────────────────────┤
│ [Повторить]  [Сообщить в поддержку]                          │
└──────────────────────────────────────────────────────────────┘

---

5. Дизайн-система

5.1. Цвета

Тёмная тема (P1): фон #070B14, поверхность #0E1626, текст #EAF1FF, primary #4C8DFF. Контраст проверяется отдельно.

5.2. Типографика

• Основной шрифт: Manrope (кириллица), fallback Inter, system-ui, -apple-system, Segoe UI, sans-serif.
• Моно: JetBrains Mono для ID, токенов, логов.
• Шкала: 12 / 14 / 16 / 18 / 22 / 28 / 36 / 48 / 64 px.
• Заголовок hero: 48–64 px, weight 700, line-height 1.05, letter-spacing -0.02em.
• Body: 16 px, line-height 1.6.
• Максимум 70 символов в строке для текста.

5.3. Сетка и отступы

• Контейнер: 1200 px, боковые поля 24 px (моб. 16 px).
• Сетка: 12 колонок, gutter 24 px.
• Шкала отступов: 4, 8, 12, 16, 24, 32, 48, 64, 96.
• Радиусы: 10 px (inputs), 14 px (карточки), 999 px (pill).
• Тени: мягкие, 1–2 слоя, без тяжёлых чёрных.

5.4. Компоненты (база shadcn/ui)

Button, Input, Select, Combobox, Checkbox, Radio, Switch, Textarea, Dialog, Sheet, Popover, Tooltip, Tabs, Accordion, Badge, Alert, Toast, Table, Pagination, Breadcrumbs, Progress, Skeleton, EmptyState, Stepper, CodeBlock, CopyButton.

5.5. Состояния

• Default / Hover / Active / Focus-visible / Disabled / Loading / Error.
• Обязательная фокус-рамка: 2 px --primary + offset 2 px.
• Loading: skeleton для контента, spinner только для действий ≤ 10 с.
• Пустые состояния: иллюстрация + объяснение + действие.

---

6. Magic UI: карта применения

Magic UI используется для акцентных, «дорогих» элементов, а не для всего интерфейса. Базовые формы и таблицы — shadcn/ui, чтобы сохранить скорость и доступность.

Правила:

• Не более 2 анимированных акцентов в одном viewport.
• Все анимации отключаются при prefers-reduced-motion: reduce.
• Никаких автопрокручивающихся каруселей с текстом.
• Анимация не должна блокировать CLS: фиксированные размеры контейнеров.
• Magic UI-компоненты оборачиваются в собственные обёртки с дизайн-токенами, чтобы не зависеть от дефолтных цветов библиотеки.

---

7. Экранные требования

7.1. Главная

• Первый экран: оффер, подзаголовок, 2 CTA, визуальный пример связки.
• Визуальный пример — интерактивная карточка: «Tilda → Telegram», статус, превью сообщения. Без реальных данных.
• Секция «Как это работает»: 3 шага с иконками.
• «Популярные связки»: 6 карточек с переходом.
• Сравнение: таблица «Конструкторы vs easy-connect» (простота, цена, скорость).
• Тариф: 200 ₽, trial, отсутствие транзакционных списаний.
• FAQ: 6–8 вопросов.
• Финальный CTA.
• Футер: документы, контакты, статус, GitHub.

7.2. Страница связки

• H1: «Заявка Tilda → сообщение в Telegram».
• Underline: «Каждая новая заявка автоматически приходит в чат».
• Схема A → B с иконками.
• «Что нужно»: аккаунты и доступы.
• «Что произойдёт»: пример сообщения/записи.
• «Сколько стоит»: 200 ₽/мес, trial.
• CTA sticky на мобильном.
• Похожие связки.
• Статус коннекторов.

7.3. Wizard

• Stepper с названиями шагов.
• Один основной вопрос на экран.
• Контекстная помощь: ссылка «Где взять токен?» с инструкцией и скриншотами.
• Валидация на месте, без перезагрузки.
• Тест: чёткое предупреждение о реальных данных.
• Активация: итоговая карточка «Что включим», цена, trial.

7.4. Кабинет

• Левое меню (desktop), нижняя навигация (mobile, 4 пункта + «Ещё»).
• Верхняя панель: поиск, уведомления, профиль.
• Плотность: таблицы с 44 px строками, на mobile — карточки.
• Все действия доступны с клавиатуры.

7.5. Админка

• Отдельный layout, тёмная тема (P1), плотные таблицы.
• Фильтры сохраняются в URL.
• Опасные действия — с подтверждением и аудитом.

---

8. Тексты и микрокопирайтинг

Запрещено: «произошла неизвестная ошибка», «обратитесь к администратору», «упс», «что-то пошло не так» без объяснения.

---

9. Доступность (WCAG 2.1 AA)

• Контраст текста ≥ 4,5:1, крупного ≥ 3:1.
• Все интерактивные элементы доступны с клавиатуры, логичный порядок Tab.
• aria-label для иконочных кнопок; aria-live для тостов и результатов теста.
• Формы: label связан с полем, ошибки озвучиваются, aria-invalid.
• Не использовать цвет как единственный носитель смысла.
• Анимации отключаются при prefers-reduced-motion.
• Видео/гифки с субтитрами, без автозвука.
• Проверка: axe, ручной проход со скринридером (NVDA), клавиатура.

---

10. Адаптивность

Тестируемые ширины: 320, 375, 414, 768, 1024, 1280, 1440, 1920.

---

11. Производительность интерфейса

• LCP ≤ 2,5 с, INP ≤ 200 мс, CLS ≤ 0,1 (75-й перцентиль).
• JS на лендинге ≤ 180 КБ gzip (без тяжёлых библиотек).
• Изображения: AVIF/WebP, srcset, ленивая загрузка ниже первого экрана.
• Шрифты: self-hosted, font-display: swap, preload основного weight.
• Иконки: SVG-спрайт или Lucide, без иконочных шрифтов.
• Анимации: только transform/opacity, will-change точечно.

---

12. SEO и метаданные

• Уникальные title/description для лендинга, каталога, страниц связок.
• Canonical, Open Graph, Twitter Card.
• JSON-LD: Organization, WebSite, SoftwareApplication, FAQPage, BreadcrumbList.
• sitemap.xml, robots.txt; кабинет и админка — noindex.
• Человекочитаемые URL: /bundle/tilda-to-telegram.
• Хлебные крошки на страницах связок и категорий.
• 404/500 — брендированные, с навигацией.

---

13. Контент-требования

• Каждая связка: заголовок, 1–2 абзаца, пример данных, требования, ограничения.
• Скриншоты/гифки настройки — для топ-10 связок.
• Статьи помощи: «Где взять токен Telegram», «Как подключить Tilda», «Что делать, если amoCRM отклонила токен».
• Юридические тексты — на русском, версионируются, дата публикации.

---

14. Definition of Done для UI

1. Макеты desktop/mobile согласованы.
2. Компоненты реализованы на shadcn/ui + Magic UI, токены применены.
3. Все состояния (loading, empty, error, disabled) проработаны.
4. Доступность проверена (axe + клавиатура).
5. Lighthouse ≥ 90 по Performance/Accessibility/Best Practices/SEO.
6. Тексты проверены редактором, нет англицизмов без необходимости.
7. Аналитика кликов и воронки размечена.