Gamble Hub UI Component Library

1) Goals and principles

Why: Speed up feature delivery, provide consistent UX, and simplify support.

• Semantics and neutrality. The component solves the UI problem without sewing in the business logic.
• A11y-by-default. Roles, focus rings, aria attributes and contrast are sewn into the components.
• i18n-first. Line lengths, numerical formats, RTL - take into account out of the box.
• Temization. Light/dark themes and branded accents through tokens.
• Scalability. Uniform APIs, stability of minor releases, migrations under major.

2) Grounds: design tokens (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 }
}

Rules: semantic tokens (e.g. 'color. accent. success') are used by components; palette - internal.

3) Component categories

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

• GameTile (game card)
• ProviderBadge
• JackpotTicker
• LiveBadge (live table/show)
• LobbyFilters (provider/genre/limit)
• BonusBanner / BonusCard
• MissionProgress / AchievementBadge
• TournamentLeaderboard
• WalletCard / BalanceWidget
• PaymentMethodCard
• DepositForm / WithdrawalForm
• KYCStatusBadge / KYCChecklist
• ResponsibleGamingBanner / LimitsControl
• AgeGate / SessionTimer / RiskAlert
• SystemStatus / MaintenanceBanner

4) Component Page: Required Content

Purpose and when to use/not to use.
Composition and variants. Dimensions, states, modifiers.
API. Props, events, slots, controlled/uncontrolled modes.
A11y. Roles, focus, aria connections, live regions.
i18n. Lengths, formats, localizable signatures.
Microcopy. Recommended texts (CTA, hints, errors).
Code examples. Typical cases, edge cases (errors, loading, empty).
Tests. Visual matrix/unit/interaction/A11y.
Anti-examples. Frequent usage errors.

5) Key Components: Quick Specs

5. 1 Button

Variants: 'primary | secondary | ghost | destructive' Dimensions: 'sm | md | lg'

States: normal, hover, focus-visible, active, loading, disabled

A11y: visible focus-ring, 'aria-busy' for 'loading', 'aria-pressed' for toggle

Microcopy: action + object (Save Changes, Verify)

Anti-example: "OK"

5. 2 Input / Field

Ingredients: label, field, helper, error, prefix/suffix

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

Error pattern: what is wrong + how to fix ("Enter the number in the format + 380...")

Slots: 'prefix' (icon), 'suffix' (button "show password")

5. 3 Select / Combobox

Features: list search, keyboard, long list virtualization

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

Blank results: "Nothing found. Change the request"

5. 4 Modal / Drawer

Rules: trap focus, ESC/overlay close, return focus to initiator

Usage: Payment Confirmations, Rebate Rules, KYC Steps

5. 5 Toast / Snackbar

Time: 2-4 s, no flow blocking

Live regions: 'aria-live = "polite"' for success, '"assertive"' for mistakes

Examples: "Payment accepted. The balance has been updated"

5. 6 EmptyState

Template: context + value + CTA + secondary CTA

Example: "Selected games will appear here when you add the first one. [Add to Favorites"

6) iGaming components: specifics and API

6. 1 GameTile

Purpose: game card in the lobby/catalog.
Composition: cover, provider, tags (New/Hot/Jackpot/Live), RTP (wholesale) , quick action.

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

States: hover (fast start), skeleton, unavailable (region/time).
A11y: alt-text, keyboard start, 'aria-label = "Play Lightning Roulette"'.

6. 2 LobbyFilters

Purpose: lobby filters (genre, provider, limits, volatility).
Features: saved presets, resetting filters, result counter.

Microcopy: "Filters," "Reset filters," "Found: 128."

6. 3 BonusBanner / BonusCard

Options: welcome, reload, cashback, freespins, tournament.
Fields: header, conditions, validity period, CTA ("Activate bonus").
A11y: references to conditions are readable, 'aria-describby' → details of conditions.
Anti-pattern: Hide key constraints.

6. 4 JackpotTicker

Purpose: Auto-refresh jackpot running amount.
API: data source, update period, currency format.
A11y: 'role = "status"', do not violate the readability of the screen reader.

6. 5 TournamentLeaderboard

Composition: position table, points, prizes, timer, own position.
Feature: pagination/virtualization, fixing your line.
A11y: 'th '/' scope', readable columns, arrow navigation.

6. 6 WalletCard / BalanceWidget

Fields: balance, blocked funds, bonus balance, currency.

Actions: "Top up," "Display," "History."

Security: hide/show amount, masking in common areas.

6. 7 PaymentMethodCard

