Библиотека компонентов Gamble Hub UI

1) Цели и принципы

Зачем: ускорить поставку фич, обеспечить консистентный UX и упростить поддержку.

• Семантика и нейтральность. Компонент решает UI-задачу, не вшивая бизнес-логику.
• A11y-by-default. Роли, фокус-кольца, aria-атрибуты и контраст — вшиты в компоненты.
• i18n-first. Длины строк, числовые форматы, RTL — учитываем из коробки.
• Темизация. Светлая/темная темы и брендовые акценты через токены.
• Масштабируемость. Единые API, стабильность минорных релизов, миграции при major.

2) Основания: дизайн-токены (foundation)

json
{
"color": {
"text": { "default": "{palette. neutral. 900}", "muted": "{palette. neutral. 600}", "inverse": "{palette. neutral. 0}" },
"surface": { "default": "{palette. neutral. 0}", "elevated": "{palette. neutral. 50}", "brand": "{palette. brand. 50}" },
"accent": { "primary": "{palette. brand. 600}", "success": "{palette. green. 600}", "warning": "{palette. amber. 600}", "error": "{palette. red. 600}" }
},
"space": { "xs": 4, "sm": 8, "md": 12, "lg": 16, "xl": 24 },
"radius": { "sm": 8, "md": 12, "lg": 16, "full": 999 },
"elevation": { "0": "none", "1": "0 1px 2px rgba(0,0,0,.08)", "2": "0 4px 12px rgba(0,0,0,.12)" },
"motion": { "fast": "120ms", "base": "200ms" },
"opacity": { "disabled": 0. 45, "muted": 0. 7 }
}

Правила: семантические токены (например, `color.accent.success`) используются компонентами; палитра — внутренняя.

3) Категории компонентов

1. Базовые (Primitives): Button, Icon, Typography, Link, Badge, Divider, Avatar.
2. Формы: Input, PasswordInput, NumberInput, Select, Combobox, DatePicker, Checkbox, Radio, Switch, Slider, Textarea, FileUpload.
3. Навигация: AppBar, Tabs, Breadcrumbs, Pagination, Drawer/Sidebar, Stepper.
4. Фидбек: Alert, InlineError, Tooltip, Toast, Snackbar, Modal, Popover, Skeleton, Progress, StatusDot.
5. Данные и таблицы: Table, DataList, Card, Accordion, Tag, EmptyState.

• GameTile (карточка игры)
• ProviderBadge
• JackpotTicker
• LiveBadge (live-стол/шоу)
• LobbyFilters (провайдер/жанр/лимит)
• BonusBanner / BonusCard
• MissionProgress / AchievementBadge
• TournamentLeaderboard
• WalletCard / BalanceWidget
• PaymentMethodCard
• DepositForm / WithdrawalForm
• KYCStatusBadge / KYCChecklist
• ResponsibleGamingBanner / LimitsControl
• AgeGate / SessionTimer / RiskAlert
• SystemStatus / MaintenanceBanner

4) Страница компонента: обязательное содержание

Назначение и когда использовать/не использовать.
Состав и варианты. Размеры, состояния, модификаторы.
API. Пропсы, события, слоты, контролируемые/неконтролируемые режимы.
A11y. Роли, фокус, aria-связи, лайв-регионы.
i18n. Длины, форматы, локализуемые подписи.
Microcopy. Рекомендованные тексты (CTA, подсказки, ошибки).
Примеры кода. Типовые кейсы, edge-кейсы (ошибки, загрузка, пусто).
Тесты. Матрица визуальных/юнит/interaction/A11y.
Анти-примеры. Частые ошибки использования.

5) Ключевые компоненты: быстрые спецификации

5.1 Button

Варианты: `primary | secondary | ghost | destructive` Размеры: `sm | md | lg`

Состояния: normal, hover, focus-visible, active, loading, disabled

A11y: видимый focus-ring, `aria-busy` при `loading`, `aria-pressed` для toggle

Microcopy: действие + объект («Сохранить изменения», «Пройти верификацию»)

Анти-пример: «ОК»

5.2 Input / Field

Состав: label, field, helper, error, prefix/suffix

A11y: `aria-invalid`, `aria-describedby`, связка `for/id`

Паттерн ошибок: что не так + как исправить («Введите номер в формате +380…»)

Слоты: `prefix` (иконка), `suffix` (кнопка «показать пароль»)

