@scalar/api-reference sets body { background-color } in @layer scalar-base, breaking host apps that also use CSS layers (Nuxt UI v4 / Tailwind v4)

What happens?

When @scalar/nuxt is used as a Nuxt module in an app that also uses CSS layers (e.g. Nuxt UI v4 with Tailwind CSS v4), the body { background-color: var(--scalar-background-1) } rule inside @layer scalar-base overrides the host app's body { background-color: var(--ui-bg) } rule inside @layer base.

Because scalar-base is encountered after base in the global CSS layer cascade, it has higher priority. On pages where the Scalar component is not rendered, --scalar-background-1 is undefined (it is only set inside .dark-mode / .light-mode scopes), so the body background resolves to transparent — revealing the browser's default white background.

This is especially visible during client-side navigation: navigating from a non-Scalar page to any other page causes the body to flash white or remain white.

What did you expect to happen?

Scalar's CSS should not globally set body { background-color }. The style should be scoped to .scalar-app or the Scalar component's wrapper element, so it does not interfere with the host application's body styling.

Root cause

The rule originates from @scalar/api-reference/dist/style.css (position ~101425 in the minified file):

@layer scalar-base {
  /* ... other rules ... */
  body {
    background-color: var(--scalar-background-1);
    margin: 0;
  }
}

This appears to come from Tailwind CSS v4's preflight/base layer being bundled inside scalar-base. The body { margin: 0 } reset also leaks globally, though its impact is less visible.

When a host app uses CSS layers (@layer base, as Nuxt UI v4 does), the CSS Cascade Layers specification dictates that later-declared layers have higher priority. Since scalar-base is declared after base in the combined stylesheet order, Scalar's body rules override the host's:

Workaround

Add an unlayered CSS rule to the host app (unlayered styles always win over all @layer rules):

/* app/assets/css/main.css — loaded via nuxt.config.ts css: [] */
body {
  background-color: var(--ui-bg);
}

This works, but host apps should not need to know about Scalar's internal CSS layer structure.

Suggested fix

Scope the body background to the Scalar component wrapper instead of the global body:

@layer scalar-base {
  .scalar-app {
    background-color: var(--scalar-background-1);
  }
}

Alternatively, add a fallback value so the variable degrades gracefully:

body {
  background-color: var(--scalar-background-1, inherit);
}

Reproduction

1. Create a Nuxt 4 app with @nuxt/ui v4 (which uses Tailwind CSS v4 with @layer base)
2. Add @scalar/nuxt to modules
3. Configure Scalar with pathRouting to serve API docs at a sub-path (e.g. /developer/api)
4. Set the app to dark mode
5. Navigate from the home page to any non-Scalar content page via client-side navigation
6. Observe the body background is transparent/white instead of the host app's dark background

Environment

Related issues

• #5387 — CSS Conflict with other dependencies (closed without upstream fix; workaround was to manually reorder CSS imports, which is not possible when using @scalar/nuxt module)
• #2517 — Original PR that added body { background-color } in a CSS layer
• #5358 — Removed HTML background but kept body background

OpenAPI Document

No response