no-mobile-navbar-stacking-context-traps
Disallow containing-block and stacking-context properties on Docusaurus navbar selectors unless they are guarded behind the desktop breakpoint.
Targeted pattern scopeโ
This rule targets Docusaurus navbar selectors such as .navbar, .navbar--fixed-top, and .theme-layout-navbar when they use properties that can trap the mobile sidebar and backdrop inside a new containing block or stacking context.
The initial rule scope checks:
transformfilterperspectivecontainwill-changewhen it hints transform-like behavior
The rule allows safe reset values like none, initial, and unset, and it also allows these properties inside a desktop-only media query such as @media (min-width: 997px).
What this rule reportsโ
This rule reports navbar declarations that can change containing-block or stacking-context behavior for the mobile sidebar subtree.
Why this rule existsโ
In Docusaurus mobile view, the sidebar and its backdrop are rendered inside the navbar subtree.
Those mobile overlay elements rely on fixed-position behavior. If custom CSS puts transform-like or containment properties on the navbar itself, the mobile sidebar can start behaving relative to the navbar instead of the viewport, which can break positioning, clipping, and overlay rendering.
โ Incorrectโ
.navbar {
transform: translateZ(0);
}
โ Correctโ
@media (min-width: 997px) {
.navbar {
transform: translateZ(0);
}
}
Behavior and migration notesโ
- This rule is intentionally conservative and only checks a curated set of high-risk properties.
- It is report-only because moving or restructuring these declarations safely requires layout intent that Stylelint cannot infer.
- If you need one of these properties on desktop only, guard it explicitly behind the desktop breakpoint.
Additional examplesโ
โ Incorrect โ containment on the navbarโ
.navbar--fixed-top {
contain: content;
}
โ Correct โ harmless resetโ
.navbar {
transform: none;
will-change: opacity;
}
Stylelint config exampleโ
import { docusaurusPluginConfigs } from "stylelint-plugin-docusaurus";
export default {
...docusaurusPluginConfigs["docusaurus-all"],
rules: {
...docusaurusPluginConfigs["docusaurus-all"].rules,
"docusaurus/no-mobile-navbar-stacking-context-traps": true,
},
};
When not to use itโ
Disable this rule if your site has swizzled the navbar layout enough that the mobile sidebar no longer depends on the default Docusaurus navbar subtree behavior.
Package documentationโ
Docusaurus package documentation:
Rule catalog ID: R008