Biblioteca de componentes de Gamble Hub UI

1) Objetivos y principios

Por qué: acelerar la entrega de fich, proporcionar un UX consistente y simplificar el soporte.

• Semántica y neutralidad. El componente resuelve un problema de IU sin fusionar la lógica empresarial.
• A11y-by-default. Roles, anillos de enfoque, atributos aria y contraste - cosidos en componentes.
• i18n-first. Longitudes de fila, formatos numéricos, RTL - tomar en cuenta fuera de la caja.
• Temización. Temas claros/oscuros y acentos de marca a través de tokens.
• Escalabilidad. APIs unificadas, estabilidad de versiones menores, migración a mayor.

2) Bases: tokens de diseño (fundación)

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 }
}

Reglas: tokens semánticos (por ejemplo, 'color. accent. success ') son utilizados por los componentes; paleta - interior.

3) Categorías de componentes

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

• GameTile (tarjeta del juego)
• ProviderBadge
• JackpotTicker
• LiveBadge (live-table/show)
• LobbyFilters (proveedor/género/límite)
• BonusBanner / BonusCard
• MissionProgress / AchievementBadge
• TournamentLeaderboard
• WalletCard / BalanceWidget
• PaymentMethodCard
• DepositForm / WithdrawalForm
• KYCStatusBadge / KYCChecklist
• ResponsibleGamingBanner / LimitsControl
• AgeGate / SessionTimer / RiskAlert
• SystemStatus / MaintenanceBanner

4) Página del componente: contenido obligatorio

Asignación y cuándo usar/no utilizar.
Composición y opciones. Dimensiones, estados, modificadores.
API. Props, eventos, ranuras, modos controlados/no controlados.
A11y. Roles, enfoque, conexiones aria, regiones en vivo.
i18n. Longitudes, formatos, firmas localizables.
Microcopy. Textos recomendados (CTA, pistas, errores).
Ejemplos de código. Casos típicos, casos edge (errores, descarga, en blanco).
Pruebas. Matriz visual/unit/interaction/A11y.
Ejemplos anti. Frecuentes errores de uso.

5) Componentes clave: especificaciones rápidas

5. 1 Button

Opciones: 'primary | secondary | ghost | destructive' Dimensiones: 'sm | md | lg'

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

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

Microcopy: acción + objeto (Guardar cambios, Pasar verificación)

Anti-ejemplo: «OK»

5. 2 Input / Field

Composición: label, campo, helper, error, prefix/suffix

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

Patrón de errores: qué no es así + cómo corregir («Escriba el número en formato + 380»...)

Ranuras: 'prefix' (icono), 'suffix' (botón 'mostrar contraseña')

5. 3 Select / Combobox

Características: búsqueda por lista, teclado, virtualización de listas largas

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

Resultados vacíos: "No se ha encontrado nada. Cambie la consulta"

5. 4 Modal / Drawer

Reglas: trap focus, cierre por ESP/overlay, devuelve el enfoque al iniciador

Uso: confirmaciones de pago, reglas de bonificación, pasos KYC

5. 5 Toast / Snackbar

Tiempo: 2-4 s, sin bloqueo de flujo

Regiones en vivo: 'aria-live =' polite 'para el éxito,' assertive 'para los errores

Ejemplos: "Pago aceptado. Balance actualizado"

5. 6 EmptyState

Plantilla: contexto + valor + CTA + CTA secundario

Ejemplo: "Los juegos favoritos aparecerán aquí cuando agregues el primero. [Añadir a Favoritos"

6) Componentes iGaming: específico y API

6. 1 GameTile

Asignación: tarjeta de juego en el lobby/directorio.
Composición: portada, proveedor, etiquetas (New/Hot/Jackpot/Live), RTP (opt.) , acción rápida.

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

Estados: hover (inicio rápido), skeleton, no disponible (región/hora).
A11y: texto alt, inicio de teclado, 'aria-label =' Juega a la ruleta de luz '.

6. 2 LobbyFilters

Propósito: filtros de lobby (género, proveedor, límites, volatilidad).
Fichas: preajustes guardados, restablecimiento de filtros, contador de resultados.
Microcopy: «Filtros», «Restablecer filtros», «Encontrado: 128».

6. 3 BonusBanner / BonusCard

Opciones: bienvenida, reload, cashback, freespins, torneo.
Campos: título, condiciones, fecha de caducidad, CTA («Activar bonificación»).
A11y: las referencias a las condiciones son legibles, 'aria-describedby' → los detalles de las condiciones.
Anti-patrón: ocultar las restricciones clave.

6. 4 JackpotTicker

Asignación: la suma de ejecución del jackpot con AutoUpdate.
API: origen de datos, período de actualización, formato de moneda.
A11y: 'role = «status»', no alterar la legibilidad por parte del screenrider.

6. 5 TournamentLeaderboard

Composición: tabla de posiciones, puntos, premios, temporizador, posición propia.
Fichi: paginación/virtualización, anclando su línea.
A11y: 'th '/' scope', columnas legibles, navegación con flechas.

6. 6 WalletCard / BalanceWidget

Campos: saldo, fondos bloqueados, saldo de bonificación, moneda.
Acciones: «Reponer», «Sacar», «Historia».
Seguridad: ocultar/mostrar la cantidad, enmascarar en zonas comunes.

