Una plataforma de puzzles tiene una contradicción interesante. Queremos que cada juego conserve su personalidad, pero también queremos que aprender a usar Blupoli 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.
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 Blupoli. 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 decenas de 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 decenas de pantallas de ayuda. Es menos espectacular que un nuevo motor, pero probablemente una de las piezas que más hará que Blupoli se sienta como un solo producto.
La cifra histórica no debe convertirse en arquitectura
La entrada original documentaba el catálogo anunciado el 15 de septiembre de 2026. Esa cifra sirve para entender la escala de aquel momento, no para definir la cobertura actual. El gate de onboarding actual lee los manifiestos presentes en games/, calcula cobertura a partir de esa fuente y falla si un juego no tiene receta, si hay slugs duplicados o si el total cubierto no coincide con los juegos detectados. La obligación crece con el catálogo automáticamente.
Este cambio evita una deuda frecuente: números editoriales convertidos accidentalmente en contratos técnicos. El requisito real es más sencillo y más fuerte: todo juego que la plataforma reconoce debe tener una explicación intencional.
Los perfiles describen interacción, no todo el razonamiento
Un perfil como digits, shade, edges, move o connect describe la gramática que conviene demostrar en una escena breve. No intenta resumir toda la lógica del puzzle. Sudoku y Kropki pueden compartir una forma de entrada basada en dígitos y, aun así, enseñar reglas totalmente distintas.
Para descubrimiento usamos un mapa más rico, explicado en las categorías del catálogo. Para onboarding preguntamos algo más concreto: ¿qué debe hacer la persona una vez para entender cómo responde este tablero?
La asignación explícita por slug hace visible la intención
El módulo de perfiles mantiene un mapeo explícito entre slugs y recetas. Puede parecer más manual que inferir automáticamente por categoría, pero es más seguro. Un fallback genérico puede producir un tutorial plausible y equivocado sin que nadie lo note. Una asignación explícita, en cambio, se puede revisar junto con el resto del código.
Cuando falta mapeo, el runtime puede expresar source:'missing'. Ese estado es útil durante desarrollo porque no oculta el problema. El pipeline no lo acepta como terminado. Representar una ausencia no significa aprobarla para producción.
El manifiesto completa la receta sin duplicar la verdad
El adapter combina el perfil con summary y rules del game.json. Además, un juego puede aportar experience.onboardingRecipe para personalizar partes de la escena cuando la mecánica no encaja en un perfil compartido.
Así evitamos escribir la misma regla principal en múltiples archivos. El manifiesto conserva contexto del juego y la receta decide cómo convertirlo en una práctica breve. Cuando hace falta una excepción, existe como override explícito en vez de crecer como condición escondida dentro del componente.
Primera visita y “Cómo jugar” son dos momentos distintos
El runtime guarda estado versionado bajo blupoli:onboarding. Si el juego todavía no se ha visto, el tutorial se abre automáticamente; después, el botón “Cómo jugar” permite reabrirlo manualmente.
La apertura inicial responde a “acabo de llegar y quizá necesito orientación”. La reapertura responde a “quiero recordar algo”. Compartir la misma infraestructura para ambos momentos reduce el riesgo de que onboarding y ayuda terminen explicando cosas diferentes.
Versionar el onboarding deja espacio para mejorar la enseñanza
Guardar solo un booleano permanente de “visto” convierte una decisión antigua en eterna. Una clave versionada permite distinguir una revisión menor de un cambio importante. No significa que cada ajuste visual obligue a repetir el tutorial.
Significa que el producto tiene un mecanismo explícito para decidir cuándo una experiencia anterior sigue siendo válida y cuándo una mejora sustancial merece otra presentación. Esa separación facilita evolucionar sin borrar el historial indiscriminadamente.
La práctica tiene que pedir una acción real
En los pasos interactivos, el mini tablero deja de ser decoración. La receta define una acción guiada y un pequeño reto. Acertar produce feedback y permite avanzar; una elección equivocada mantiene el paso y explica que hay que intentarlo de nuevo.
Eso no pretende demostrar que el usuario domina el puzzle. Solo confirma que entiende la gramática básica de interacción. El onboarding reduce la fricción para empezar; no sustituye el proceso de aprender a resolver.
La escena pedagógica no debe contaminar la partida
El mini tablero pertenece al tutorial, no al estado real del juego. Una acción de práctica no debería sumar movimientos, alterar estadísticas, modificar una racha ni dejar progreso falso.
Incluso si futuras escenas reutilizan lógica del motor real para ganar fidelidad, conviene mantener separadas las reglas compartidas del estado de sesión. Enseñar una acción y ejecutar una acción de juego son eventos diferentes, aunque visualmente se parezcan.
Responsive forma parte de enseñar
Una superposición que funciona en escritorio puede tapar justo lo que intenta explicar en móvil. El CSS actual cambia de dos columnas a una por debajo de 720 px, reduce márgenes, adapta el mini tablero y flexibiliza acciones. Por debajo de 430 px simplifica la cabecera para recuperar espacio.
La capa que enseña no puede competir con el objeto que enseña. Si obliga a hacer zoom, oculta la práctica o convierte botones en objetivos difíciles, el tutorial falla aunque el copy sea impecable.
Accesibilidad es responsabilidad del shell compartido
El botón de ayuda anuncia que abre un diálogo y referencia el onboarding. El diálogo usa aria-labelledby, el tablero de práctica tiene semántica de grupo, las celdas interactivas pueden recibir foco y el feedback usa una región aria-live="polite". El comportamiento de cancelación también se maneja explícitamente.
Centralizar estas responsabilidades significa que una mejora de foco, labels o feedback beneficia a todas las recetas, en lugar de repetirse juego por juego.
Reduced motion muestra el valor de una política común
El CSS elimina transiciones y sustituye la animación de error cuando el sistema indica prefers-reduced-motion: reduce. Ningún perfil necesita implementar esa preferencia por separado.
No pertenece a Sudoku, Slant o Ball Sort. Pertenece a cómo Blupoli presenta interacción. Resolverla en el shell evita que la accesibilidad dependa de cuándo se construyó cada juego.
Skip, cerrar, completar y reabrir no significan lo mismo
El runtime emite eventos distintos para inicio, reapertura, cierre, salto, finalización, éxito de práctica y error. Esa separación permite estudiar el sistema sin tratar cualquier salida del diálogo como la misma señal.
La interpretación debe ser prudente. Un skip no demuestra que el tutorial sea malo y una finalización no demuestra aprendizaje. Lo útil es detectar patrones concretos: escenas con demasiados errores, puntos de abandono o recetas que se consultan repetidamente.
La analítica debe describir comportamiento, no personalidad
“Reabrió Cómo jugar” significa exactamente eso. No demuestra mala memoria ni que el puzzle sea objetivamente demasiado difícil. Los eventos ayudan a encontrar fricción dentro de Blupoli; cualquier conclusión psicológica requeriría evidencia que este sistema no tiene.
La misma cautela aparece en la taxonomía del catálogo: podemos describir interacciones concretas sin convertirlas en diagnósticos.
El runtime inspeccionado sigue teniendo chrome explícito para ES y EN
La implementación actual define los textos del shell —“Cómo jugar”, “Continuar”, títulos de paso y feedback— para español e inglés, y decide entre ambos según el idioma del documento.
Por tanto, no sería correcto afirmar que este runtime concreto ya ofrece paridad completa para los seis idiomas documentados en la expansión multilingüe de Blupoli Puzzles. La arquitectura de recetas puede localizarse, pero ampliar el chrome a otros locales sigue siendo una responsabilidad concreta.
Las recetas específicas impiden que reutilizar signifique enseñar algo incorrecto
El adapter permite que un juego defina una receta propia cuando la familia compartida no es suficiente. Sin esa salida solo quedarían dos malas opciones: clonar todo el tutorial o forzar una escena genérica que se parece a la mecánica pero no la representa bien.
La regla coincide con la arquitectura de solvers: compartir aquello que realmente se repite y conservar un escape explícito para diferencias legítimas.
Una escena determinista suele enseñar mejor que un tablero aleatorio
El primer ejemplo debe coincidir con su explicación cada vez. Si la escena se genera aleatoriamente, la redacción puede dejar de encajar o aparecer un caso demasiado complejo. Un ejemplo fijo sacrifica variedad a cambio de control editorial.
El juego real puede recuperar toda la diversidad del generador. Enseñanza y contenido jugable optimizan objetivos distintos: el tutorial quiere claridad y reproducibilidad; la partida quiere riqueza y variedad.
El gate de cobertura no sustituye la revisión semántica
Que todos los slugs tengan receta demuestra cobertura estructural, no calidad pedagógica. Un juego puede estar mapeado a un perfil válido y aun así enseñar una acción poco representativa.
CI responde “ningún juego se quedó sin asignación”. Review editorial y QA responden “esta asignación es verdadera, comprensible y útil”. Automatización y juicio humano prueban cosas distintas y ambos son necesarios.
Compartir perfiles también crea blast radius
Si varios juegos dependen del mismo perfil, cambiar ese perfil puede afectar a todos. Reutilizar reduce duplicación, pero aumenta el alcance de una modificación.
Por eso conviene revisar un cambio compartido sobre varios consumidores representativos y conservar mapeos explícitos que permitan saber quién depende de qué. “Compartido” no significa automáticamente “seguro”.
Los perfiles necesitan pruebas representativas además de cobertura
El gate sabe si un slug está asignado, pero no si el mini tablero sigue ofreciendo una acción válida después de cambiar un perfil. Una suite más madura puede seleccionar representantes por familia y comprobar que la escena renderiza, que el objetivo esperado existe y que el texto principal procede del manifiesto correcto.
No hace falta multiplicar tests end-to-end por cada juego. Basta con cubrir las invariantes que hacen segura la reutilización y conservar fixtures específicas para mecánicas con comportamiento especial.
La reapertura manual puede evolucionar sin crear otro sistema
Hoy “Cómo jugar” vuelve a abrir el flujo completo. En el futuro podríamos querer una referencia más rápida para quien ya lo completó, recordar el último paso consultado o abrir directamente una regla concreta.
Ninguna de esas mejoras exige otro modal ni otra fuente de contenido. Pueden crecer sobre el mismo contrato, distinguiendo modos de entrada sin duplicar conocimiento. Esa continuidad es uno de los beneficios de tratar onboarding como infraestructura.
El onboarding debería evolucionar sin tocar el historial de juego
Cambiar copy, escena o versión del tutorial no debería alterar partidas guardadas, estadísticas ni resultados comunes. El onboarding pertenece a la capa de experiencia; el estado lógico del puzzle tiene otro ciclo de vida.
Esta frontera permite mejorar cómo enseñamos una mecánica sin migrar el dominio de cada juego y decidir independientemente si conviene mostrar otra vez una versión renovada.
Una mejora compartida debe validarse contra su radio de impacto
Cuando retocamos un perfil para solucionar un problema concreto, el cambio no termina al verse bien en ese juego. Conviene revisar otros consumidores del mismo perfil, porque la escena, el target o el valor esperado pueden haber dejado de representar correctamente otra mecánica.
Esta es la cara menos visible de la reutilización. Compartir reduce duplicación, pero exige saber qué depende de la pieza compartida. El mapeo explícito proporciona ese inventario y permite que QA seleccione ejemplos representativos antes de publicar.
El shell común también permite corregir bugs de producto una sola vez
Un problema de cierre con Escape, una etiqueta accesible insuficiente, una animación demasiado intensa o un botón demasiado pequeño no debería resolverse juego por juego. Al vivir en el shell, una corrección puede beneficiar a todo el catálogo.
Ese ahorro no es solo de código. También mejora consistencia: la persona aprende que “Cómo jugar” se comporta igual sin importar qué puzzle haya abierto, incluso cuando el contenido y la mini escena cambian por completo.
La revisión final debe comprobar producto y contenido juntos
Un onboarding puede estar técnicamente cubierto y editorialmente mal explicado, o tener un texto excelente dentro de un diálogo que falla en móvil. La publicación necesita revisar ambas capas a la vez: receta correcta, shell funcional, accesibilidad, responsive, locale y una práctica que represente de verdad la mecánica.
Ese doble criterio evita confundir “existe una receta” con “existe una buena primera experiencia”.
El mejor onboarding desaparece rápido y sigue disponible
El objetivo no es que la persona admire el tutorial. Es que entienda una acción útil, entre en el tablero real y deje de necesitar ayuda. Al mismo tiempo, “Cómo jugar” debe permanecer cerca cuando surja una duda.
Ese equilibrio sería difícil con decenas de modales independientes. Perfiles, mappings, manifest y gates convierten el problema en infraestructura que puede crecer. La plataforma se siente coherente no porque todos los puzzles sean iguales, sino porque todos reciben una explicación intencional dentro del mismo lenguaje de producto.
El contenido también necesita arquitectura
Es fácil reservar la palabra arquitectura para engines y APIs. El onboarding demuestra que copy, escenas y recorridos también se benefician de estructura explícita. Si cada explicación vive incrustada en una página, localizarla, revisarla y comprobar cobertura se vuelve caro.
Si está modelada como datos y perfiles, esas operaciones pueden sistematizarse. La ganancia final no es simplemente tener tutoriales, sino poder demostrar que cada juego entra en una experiencia de aprendizaje revisable, adaptable y verificable sin que cada nueva mecánica vuelva a empezar desde cero.