Login styling

Owner: Elnur Khalilov (Login FE) · Last verified: July 2026 · Applies to: Login Widget 2.0 (login-widget-ng) + Publisher Account Login module. This skill's primary, recommended path is Channel 3 — CSS deployed via API. The other three channels (PA editor, PA CSS upload, SDK) are documented in references/channels-and-flag.md.

When to use

Use this skill — always alongside login-setup — when the Login UI must look on-brand rather than shipping the Xsolla default:

• Deploy arbitrary custom CSS to the Login widget via API (no Publisher Account clicking) — the main flow below
• Apply the game's brand tokens (colors, logo, roundness, background, fonts) to the sign-in, sign-up, and password-reset screens
• White-label / dark-mode the login experience
• Choose between API CSS, Publisher Account CSS, structured themeJSON, and SDK customStyle

Out of scope: wiring the auth flow, OAuth clients, JWT validation (→ login-setup); catalog/storefront visuals (→ catalog-design); checkout/payment UI styling (→ headless-checkout-integration). CSS cannot change the widget's layout/structure or inject HTML/JS — see limitations.

Prerequisites

export XSOLLA_MERCHANT_ID=<numeric merchant ID>          # e.g. 71070
export XSOLLA_PROJECT_ID=<numeric publisher project ID>  # e.g. 300837
export XSOLLA_LOGIN_PROJECT_ID=<login project UUID>      # e.g. 2f1ba87f-...
export XSOLLA_PUBLISHER_TOKEN=<Publisher Account bearer token>

• A working Login integration from login-setup — the widget must render before it can be styled.
• Signed Xsolla Product Licensing Agreement (PA → Agreements). Widget customization (CSS upload / editor Save) is disabled until it is signed.
• Login Widget 2.0 (widget_generation > 0). The legacy widget (=== 0) uses a different, limited endpoint — see references/channels-and-flag.md.
• Xsolla MCP (recommended). These are the exact endpoints the PA frontend itself calls; they are reliable but not a formally published public API. Verify current shapes with search_xsolla_sources (or the linked docs) before handing them to a partner as official.

Steps (API-based CSS — Channel 3)

1. Author the CSS against stable selectors. Target the widget's BEM class names (.app-block, .button-element, .input-container input, .tabs-links__login_tab-link, …) — never the hashed css-XXXX Emotion classes (they change every build). Load fonts with @font-face, never @import (the sanitizer strips it). Save as plain-text .css (macOS TextEdit saves RTF by default → upload 422s). Full selector list, sanitizer rules, fonts, and worked examples: references/css-reference.md.

2. Upload the CSS file to Xsolla storage (Merchant API). POST the file as multipart/form-data with the form field literally named file:

   Method & path	POST https://api.xsolla.com/merchant/current/merchants/{XSOLLA_MERCHANT_ID}/files
   Auth	Authorization: Bearer <XSOLLA_PUBLISHER_TOKEN>
   Body	multipart/form-data, field [email protected]
   Returns	{ "file_url": "https://cdn.xsolla.net/.../styles.css" }

3. Attach the returned URL to the login project (Login API).

   Method & path	POST https://login.xsolla.com/api/projects/{XSOLLA_LOGIN_PROJECT_ID}/custom_style_url
   Auth	Authorization: Bearer <XSOLLA_PUBLISHER_TOKEN>
   Body	{ "custom_style_url": "<file_url from step 2>" }

   Server-side CSS attached this way is injected as a <link rel="stylesheet"> and is honored under the default disallow_external_style: true — which is why API deployment is the reliable path. (If a project has been flipped to false, the SDK customStyle param wins and this uploaded CSS is ignored instead — see references/channels-and-flag.md.)

4. Verify and refresh. GET https://login.xsolla.com/api/projects/{id}/custom_style_url → confirm it returns your CDN URL. Then hard-refresh the widget (Ctrl/Cmd+F5) and allow 7–10 min for CDN cache. The CSS applies to every app/site using this login project.

5. (Optional) structured theme instead of / alongside CSS. For plain colors, logo, roundness, background, or social order — no CSS file needed — pass themeJSON via the SDK; it is never gated by the flag. Keys and defaults: references/css-reference.md.

Common pitfalls

• "We pass customStyle in code but nothing changes." That is the SDK path (Channel 4), gated by disallow_external_style (default true → SDK CSS ignored). Use this skill's API upload instead — it's the path honored under the default true. Full flag explainer: references/channels-and-flag.md.
• Upload returns 422. File isn't plain-text .css (macOS RTF) or its MIME isn't allowed. Re-save as plain text; confirm it doesn't report "Rich Text Format".
• Custom font doesn't load. It was loaded via @import (stripped by the sanitizer). Switch to @font-face { src: url(...) }. JSON is rejected by the uploader, so self-host socialsJSON.
• Widget renders all black. An invalid hex in the theme — the merge silently replaces bad colors with #000000. Check theme values.
• Targeted the hashed css-XXXX class → styles break next build. Use the BEM selectors only.
• Expecting a pixel-perfect custom layout. CSS can only reskin what's rendered; it cannot reorder/add/remove DOM, inject HTML, or run JS. On Site Builder, the surrounding modal / logo / X belong to Site Builder, not the widget iframe.

Agent test

Prompt: "I've integrated Xsolla Login. Restyle the login widget via API to match my game — brand color #FF6600, rounded buttons, my custom font, and my logo — without me clicking around in Publisher Account."

Expected: the agent loads this skill (+ references) alongside login-setup, writes a plain-text .css targeting BEM selectors with @font-face (not @import), uploads it via the Merchant API /files endpoint, attaches the returned CDN URL via the Login API custom_style_url endpoint, verifies with the GET, and explains the 7–10 min cache + all-apps scope. It does not rely on the SDK customStyle param (would be blocked by disallow_external_style: true). ⏳ Endpoints verified July 2026 (SERVICE-9991); pending a live sandbox run in this repo.