no-unwrapped-global-theme-selectors-in-css-modules

Disallow unwrapped Docusaurus and Infima runtime theme selectors inside CSS Modules.

Targeted pattern scope

This rule runs on CSS Modules files such as *.module.css, *.module.scss, and *.module.sass.

It reports global Docusaurus or Infima class selectors like .navbar, .theme-doc-sidebar-menu, .menu__link, and .DocSearch when they appear directly in a CSS Module selector instead of being wrapped with :global(...).

What this rule reports

This rule reports CSS Module selectors that rely on runtime theme classes without marking them global.

CSS Modules localize class selectors by default, so a selector like .navbar inside Component.module.css does not target the real Docusaurus navbar unless you explicitly opt out of localization.

Why this rule exists

This is one of the most common Docusaurus + CSS Modules mistakes.

Authors often move a working selector from src/css/custom.css into a CSS Module and assume it still targets the same markup. It does not. The selector silently becomes local, the runtime class stops matching, and the override appears to "randomly" stop working.

❌ Incorrect

.theme-doc-sidebar-menu .menu__link {
 font-weight: 700;
}

✅ Correct

:global(.theme-doc-sidebar-menu) :global(.menu__link) {
 font-weight: 700;
}

Behavior and migration notes

This rule only runs for CSS Modules file names.
It is report-only because automatically inserting :global(...) can change selector meaning in nested selectors and CSS Modules syntax.
It intentionally focuses on Docusaurus and Infima runtime classes rather than trying to lint every possible global class name.

Additional examples

❌ Incorrect — unwrapped DocSearch selector in a module

.DocSearch {
 --docsearch-primary-color: #818cf8;
}

✅ Correct — local component class plus explicit global runtime selector

.card :global(.navbar__link) {
 text-decoration: underline;
}

Stylelint config example

import { docusaurusPluginConfigs } from "stylelint-plugin-docusaurus";

export default {
 ...docusaurusPluginConfigs["docusaurus-recommended"],
 rules: {
  ...docusaurusPluginConfigs["docusaurus-recommended"].rules,
  "docusaurus/no-unwrapped-global-theme-selectors-in-css-modules": true,
 },
};

When not to use it

Disable this rule if your CSS Modules setup intentionally avoids :global(...) syntax or if your build chain rewrites theme selectors in a non-standard way.

Package documentation

Docusaurus package documentation:

Styling and Layout

Rule catalog ID: R009

Targeted pattern scope​

What this rule reports​

Why this rule exists​

❌ Incorrect​

✅ Correct​

Behavior and migration notes​

Additional examples​

❌ Incorrect — unwrapped DocSearch selector in a module​

✅ Correct — local component class plus explicit global runtime selector​

Stylelint config example​

When not to use it​

Package documentation​

Further reading​