Extract the Stylelint set of rules so that it can be reused in Core

What problem does this address?

In https://core.trac.wordpress.org/ticket/29792 / WordPress/wordpress-develop#12934 I'm proposing to add Stylelint to core, as an NPM script and Grunt task.

It would be nice to have the set of Stylelint rules in the config extracted to a separate file (or package?) so that we'd have only one centralized source for the set of rules that can be resued in Core avoiding cuplication and maintenance issues.

We can't jiust reuse the whole config.js because it contains Gutenberg=specific configuration. See for example the overrides section.

Also, some rules like 'plugin-wpds/no-token-fallback-values': true, wouldn't make sense for Core.

What is your proposed solution?

Make the rules set reusable.

Working on a PR for this.

The overlap turns out to be exact: Core's .stylelintrc.js in wordpress-develop#12934 is tools/stylelint/config.js minus three things — declaration-property-value-disallowed-list, plugin-wpds/no-token-fallback-values, and the overrides section. The other ~22 rules and both report*Disables options are identical in both files.

So rather than a new package, the shared set becomes a fourth preset in the already-published @wordpress/stylelint-config, alongside scss / stylistic / scss-stylistic. It extends scss-stylistic and both sides then become thin:

// Gutenberg — tools/stylelint/config.js
extends: '@wordpress/stylelint-config/project',
plugins: [ 'stylelint-plugin-logical-css' ],
rules: { /* wp-components-color / font-weight / cursor only */ },
overrides: [ /* CSS modules + routes/ */ ],

// Core — .stylelintrc.js
extends: '@wordpress/stylelint-config/project',
ignorePath: '.stylelintignore',

--print-config output is unchanged for every file shape in the repo, and lint:css stays clean.

Two notes. project is a first-pass name — the preset for WordPress projects that lint their own stylesheets, vs. the theme/plugin-facing ones. It's a published export, so worth settling before release if anyone prefers something else.

And on plugin-wpds/no-token-fallback-values: leaving it out of the extracted set doesn't actually keep it out of Core, since it's already enabled in the base index.js that Core extends, along with no-unknown-ds-tokens and no-setting-wpds-custom-properties. It's inert there in practice (Core has no --wpds-* tokens), so I've left the base preset alone — but if the intent is that Core carries no WPDS rules at all, that's a separate and more disruptive change.

Raised an in progress draft PR - #81369

@i-am-chitti

Raised an in progress draft PR - #81369

@i-am-chitti thanks for your PR.
The new preset approach seems to be a good choice. It may be a little early though. Some of the Gutenberg rules in the preset are not applicable to Core. For example the custom regexes for selector-class-pattern and selector-id-pattern would trigger too many 'false positive' errors in Core.
We'll need to adjust the rules for Core or maybe override them, not sure yet.

@afercia

Thanks @afercia - agreed the rule set is the open question, that's why I'll keep it in draft.

On those two rules specifically:

selector-id-pattern isn't in the preset — it comes from the base index.js that Core already extends via scss-stylistic, so it's unchanged by this PR.

selector-class-pattern is in the preset, but it relaxes the base:

base    ^([a-z][a-z0-9]*)(-[a-z0-9]+)*$
preset  ^[a-z][a-z0-9]*(?:(?:__|--|-)[a-z0-9]+)*$

A strict superset - it can only reduce errors, never add them. Your .stylelintrc.js already has this same regex.

Selectors like #TB_window do fail, but under the base config Core inherits either way.

I'll leave this as a draft while Core's rules settle. Happy to take whichever approach the team lands on. I'd like to pick this up once the decision is made.

@youknowriad

The work to introduce Stylelint in Core is almost done and ready for review. It could be further simplified if only the various set of rules / configs in Gutenberg were simplified as well. I'm not sure I understand why there are different configurations in Gutenberg that inherit one from the other one.
This is not a criticism, it's just a genuine question to understand the historical reasons why there are so many configs. Cc @youknowriad when you have a chance and can remember why, it would be very appreciated.

@mirka

Styling approach changed a lot over time in Gutenberg which lead to the chaos that exist today. Different Packages have different styling approaches. @mirka and @ciampo might know better what's the latest recommendations here.

