Una plataforma de puzzles tiene una contradicción interesante. Queremos que cada juego conserve su personalidad, pero también queremos que aprender a usar PuzzleHub una vez sirva para los demás. Si copiamos una interfaz completa por juego, el producto se fragmenta. Si enseñamos exactamente lo mismo en todos, el tutorial deja de enseñar.
El problema apareció con claridad al superar las primeras decenas de juegos. «Nueva partida», dificultad, deshacer o estadísticas podían compartir lenguaje. «Cómo empiezo a pensar este tablero» no.
El primer error: confundir onboarding con manual
Una página de reglas puede ser completa y seguir siendo una mala primera experiencia. El usuario que abre un puzzle desconocido no necesita todavía una taxonomía exhaustiva; necesita comprender qué puede tocar, qué cambia al hacerlo y qué objetivo persigue.
Por eso el onboarding compartido se organiza como una secuencia corta de pasos interactivos. El shell decide cómo se presenta, se avanza, se cierra y se recuerda. El perfil aporta una pequeña escena que se parece al tipo de interacción del puzzle.
Compartir el contenedor no significa compartir la explicación.
La estructura de cinco pasos
El sistema nació como una guía visual de cinco etapas que podía acompañar a cualquier juego. La ventaja no es el número cinco en sí, sino disponer de una gramática común: orientar, mostrar una acción, explicar una restricción, proponer una pequeña decisión y dejar claro cuál es el objetivo.
La estructura puede evolucionar sin que cada motor tenga que reinventar navegación, estilos o estado del tutorial. Esa separación es la que permite mejorar el onboarding como producto en lugar de mantener decenas de modales independientes.
Los perfiles son datos, no nuevas páginas
El sistema mantiene perfiles de interacción como movimiento, sombreado, aristas, dígitos, conexiones, regiones o lógica. Cada perfil define una escena de demostración, una acción guiada y un pequeño reto. Después existe un mapeo explícito entre el slug de cada juego y el perfil que debe utilizar.
Eso permite reutilizar donde la mecánica realmente coincide. Sudoku, Jigsaw Sudoku o X-Sudoku pueden compartir una base de entrada numérica; Slant necesita su propio perfil de diagonales; Ball Sort utiliza uno de movimiento; Kropki utiliza uno de dígitos con relaciones visuales. TriangleBlocks entra en la misma arquitectura con su propia asignación. Reutilizar un perfil compatible es distinto de dejar que un fallback genérico decida por nosotros.
El manifiesto del juego completa la receta
Cuando se construye el onboarding, el perfil no trabaja solo. El sistema toma también el summary y las rules del game.json para formar el objetivo y la regla principal. Así, una escena reutilizable puede conservar contexto específico sin duplicar el contenido fundamental del juego.
Este detalle es importante para mantenimiento e internacionalización. La mecánica demostrada y el contenido editorial pueden evolucionar por separado, pero siguen reuniéndose en un único contrato de onboarding.
Responsive también forma parte de enseñar
Una superposición que funciona en escritorio puede tapar justo la casilla que intenta explicar en un móvil. El sistema visual del onboarding se diseñó con objetivos táctiles, tarjetas adaptables y espacio suficiente alrededor del tablero.
La regla es sencilla: el tutorial no puede competir con el juego por la atención. Debe orientar y retirarse. Si obliga a cerrar un modal para recordar qué había que hacer, ha enseñado demasiado tarde.
La parte más importante llegó después: CI
La flexibilidad de los perfiles introducía un riesgo: añadir un juego al catálogo y olvidarse de mapearlo. El componente puede expresar técnicamente que falta configuración, pero eso no debe convertirse en una forma aceptable de publicar.
Cambiamos el contrato. check-onboarding-recipes.mjs recorre todos los manifiestos del directorio games, calcula la cobertura y falla si algún juego aparece como missing, si hay slugs duplicados o si el número de entradas cubiertas no coincide con el catálogo.
“Missing” es una señal de desarrollo, no una experiencia de producción
El código sigue pudiendo expresar que no existe una receta para un slug. Eso es útil porque hace visible el error en lugar de inventar silenciosamente una explicación. Pero la comprobación de cobertura convierte ese estado en fallo antes de publicar.
Esta distinción se está repitiendo en PuzzleHub. Un sistema robusto puede saber describir un estado incompleto; el pipeline no tiene por qué aceptar ese estado como terminado.
Escalar contenido requiere el mismo diseño que escalar código
El onboarding también nos ha recordado que el contenido es arquitectura. Si cada explicación vive incrustada en una página, traducirla, revisarla o comprobar su cobertura se vuelve caro. Si las piezas están estructuradas, podemos localizarlas, validarlas y evolucionarlas.
Eso encaja con el trabajo de internacionalización reciente: interfaz, catálogo, reglas y tutoriales deben poder crecer por idiomas sin crear seis versiones independientes del producto.
La experiencia compartida se nota precisamente cuando desaparece
El objetivo final no es que alguien admire nuestro sistema de onboarding. Es que abra un puzzle desconocido, entienda la primera acción en unos segundos y después deje de necesitarlo.
Cuando eso ocurre en 76 juegos distintos con un sistema común detrás, la plataforma gana coherencia sin borrar las diferencias entre mecánicas. Esa es exactamente la clase de infraestructura que queremos seguir construyendo.
Lo que aprendimos
Al crecer el catálogo, la pregunta dejó de ser «¿tenemos tutorial?». Ahora es «¿cada juego está conectado de forma explícita con una demostración que represente su tipo de interacción y podemos demostrar que ninguno se ha quedado atrás?».
Convertir esa respuesta en perfiles, mappings y un gate de CI ha sido mucho más valioso que diseñar setenta y seis pantallas de ayuda. Es menos espectacular que un nuevo motor, pero probablemente una de las piezas que más hará que PuzzleHub se sienta como un solo producto.