The purpose of this proposal is to introduce minor changes to the WordPress CSS Coding Standards required to integrate Stylelint into Core Core is the set of software required to run WordPress. The Core Development Team builds WordPress.. Please keep any feedback focused on the scope of these minor changes.

On Trac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticket Created for both bug reports and feature development on the bug tracker. #29792 a proposal has been made to introduce a CSS Cascading Style Sheets. linter to check for syntax errors and enforce the CSS Coding Standards for Core. A versioned version of the current standards is available on the WordPress Coding Standards The Accessibility, PHP, JavaScript, CSS, HTML, etc. coding standards as published in the WordPress Coding Standards Handbook. May also refer to The collection of PHP_CodeSniffer rules (sniffs) used to format and validate PHP code developed for WordPress according to the PHP coding standards. Docs repository.

While syntax errors are already caught by postcss, the coding standards aren’t currently enforced. There is now a proposal to introduce Stylelint as a tool to enforce them. Stylelint has been used in the Gutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ editor repository for several years, and is widely used in the tech industry. It’s a flexible and powerful tool that will help make sure no new standards errors are introduced, for better compliance and future maintainability.

To introduce Stylelint in Core and in the WordPress Continuous Integration pipeline, a minor update to the CSS Coding Standards must happen first. A pull request is ready on the related repository for the proposed update.

Two changes are relevant, while others are minor or purely cosmetic changes. The rest of the Stylelint configuration matches the current coding standards.

The sentence Add two blank lines between sections and one blank line between blocks in a section is changed to Add one blank line between sections and between blocks in a section.

Rationale: Stylelint can’t distinguish between blank lines that come before sections and blocks in a section. As such, the rule is simplified to require one blank line everywhere.

In the Properties and in the Values sections, two new bullet points are added to require avoiding the usage of the order property and the *-reverse values. Note that this matches the rules that are already in use in the Gutenberg repository.

Rationale: the order property and the *-reverse values are known to be potentially harmful for accessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility). For accessibility reasons, visual, reading, and DOM order must match. Only use order and the reverse values when they do not affect reading order, meaning, and interaction.

Quoting from the W3C CSS Display Module Level 3 and the W3C CSS Flexible Box Layout Module Level 1:

Authors must use order only for spatial, not logical, reordering of content. Style sheets that use order to perform logical reordering are non-conforming.

Authors must not use order or the *-reverse values of flex-flow/flex-direction as a substitute for correct source ordering, as that can ruin the accessibility of the document.

Added explicit exceptions to lowercase values for:

• currentColor
• optimizeLegibility

Changed the sentence Things that are not yet used in core itself, such as CSS3 animations ... by removing the part: such as CSS3 animations because CSS3 animations are now used in Core.

Entirely removed the following bullet point:

• An exception is made for the wp-admin.css file in core, as it is very large and each section essentially represents a stylesheet of its own. Media queries are therefore added at the bottom of sections as applicable.

because wp-admin.css is no longer split into sections.

Other changes are purely cosmetic, for example long sentences have been split into bullet points for better readability.

I would like to propose leaving this proposal open for comments for one week to gather feedback and any concerns. After a week, in the absence of significant objections, I suggest proceeding with the update.

Any feedback and comments are welcome.

Once Stylelint will be in place, WordPress will have a solid baseline for further Core CSS improvements. If the CSS Coding Standards require major changes, they can be considered based on actual data provided by Stylelint. This could be addressed in a future, more wide-ranging proposal.

Props to @joedolson for review and feedback.

#codingstandards, #core-css, #proposal