Interactive docs game POC

[yuliiakachmaryk]

POC: Interactive walkthrough ("game mode") for Realm docs

Pilot page: reunite/organization/sso/add-idp · Stack: Realm 0.137, Markdoc, React · New dependencies: none

Why

Long setup pages get skimmed, and skimming is how configuration goes wrong. Our investigation of support cases shows the SSO docs are where readers most often miss a section — almost always Team mapping — which comes back as "logged in but can't see the project" tickets and admin lockouts. The docs already answer this; the format doesn't make the reader stop there.

What the reader gets

1. The page renders as usual. A banner offers Play the SSO quest (only on pages that have game content).
2. A guide character runs to the first section; a card appears under it with a tip, optional gif/video, and a question.
3. Answers give instant feedback; a bottom HUD shows progress and score. Progress survives reloads; ?mode=game deep-links into it.

Interaction kinds: tip (text/media only), quiz (single choice), golf (aim ← → and swing at the right hole), match (connect two shuffled columns with drawn wires). All keyboard-driven, prefers-reduced-motion aware.

"Most skipped step" treatment (highlight=true): one-time dim of the page, pulsing brand-blue border, badge, and the character holds up a sign. Used on Team mapping together with the match game — the reader connects IdP groups to Redocly teams before moving on.

Pilot: the SSO quest (5 stops)

| Stop | Kind | Checks

-- | -- | -- | --
1 | Welcome | tip | —
2 | Gather what you need | quiz | SAML vs OIDC prerequisites
3 | Corporate or Guest? | quiz | Login type for partners
4 | The step everyone skips | match · highlight | IdP group → Redocly team
5 | Don't lock yourself out | golf | Test connection before Require SSO

How it's authored

Plain Markdoc, next to the section it belongs to; the Markdown page stays the single source of truth.

{% gameStep id="team-mapping" type="match" highlight=true badge="Most skipped step"
   leftLabel="IdP groups" rightLabel="Redocly teams" allowedMistakes=1 %}
  {% gameSay %}Adding an IdP only proves *who* someone is. Team mapping decides *what they can do*.{% /gameSay %}
  {% gameMedia src="./images/team-mapping.gif" caption="Mapping a group to a team" /%}
  {% gameQuestion %}Connect each IdP group to the team it should map to:{% /gameQuestion %}
  {% gamePair left="idp: api-writers" right="Writer (default team)" /%}
  {% gamePair left="idp: partner-readers" right="partners-readonly (RBAC team)" /%}
{% /gameStep %}

Per-page tweaks (title, CTA, labels, keyboard hints) go in front matter under game:.

How it's built

• Template @theme/templates/DocsWithGame.tsx wraps the default Markdown template, applied to docs/realm/** via markdown.template. It activates only when the page's Markdoc tagList contains gameStep — other pages render unchanged.
• Engine @theme/components/DocsGame/: store (useSyncExternalStore), tags, step card, launcher/HUD, character (SVG frames from Design, CSS motion), media.
• Kinds kinds/ are pluggable: one component + one registerStepKind() line.
• Theming via Realm theme variables + --docs-game-* tokens; dark theme included.
• The active card renders in the document flow under its section — no coordinate math, responsive by default.

Known gaps

• No analytics events yet.
• Relies on two Realm internals: @redocly/theme/core/templates/Markdown import and the imageSrc attribute resolver.
• Traced SVG frames are heavy (130–600 KB); re-export at 432×578 would cut ~4×.
• Confirm hidden game text stays out of search / AI-assistant indexing.

Proposed next steps

1. Review the pilot on a preview deploy; agree on tone and on how loud the highlight should be.
2. Add events (started, step reached, correct/incorrect per step, finished, exited).
3. Ship behind the opt-in banner; compare SSO tickets and page mood over 6–8 weeks.
4. Extend to the next high-miss pages (RBAC, requiresLogin, SCIM); add remaining character poses.
5. If numbers hold, package as a Realm plugin.

Code lives in the marketing site repo under @theme/components/DocsGame/ (README = authoring guide); currently an uncommitted local change.

Check yourself

• Code is linted
• Tested
• All new/updated code is covered with tests

Security

• Security impact of change has been considered
• Code follows company security practices and guidelines

[adamaltman]

I like this but we really need it for RBAC.

Also, I felt like it should mention there is also Redocly's log in system as an option (but those users get the signup/forgot password type emails from Redocly).