Бібліотека компонентів 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

Призначення: ліміти депозитів/ставок/часу, перерви, самовиключення.
А11у/Тон: нейтрально, без тиску, з посиланням на довідку.

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

Реєстрація/КУС: 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.