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'

Жай-күйлер: қалыпты, 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 с, ағынды бұғаттаусыз

Live-аймақтар: '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 - бұл жай ғана блоктар жиынтығы емес, пән: токендер → компоненттер → паттерндер → құжаттама → метрика. Осы гайдаға сәйкес, командалар фичтерді тез жеткізеді, пайдаланушылар болжамды және қолжетімді интерфейске ие болады, ал өнім визуалды борышсыз масштабталады. Қажет болса, i18n үлгілері мен кілттері бар MVP жиынтығы бойынша доктың бірінші беттерін жинаймын.