Skip to main content

prefer-docsearch-theme-tokens-over-structural-overrides

Prefer curated DocSearch theme tokens over hard-coded structural overrides on common DocSearch UI surfaces.

Targeted pattern scopeโ€‹

This rule is intentionally curated.

The initial coverage focuses on common DocSearch surfaces that Docusaurus documents through --docsearch-* variables, including:

  • DocSearch button / search box background โ†’ --docsearch-searchbox-background
  • DocSearch button text color โ†’ --docsearch-text-color
  • DocSearch container background โ†’ --docsearch-container-background
  • DocSearch modal background โ†’ --docsearch-modal-background
  • DocSearch hit background โ†’ --docsearch-hit-background
  • DocSearch hit text color โ†’ --docsearch-hit-color
  • DocSearch footer background โ†’ --docsearch-footer-background

What this rule reportsโ€‹

This rule reports direct structural declarations like background, background-color, or color on those curated DocSearch surfaces when the declaration hard-codes a value instead of consuming the documented DocSearch token.

Why this rule existsโ€‹

Docusaurus already exposes a documented token surface for DocSearch theming.

Using those tokens keeps DocSearch customization aligned with the official integration path, makes color-mode overrides easier to audit, and avoids scattering brittle structural overrides across curated .DocSearch-* selectors.

โŒ Incorrectโ€‹

.DocSearch-Button {
 background-color: rgb(17 24 39 / 80%);
}
.DocSearch-Modal {
 background: #111827;
}

โœ… Correctโ€‹

[data-theme="dark"] .DocSearch {
 --docsearch-searchbox-background: rgb(17 24 39 / 80%);
 --docsearch-modal-background: #111827;
}
.DocSearch-Button {
 background-color: var(--docsearch-searchbox-background);
}

Behavior and migration notesโ€‹

  • This rule only reports the curated selector/property combinations documented above.
  • It does not report declarations that already consume the matching DocSearch token, such as background-color: var(--docsearch-searchbox-background).
  • It is report-only because automatically moving structural declarations into DocSearch token scopes would be unsafe.

Additional examplesโ€‹

โŒ Incorrect โ€” hard-coded footer backgroundโ€‹

.DocSearch-Footer {
 background-color: #111827;
}

โœ… Correct โ€” token-driven footer stylingโ€‹

[data-theme="dark"] .DocSearch {
 --docsearch-footer-background: var(--ifm-background-surface-color);
}

Stylelint config exampleโ€‹

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

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

When not to use itโ€‹

Disable this rule if your site intentionally bypasses the documented DocSearch token surface and you prefer direct .DocSearch-* structural overrides for those curated surfaces.

Package documentationโ€‹

Docusaurus package documentation:

Rule catalog ID: R024

Further readingโ€‹