5.3 Select / Combobox

Особенности: поиск по списку, клавиатура, виртуализация длинных списков

A11y: `role="combobox"`, `aria-expanded`, `aria-activedescendant`

Пустые результаты: «Ничего не найдено. Измените запрос.»

5.4 Modal / Drawer

Правила: trap focus, закрытие по ESC/overlay, возврат фокуса инициатору

Использование: подтверждения платежей, правила бонуса, KYC-шаги

5.5 Toast / Snackbar

Время: 2–4 с, без блокировки потока

Лайв-регионы: `aria-live="polite"` для успехов, `"assertive"` для ошибок

Примеры: «Платеж принят. Баланс обновлен.»

5.6 EmptyState

Шаблон: контекст + ценность + CTA + вторичный CTA

Пример: «Здесь появятся избранные игры, когда вы добавите первую. [Добавить в избранное]»

6) iGaming-компоненты: специфика и API

6.1 GameTile

Назначение: карточка игры в лобби/каталоге.
Состав: обложка, провайдер, метки (New/Hot/Jackpot/Live), RTP (опц.), быстрые действия.

ts
<GameTile title="Lightning Roulette"
provider="Evolution"
tags={["Live","Popular"]}
isJackpot={true}
onPlay={...}
onFavToggle={...}
/>

Состояния: hover (быстрый старт), skeleton, недоступно (регион/время).
A11y: alt-текст, клавиатурный старт, `aria-label="Играть в Lightning Roulette"`.

6.2 LobbyFilters

Назначение: фильтры лобби (жанр, провайдер, лимиты, волатильность).
Фичи: сохраненные пресеты, сброс фильтров, счетчик результатов.
Microcopy: «Фильтры», «Сбросить фильтры», «Найдено: 128».

6.3 BonusBanner / BonusCard

Варианты: приветственный, релоад, кэшбэк, фриспины, турнир.
Поля: заголовок, условия, срок действия, CTA («Активировать бонус»).
A11y: ссылки на условия читаемы, `aria-describedby` → детали условий.
Анти-паттерн: скрывать ключевые ограничения.

6.4 JackpotTicker

Назначение: бегущая сумма джекпота с автообновлением.
API: источник данных, период обновления, формат валюты.
A11y: `role="status"`, не нарушать читаемость скринридером.

6.5 TournamentLeaderboard

Состав: таблица позиций, очки, призы, таймер, собственная позиция.
Фичи: пагинация/виртуализация, закрепление своей строки.
A11y: `th`/`scope`, читаемые колонки, навигация стрелками.

6.6 WalletCard / BalanceWidget

Поля: баланс, заблокированные средства, бонусный баланс, валюта.
Действия: «Пополнить», «Вывести», «История».
Безопасность: скрыть/показать сумму, маскирование в общих зонах.

6.7 PaymentMethodCard

Поля: логотип провайдера, лимиты, комиссии, ETA, региональная доступность.
Состояния: недоступно (регион/статус), в обработке, предупреждение лимитов.
Microcopy: «Комиссия 1,5% удерживается провайдером», «Выплата — до 15 минут».

6.8 DepositForm / WithdrawalForm

Паттерны: inline-валидация, суммовые лимиты, same-method rule подсказками.
A11y: объявление ошибок (`assertive`), перевод фокуса к первой ошибке.
Служебные поля: «Источник средств», «Назначение», если требуется AML.

6.9 KYCStatusBadge / KYCChecklist

Состояния: `none | basic | extended | rejected | pending`.
Тексты: «Это займет ~2 минуты», «Фото без бликов, видны углы и текст».
CTA: «Пройти верификацию», вторичный: «Почему это важно?».

6.10 LimitsControl / ResponsibleGamingBanner

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

7) Паттерны компоновки (Recipes)

Регистрация/KYC: Stepper + Form + InlineError + PageAlert + SuccessToast.
Депозит: PaymentMethodCard + AmountInput + LimitsHint + ConfirmModal + StatusToast.
Лобби: SearchBar + LobbyFilters + GameGrid (из GameTile) + Pagination + EmptyState.
Турнир: TournamentLeaderboard + MissionProgress + BonusBanner.
Ответственная игра: ResponsibleGamingBanner + LimitsControl + FAQ-link.

8) Accessibility (A11y)

