no-direct-theme-token-consumption-in-css-modules

Disallow direct --ifm-* and --docsearch-* token consumption in CSS Modules declarations.

Targeted pattern scope

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

It reports non-custom-property declarations that read global theme tokens directly with var(--ifm-...) or var(--docsearch-...).

What this rule reports

This rule reports declarations like color: var(--ifm-color-primary) inside CSS Modules.

Why this rule exists

Direct token consumption makes a local component depend on global theme token names everywhere those values are used.

Aliasing the global token to a component-scoped custom property keeps the boundary clearer and makes later refactors easier.

❌ Incorrect

.card {
 color: var(--ifm-color-primary);
}

✅ Correct

.card {
 --card-link-color: var(--ifm-color-primary);
 color: var(--card-link-color);
}

Behavior and migration notes

Local alias declarations such as --card-link-color: var(--ifm-color-primary) are allowed.
This rule only runs on CSS Modules file names.
It is report-only because introducing the right local alias name requires human judgment.

Additional examples

❌ Incorrect — direct DocSearch token use in a module

.search {
 background: color-mix(in srgb, var(--docsearch-primary-color) 75%, white);
}

Stylelint config example

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

export default {
 ...docusaurusPluginConfigs["docusaurus-all"],
 rules: {
  ...docusaurusPluginConfigs["docusaurus-all"].rules,
  "docusaurus/no-direct-theme-token-consumption-in-css-modules": true,
 },
};

When not to use it

Disable this rule if your CSS Modules intentionally read global Docusaurus or DocSearch tokens directly and you do not want a local alias layer.

Package documentation

Docusaurus package documentation:

Rule catalog ID: R021

Targeted pattern scope​

What this rule reports​

Why this rule exists​

❌ Incorrect​

✅ Correct​

Behavior and migration notes​

Additional examples​

❌ Incorrect — direct DocSearch token use in a module​

Stylelint config example​

When not to use it​

Package documentation​

Further reading​