Fields: provider logo, limits, commissions, ETA, regional availability.
States: not available (region/status), in process, limit warning.

Microcopy: "1.5% commission is withheld by the provider," "Payment - up to 15 minutes."

6. 8 DepositForm / WithdrawalForm

Patterns: inline validation, amount limits, same-method rule prompts.
A11y: declaring errors ('assertive'), turning focus to the first error.
Service fields: "Source of funds," "Purpose," if AML is required.

6. 9 KYCStatusBadge / KYCChecklist

States: 'none | basic | extended | rejected | pending'.

Texts: "It will take ~ 2 minutes," "Photo without glare, corners and text are visible."

CTA: "Get verified," secondary: "Why is this important? ».

6. 10 LimitsControl / ResponsibleGamingBanner

Purpose: limits of deposits/rates/time, breaks, self-exclusion.
А11у/Tone: neutral, no pressure, with reference to the help.

7) Layout patterns (Recipes)

Registration/ACC: Stepper + Form + InlineError + PageAlert + SuccessToast.
Депозит: PaymentMethodCard + AmountInput + LimitsHint + ConfirmModal + StatusToast.
Лобби: SearchBar + LobbyFilters + GameGrid (из GameTile) + Pagination + EmptyState.
Турнир: TournamentLeaderboard + MissionProgress + BonusBanner.
Responsible: ResponsibleGamingBanner + LimitsControl + FAQ-link.

8) Accessibility (A11y)

Visible focus always (including in a dark theme).
Keyboard navigation through all interactive elements.
'aria-live = "polite/assertive" 'for toasts/statuses.
Contrasts not lower than WCAG 2. 1 AA.
The text in the icons is not the only carrier of meaning.
RTL modes, 320 px check and readability out loud.

9) Localization and formats

All user strings are through i18n keys.

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

Formatting dates/currencies - with utilities, not strings.
Tone in languages ​ ​ - via tone-map (neutral/supportive/official).

10) Performance and quality

List virtualization (games, tables).
Lazy loading of illustrations, code-splicing by pages.
Bundle sizes: UI package budget, no heavy dependencies.
Skeleton for speed perception, spinners - minimal.
Tests: unit, visual snapshots, interaction, A11y, E2E for critical flow.

11) Versioning and releases

SemVer: patch - bugs; minor - non-destructive; major - with migrations.
Release Notes: tokens/API/behavior, before/after screenshots.
Deprecations: Dock markings, code mods and linter rules.
Storybook/Playground: live examples, accessibility panel, RTL toggle.

12) Contributing

RFC on a new component: a problem → options → the chosen decision → A11y → i18n → API → risks.
PR checklist: docks, stories, tests, visual snapshots, contrasts, i18n, dark/RTL.
Definition of Done: component + documentation + tests + pattern examples.

13) MVP set and road map

• 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 examples (finished inserts)

CTA: "Save changes," "Get verified," "Add a payment method."

Errors: "Invalid date format. Use DD. MM. YYYY. , ""The file is too large (max. 10 MB)"

Success: "Payment accepted. Balance updated. "",Done! Documents verified"

Empty states: "By "{query}" nothing was found. Reset the filters or refine the query"

15) Anti-patterns

Business logic within UI components (breaks overuse).
Invisible focus or dependence of meaning only on color.
Strings embedded in component code (without i18n).
Violation of semantics (button on 'div', lists without 'ul/ol/li').
Variants without clear rules (multiplication 'ButtonPrimaryBlueBig2').

16) Checklists

• Purpose, variants, API are described.
• A11y: role, focus, aria attributes, contrast.
• i18n: all lines are rendered, long languages ​ ​ and RTL are checked.
• Story/Demo: Normal, Download, Error, Blank.
• Tests: unit + visual + interaction + A11y.
• No business logic, only UI/behavior.

• There is a scheme of components and a focus order.
• Microcopy and error/success texts are defined.
• Key metrics measured (step conversion, error rate, time-to-complete).

17) Document skeleton for component (template)

Name and purpose

When to use/not to use

Options and states

API (props, events, slots)

Accessibility (role, keyboard, aria, contrast)

i18n (keys, formats, lengths, RTL)

Microcopy (examples)

Code samples (typical and edge)

Test matrix

Anti-examples

Total

Gamble Hub UI is not just a set of blocks, but a discipline: tokens → components → patterns → documentation → metrics. Following this guide, teams deliver features faster, users get a predictable and affordable interface, and the product scales without visual debt. If necessary, I will collect the first pages of the dock by MVP-set with examples and i18n keys.