Видимый фокус всегда (в т.ч. в темной теме).
Навигация клавиатурой по всем интерактивным элементам.
`aria-live="polite/assertive"` для тостов/статусов.
Контрасты не ниже WCAG 2.1 AA.
Текст в иконках — не единственный носитель смысла.
RTL-режимы, проверка на 320 px и читабельность вслух.

9) Локализация и форматы

Все пользовательские строки — через i18n-ключи.

ui. button. save = Save wallet. deposit. success = Payment accepted. Balance updated.
kyc. photo. hint = Photo without glare, corners and text are visible.
filters. reset = Reset filters

Форматирование дат/валют — утилитами, не строками.
Тон на языках — через tone-map (нейтральный/поддерживающий/официальный).

10) Перформанс и качество

Виртуализация списков (игры, таблицы).
Ленивая загрузка иллюстраций, код-сплитинг по страницам.
Размеры бандла: бюджет на пакет UI, без тяжелых зависимостей.
Skeleton для восприятия скорости, спиннеры — минимально.
Тесты: юнит, визуальные снапшоты, interaction, A11y, E2E для критичных флоу.

11) Версионирование и релизы

SemVer: patch — баги; minor — неразрушающие; major — с миграциями.
Release Notes: токены/API/поведение, скриншоты до/после.
Deprecations: пометки в доке, код-моды и линтер-правила.
Storybook/Playground: живые примеры, accessibility-панель, RTL toggle.

12) Contributing (вклад)

RFC на новый компонент: проблема → варианты → выбранное решение → A11y → i18n → API → риски.
PR-чек-лист: дока, сторис, тесты, визуальные снапшоты, контрасты, i18n, dark/RTL.
Definition of Done: компонент + документация + тесты + примеры паттернов.

13) MVP-набор и дорожная карта

• Button, Input, Select, Checkbox, Radio, Switch, Modal, Toast, Tooltip, Progress, Skeleton, Card, EmptyState, Tabs, Pagination, Breadcrumbs, Table, GameTile, LobbyFilters, BonusBanner, WalletCard, PaymentMethodCard, DepositForm, KYCStatusBadge.

Далее: TournamentLeaderboard, JackpotTicker, MissionProgress, LimitsControl, SystemStatus, Drawer/Sidebar, DatePicker, Combobox, FileUpload.

14) Примеры microcopy (готовые вставки)

CTA: «Сохранить изменения», «Пройти верификацию», «Добавить способ оплаты».

Ошибки: «Неверный формат даты. Используйте ДД.ММ.ГГГГ.», «Файл слишком большой (макс. 10 МБ).»

Успех: «Платеж принят. Баланс обновлен.», «Готово! Документы проверены.»

Пустые состояния: «По “{query}” ничего не нашлось. Сбросьте фильтры или уточните запрос.»

15) Анти-паттерны

Бизнес-логика внутри UI-компонентов (ломает переиспользуемость).
Невидимый фокус или зависимость смысла только от цвета.
Строки, зашитые в код компонентов (без i18n).
Нарушение семантики (кнопка на `div`, списки без `ul/ol/li`).
Варианты без четких правил (размножение `ButtonPrimaryBlueBig2`).

16) Чек-листы

• Описаны назначение, варианты, API.
• A11y: роль, фокус, aria-атрибуты, контраст.
• i18n: все строки вынесены, проверены длинные языки и RTL.
• Сторис/демо: обычные, загрузка, ошибки, пусто.
• Тесты: юнит + визуальные + interaction + A11y.
• Нет бизнес-логики, только UI/поведение.

• Есть схема из компонентов и порядок фокуса.
• Определены microcopy и тексты ошибок/успехов.
• Замерены ключевые метрики (конверсия шага, error rate, time-to-complete).

17) Скелет документа для компонента (шаблон)

Название и назначение

Когда использовать / не использовать

Варианты и состояния

API (пропсы, события, слоты)

Accessibility (роль, клавиатура, aria, контраст)

i18n (ключи, форматы, длины, RTL)

Microcopy (примеры)

Примеры кода (типовые и edge)

Тест-матрица

Анти-примеры

Итог

Gamble Hub UI — это не просто набор блоков, а дисциплина: токены → компоненты → паттерны → документация → метрики. Следуя этому гайду, команды быстрее доставляют фичи, пользователи получают предсказуемый и доступный интерфейс, а продукт масштабируется без визуального долга. Если нужно, соберу первые страницы доки по MVP-набору с примерами и ключами i18n.