A large puzzle platform has an awkward design problem. Every game should keep its own personality, but learning how Blupoli works once should make the next puzzle feel less foreign. If every engine ships a completely separate tutorial, the product fragments. If every puzzle receives the same generic lesson, onboarding stops teaching the thing that makes each mechanic different.
The original September 15, 2026 article documented a historical catalogue snapshot of the announced catalogue and an onboarding system built around a shared shell, interaction profiles and explicit recipe mappings. That number belongs to that date. It should not be treated as the current catalogue count. The current coverage gate does something stronger: it reads the manifests that actually exist under games/ and validates onboarding against that source of truth, so the requirement grows automatically with the platform.
The first mistake is treating onboarding as a rulebook
A rules page can be thorough and still be a terrible first experience. Somebody opening an unfamiliar puzzle does not immediately need every exception, every edge case and a complete taxonomy of controls. They need to understand what can be touched, what changes when they act and what immediate goal they are working toward.
Interactive onboarding should shorten the distance to the first meaningful move. A brief orientation gives context, a guided scene demonstrates one action, a small challenge asks the player to repeat the idea and the final step hands control back to the real board. Full rules still matter, but they serve reference and depth. The tutorial should not compete with them by trying to become a compressed manual.
Three layers exist because three responsibilities change at different speeds
The first layer is the shared shell: dialog behaviour, progress, buttons, persistence, closing and navigation. The second is the interaction profile: movement, shading, edges, digits, connections, regions, logic and other input grammars. The third is game-specific content: summary, primary rule and, where needed, a custom recipe.
This structure avoids two bad extremes. We do not need one component for every puzzle, but we also do not force Slant, Sudoku and Ball Sort to pretend that they teach the same action. Reuse happens where repetition is real. That mirrors Blupoli's shared UI approach: sharing a container should not mean erasing semantics.
The historical number should not become architecture
The old article could truthfully talk about 76 mappings because 76 was the documented catalogue snapshot on September 15, 2026. The current checker does not contain an expected magic number. It reads game manifests, calculates recipe coverage and fails when a game is missing a puzzle-specific mapping, when duplicate slugs appear or when coverage no longer matches the catalogue source.
This is a small implementation detail with a large maintenance benefit. Editorial numbers describe a moment. Build rules should describe an invariant. The invariant is not “there must always be 76 tutorials.” It is “every game the repository considers part of the catalogue must have an intentional onboarding recipe.”
Profiles describe interaction grammar, not the whole puzzle
A profile such as digits, shade, edges, move or connect describes the type of action worth demonstrating in a short scene. It is not a claim that every game using that profile has the same reasoning.
Sudoku and Kropki can both involve entering digits while teaching very different constraints. Numberlink and Bridges can both use a connection grammar without becoming the same puzzle. For discovery, Blupoli uses a richer map of mechanics and reasoning, discussed in our catalogue taxonomy article. Onboarding asks a narrower question: what should somebody do once to understand how this board responds?
Explicit slug mapping is safer than a clever fallback
The profile module keeps an explicit relationship between game slugs and recipes. That may look more manual than deriving a tutorial from a category name, but it makes intent reviewable. A generic fallback can produce something plausible and wrong without drawing attention to itself.
When no recipe exists, the current code can return source:'missing'. That is valuable in development because the absence stays visible. The build gate then refuses to treat that state as finished. The distinction matters: robust systems can represent incomplete states without accepting those states as publication quality.
The game manifest completes the recipe without duplicating truth
The recipe adapter combines the interaction profile with the game's summary and rules. A game can also define experience.onboardingRecipe when it needs to override part of the shared profile without replacing the entire shell.
This keeps primary rule text from being copied into multiple unrelated files just because onboarding needs to display it. The manifest remains a source of game-specific meaning, while the recipe describes how to turn that meaning into a short practice scene. Where a mechanic genuinely needs something special, the override is explicit instead of becoming a hidden conditional inside rendering code.
First visit and “How to play” are different moments
The current runtime stores versioned state under the blupoli:onboarding namespace. If a game has not been seen, onboarding opens automatically. Afterwards, the “How to play” trigger can reopen the same flow manually.
Those are distinct needs. First-run onboarding answers “I just arrived and may not know where to begin.” Manual help answers “I want to refresh this.” Reusing the same infrastructure reduces the chance that the initial lesson and later help drift into two contradictory explanations of the same mechanic.
Versioned state gives the tutorial room to improve
A permanent boolean saying “seen” can turn an old decision into an eternal one. Versioning gives the product a place to decide whether a substantially changed tutorial should count as a new experience.
That does not mean every visual adjustment should force somebody through onboarding again. It means the system can distinguish a minor presentation change from a meaningful teaching change. A versioned contract is easier to evolve because it does not pretend that one interaction months ago settles every future onboarding decision.
Interactive practice is more useful than another Continue button
In the practice stages, the mini board stops being decorative. A recipe identifies a guided action and a challenge. Selecting the expected target produces positive feedback and allows progression; an incorrect action returns an error message and keeps the step active.
This is deliberately modest. Completing one small scene does not prove that somebody understands a complex puzzle. It proves something much more practical: they have successfully performed the type of action the real board expects. That is often enough to remove the friction that makes the first move feel uncertain.
Practice must not contaminate the real game
The onboarding mini board is a teaching scene, not the active puzzle session. A practice click should not increment move count, affect statistics, change a streak or leave artificial progress behind.
This boundary will remain important if future recipes use real engine adapters for greater fidelity. Sharing domain rules can improve correctness, but pedagogical state and player-session state should remain separate. Teaching an action and performing that action in a scored or persisted game are different product events even when they look similar on screen.
Responsive behaviour is part of teaching
A desktop overlay can become a teaching failure on a phone if it covers the exact element the copy refers to. The current stylesheet moves from two columns to one below 720 pixels, reduces padding, constrains the mini board and makes actions more flexible. Below 430 pixels, the long game title is hidden in the onboarding header to recover space.
The principle is straightforward: the layer explaining the puzzle cannot compete with the puzzle for attention. A tutorial should remain readable and touch-friendly without asking the player to zoom, fight horizontal overflow or close the dialog just to remember what it was trying to teach.
Accessibility belongs to the shared shell contract
The help trigger announces that it opens a dialog and points to the onboarding element. The dialog uses aria-labelledby, the practice board is exposed as a group, interactive cells can receive focus and feedback uses an aria-live="polite" status region. Dialog cancellation is handled explicitly.
This does not mean accessibility is permanently finished. It means the shared shell creates one place where improvements to labels, focus, feedback and semantics can benefit every recipe. Dozens of independent tutorial implementations would multiply the same maintenance problem.
Reduced motion is a good example of why behaviour belongs in one place
The current CSS removes transitions and replaces the error animation when prefers-reduced-motion: reduce is active. No individual game profile has to remember to implement that preference.
This is not Sudoku logic, Slant logic or Ball Sort logic. It is a Blupoli interaction policy. Centralizing it reduces the chance that accessibility varies simply because different games were built at different moments by different pieces of the codebase.
Skip, close, complete and reopen are not the same outcome
The runtime emits distinct events for start, reopen, close, skip, completion, practice success and error. That separation creates a more useful basis for observing the onboarding system.
Interpretation still needs restraint. A skip does not prove the tutorial is bad, and completion does not prove learning. The useful questions are narrower: does one step produce unusually many errors? Is one recipe reopened more often than others? Does a particular transition correlate with abandonment? Those signals can improve the flow without pretending to diagnose the player.
Onboarding analytics should describe behaviour, not personality
“Reopened How to play” means exactly that. It does not mean the player has poor memory or that the puzzle is objectively too difficult. Product telemetry can describe interactions inside Blupoli; broader psychological conclusions require evidence the onboarding system does not have.
This is the same restraint we apply to catalogue categories and reasoning labels. Data can help us identify friction without turning a help feature into an unnecessary profiling system.
The inspected runtime still has explicit shell copy for Spanish and English
Reviewing the implementation for this rewrite reveals an important boundary. The tutorial chrome—How to play, Continue, step titles, success feedback and error feedback—is currently defined for Spanish and English, and the runtime chooses between those two sets based on document language.
It would therefore be inaccurate to claim that this exact onboarding runtime already has full parity across the six product locales documented in the multilingual product release. The recipe architecture is localizable, but expanding the shared chrome beyond ES/EN remains a concrete responsibility. Precise boundaries are more useful than a vague “the product is multilingual” claim.
Custom recipes keep reuse from becoming false equivalence
Shared profiles are valuable until a mechanic genuinely does not fit. The adapter allows a manifest-level experience.onboardingRecipe to override selected fields while preserving the shell.
That escape hatch avoids two bad choices: cloning the whole tutorial component or forcing a generic scene that teaches something merely similar rather than correct. The principle matches our solver architecture: share what truly repeats and leave an explicit path for legitimate mathematical or interaction differences.
Deterministic scenes are usually better teachers than random boards
A first example should match its explanation every time. If onboarding generates a fresh random state on each opening, the copy can drift away from the visible situation or accidentally receive a case that is too difficult for an introduction.
A deterministic mini scene trades variety for reviewability. The real game can restore generator diversity immediately afterwards. Teaching and playing optimize different things: onboarding wants clarity and repeatability, while the game wants richness and variety.
Coverage tests do not replace semantic review
A recipe mapping for every slug proves structural coverage. It does not prove teaching quality. A game can be assigned to a technically valid profile and still show an action that is confusing or unrepresentative.
CI answers “nothing is missing.” Editorial review and product QA answer “this lesson is true, clear and useful.” Those are different forms of evidence. Treating a green coverage report as proof of pedagogy would be the same mistake as assuming a generated puzzle is correct merely because generation completed.
Shared profiles create blast radius as well as reuse
If several games depend on one profile, changing that profile can affect all of them. Reuse reduces duplicated implementation, but it increases the reach of a shared modification.
That means profile changes should be checked against representative consumers, not only the game that motivated the edit. Explicit mappings make the dependency graph visible and let QA identify which tutorials deserve another look after a shared scene, target or expected value changes.
Representative tests make shared profiles safer
The coverage gate knows whether a slug is mapped. It does not know whether the mini board still contains a valid target after a profile refactor. A mature test layer can choose representative games per profile and assert basic invariants: the scene renders, the guided target exists, the challenge target exists and game-specific text comes from the expected manifest.
That does not require a giant end-to-end suite for every puzzle. The useful goal is to test the assumptions that make profile reuse safe and preserve dedicated fixtures for mechanics that need special behaviour.
Manual reopening can evolve without creating a second help system
Today, “How to play” reopens the full onboarding flow. A future version may want a faster rule reference for somebody who already completed it, or perhaps the ability to return directly to a specific mechanic step.
None of those ideas require another modal or another copy source. They can grow on top of the same shell and recipe contract. Treating help as a recoverable capability leaves room for new modes of entry without duplicating the knowledge being maintained.
Onboarding should evolve independently of saved-game history
Changing a recipe, rewriting copy or releasing a new onboarding version should not mutate saved boards, statistics or common game results. Tutorial state belongs to the experience layer, while the logical puzzle session has a different lifecycle.
This separation keeps migrations small. We can improve how a mechanic is taught and independently decide whether a returning player should see that revision, without touching the durable game state they created while playing.
Shared shell bugs should be fixed once
A problem with Escape behaviour, an inaccessible label, an overactive animation or a button that is too small should not require one patch per game. When those behaviours live in the shell, one correction can benefit the catalogue.
The gain is not only engineering efficiency. It also creates a stronger product language. Players learn that “How to play” behaves consistently even when the puzzle, rule set and practice scene change completely.
Final review has to examine product and content together
An onboarding recipe can be structurally complete and editorially poor. It can also have excellent copy inside a dialog that fails on mobile. Publication therefore needs both layers at once: correct mapping, working shell, accessibility, responsive behaviour, locale handling and a practice scene that truthfully represents the mechanic.
This combined review prevents “a recipe exists” from becoming shorthand for “a good first experience exists.” Coverage is necessary; usefulness still has to be judged.
The best onboarding disappears quickly and remains available
The goal is not to make somebody admire the tutorial. It is to help them understand one useful action, enter the real board and stop needing assistance. At the same time, help should remain close enough to recover when the mechanic becomes uncertain.
That balance would be difficult to maintain with dozens of unrelated tutorial pages. Profiles, explicit mappings, manifests and build gates turn the problem into infrastructure that can grow with the catalogue. Coherence comes from intentional teaching inside one product language, not from pretending every puzzle is the same.
Content needs architecture too
It is easy to reserve the word architecture for engines, APIs and modules. Onboarding shows that copy, examples, rules and teaching flows benefit from explicit structure as well. If every explanation is embedded in a page, localization, review and coverage become expensive. When those pieces are represented as data and profiles, the same operations become systematic.
The important result is not merely “we have tutorials.” It is the ability to demonstrate that every game entering the catalogue also enters a reviewable, adaptable and verifiable learning experience. That is the kind of infrastructure that lets Blupoli keep adding distinct mechanics without making every new puzzle start from zero.
Engine-backed practice should borrow rules, not session lifecycle
The recipe README leaves room for future adapters that are backed by real game engines. That can be valuable when a static four-by-four scene cannot express an interaction faithfully enough. The important design constraint is to reuse the rule logic without importing every responsibility of a live game. Onboarding does not need full generation, persistence, scoring, statistics and recovery simply because it wants a truthful move.
A good adapter can ask the engine whether an action is valid, derive a small state transition and then discard the scene when the tutorial closes. That gives the lesson stronger semantic grounding while preserving the boundary between teaching and playing.
Localized teaching needs more than translated buttons
Even once the shared shell supports more locales, the recipe itself still needs semantic review. A translated core rule may be grammatically correct and yet fail to match the demonstration, especially when the mechanic depends on terms such as adjacent, exactly, consecutive or region.
The localization architecture described in our quality-gate article applies here too: structure can be checked automatically, but mechanic-sensitive teaching still deserves review against the actual scene. The tutorial is successful only when text, target and rule all describe the same idea.
Recipe changes deserve version-aware review
A shared onboarding version tells us that the shell changed, but a recipe can change independently as well. If a game receives a substantially better teaching scene, the product may eventually need to decide whether returning players should see it again. That decision should be explicit rather than an accidental consequence of localStorage keys.
We do not need per-recipe migration machinery for every wording edit. We do need enough provenance to understand what “seen” means when the experience underneath it changes materially.
One shared tutorial system is valuable because the catalogue is not static
The most important advantage appears after launch. New puzzles will arrive, existing mechanics will evolve, accessibility guidance will improve and localization coverage will expand. A collection of one-off tutorials would turn each of those changes into a manual sweep across the catalogue.
With profiles, recipes, manifests and gates, growth becomes a repeatable operation: add the game, make an explicit teaching decision, verify structural coverage, review the semantic scene and inherit shell improvements automatically. That is the kind of reuse that preserves difference instead of flattening it.