agentleFS
xsollaxsolla/xsolla-ai-kit/skills/login-styling/SKILL.md

login-styling

Skill9 starsChanged 5 months agoMITView on GitHub

Styles the Xsolla Login widget (sign-in, sign-up, password reset): upload custom CSS through the API and attach it to the login project, or set colors, logo, background and social order through themeJSON. Use for "style the login", "brand the sign-in screen", "upload login CSS", "dark-mode login". Pairs with login-setup, which wires the auth flow.

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

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

    line 22

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 & pathPOST https://api.xsolla.com/merchant/current/merchants/{XSOLLA_MERCHANT_ID}/files
    AuthAuthorization: Bearer <XSOLLA_PUBLISHER_TOKEN>
    Bodymultipart/form-data, field file=@styles.css
    Returns{ "file_url": "https://cdn.xsolla.net/.../styles.css" }
  3. Attach the returned URL to the login project (Login API).

    Method & pathPOST https://login.xsolla.com/api/projects/{XSOLLA_LOGIN_PROJECT_ID}/custom_style_url
    AuthAuthorization: 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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.