As for the design system lint rules, they are enabled by default in the preset because they are good to have everywhere (just to prevent common mistakes), and will only affect lines that are actually using wpds tokens. So if Core is ever going to use design tokens anywhere, I don't think there's a reason not to keep it in the config, especially if that's easier for keeping all the config in sync.

Thank you both for the feedback.
So far, in WordPress/wordpress-develop#12934 I'm extending @wordpress/stylelint-config/scss-stylistic.
But then, any change to the rules inherited by scss-stylistic or the rules within scss-stylistic itself would impact the configuration used in Core.
I'm wondering whether to keep the current approach or build a completely separete config for Core. Any suggestion would be very appreciated.

But then, any change to the rules inherited by scss-stylistic or the rules within scss-stylistic itself would impact the configuration used in Core.
I'm wondering whether to keep the current approach or build a completely separete config for Core. Any suggestion would be very appreciated.

At least in my understanding, the @wordpress/stylelint-config presets are intended to be reasonable defaults for any WordPress-related project, not just the Gutenberg repo. So personally I'm not adding any new config in there that I don't think would be good for the general case, including Core. Of course there may be Core-specific considerations that we don't know about and fail to take into account, but I won't be adding new defaults that are clearly just in the realm of taste and cause churn for no reason.

At least in my understanding, the @wordpress/stylelint-config presets are intended to be reasonable defaults for any WordPress-related project, not just the Gutenberg repo.

Actually, no. The Gutenberg configurations slightly deviate from the WordPress CSS Coding Standards. None of them can be used 'as is' in Core. At the point that in WordPress/wordpress-develop#12934 I'm extending @wordpress/stylelint-config/scss-stylistic but then I had to use a custom ruleset configuration to meet the coding standards for Core.

It depends on how Core wants to manage it's config then. I don't have a strong opinion. At the very least, I doubt that we'll be adding or modifying any rules in @wordpress/stylelint-config that are a matter of taste and cause churn for no reason. Not any further. So if rules of that nature are already overridden appropriately in Core, there probably won't be a lot of issues moving forward.

Styling approach changed a lot over time in Gutenberg which lead to the chaos that exist today. Different Packages have different styling approaches.

While I understand the historical reasons for that, the fact that different packages use different rulesets seems less than ideal to me. Ideally, any project should use a unique, consistent, set of coding standard rules.

Also, the Gutenberg Stylelint rulesets have deviated from the WordPress CSS Coding Standards. Assuming that Gutenberg is considered part of Core (isn't it?), ownership should have been taken and a proposal to update the CSS Coding Standards as needed for Gutenberg should have been done. For what is worth, personally I'm not opposed to updating the current CSS coding standards, which are pretty old to be honest.

It doesn't seem ideal to me that WordPress does have established standards but then it doesn't follow them.

I would have loved to have a unique source of truth and be able to just use one of the Gutenberg presets. Instead, to my understanding, as things stand I can't rely on the Gutenberg presets configurations. Which leads once again to unnecessary code duplication.

doubt that we'll be adding or modifying any rules

I don't think I ever asked to add rulesets. Rather the opposite. I asked to have one config that can be just dropped into Core and it works for both Gutenberg and Core, one that follows the CSS Coding Standards.

Navigation Menu

Repository navigation

Extract the Stylelint set of rules so that it can be reused in Core #81349

What problem does this address?

What is your proposed solution?

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Extract the Stylelint set of rules so that it can be reused in Core #81349

Description

What problem does this address?

What is your proposed solution?

Activity

i-am-chitti commented on Aug 8, 2026

i-am-chitti commented on Aug 10, 2026

afercia commented on Aug 10, 2026

i-am-chitti commented on Aug 10, 2026

afercia commented on Aug 24, 2026

youknowriad commented on Aug 24, 2026

mirka commented on Aug 24, 2026

afercia commented on Aug 25, 2026

mirka commented on Aug 26, 2026

afercia commented on Aug 26, 2026

mirka commented on Aug 27, 2026

afercia commented on Aug 27, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions