prefer-infima-theme-tokens-over-structural-overrides
Prefer curated Infima theme tokens over hard-coded structural overrides on common Docusaurus theme surfaces.
Targeted pattern scopeโ
This rule is intentionally curated.
The initial coverage focuses on common Docusaurus/Infima surfaces that already expose official tokens, including:
- navbar background โ
--ifm-navbar-background-color - navbar height โ
--ifm-navbar-height - navbar shadow โ
--ifm-navbar-shadow - footer background โ
--ifm-footer-background-color - pagination border radius โ
--ifm-pagination-nav-border-radius
What this rule reportsโ
This rule reports direct structural declarations like background-color, height, box-shadow, or border-radius on those curated surfaces when the declaration hard-codes a value instead of relying on the documented token.
Why this rule existsโ
Token overrides survive Docusaurus and Infima updates better than selector-specific hard-coded values.
When a token already exists, using it keeps the styling contract in one predictable place and reduces the amount of structural CSS that has to be audited after framework upgrades.
โ Incorrectโ
.navbar {
background-color: #111827;
}
โ Correctโ
:root {
--ifm-navbar-background-color: #111827;
}
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 token, such as
background-color: var(--ifm-navbar-background-color). - It is report-only because automatically moving declarations into token scopes would be unsafe.
Additional examplesโ
โ Incorrect โ hard-coded footer backgroundโ
.theme-layout-footer {
background: #111827;
}
โ Correct โ token-driven navbar heightโ
:root {
--ifm-navbar-height: 4rem;
}
Stylelint config exampleโ
import { docusaurusPluginConfigs } from "stylelint-plugin-docusaurus";
export default {
...docusaurusPluginConfigs["docusaurus-all"],
rules: {
...docusaurusPluginConfigs["docusaurus-all"].rules,
"docusaurus/prefer-infima-theme-tokens-over-structural-overrides": true,
},
};
When not to use itโ
Disable this rule if your site intentionally bypasses those Infima tokens and you prefer direct selector-based structural overrides for those surfaces.
Package documentationโ
Docusaurus package documentation:
Rule catalog ID: R016