From b7713517b3c0db8f791e12e6abfcb80425bcf4d8 Mon Sep 17 00:00:00 2001 From: Andrea Fercia Date: Mon, 17 Aug 2026 15:45:19 +0200 Subject: [PATCH 1/4] Update minor CSS coding standards to adapt to the Stylelint configuration. --- changelog.md | 1 + wordpress-coding-standards/css.md | 63 +++++++++++++++++++++++++------ 2 files changed, 53 insertions(+), 11 deletions(-) diff --git a/changelog.md b/changelog.md index cf03850..ddf53cf 100644 --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,6 @@ # Changelog +- 2026-08-17 Updated `css.md` to adapt to the new Stylelint configuration. - 2020-09-25 Update code examples to use Markdown code fence notation instead of shortcodes. - 2019-12-21 Update `javascript.md` from the [handbook page](https://make.wordpress.org/core/handbook/best-practices/coding-standards/javascript/). - 2019-12-21 Update `accessibility.md` from the [handbook page](https://make.wordpress.org/core/handbook/best-practices/coding-standards/accessibility-coding-standards/). diff --git a/wordpress-coding-standards/css.md b/wordpress-coding-standards/css.md index 1d2a592..7e7e397 100644 --- a/wordpress-coding-standards/css.md +++ b/wordpress-coding-standards/css.md @@ -9,8 +9,10 @@ Within core stylesheets, inconsistencies will often be found. We are working on There are plenty of different methods for structuring a stylesheet. With the CSS in core, it is important to retain a high degree of legibility. This enables subsequent contributors to have a clear understanding of the flow of the document. - Use tabs, not spaces, to indent each property. -- Add two blank lines between sections and one blank line between blocks in a section. -- Each selector should be on its own line, ending in either a comma or an opening curly brace. Property-value pairs should be on their own line, with one tab of indentation and an ending semicolon. The closing brace should be flush left, using the same level of indentation as the opening selector. +- Add one blank line between sections and between blocks in a section. +- Each selector should be on its own line, ending in either a comma or an opening curly brace. +- Property-value pairs should be on their own line, with one tab of indentation and an ending semicolon. +- The closing brace should be flush left, using the same level of indentation as the opening selector. Correct: @@ -31,15 +33,39 @@ Incorrect: color: #000; } -#selector-1 { background: #fff; color: #000; } +#selector-4 { background: #fff; color: #000; } ``` ## Selectors With specificity, comes great responsibility. Broad selectors allow us to be efficient, yet can have adverse consequences if not tested. Location-specific selectors can save us time, but will quickly lead to a cluttered stylesheet. Exercise your best judgment to create selectors that find the right balance between contributing to the overall style and layout of the DOM. -- Similar to the [WordPress PHP Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#naming-conventions) for file names, use lowercase and separate words with hyphens when naming selectors. Avoid camelcase and underscores. -- Use human readable selectors that describe what element(s) they style. +### Legacy naming convention + +Similar to the [WordPress PHP Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#naming-conventions) for file names, use lowercase and separate words with hyphens when naming selectors. Avoid camelcase and underscores. + +Selectors using this convention are extensively used in legacy stylesheets and they should not be changed for backward compatibility reasons. + +### New naming convention + +For new stylesheets, contributors are encouraged to use the new naming convention for class selectors. ID selectors should still use the legacy naming convention with only hyphens to separate words. + +For consistency with [the naming convention used in the block editor](https://github.com/wordpress/gutenberg/blob/trunk/docs/contributors/code/coding-guidelines.md#naming), class selectors are now allowed to use the [Two Dashes style of the BEM (Block, Element, Modifier) methodology](https://bem.info/en/methodology/naming-convention/#two-dashes-style). + +Example: + +``` +block-name__element-name--modifier-name +``` + +And when the modifier has a value: + +``` +block-name__element-name--modifier-name_modifier-value +``` + +### General recommendations + - Attribute selectors should use double quotes around values. - Refrain from using over-qualified selectors, `div.container` can simply be stated as `.container`. @@ -50,9 +76,21 @@ Correct: margin: 1em 0; } -input[type="text"] { +[type="text"] { line-height: 1.1; } + +.about__section { + margin: 1em 0; +} + +.wp-tooltip__toggle { + margin: 1em 0; +} + +.card__title--size_medium { + font-size: 1rem; +} ``` Incorrect: @@ -84,14 +122,18 @@ input[type=text] { /&042; Should be [type="text"] &042;/ Similar to selectors, properties that are too specific will hinder the flexibility of the design. Less is more. Make sure you are not repeating styling or introducing fixed dimensions (when a fluid solution is more acceptable). - Properties should be followed by a colon and a space. -- All properties and values should be lowercase, except for font names and vendor-specific properties. -- Use hex code for colors, or `rgba()` if opacity is needed. Avoid RGB format and uppercase, and shorten values when possible: `#fff` instead of `#FFFFFF`. +- All properties should be lowercase. +- All values should be lowercase, except for font names and vendor-specific properties. Additional exceptions are: + - `currentColor` + - `optimizeLegibility` +- Use hex code for colors, or `rgba()` if opacity is needed. Avoid RGB format and uppercase. +- Shorten color values when possible: `#fff` instead of `#FFFFFF`. - Use shorthand, except when overriding styles, for `background`, `border`, `font`, `list-style`, `margin`, and `padding` values as much as possible. For a shorthand reference, see [CSS Shorthand](https://codex.wordpress.org/CSS_Shorthand). Correct: ```css -#selector-1 { +#selector-5 { background: #fff; display: block; margin: 0; @@ -102,7 +144,7 @@ Correct: Incorrect: ```css -#selector-1 { +#selector-5 { background:#FFFFFF; display: BLOCK; margin-left: 20PX; @@ -264,7 +306,6 @@ For sections and subsections: * * Description of section, whether or not it has media queries, etc. */ - .selector { float: left; } From 8c9c703e9b433a06cbf2ce0d5a07d42729ec9cd9 Mon Sep 17 00:00:00 2001 From: Andrea Fercia Date: Wed, 19 Aug 2026 10:25:09 +0200 Subject: [PATCH 2/4] Remove unnecessary changelog entry. --- changelog.md | 1 - 1 file changed, 1 deletion(-) diff --git a/changelog.md b/changelog.md index ddf53cf..cf03850 100644 --- a/changelog.md +++ b/changelog.md @@ -1,6 +1,5 @@ # Changelog -- 2026-08-17 Updated `css.md` to adapt to the new Stylelint configuration. - 2020-09-25 Update code examples to use Markdown code fence notation instead of shortcodes. - 2019-12-21 Update `javascript.md` from the [handbook page](https://make.wordpress.org/core/handbook/best-practices/coding-standards/javascript/). - 2019-12-21 Update `accessibility.md` from the [handbook page](https://make.wordpress.org/core/handbook/best-practices/coding-standards/accessibility-coding-standards/). From a49d497a8e90d945fb8779130937e889b6d5c64a Mon Sep 17 00:00:00 2001 From: Andrea Fercia Date: Mon, 24 Aug 2026 10:33:10 +0200 Subject: [PATCH 3/4] Remove outdated recommendations and use more bullet points. --- wordpress-coding-standards/css.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/wordpress-coding-standards/css.md b/wordpress-coding-standards/css.md index 7e7e397..ed41751 100644 --- a/wordpress-coding-standards/css.md +++ b/wordpress-coding-standards/css.md @@ -165,7 +165,7 @@ Above all else, choose something that is meaningful to you and semantic in some - Colors and Typography - Other -Things that are not yet used in core itself, such as CSS3 animations, may not have a prescribed place above but likely would fit into one of the above in a logical manner. Just as CSS is evolving, so our standards will evolve with it. +Things that are not yet used in core itself may not have a prescribed place above but likely would fit into one of the above in a logical manner. Just as CSS is evolving, so our standards will evolve with it. Top/Right/Bottom/Left (TRBL/trouble) should be the order for any relevant properties (e.g. `margin`), much as the order goes in values. Corner specifiers (e.g. `border-radius-*-*`) should be ordered as top-left, top-right, bottom-right, bottom-left. This is derived from how shorthand values would be ordered. @@ -281,7 +281,6 @@ Incorrect: Media queries allow us to gracefully degrade the DOM for different screen sizes. If you are adding any, be sure to test above and below the break-point you are targeting. - It is generally advisable to keep media queries grouped by media at the bottom of the stylesheet. - - 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. - Rule sets for media queries should be indented one level in. Example: @@ -294,9 +293,12 @@ Example: ## Commenting -- Comment, and comment liberally. If there are concerns about file size, utilize minified files and the `SCRIPT_DEBUG` constant. Long comments should manually break the line length at 80 characters. +- Comment, and comment liberally. If there are concerns about file size, utilize minified files and the `SCRIPT_DEBUG` constant. +- Long comments should manually break the line length at 80 characters. - A table of contents should be utilized for longer stylesheets, especially those that are highly sectioned. Using an index number (`1.0`, `1.1`, `2.0`, etc.) aids in searching and jumping to a location. -- Comments should be formatted much as PHPDoc is. The [CSSDoc](https://web.archive.org/web/20070601200419/http://cssdoc.net/) standard is not necessarily widely accepted or used but some aspects of it may be adopted over time. Section/subsection headers should have newlines before and after. Inline comments should not have empty newlines separating the comment from the item to which it relates. +- Comments should be formatted much as PHPDoc is. The [CSSDoc](https://web.archive.org/web/20070601200419/http://cssdoc.net/) standard is not necessarily widely accepted or used but some aspects of it may be adopted over time. +- Section/subsection headers should have newlines before and after. +- Inline comments should not have empty newlines separating the comment from the item to which it relates. For sections and subsections: From e87b52299e75783e6facb10e74796b3d464758e7 Mon Sep 17 00:00:00 2001 From: Andrea Fercia Date: Mon, 24 Aug 2026 11:12:08 +0200 Subject: [PATCH 4/4] Discourage use of ID selectors. --- wordpress-coding-standards/css.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/wordpress-coding-standards/css.md b/wordpress-coding-standards/css.md index ed41751..0904407 100644 --- a/wordpress-coding-standards/css.md +++ b/wordpress-coding-standards/css.md @@ -48,7 +48,9 @@ Selectors using this convention are extensively used in legacy stylesheets and t ### New naming convention -For new stylesheets, contributors are encouraged to use the new naming convention for class selectors. ID selectors should still use the legacy naming convention with only hyphens to separate words. +For new stylesheets, contributors are encouraged to use the new naming convention for class selectors. + +ID selectors are not encouraged but are sometimes unavoidable. Avoid them as much as possible. They should still use the legacy naming convention with only hyphens to separate words. For consistency with [the naming convention used in the block editor](https://github.com/wordpress/gutenberg/blob/trunk/docs/contributors/code/coding-guidelines.md#naming), class selectors are now allowed to use the [Two Dashes style of the BEM (Block, Element, Modifier) methodology](https://bem.info/en/methodology/naming-convention/#two-dashes-style).