Phase 3: build the xore/theme-based Keycloak theme to match the current auth-backend #91

Scope

Reproduce the current auth-backend look and feel as a supported Keycloak theme built from the vendored xore/theme design system. The Keycloak experience should feel like the same product even though the authentication runtime changes completely.

The theme is the only bespoke user-facing authentication implementation retained from this repository. xore/theme remains the source of truth for tokens, components, assets, and styling; do not add a parallel custom CSS system outside it.

Visual source of truth

• Inventory the current auth-backend pages, states, assets, typography, colors, spacing, controls, focus treatments, responsive behavior, and error/success messaging.
• Map every visual primitive to xore/theme; add reusable theme capabilities there when a required primitive is missing.
• Capture approved desktop and mobile reference screenshots from the current auth-backend before cutover.
• Preserve recognizable APIARY branding while adapting markup only where Keycloak's supported templates require it.

Theme surfaces

• Login and username/password forms.
• TOTP and recovery-code challenges.
• WebAuthn/passkey registration and sign-in.
• Required actions: password change, profile update, email verification, MFA enrollment.
• Password recovery and email-link pages.
• Error, expired-action, logout, consent, device, and informational screens.
• Account console only if it is part of the approved product surface.
• Email templates where branding is required.

Constraints

• Use supported Keycloak theme inheritance and message bundles.
• Consume xore/theme; no standalone dashboard/auth CSS fork or copied one-off design tokens.
• No custom Java/Go authentication provider, session adapter, or policy code.
• No inline secrets, external runtime CDN dependency, or weakened CSP.
• Preserve accessibility, responsive behavior, keyboard focus, reduced motion, and dark/light contrast.
• Clearly record upstream Keycloak template/version compatibility.

Acceptance criteria

• Theme builds/packages reproducibly and is selected through realm configuration.
• Every enabled authentication/required-action page renders without missing resources or raw message keys.
• Theme contains presentation only; authentication decisions remain Keycloak-owned.
• Approved screenshot comparisons demonstrate the same look and feel as the current auth-backend at desktop and mobile widths. (baselines exist and are diffed in CI across all 6 viewport tiers; "approved" is a human design sign-off this session cannot self-certify -- left unchecked for a real look, not a formality.)
• Visual/DOM regression coverage includes default, hover, focus, disabled, loading, validation, error, and success states. (default/validation/error/success are covered thoroughly; hover/disabled/loading are not explicitly exercised yet -- tracked in Theme: add hover/focus/disabled/loading state regression coverage (#91 follow-up) #114, not silently dropped.)
• All styling and reusable assets originate from or are contributed to xore/theme; no parallel custom CSS system is introduced.
• Upgrade compatibility check fails loudly when the pinned Keycloak templates change incompatibly.

Depends on Phases 0 and 2.

Research decomposition (2026-08-09)

The official Keycloak guidance and current upstream theme sources support a CSS-first child theme that extends keycloak.v2, keeps inherited FreeMarker templates, and overrides templates only when the required semantic structure cannot be achieved safely with styles. The Xore auth example is the visual source of truth, not a functional form implementation.

Important findings:

• A child styles declaration replaces the parent list. The parent css/styles.css must therefore be explicitly loaded before Xore and APIARY adapters.
• The complete login surface spans password, OTP, authenticator selection, WebAuthn/passkeys, TOTP/recovery codes, required actions, reset/verification, consent/device/IdP, logout/info/error, locale and organization states.
• CSS selectors and inherited templates must be validated against APIARY's exact pinned Keycloak release, not mutable upstream main.
• Visual screenshots need DOM/interaction and accessibility assertions; screenshots alone cannot prove a working authentication page.
• Branding drift remains separately tracked in Keycloak theme doesn't match APIARY branding: hardcoded 'xore//auth' header text, stock demo artwork, stale pre-rebrand typography pin, no favicon #98.

Implementation children:

• Theme: preserve keycloak.v2 functional CSS before applying Xore overrides #99 ? preserve the keycloak.v2 functional stylesheet before Xore overrides
• Theme: audit and style every enabled Keycloak login and required-action state #100 ? audit and style every enabled login and required-action state
• Theme: pin Keycloak compatibility and fail CI on upstream theme drift #101 ? pin Keycloak compatibility and fail CI on upstream theme drift
• Testing: add visual, responsive, and accessibility regression coverage for the Keycloak theme #102 ? add visual, responsive, interaction, and accessibility regression coverage

Research sources:

• https://www.keycloak.org/ui-customization/themes
• https://github.com/keycloak/keycloak/tree/main/themes/src/main/resources/theme
• https://github.com/keycloak/keycloak/tree/main/themes/src/main/resources/theme/keycloak.v2/login
• https://xore.github.io/theme/examples/auth.html

Full-fidelity interaction amendment (2026-08-09)

Custom local JavaScript and targeted FreeMarker overrides are explicitly allowed and expected when required to reproduce the Xore authentication experience. The implementation must not stop at recoloring inherited PatternFly markup.

• Theme: implement the Xore authentication interaction layer with local JavaScript #103 ? implement the Xore authentication interaction layer with local JavaScript

Fidelity requirements include staged identity-to-credential presentation, Xore light/dark/system behavior, focus and keyboard handling, ARIA state, reduced-motion-aware transitions, submitting/disabled feedback, alternate passkey/IdP actions, and visual continuity across server-rendered required actions.

CSS-first remains an upgrade-risk preference, not a product-fidelity ceiling. Override templates when semantic markup or stable JavaScript hooks require it, while preserving all Keycloak form actions, hidden fields, built-in scripts, WebAuthn hooks, server messages, and security behavior. JavaScript must be local, pinned, CSP-compatible, progressively enhanced, and unable to change authentication decisions.

Historical production reference (2026-08-09)

The authoritative visual and interaction reference is now the old production login at commit 3c2779a8ca03f9d6df6ba5bba0a263131a514c2b, not the generic split-screen Xore example:

• https://github.com/Xore/auth-backend/blob/3c2779a8ca03f9d6df6ba5bba0a263131a514c2b/forward-auth/ui/login.html
• https://github.com/Xore/auth-backend/blob/3c2779a8ca03f9d6df6ba5bba0a263131a514c2b/forward-auth/ui/verify.html
• Theme parity: replace the split demo with the historical centered login experience #104 ? replace the split demo with the historical centered login experience

The old page's centered brand, compact 384px card, accent primary actions, fixed theme toggle, staged identity/credential interaction, SSO/passkey/recovery ordering, and quiet footer define parity. Current Xore tokens and approved APIARY branding may update colors/assets/content, but must not replace that composition with the generic artwork split layout.

The retired Go form token, honeypot, passkey endpoints, trusted-device policy, and inline credential ceremony are behavioral history only and must not be reimplemented. Keycloak remains authoritative for every authentication and protocol decision.