Stylelint: report & clean needless disables by simison · Pull Request #50174 · Automattic/jetpack

simison · 2026-07-02T13:41:47Z

Proposed changes

Enable reportNeedlessDisables: true for Stylelint: it turns these stale comments into CI failures instead of letting them accumulate.
Clean out needless disables

Related product discussion/links

See an AI-produced summary for each rule.

Here is a rule-by-rule breakdown of why those disables were added originally, and why `reportNeedlessDisables` correctly flagged them as dead weight.

The common thread matches Gutenberg #79788: most were workarounds for older Stylelint versions or older @wordpress/stylelint-config rules that no longer fire on the current toolchain (Stylelint 17 + @wordpress/stylelint-config 23.x).

`scales/radii`

Why added: A legacy WordPress Stylelint plugin (scales/radii) required border-radius values to match the Gutenberg design scale ($radius-small, $radius-medium, etc.). Raw values like 8px, 12px, or 15px were flagged.

Where it showed up: number-slider, social previews (threads/tumblr/twitter), backup storage meter, wpcom-global-styles toggle.

Why not needed anymore: The scales/* plugin rules were removed from @wordpress/stylelint-config during the Stylelint 15→17 migration. Jetpack extends scss-stylistic, which no longer enables them. The comments outlived the rule.

`scales/font-sizes`

Why added: Same scales/* family — enforced the WordPress admin typography scale. Social preview components intentionally use platform-specific sizes (e.g. Facebook’s 15px / 0.9375rem) that don’t match Gutenberg tokens.

Where it showed up: bluesky, facebook, mastodon, tumblr previews.

Why not needed anymore: Same as scales/radii — the rule is gone from the active config. Those pixel-perfect sizes are still valid CSS; only the lint enforcement disappeared.

`scales/font-weights`

Why added: Enforced allowed font-weight values from the design scale. font-weight: 900 on the event-countdown block was outside what the rule accepted.

Where it showed up: event-countdown.scss.

Why not needed anymore: Another retired scales/* rule — no longer part of the config.

`no-invalid-position-declaration`

Why added: A relatively new core Stylelint rule (added in v16.11) that flags declarations in invalid positions within a rule block. It false-positived heavily in SCSS mixins, where properties inside @media blocks get expanded into output Stylelint couldn’t reason about correctly. Comments explicitly said “Ok in a sass mixin.”

Where it showed up: forms _mixins.scss, my-jetpack product-interstitial _mixins.scss (10 instances).

Why not needed anymore: Stylelint fixed mixin false positives (#9120). Declarations like margin-bottom inside a mixin’s @media block are now understood correctly.

`selector-max-id`

Why added: Limits ID selectors (#foo), which WordPress coding standards discourage. memberships.scss had a file-level disable, likely from when it styled Thickbox modal IDs (#TB_*).

Where it showed up: memberships.scss.

Why not needed anymore: The file was refactored to classes and <dialog> — there are no ID selectors left. The blanket disable was leftover from old Thickbox integration.

`no-duplicate-selectors`

Why added: Flags when the same selector appears twice in a file. In the contact-form editor, border-left: none !important was split into a separate nested rule as a workaround for production CSS attribute reordering (comment in the file explains this). That structural split created a duplicate-selector pattern Stylelint flagged.

Where it showed up: contact-form/editor.scss.

Why not needed anymore: Stylelint 17 improved no-duplicate-selectors handling (including ignoreSelectors support and fewer false positives). The workaround structure no longer triggers the rule.

`function-url-quotes`

Why added: @wordpress/stylelint-config sets function-url-quotes: 'never'. Disables were added for quoted url() values in inline SVG data URLs (mask-image: url("data:image/svg+xml,...")), where quotes are often required for parsing.

Where it showed up: wpcom-global-styles/notice.scss.

Why not needed anymore: Newer Stylelint / config versions handle quoted data URLs correctly, or the specific mask-image usage no longer violates the rule. Gutenberg removed the same disable in #79788 for identical mask-image patterns.

`declaration-property-unit-allowed-list`

Why added: WordPress config restricts units on certain properties (historically centered on line-height: px only). Disables were sprinkled on font-size declarations using px, rem, or % in wpcom blocks — likely copied from an era when the rule was broader, or from a misunderstanding of which properties it targets.

Where it showed up: event-countdown, global-styles-sidebar, recommended-tags-modal.

Why not needed anymore: The current @wordpress/stylelint-config only restricts line-height, not font-size. Those font-size disables were suppressing a rule that never applied to those declarations.

`property-no-unknown` + `selector-pseudo-element-no-unknown`

Why added: Stylelint didn’t recognize View Transitions API syntax when premium-analytics added popover animations:

view-transition-name
::view-transition-group(), ::view-transition-new(), ::view-transition-old()

Where it showed up: date-comparison-dropdown.scss, date-range-filter.scss.

Why not needed anymore: Stylelint’s built-in known-property and pseudo-element lists were updated to include View Transitions. The same change landed in Gutenberg core around the same time.

`declaration-no-important`

Why added: Stylelint discourages !important as a maintainability smell. The WC price filter slider uses !important on padding and border to reset native range input styles that themes override.

Where it showed up: filter-wc-price/style.scss.

Why not needed anymore: declaration-no-important is not enabled in Jetpack’s effective config chain (@wordpress/stylelint-config/scss-stylistic + Jetpack overrides). The inline disables were guarding a rule that isn’t active.

`selector-pseudo-class-no-unknown`

Why added: Flags unrecognized pseudo-classes. CSS Modules’ :global() pseudo-class isn’t standard CSS, so Stylelint flagged :global(.visx-bar) and :global(.visx-tooltip):has(.tooltip).

Where it showed up: premium-analytics chart-bar and chart-tooltip modules.

Why not needed anymore: Jetpack’s base config already whitelists it:

		'selector-pseudo-class-no-unknown': [
			true,
			{
				ignorePseudoClasses: [ 'export', 'global' ], // Ignore pseudo-classes used by CSS Modules.
			},
		],

The per-file disables predated (or duplicated) that central config.

Summary table

Rule	Original reason	Why obsolete now
`scales/radii`	Enforce Gutenberg radius tokens	Rule removed from `@wordpress/stylelint-config`
`scales/font-sizes`	Enforce typography scale	Rule removed; social previews need custom sizes anyway
`scales/font-weights`	Enforce weight scale	Rule removed
`no-invalid-position-declaration`	Mixin false positives	Fixed in Stylelint for `@mixin`
`selector-max-id`	Discourage `#id` selectors	Code refactored; no IDs remain
`no-duplicate-selectors`	Split-rule workaround in editor	Stylelint 17 fewer false positives
`function-url-quotes`	Quoted data URLs in `mask-image`	Rule/parser now accepts the pattern
`declaration-property-unit-allowed-list`	Unit restrictions	Only applies to `line-height`, not `font-size`
`property-no-unknown`	View Transitions properties	Added to Stylelint’s known list
`selector-pseudo-element-no-unknown`	`::view-transition-*`	Added to Stylelint’s known list
`declaration-no-important`	Discourage `!important`	Rule not enabled in Jetpack config
`selector-pseudo-class-no-unknown`	CSS Modules `:global()`	Globally ignored in `stylelint.config.base.mjs`

Does this pull request change what data or activity we track or use?

Testing instructions

CI lint passing?

github-actions · 2026-07-02T13:44:02Z

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

✅ Include a description of your PR changes.
✅ Add a "[Status]" label (In Progress, Needs Review, ...).
✅ Add testing instructions.
✅ Specify whether this PR includes any changes to data or privacy.
✅ Add changelog entries to affected projects

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

Follow this PR Review Process:

Ensure all required checks appearing at the bottom of this PR are passing.
Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
You can use GitHub's Reviewers functionality to request a review.
When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

Jetpack plugin:

The Jetpack plugin has different release cadences depending on the platform:

WordPress.com Simple releases happen as soon as you deploy your changes after merging this PR (PCYsg-Jjm-p2).
WoA releases happen weekly.
Releases to self-hosted sites happen monthly:
- Scheduled release: July 7, 2026
- Code freeze: July 6, 2026

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

github-actions · 2026-07-02T13:55:31Z

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack or WordPress.com Site Helper), and enable the update/stylelint-report-needless-disables branch.
To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack update/stylelint-report-needless-disables

bin/jetpack-downloader test jetpack-mu-wpcom-plugin update/stylelint-report-needless-disables

Interested in more tips and information?

In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
Read more about our development workflow here: PCYsg-eg0-p2
Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

simison · 2026-07-02T13:59:24Z

 		// styles that try to re-style native inputs.
 		margin: 0;
-		padding: 0 !important; // stylelint-disable-line declaration-no-important
-		border: 0 !important; // stylelint-disable-line declaration-no-important


While declaration-no-important isn't enabled in Jetpack, it might make sense to enable repo wide. But not in this PR. :-)

1355 instances of !important in .css and .scss files across 208 files would need cleaning up. 😉

~500 are in projects/plugins/jetpack/scss/cleanslate.scss and projects/plugins/jetpack/scss/wordads-ccpa.scss.

jp-launch-control · 2026-07-02T14:14:23Z

Code Coverage Summary

This PR did not change code coverage!

That could be good or bad, depending on the situation. Everything covered before, and still is? Great! Nothing was covered before? Not so great. 🤷

Full summary · PHP report · JS report

anomiex

Thanks, looks like a good cleanup!

Two comments inline. I'm iffy on the one without a suggestion though.

anomiex · 2026-07-02T14:42:38Z

@@ -1,6 +1,3 @@
-/* Additional styling to thickbox that displays modal */


