wikimedia / stylelint-config-wikimedia

CSS/Less Stylelint configuration according to CSS coding conventions for Wikimedia.

stylelint-config-wikimedia

Wikimedia CSS Coding Standards shareable config for stylelint

Configuration rules to ensure your CSS is compliant with the Wikimedia CSS Coding Standards.

Installation

$ npm install -D stylelint-config-wikimedia

Usage

Set your stylelint config file, .stylelintrc.json, to:

{
	"extends": "stylelint-config-wikimedia"
}

If you would also like to enable rules to disallow CSS which is unsupported by modern browsers Grade A or basic supported browsers Grade C browsers, you can use the following configurations instead:

{
	"extends": "stylelint-config-wikimedia/support-modern"
}

{
	"extends": "stylelint-config-wikimedia/support-basic"
}

If you are using in a MediaWiki environment, you can add the following config:

{
	"extends": [
		"stylelint-config-wikimedia",
		"stylelint-config-wikimedia/mediawiki"
	]
}

If you need to combine this with browser support rules:

{
	"extends": [
		"stylelint-config-wikimedia/support-modern",
		"stylelint-config-wikimedia/mediawiki"
	]
}

Extend or override the configuration

Add a "rules" object to your config file, and add your overrides or additional rules there, for example:

{
	"extends": "stylelint-config-wikimedia/support-basic",
	"rules": {
		"@stylistic/max-empty-lines": null
	}
}

Changelog

You can read the changelog for release versions.

License

This is available under the MIT License.

stylelint-config-wikimedia's Issues

Enforce a specific ordering of attributes

