Advanced CSS

The Advanced CSS field is an escape hatch. It lets you inject tenant-specific CSS into the hosted login surface without touching code or shipping a release. Use it sparingly — the presets cover most needs, and custom CSS is the first thing to break when underlying components evolve.

If you find yourself writing dozens of lines, step back. The right answer is usually a different preset, or a feature request. Custom CSS is for targeted polish — not a theme rewrite.

Scope and sandboxing

CSS you enter in this field is injected inside the .hosted-login surface. It can only target elements inside that container. The studio injects your CSS as a <style> block scoped to the HostedLoginSurface component's shadow root. Practical consequences:

It cannot leak into the admin panel, the docs site, or any downstream Blu app.
It cannot reach the global html / body — those are outside the surface.
It cannot use @import to fetch external stylesheets — the CSP blocks it.
It cannot include <script> tags or execute JavaScript. It's pure CSS.

If you need JS-driven behavior, the hosted login is not the right venue. Talk to the platform team.

Available CSS custom properties

The hosted login surface exposes a handful of CSS custom properties you can reference for consistency with the rest of the theme. Using these instead of hard-coded values means your custom CSS automatically follows color and font changes made via the standard studio controls.

Variable	Value
`--auth-primary`	Theme primary color (hex).
`--auth-background`	Theme background color (hex).
`--auth-surface`	Resolved surface color (respects the `useSurfaceColor` toggle).
`--auth-font-family`	Resolved font stack for the selected preset.
`--auth-background-image`	`url(...)` for the background image, or `none`.

Reference them with var(--auth-primary), color-mix(in srgb, var(--auth-primary) 30%, white), etc. Works the same as any other CSS custom property.

BEM class hooks

BluAuth uses BEM conventions for the hosted login markup. These are the stable class hooks you can target.

Shared across layouts

.hosted-login — the outermost container. Everything lives inside this.
.hosted-login__surface — the layout's rendering root.
.hosted-login__card — the form card wrapper (every layout that has a card).
.hosted-login__hero — the hero panel (on layouts that have one).
.hosted-login__form — the form element.
.hosted-login__input — inputs.
.hosted-login__primary-action — the primary CTA.
.hosted-login__provider-list — the container for provider buttons.
.hosted-login__provider-button — individual provider buttons.
.hosted-login__support — the support text block.
.hosted-login__footer — the footer text block.

Cinematic Split

The cinematic-split layout has its own namespace (reflecting its extra structural complexity):

.cinematic-split — root.
.cinematic-split__hero, .cinematic-split__form-panel — the two columns.
.cinematic-split__hero-bg — the hero background (mesh or image variant).
.cinematic-split__heading, .cinematic-split__subtitle, .cinematic-split__eyebrow — hero copy.
.cinematic-split__plaques, .cinematic-split__plaque — hero plaques.
Modifiers: .cinematic-split--edge, .cinematic-split--contained, .cinematic-split--height-full, .cinematic-split--height-contained.

Aurora

.aurora-layout — root.
.aurora-bg, .aurora-bg__blob, .aurora-bg__noise — the animated background. Do not override these unless you really mean to — they're tuned against accessibility and performance constraints.
.aurora-layout__card — the glass form card.
.aurora-layout__chips, .aurora-layout__chip — hero chips.
Intensity modifiers: .aurora-bg--subtle, .aurora-bg--atmospheric, .aurora-bg--reactive.

BluAuth does not version-lock these class names across major releases — treat them as best-effort stable. Re-verify after BluAuth minor bumps.

When to use Advanced CSS

Tenant-specific polish that a preset doesn't cover — a custom button gradient from your brand guide, a specific card inner shadow.
Overriding a single selector on one tenant's theme without forking the whole preset system.
Logotype-specific positioning — nudging the logo up a few pixels because your specific mark sits visually low in its bounding box.
Brand-specific link colors inside hero card descriptions.

When not to use Advanced CSS

To hide bugs. If a layout is broken, file it. Don't paper over it with CSS — it hides the issue for every other tenant.
To replace preset behavior globally. If you find yourself writing border: none !important on every input, flip fieldStylePreset to quiet instead.
For JavaScript-driven behavior. This is CSS only — no hover/scroll logic that depends on DOM state the hosted login doesn't expose.
To duplicate theme fields. If you're writing background-color: #123456 and that color is also your theme's primary, use var(--auth-primary) instead.

Danger warnings

`!important` is a smell

!important wins specificity battles, but it signals that you're fighting the component. Every !important in your Advanced CSS is a potential breakage — when the component evolves, your rule outranks the new correct rule and you end up debugging a theme that looks "broken" after a deploy. Use it only when absolutely necessary, and leave a comment explaining why.

`@media (prefers-reduced-motion)` must be respected

BluAuth's layouts — especially aurora and cinematic-split — honor the prefers-reduced-motion media query. If your custom CSS introduces animation, mirror that respect:

.hosted-login__card {
    transition: transform 240ms ease;
}

@media (prefers-reduced-motion: reduce) {
    .hosted-login__card {
        transition: none;
    }
}

Breaking reduced-motion respect is an accessibility failure — it is not negotiable. If a tenant insists on motion without the respect clause, escalate; we will not ship it.

Accessibility-affecting rules require contrast proof

Any rule that changes a color, background, or font size inside the form can push the surface below WCAG 4.5:1 on interactive elements. Validate with a contrast checker before you save. The studio does not block this for you — if you break it, nobody fires a warning.

CSP / url()

Background images referenced in Advanced CSS via url(...) must come from BluAuth's asset bucket. The CSP blocks arbitrary external URLs. Upload your images via the studio and reference the resulting URL.

Example: Emerald primary gradient

Per the design tokens reference, the primary CTA can use a diagonal gradient for depth:

.hosted-login__primary-action {
    background-image: linear-gradient(135deg, var(--auth-primary) 0%, color-mix(in srgb, var(--auth-primary) 75%, white 25%) 100%);
}

Example: Custom card corner radius

.hosted-login__card {
    border-radius: 0.125rem;
}

Example: Tint the provider buttons

.hosted-login__provider-button {
    background-color: color-mix(in srgb, var(--auth-surface) 92%, var(--auth-primary) 8%);
}

.hosted-login__provider-button:hover {
    background-color: color-mix(in srgb, var(--auth-surface) 86%, var(--auth-primary) 14%);
}

Example: Dim the aurora for a specific tenant

Works on the aurora layout only. Lowers the overall energy without changing the intensity preset:

.aurora-bg__blob {
    opacity: 0.6;
}

What breaks

If a component restructures its DOM or swaps class names — which happens during major Nuxt UI or BluAuth releases — your custom CSS stops targeting anything. There is no automated migration. Re-check your Advanced CSS after every BluAuth minor version bump.

Keep your Advanced CSS short, commented, and targeted. The smaller it is, the less fragile it is.

Design tokens — the visual contract your custom CSS should align with.
Styling tokens — check whether a preset already does what you need.
Layouts — the class hooks are easier to use when you know what they wrap.