OTOH, this comment seems like it should possibly be kept. It seems to be commenting on the file, not the disable.

I think it can go; it refers to adding override styles for Thickbox, which was also the reason for the lint-disable.

Now the modal is created fresh from scratch entirely.

Co-authored-by: Brad Jorsch <anomiex@users.noreply.github.com>

Stylelint: report needless disables

ab06701

github-actions Bot added [Status] In Progress [Status] Needs Author Reply We need more details from you. This label will be auto-added until the PR meets all requirements. labels Jul 2, 2026

simison added 2 commits July 2, 2026 16:48

Stylelint: remove needless disables

9a4c8cc

Changelogs

2c1ee33

simison changed the title ~~Stylelint: report needless disables~~ Stylelint: report & clean needless disables Jul 2, 2026

simison marked this pull request as ready for review July 2, 2026 13:57

simison requested review from a team as code owners July 2, 2026 13:57

simison added [Status] Needs Review This PR is ready for review. and removed [Status] Needs Author Reply We need more details from you. This label will be auto-added until the PR meets all requirements. labels Jul 2, 2026

simison added Reviewer Can Merge PR author indicates the reviewer is free to merge/deploy if they want to own the change. [Type] Janitorial Build labels Jul 2, 2026

simison commented Jul 2, 2026