"declaration-block-properties-order": [ "content", "background-image", "backg
round-origin", "background-position", "background-repeat", "background-size", "color"
, "list-style", "filter", "opacity", "display", "clip", "overflow", "visibility", "fl
oat", "clear", "position", "top", "left", "bottom", "right", "z-index", "box-sizing",
 "min-width", "max-width", "width", "height", "outline", "margin", "padding", "border
", "border-radius", "box-shadow", "direction", "hyphens", "font-family", "font-size",
 "font-weight", "line-height", "text-align", "text-decoration", "text-overflow", "tex
t-shadow", "text-transform", "vertical-align", "white-space", "cursor", "zoom", "anim
ation", "transition" ],

Add `box-sizing`, `box-shadow`, `hyphens`, `transform` & `transition` to 'property-blacklist' rule as long as corresponding mixins are there

We feature a number of property mixins for needed cross-browser support. We should enforce their usage in our deployed products as long as they are part of mediawiki.mixins and reflect our browser support matrix by adding them on 'property-blacklist' rule.
The only way to get such property in is to then use the corresponding mixin.

Unluckily we can't rely on some more automated magic like Autoprefixer in our environments.
Proposal would mean a bit more manual work, but ensuring we're living up to our browser support matrix promise.

Stylelint doesn't catch mistyped background-image value

That's probably an upstream issue, but

.link-https {
	background-image: images/external-ltr.svg );

isn't caught locally.

Upgrade to latest version of stylelint (6.3.3 -> 6.5.x+)

Whole Less mixin whitespace area untouched

Whole Less mixin notation stays with current rules yet untouched, for example:
.oo-ui-inline-spacing(0.5em);

Create stylelint-no-unsupported-browser-features based configs for MediaWiki Grade A & Grade C browsers

See https://www.mediawiki.org/wiki/Compatibility

Low severity ReDoS found for braces < 2.3.1 dependency (via npm audit)

https://npmjs.com/advisories/786

─┬ [email protected]
  └─┬ [email protected]
    └─┬ [email protected]
      └── [email protected]

Found during https://phabricator.wikimedia.org/T214152

Address 8.0 deprecation warnings

From the VE build:

1. 'no-browser-hacks' has been deprecated and in 8.0 will be removed. See: https://stylelint.io/user-guide/rules/no-browser-hacks/
2. 'no-unsupported-browser-features' has been deprecated and in 8.0 will be removed. See: https://stylelint.io/user-guide/rules/no-unsupported-browser-features/
3. 'block-no-single-line' has been deprecated and in 8.0 will be removed. Instead use 'block-opening-brace-newline-after' and 'block-closing-brace-newline-before' with the "always" option. See: https://stylelint.io/user-guide/rules/block-no-single-line/
4. 'selector-root-no-composition' has been deprecated and in 8.0 will be removed. See: https://stylelint.io/user-guide/rules/selector-root-no-composition/
5. 'media-feature-no-missing-punctuation' has been deprecated and in 8.0 will be removed. See: https://stylelint.io/user-guide/rules/media-feature-no-missing-punctuation/
6. 'at-rule-empty-line-before's' "blockless-group" option has been deprecated and in 8.0 will be removed. Instead use the "blockless-after-blockless" option. See: https://stylelint.io/user-guide/rules/at-rule-empty-line-before/

Give an rationale for why we enforce certain property values, using `message` property.

Should we provide comments in index.js on certain property values? The "stylelint-value-border-zero" plugin returned

Line 292, column 3: 'border: 0' is preferred over 'border: none' (value-border-zero) (error)

while declaration-property-value-blacklist offers following error

292:3 ✖ Unexpected value "none" for property "border" declaration-property-value-blacklist

It could be a bit more insightful. The blacklist rule doesn't provide option to customize output. So I think providing guidance in comments/links to guiding principles would be useful…

Provide a mechanism to enforce '0' vs. 'none' for `outline`

Like we did in #12 via the stylelint-value-border-zero plugin.

Remove `block-closing-brace-space-after` rule for now

block-closing-brace-space-after runs into errors –no matter which config– on rules like
.theme-oo-ui-outlineControlsWidget () {

See https://gerrit.wikimedia.org/r/#/c/289599/
Let's remove it for now and revisit it.

'declaration-block-no-duplicate-properties' exception 'consecutive-duplicates' might do more harm than good

Coming from https://gerrit.wikimedia.org/r/#/c/mediawiki/extensions/VipsScaler/+/483484/1/modules/ext.vipsScaler/ext.vipsScaler.css
it seems that ignoring 'consecutive-duplicates' as general rule seems to be overly loose rule.
We should consider having devs go for stylelint-disable-next-line instead if they need it for progressively enhancing browser rendering quirks (example: color: rgb() over hex value.)

Review new rules as of stylelint 10.0.0

From https://github.com/stylelint/stylelint/releases/tag/10.0.0:

• Added: at-rule-property-requirelist rule (#3997).
• Added: disallowInList to no-duplicate-selectors (#3936).
• Added: ignore: ["comments"] to block-no-empty (#4008).

Add `outline: 0` to flagged property/value combinations

outline: 0 is seen an accessibility anti-pattern and there are several places, where this was introduced for styling reasons and assumed lack of knowledge.
I'd propose for adding it to 'declaration-property-value-blacklist' which would need an extra override in case you're re-adding custom focus styles to your project.

"font-family-name-quotes" rule – "always-where-recommended" preferable

Quotes on font-family property are one of those fuzzy things in CSS. It is very uncommon to quote all custom font family names in CSS, therefore I'd suggest to use always-where-recommended instead of always-unless-keyword

Error with always-unless-keyword, ok with always-where-recommended
font-family: "Linux Libertine", "Hoefler Text", Georgia, "Times New Roman", Times, serif;

Enforced with always-unless-keyword:
font-family: "Linux Libertine", "Hoefler Text", "Georgia", "Times New Roman", "Times", serif;

Enforced with always-where-required (updated):
font-family: Linux Libertine, Hoefler Text, Georgia, Times New Roman, Times, serif;

Moreover the quotes aren't even necessary as long as font family name is “a sequence of one or more identifiers” as laid out by Mathias Bynens in this insightful article.

Comparing implementation of other projects.

• W3C CSS Fonts Module Level 3:
  
  font-family: "New Century Schoolbook", serif
• WordPress 4.6:
  
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;
• Drupal 8, theme Bartik (comes with default installation):
  
  font-family: Georgia, "Times New Roman", Times, serif;

Add "stylelint-value-border-zero" plugin to package

stylelint-value-border-zero stylelint plugin is a good addition to our central ruleset as there's no reason for mixing the border-shorthand reset none and 0 and latter is shorter (ah!) and aligns with margin and padding.
border: 0; for the win!

Change rule: `selector-attribute-brackets-space-inside` should be 'true'

Review all the rest of the stylelint rules to see if we should add them

Add "unit-disallowed-list": "%" to config

Consider settling on ems only for relative font-sizing, not ending up with using both. We could also add ex to disallowed list in same activity.

Provide a mechanism to enforce '0' vs. 'none' for `box-shadow`

Like we did in #12 via the stylelint-value-border-zero plugin.

Flag setting `height` in `px` values

That's an accessibility anti-pattern. For example when user overrides text default size. And should only be allowed with disable line. Latest initiation was https://gerrit.wikimedia.org/r/c/wvui/+/651245

Support @counter-style and related properties

Both Firefox and Chrome now support the @counter-style feature, which is described at https://www.w3.org/TR/css-counter-styles-3/

stylelint doesn't seem to support it yet, and fails with property-no-unknown.

The necessary properties are:

• system
• negative
• prefix
• suffix
• range
• pad
• fallback
• symbols
• additive-symbols
• speak-as

Many code examples can be found at https://www.w3.org/TR/predefined-counter-styles/ . They were checked by W3C and are supposed to be valid.

This feature is used on Wikipedia in some languages, such as Santali (sat.wikipedia.org) and Meetei (mni.wikipedia.org), and Wikimedia's code is checked using stylelint, so it would be nice to support it properly without stylelint-disable.

Set "selector-pseudo-element-colon-notation" to single

While double colons are CSS3 recommended, they don't work in IE8 and below. As our rules should support Grade C browsers (IE6+) we should default to single. Individual projects can override to double if they are Grade A only.

Add "no-indistinguishable-colors" to general config

From a UI Standardization perspective no-indistinguishable-colors is a powerful addition to combat the little annoyances when there are too many similar color definitions at too many different rules.
Let's add "no-indistinguishable-colors": [ true, { "threshold": 1 } ]

Threshold set to 3 is the default, 1 seemed to be the right one for our current color shades in my test runs (OOjs UI, Echo).

Disallow @import rules except for LESS

Using @import in production CSS code should be forbidden by a stylerule. Doing this is basically never intentional as it would mean that the browser blocks all rendering while it parses the stylesheet until it has lazily discovered, downloaded, and parsed this other CSS file first.

Also, given that the CSS syntax requires @import to be at the top of a stylesheet, these statements generally stop working after bundling anyway. To bundle CSS files, one should use an RL module bundle definition with multiple style files, or use LESS to import them.

Which brings us to an interesting edg case: Using @import in a LESS file can still cause the same issue if the subject of the import is a .css file since the LESS specification says to only include/resolve other LESS files, unless the @import (inline) instruction is used. The number of times we've done this intentionally and purposefully is exactly zero. The only time I've seen it at all was in change 682085 after the above mistake was made as a temporary fix, which could still work even with this rule in place through an inline disable comment.

As such, I'm proposing that we error by default for all @import statements in CSS files, and any @import statemess for .css files in a LESS file – regardless of whether it has (inline) specified. If at some point in the next ten years there is another instance of this being done temporarily/intentionally, one can always disable the rule locally on that line, which seems worth the price for all other cases where you'd likely need to be reminded about it via a stylelint rule if you did it by accident or didn't know why it matters.

selector-max-id detectes isses even when the lines are disabled inline

When updating stylelint-config-wikimedia 0.5.0 to 0.6.0 npm begins to fail on MinervaNeue skin

I have updated grunt-stylelint to 0.14.0 and the issues remains, so I fault the config here, not stylelint

Running "stylelint:all" (stylelint) task

skinStyles/mediawiki.action.history.styles.less
  2:3  ✖  Expected ".action-history #pagehistory input[ type='radio' ]" to have no more than 0 ID selectors                                                                       selector-max-id
  8:3  ✖  Expected ".action-history #pagehistory input[ type='checkbox' ]" to have no more than 0 ID selectors                                                                    selector-max-id
 13:3  ✖  Expected ".action-history #pagehistory .mw-history-histlinks" to have no more than 0 ID selectors                                                                       selector-max-id
 18:3  ✖  Expected ".action-history #pagehistory .mw-changeslist-date" to have no more than 0 ID selectors                                                                        selector-max-id
 25:3  ✖  Expected ".action-history #pagehistory .history-user" to have no more than 0 ID selectors                                                                               selector-max-id
 31:4  ✖  Expected ".action-history #pagehistory .history-user .mw-userlink" to have no more than 0 ID selectors                                                                  selector-max-id
 39:3  ✖  Expected ".action-history #pagehistory .mw-changeslist-links:not( .mw-usertoollinks ):not( .mw-history-histlinks )" to have no more than 0 ID selectors                 selector-max-id
 41:4  ✖  Expected ".action-history #pagehistory .mw-changeslist-links:not( .mw-usertoollinks ):not( .mw-history-histlinks ) > span:before" to have no more than 0 ID selectors   selector-max-id
 45:4  ✖  Expected ".action-history #pagehistory .mw-changeslist-links:not( .mw-usertoollinks ):not( .mw-history-histlinks ) > span:after" to have no more than 0 ID selectors    selector-max-id
 51:3  ✖  Expected ".action-history #pagehistory .comment" to have no more than 0 ID selectors                                                                                    selector-max-id
 58:3  ✖  Expected ".action-history #pagehistory .comment" to have no more than 0 ID selectors                                                                                    selector-max-id
 58:3  ✖  Expected ".action-history #pagehistory .updatedmarker" to have no more than 0 ID selectors                                                                              selector-max-id
 58:3  ✖  Expected ".action-history #pagehistory .mw-diff-bytes" to have no more than 0 ID selectors                                                                              selector-max-id
 58:3  ✖  Expected ".action-history #pagehistory .mw-tag-markers" to have no more than 0 ID selectors                                                                             selector-max-id
 67:3  ✖  Expected ".action-history #pagehistory .history-user" to have no more than 0 ID selectors                                                                               selector-max-id
 67:3  ✖  Expected ".action-history #pagehistory .comment" to have no more than 0 ID selectors                                                                                    selector-max-id
 67:3  ✖  Expected ".action-history #pagehistory .updatedmarker" to have no more than 0 ID selectors                                                                              selector-max-id
 67:3  ✖  Expected ".action-history #pagehistory .mw-diff-bytes" to have no more than 0 ID selectors                                                                              selector-max-id
 67:3  ✖  Expected ".action-history #pagehistory .mw-history-tools" to have no more than 0 ID selectors                                                                           selector-max-id
 67:3  ✖  Expected ".action-history #pagehistory .mw-tag-markers" to have no more than 0 ID selectors                                                                             selector-max-id
 82:3  ✖  Expected ".action-history #pagehistory li:after" to have no more than 0 ID selectors                                                                                    selector-max-id
 87:3  ✖  Expected ".action-history #pagehistory input[ type='radio' ]" to have no more than 0 ID selectors                                                                       selector-max-id
 87:3  ✖  Expected ".action-history #pagehistory input[ type='checkbox' ]" to have no more than 0 ID selectors                                                                    selector-max-id

skinStyles/mediawiki.special.userlogin.common.styles/minerva.less
 2:2  ✖  Expected ".client-nojs #userloginForm" to have no more than 0 ID selectors                                     selector-max-id
 3:3  ✖  Expected ".client-nojs #userloginForm .mw-htmlform-field-HTMLCheckField" to have no more than 0 ID selectors   selector-max-id

At least the issues in mediawiki.special.userlogin.common.styles/minerva.less are disabled, but it seems stylelint just reports the wrong line:column and both lines are not disabled. When moving the disable comment up to the top of the file, it works. But that seems like a bad workaround
https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/skins/MinervaNeue/+/3fab70f8bc4ad0603602fb56bd8456a8d7c83ff2/skinStyles/mediawiki.special.userlogin.common.styles/minerva.less

The issue in mediawiki.action.history.styles.less remains
https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/skins/MinervaNeue/+/3fab70f8bc4ad0603602fb56bd8456a8d7c83ff2/skinStyles/mediawiki.action.history.styles.less

It also seems that stylelint cannot show lines with 3 digits (.mw-history-histlinks is in 113 of that file, not 13)

background-image with broken value isn't picked up on

background-image: ( 'images/tab-normal-fade.png' ) doesn't result in an error. Mind the missing url part.

Add "declaration-property-unit-disallowed-list": { "font-size": "px" }

In course of making our interfaces more accessible, we should add "px" to unit blacklist for font-size and possibly also line-height.

Make rules follow a logical order in the definition

Rules currently don't seem to follow a specific order, let's bring them in a logical order for better scan-ability, especially when you have to build project-own rules on top and have to compare it to own rules.

Update stylelintrc in README

Please use the name .stylelintrc.json in README
If possible use a tab in the json example

That would reflect the current usage on extensions on gerrit.wikimedia.org

Thanks

Add `declaration-empty-line-before` option

Propose to add declaration-empty-line-before and orientate on stylelint-config-standard here, with exception, that we shouldn't need to ignore inside-single-line-block:

"declaration-empty-line-before": [  "never", {
    ignore: [
        "after-comment",
        "inside-single-line-block",
    ],
} ],

Needs some closer testing, I don't want to see new lines except for rare exceptions.

That will do away with messy, inconsistent sometimes property sequences like:

.mw-notification {
	padding: 0.75em 1.5em;
	margin-bottom: 0.5em;
	border: solid 1px #ddd;
	background-color: #fff;
	/* Click handler in mediawiki.notification.js */
	cursor: pointer;

	opacity: 0;
	-webkit-transform: translateX( 35px );
	transform: translateX( 35px );
	-webkit-transition: opacity 0.35s ease-in-out, -webkit-transform 0.35s ease-in-out;
	transition: opacity 0.35s ease-in-out, transform 0.35s ease-in-out;
}

Add `rule-empty-line-before`

This missing feature has been an upsetting part so far to – the chaotic variability of how we're applying with new lines before selectors across the board:
I propose that we require always except after comments and when nesting selectors in media and supports queries. Things like that should not be possible any more:

.site__title {
	color: #222;
	font-family: system-ui, sans-serif;
}
.site__title a {
	color: inherit;
}
.site__title a:hover {
	// Test comment

	color: #000; 
}

@media only screen and ( max-width: 480px ) {

	.site__title {
		color: #444;
	}
}

Expected outcome:

.site__title {
	color: #222;
	font-family: system-ui, sans-serif;
}

.site__title a {
	color: inherit;
}

.site__title a:hover {
	// Test comment
	color: #000; 
}

@media only screen and ( max-width: 480px ) {
	.site__title {
		color: #444;
	}
}

Add rule to check for one space between selector and open brace

The missing space in the following css is not detected with the stylelint-config-wikimedia version 0.4.1

.articleplaceholder-identifierlist td{
	vertical-align: top;
	padding: 0.25em;
}

Please add a rule to check for one space between the td and {

minimist vulnerability needs update to ^1.2.3

It looks like this package is dependent on a vulnerable version of minimist, and might need to be updated past 1.2.3.

Remove `string-quotes` rule for now

"string-quotes": [ "single" ] should be discussed more broadly before setting it centralized – there's no guideline of it at https://www.mediawiki.org/wiki/Manual:Coding_conventions/CSS yet.

Add browser support rules

In theory we should be able to add "no-browser-hacks" for Grade C+ browsers and "no-unsupported-browser-features" for Grade A browsers. The latter will probably throw a bunch of warnings because we regularly use features that aren't supported in IE9 (mostly transitions).

Add "unit-blacklist": "rem" to config

In our environment, with skins providing independent font-size bases,rem is not a good choice and should be the explicit exception.
https://stylelint.io/user-guide/rules/unit-blacklist/#unit-blacklist

Ha, https://codesearch.wmflabs.org/deployed/?q=rem%3B&i=nope&files=&repos=

Upgrade to stylelint 7.12

Introduces some more deprecation: https://github.com/stylelint/stylelint/releases/tag/7.12.0

Only selector-no-id is of interest to us.

Unable to install: peerinvalid

npm install
npm WARN prefer global [email protected] should be installed with -g
npm ERR! peerinvalid The package stylelint does not satisfy its siblings' peerDependencies requirements!
npm ERR! peerinvalid Peer [email protected] wants stylelint@^7.0.2

npm ERR! System Linux 3.13.0-85-generic
npm ERR! command "/usr/bin/nodejs" "/usr/bin/npm" "install"
npm ERR! cwd /www/dev.translatewiki.net/docroot/w/extensions/UniversalLanguageSelector
npm ERR! node -v v0.10.25
npm ERR! npm -v 1.3.10
npm ERR! code EPEERINVALID
npm ERR! 
npm ERR! Additional logging details can be found in:
npm ERR!     /www/dev.translatewiki.net/docroot/w/extensions/UniversalLanguageSelector/npm-debug.log
npm ERR! not ok code 0

I am not sure if this is about npm being exceedingly difficult to use, or a bug in this package. The debug log does not say where [email protected] comes from.

Add rule for two or more newline before eof

There is a stylelint rule to check for missing end of source newline, but css with two or more newline at the end are not reported to be reduce to one newline

See https://gerrit.wikimedia.org/r/#/c/348509/2/modules/skinOverride.css for an example file, where it was not reported

Consider adding the stylelint-selector-no-mergeable plugin

https://github.com/timothyneiljohnson/stylelint-selector-no-mergeable is rather cute.

Prevent use of overly-generic class names without prefixes

As per https://www.mediawiki.org/wiki/Manual:Coding_conventions/CSS:

In MediaWiki core, use the mw- prefix. In extensions, use a ext-myextensioncodename- prefix

This means every class name should contain at least one hypen.

For stricter enforcement, we could also create a list of allowed prefixes, with mw- and ext- as the default.

Add `outline` to ignored no-unsupported-browser-features

outline might have had some support issues in the past in various browsers, a.o. not following border-radius property.
But the general feedback of 'no-unsupported-browser-features' plugin

Unexpected browser feature plugin/no-unsupported-browser-features
"outline" is only partially
supported by IE 11, Edge
12,13,14

does seem overly strict to me.

Proposal
Therefore proposing to add an ignore rule to plugin.

Investigate indentation false positive in LESS file

Have disable the indentation rule in https://gerrit.wikimedia.org/r/#/c/369874/5/view/resources/wikibase/wikibase.less

Running "stylelint:all" (stylelint) task

view/resources/wikibase/wikibase.less
51:1 ✖ Expected indentation of 1 tab indentation
Warning: Task "stylelint:all" failed.� Use --force to continue

But line 51 is a selector and should have 0 tabs for indentation. The line before has a not, please have a look and may report upstream if there is a bug in stylelint itself.
The same as css file works correctly.

Thanks

Review new rules in stylelint 9.5.0, select which ones we want and don't, and upgrade dependency

While updating some dev dependencies such as https://gerrit.wikimedia.org/r/457098/ I am getting:

npm WARN [email protected] requires a peer of [email protected] but none was installed

stylelint latest stable version is 9.5.0 according to https://www.npmjs.com/package/stylelint

Maybe we should make it compatible with our own package as well?

Thanks.

Consider making postcss-less a dependency

In Stylelint 14 this has to be installed manually, which we didn't have to do in the past.

Consider making postcss-scss a dependency

@Volker-E in #153:

Agreed, and also 'postcss-scss' for WMDE and others.

@edg2s:

SCSS seems like more of an edge case. LESS is supported by ResourceLoader.

@Volker-E:

An edge case in preference by second-biggest chapter? Also stylelint-config-wikimedia shouldn't be RL/MW exclusive from my understanding. https://trends.google.com/trends/explore?q=scss,%2Fm%2F0gjd0jv https://trends.google.com/trends/explore?q=%2Fm%2F054k6n_,%2Fm%2F0gjd0jv

Inconsistency regarding id selectors

selector-no-id is enabled, but https://www.mediawiki.org/wiki/Manual:Coding_conventions/CSS starts:

Name classes and IDs the same way [...]

While not explicitly allowing id selectors, this makes it sound like they're OK to use. Also, some of the examples use id selectors. Please update config or MW page to whichever is correct.

Add number rules

"number-leading-zero": [ "always" ],
"number-no-trailing-zeros": true,
"number-zero-length-no-unit": true,

Upgrade to align to stylelint 8.2.0

https://github.com/stylelint/stylelint/releases/tag/8.2.0