require-ifm-color-primary-scale-per-color-mode

Require matching Infima primary color-scale overrides for each Docusaurus color mode you customize.

Targeted pattern scope

This rule checks primary-scale overrides in Docusaurus theme scopes such as:

:root
[data-theme='light']
[data-theme='dark']

It focuses on whether you customize the primary scale in both light/default and dark mode, not on whether each individual scope contains every required variable. The existing require-ifm-color-primary-scale rule covers the full-scale requirement within a touched scope.

What this rule reports

This rule reports files that customize Infima primary-scale variables in only one color mode.

Why this rule exists

Docusaurus explicitly encourages different palettes in light and dark mode because one primary color scale rarely works equally well in both.

If you customize only one mode, the other mode may fall back to an unrelated default palette and the site can feel inconsistent during color-mode switches.

❌ Incorrect

:root {
 --ifm-color-primary: #4f46e5;
}

✅ Correct

:root {
 --ifm-color-primary: #4f46e5;
}

[data-theme="dark"] {
 --ifm-color-primary: #818cf8;
}

Behavior and migration notes

This rule is intentionally stricter than Docusaurus itself.
It complements require-ifm-color-primary-scale instead of replacing it.
It is report-only because choosing a second color palette is a design decision.

Additional examples

❌ Incorrect — dark mode customized without a matching light/default scope

[data-theme="dark"] {
 --ifm-color-primary: #818cf8;
}

✅ Correct — explicit light-mode scope instead of `:root`

[data-theme="light"] {
 --ifm-color-primary: #4f46e5;
}

[data-theme="dark"] {
 --ifm-color-primary: #818cf8;
}

Stylelint config example

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

export default {
 ...docusaurusPluginConfigs["docusaurus-all"],
 rules: {
  ...docusaurusPluginConfigs["docusaurus-all"].rules,
  "docusaurus/require-ifm-color-primary-scale-per-color-mode": true,
 },
};

When not to use it

Disable this rule if your design intentionally uses the same Infima primary palette for both light and dark mode, or if you are comfortable leaving one mode on the framework defaults.

Package documentation

Docusaurus package documentation:

Styling and Layout

Rule catalog ID: R014

Targeted pattern scope​

What this rule reports​

Why this rule exists​

❌ Incorrect​

✅ Correct​

Behavior and migration notes​

Additional examples​

❌ Incorrect — dark mode customized without a matching light/default scope​

✅ Correct — explicit light-mode scope instead of :root​

Stylelint config example​

When not to use it​

Package documentation​

Further reading​