prefer-data-theme-docsearch-overrides

Prefer explicit site data-theme selectors over .navbar--dark when overriding DocSearch styles.

Targeted pattern scope

This rule targets selectors that do all of the following at the same time:

match .navbar--dark
target a DocSearch class such as .DocSearch-Button or .DocSearch-Modal
do not include any explicit [data-theme=...] scope

The rule is intentionally narrow. It does not report general .navbar--dark styling, and it does not report DocSearch selectors that are already scoped by the site's actual color mode.

What this rule reports

This rule reports DocSearch overrides that use .navbar--dark as a proxy for site color mode.

Why this rule exists

In Docusaurus, the site's active light/dark mode is exposed on the root HTML element through the data-theme attribute.

DocSearch styling also follows the root site's color mode. That means .navbar--dark is not a reliable substitute for the site's active theme when you customize DocSearch UI pieces.

Using .navbar--dark for DocSearch dark-mode overrides can make the search UI drift away from the actual site color mode and produce unreadable combinations.

❌ Incorrect

.navbar--dark .DocSearch-Button {
 color: white;
 background: rgb(20 20 20 / 80%);
}

✅ Correct

[data-theme="dark"] .DocSearch-Button {
 color: white;
 background: rgb(20 20 20 / 80%);
}

Behavior and migration notes

This rule only checks selectors that touch DocSearch classes.
It does not autofix because converting .navbar--dark selectors into correct site-level data-theme selectors requires author intent.
If you truly want DocSearch to follow navbar styling instead of site color mode, disable this rule for that project.

Additional examples

✅ Correct — explicit light-mode scope

[data-theme="light"] .DocSearch-Button {
 color: var(--ifm-color-emphasis-700);
}

.navbar--dark .searchLabel {
 color: white;
}

Stylelint config example

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

export default {
 ...docusaurusPluginConfigs["docusaurus-all"],
 rules: {
  ...docusaurusPluginConfigs["docusaurus-all"].rules,
  "docusaurus/prefer-data-theme-docsearch-overrides": true,
 },
};

When not to use it

Disable this rule if your site intentionally keeps DocSearch visually tied to a permanently dark navbar style instead of the site's actual data-theme value.

Package documentation

Docusaurus package documentation:

Rule catalog ID: R005

prefer-data-theme-docsearch-overrides

Targeted pattern scope

What this rule reports

Why this rule exists

❌ Incorrect

✅ Correct

Behavior and migration notes

Additional examples

✅ Correct — explicit light-mode scope

✅ Correct — non-DocSearch navbar override

Stylelint config example

When not to use it

Package documentation

Further reading

Targeted pattern scope​

What this rule reports​

Why this rule exists​

❌ Incorrect​

✅ Correct​

Behavior and migration notes​

Additional examples​

✅ Correct — explicit light-mode scope​

✅ Correct — non-DocSearch navbar override​

Stylelint config example​

When not to use it​

Package documentation​

Further reading​

Targeted pattern scope

What this rule reports

Why this rule exists

❌ Incorrect

✅ Correct

Behavior and migration notes

Additional examples

✅ Correct — explicit light-mode scope

✅ Correct — non-DocSearch navbar override

Stylelint config example

When not to use it

Package documentation

Further reading