6. 7 PaymentMethodCard

Campos: logo del proveedor, límites, comisiones, ETA, accesibilidad regional.
Estados: no disponible (región/estado), en procesamiento, advertencia de límites.
Microcopy: «La comisión del 1,5% la tiene el proveedor», «El pago es de hasta 15 minutos».

6. 8 DepositForm / WithdrawalForm

Patrones: validación en línea, límites de suma, regla de same-method con sugerencias.
A11y: declarar errores ('assertive'), traducir el foco al primer error.
Campos de servicio: «Fuente de fondos», «Asignación» si se requiere AML.

6. 9 KYCStatusBadge / KYCChecklist

Estados: 'none | basic | extended | rejected | pending'.
Textos: «Tardará ~ 2 minutos», «Foto sin resplandor, ángulos y texto visibles».
CTA: "Pasar la verificación", secundaria: "¿Por qué es importante? ».

6. 10 LimitsControl / ResponsibleGamingBanner

Propósito: límites de depósitos/apuestas/tiempo, interrupciones, auto-exclusión.
A11u/Tono: neutral, sin presión, con referencia a la referencia.

7) Patrones de diseño (Recipes)

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

8) Accessibility (A11y)

Foco visible siempre (incluyendo en el tema oscuro).
Navega por el teclado a través de todos los elementos interactivos.
'aria-live =' polite/assertive '' para tostadas/estados.
Los contrastes no son inferiores a WCAG 2. 1 AA.
El texto en los iconos no es el único medio de significado.
Modos RTL, comprobación de 320 px y legibilidad en voz alta.

9) Localización y formatos

Todas las cadenas personalizadas - a través de 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

Formato de fecha/moneda - utilidades, no cadenas.
El tono en los idiomas es a través de tone-map (neutro/compatible/oficial).

10) Performance y calidad

Virtualización de listas (juegos, tablas).
Carga perezosa de ilustraciones, spliting de código por páginas.
Dimensiones de la banda: presupuesto para el paquete de IU, sin dependencias pesadas.
Skeleton para la percepción de la velocidad, spinners - mínimo.
Pruebas: yunite, snapshots visuales, interaction, A11y, E2E para flow crítico.

11) Versificación y lanzamientos

SemVer: patch - bugs; minor - no destructivo; major - con migraciones.
Notas de lanzamiento: tokens/API/comportamiento, capturas de pantalla antes/después.
Depresiones: marcas en el muelle, códigos de moda y reglas linter.
Storybook/Playground: ejemplos en vivo, panel de accesibilidad, toggle RTL.

12) Contributing (contribución)

RFC a un nuevo componente: el problema → las variantes → la decisión escogida → A11y → i18n → API → los riesgos.
Lista de cheques PR: dock, stories, pruebas, snapshots visuales, contrastes, i18n, dark/RTL.
Definición de Don: componente + documentación + pruebas + ejemplos de patrones.

13) Conjunto de MVP y hoja de ruta

• 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) Ejemplos de microcopia (insertos terminados)

CTA: «Guardar cambios», «Pasar la verificación», «Añadir método de pago».

Errores: "Formato de fecha incorrecto. Use DD. MM. GGG. ", "El archivo es demasiado grande (máx. 10 MB)"

Éxito: "Se acepta el pago. Balance actualizado. «, «¡Listo! Los documentos han sido verificados"

Estados vacíos: "Por "{query}" no se encontró nada. Restablezca los filtros o refine la solicitud"

15) Anti-patrones

Lógica de negocio dentro de los componentes de IU (rompe la sobreusabilidad).
Enfoque invisible o dependencia del significado sólo del color.
Líneas cosidas en el código de componentes (sin i18n).
Infracción de la semántica (botón en 'amb', listas sin 'ul/ol/li').
Variantes sin reglas claras (reproducción de 'ButtonPrimaryBlueBig2').

16) Hojas de cheques

• Se describe la asignación, opciones, API.
• A11y: rol, enfoque, atributos aria, contraste.
• i18n: todas las líneas han sido emitidas, idiomas largos y RTL probados.
• Stories/demo: normal, descarga, errores, vacío.
• Pruebas: unit + visual + interaction + A11y.
• No hay lógica de negocio, sólo IU/comportamiento.

• Hay un esquema de componentes y un orden de enfoque.
• Microcopy y textos de error/éxito definidos.
• Métricas clave medidas (conversión de paso, error rate, time-to-complete).

17) Esqueleto de documento para el componente (plantilla)

Título y destino

Cuándo utilizar/no utilizar

Opciones y estados

API (props, eventos, ranuras)

Accesibilidad (rol, teclado, aria, contraste)

i18n (claves, formatos, longitudes, RTL)

Microcopy (ejemplos)

Ejemplos de código (tipo y edge)

Matriz de prueba

Anti-ejemplos

Gamble Hub UI no es solo un conjunto de bloques, sino una disciplina: tokens → componentes → patrones → documentación → métricas. Siguiendo este gaida, los equipos entregan fiches más rápidamente, los usuarios obtienen una interfaz predecible y accesible, y el producto se escala sin deuda visual. Si es necesario, recopilaré las primeras páginas del muelle mediante un conjunto MVP con ejemplos y claves i18n.