View reviewed changes

Remove stray comment

bb65273

anomiex reviewed Jul 2, 2026

View reviewed changes

Update projects/packages/forms/src/blocks/contact-form/editor.scss

f4ca5d4

Co-authored-by: Brad Jorsch <anomiex@users.noreply.github.com>

anomiex approved these changes Jul 2, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Stylelint: report & clean needless disables#50174

Stylelint: report & clean needless disables#50174
simison wants to merge 5 commits into
trunkfrom
update/stylelint-report-needless-disables

simison commented Jul 2, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 2, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 2, 2026 •

edited

Loading

Uh oh!

simison Jul 2, 2026

Uh oh!

anomiex Jul 2, 2026

Uh oh!

jp-launch-control Bot commented Jul 2, 2026

Uh oh!

anomiex left a comment •

edited

Loading

Uh oh!

Uh oh!

anomiex Jul 2, 2026

Uh oh!

simison Jul 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -1,6 +1,3 @@
		/* Additional styling to thickbox that displays modal */

Uh oh!

Conversation

simison commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

Related product discussion/links

scales/radii

scales/font-sizes

scales/font-weights

no-invalid-position-declaration

selector-max-id

no-duplicate-selectors

function-url-quotes

declaration-property-unit-allowed-list

property-no-unknown + selector-pseudo-element-no-unknown

declaration-no-important

selector-pseudo-class-no-unknown

Summary table

Does this pull request change what data or activity we track or use?

Testing instructions

Uh oh!

github-actions Bot commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

simison Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

anomiex Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

jp-launch-control Bot commented Jul 2, 2026

Code Coverage Summary

Uh oh!

anomiex left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

anomiex Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

simison Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

simison commented Jul 2, 2026 •

edited

Loading

`scales/radii`

`scales/font-sizes`

`scales/font-weights`

`no-invalid-position-declaration`

`selector-max-id`

`no-duplicate-selectors`

`function-url-quotes`

`declaration-property-unit-allowed-list`

`property-no-unknown` + `selector-pseudo-element-no-unknown`

`declaration-no-important`

`selector-pseudo-class-no-unknown`

github-actions Bot commented Jul 2, 2026 •

edited

Loading

github-actions Bot commented Jul 2, 2026 •

edited

Loading

anomiex left a comment •

edited

Loading