Skip to content

Commit 97f19bd

Browse files
ntwbjrfnlGaryJonesdingo-d
authored
Update css.md (#70)
CSS styleguide: convert from HTML to markdown and clean up * Update css.md * Wrap CSS elements in backticks * Update headers to markdown format * Update unordered list and list items to markdown format * Update code elements to use single backtics * Update URL to markdown format * Update blockquote to markdown format * Wrap more CSS elements in backticks * Use shortform URL format * Apply suggestions from code review Co-authored-by: Juliette <663378+jrfnl@users.noreply.github.com> Co-authored-by: Gary Jones <github@garyjones.io> Co-authored-by: Denis Žoljom <dingo-d@users.noreply.github.com>
1 parent af505b8 commit 97f19bd

File tree

1 file changed

+85
-78
lines changed
  • wordpress-coding-standards

1 file changed

+85
-78
lines changed

‎wordpress-coding-standards/css.md‎

Lines changed: 85 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,15 @@
33
Like any coding standard, the purpose of the WordPress CSS Coding Standards is to create a baseline for collaboration and review within various aspects of the WordPress open source project and community, from core code to themes to plugins. Files within a project should appear as though created by a single entity. Above all else, create code that is readable, meaningful, consistent, and beautiful.
44

55
Within core stylesheets, inconsistencies will often be found. We are working on addressing these and make every effort to have patches and commits from this point forward follow the CSS coding standards. More information on the above and contributing to UI/front-end development will be forthcoming in a separate set of guidelines.
6-
<h2>Structure</h2>
6+
7+
## Structure
8+
79
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.
8-
<ul>
9-
<li>Use tabs, not spaces, to indent each property.</li>
10-
<li>Add two blank lines between sections and one blank line between blocks in a section.</li>
11-
<li>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.</li>
12-
</ul>
10+
11+
- Use tabs, not spaces, to indent each property.
12+
- Add two blank lines between sections and one blank line between blocks in a section.
13+
- 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.
14+
1315
Correct:
1416

1517
```css
@@ -32,14 +34,15 @@ Incorrect:
3234
#selector-1 { background: #fff; color: #000; }
3335
```
3436

35-
<h2>Selectors</h2>
37+
## Selectors
38+
3639
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 judgement to create selectors that find the right balance between contributing to the overall style and layout of the DOM.
37-
<ul>
38-
<li>Similar to the <a href="https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#naming-conventions">WordPress PHP Coding Standards</a> for file names, use lowercase and separate words with hyphens when naming selectors. Avoid camelcase and underscores.</li>
39-
<li>Use human readable selectors that describe what element(s) they style.</li>
40-
<li>Attribute selectors should use double quotes around values</li>
41-
<li>Refrain from using over-qualified selectors, <code>div.container</code> can simply be stated as <code>.container</code></li>
42-
</ul>
40+
41+
- 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.
42+
- Use human readable selectors that describe what element(s) they style.
43+
- Attribute selectors should use double quotes around values.
44+
- Refrain from using over-qualified selectors, `div.container` can simply be stated as `.container`.
45+
4346
Correct:
4447

4548
```css
@@ -76,14 +79,15 @@ input[type=text] { /&042; Should be [type="text"] &042;/
7679
}
7780
```
7881

79-
<h2>Properties</h2>
82+
## Properties
83+
8084
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).
81-
<ul>
82-
<li>Properties should be followed by a colon and a space.</li>
83-
<li>All properties and values should be lowercase, except for font names and vendor-specific properties.</li>
84-
<li>Use hex code for colors, or rgba() if opacity is needed. Avoid RGB format and uppercase, and shorten values when possible: <code>#fff</code> instead of <code>#FFFFFF</code>.</li>
85-
<li>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 <a href="https://codex.wordpress.org/CSS_Shorthand">CSS Shorthand</a>.)</li>
86-
</ul>
85+
86+
- Properties should be followed by a colon and a space.
87+
- All properties and values should be lowercase, except for font names and vendor-specific properties.
88+
- 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`.
89+
- 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).
90+
8791
Correct:
8892

8993
```css
@@ -106,20 +110,22 @@ Incorrect:
106110
}
107111
```
108112

109-
<h3>Property Ordering</h3>
110-
<blockquote>"Group like properties together, especially if you have a lot of them."
111-
-- Nacin</blockquote>
112-
Above all else, choose something that is meaningful to you and semantic in some way. Random ordering is chaos, not poetry. In WordPress Core, our choice is logical or grouped ordering, wherein properties are grouped by meaning and ordered specifically within those groups. The properties within groups are also strategically ordered to create transitions between sections, such as background directly before color. The baseline for ordering is:
113-
<ul>
114-
<li>Display</li>
115-
<li>Positioning</li>
116-
<li>Box model</li>
117-
<li>Colors and Typography</li>
118-
<li>Other</li>
119-
</ul>
113+
### Property Ordering
114+
115+
> "Group like properties together, especially if you have a lot of them."
116+
> -- Nacin
117+
118+
Above all else, choose something that is meaningful to you and semantic in some way. Random ordering is chaos, not poetry. In WordPress Core, our choice is logical or grouped ordering, wherein properties are grouped by meaning and ordered specifically within those groups. The properties within groups are also strategically ordered to create transitions between sections, such as `background` directly before `color`. The baseline for ordering is:
119+
120+
- Display
121+
- Positioning
122+
- Box model
123+
- Colors and Typography
124+
- Other
125+
120126
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.
121127

122-
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 top-left, top-right, bottom-right, bottom-left. This is derived from how shorthand values would be ordered.
128+
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.
123129

124130
Example:
125131

@@ -147,10 +153,11 @@ Example:
147153
}
148154
```
149155

150-
<h3>Vendor Prefixes</h3>
151-
Updated on 2014-02-13, after <a href="https://core.trac.wordpress.org/changeset/27174">[27174]</a>:
156+
### Vendor Prefixes
157+
158+
Updated on 2014-02-13, after [[27174](https://core.trac.wordpress.org/changeset/27174)]:
152159

153-
We use <a href="https://github.com/postcss/autoprefixer">Autoprefixer</a> as a pre-commit tool to easily manage necessary browser prefixes, thus making the majority of this section moot. For those interested in following that output without using Grunt, vendor prefixes should go longest (-webkit-) to shortest (unprefixed). All other spacing remains as per the rest of standards.
160+
We use [Autoprefixer](https://github.com/postcss/autoprefixer) as a pre-commit tool to easily manage necessary browser prefixes, thus making the majority of this section moot. For those interested in following that output without using Grunt, vendor prefixes should go longest (-webkit-) to shortest (unprefixed). All other spacing remains as per the rest of standards.
154161

155162
```css
156163
.sample-output {
@@ -160,20 +167,21 @@ We use <a href="https://github.com/postcss/autoprefixer">Autoprefixer</a> as a p
160167
}
161168
```
162169

163-
<h2>Values</h2>
170+
## Values
171+
164172
There are numerous ways to input values for properties. Follow the guidelines below to help us retain a high degree of consistency.
165-
<ul>
166-
<li>Space before the value, after the colon.</li>
167-
<li>Do not pad parentheses with spaces.</li>
168-
<li>Always end in a semicolon.</li>
169-
<li>Use double quotes rather than single quotes, and only when needed, such as when a font name has a space or for the values of the <code>content</code> property.</li>
170-
<li>Font weights should be defined using numeric values (e.g. <code>400</code> instead of <code>normal</code>, <code>700</code> rather than <code>bold</code>).</li>
171-
<li>0 values should not have units unless necessary, such as with transition-duration.</li>
172-
<li>Line height should also be unit-less, unless necessary to be defined as a specific pixel value. This is more than just a style convention, but is worth mentioning here. More information: <a href="http://meyerweb.com/eric/thoughts/2006/02/08/unitless-line-heights/">http://meyerweb.com/eric/thoughts/2006/02/08/unitless-line-heights/</a></li>
173-
<li>Use a leading zero for decimal values, including in rgba().</li>
174-
<li>Multiple comma-separated values for one property should be separated by either a space or a newline. For better readability newlines should be used for lengthier multi-part values such as those for shorthand properties like box-shadow and text-shadow, including before the first value. Values should then be indented one level in from the property.</li>
175-
<li>Lists of values within a value, like within rgba(), should be separated by a space.</li>
176-
</ul>
173+
174+
- Space before the value, after the colon.
175+
- Do not pad parentheses with spaces.
176+
- Always end in a semicolon.
177+
- Use double quotes rather than single quotes, and only when needed, such as when a font name has a space or for the values of the `content` property.
178+
- Font weights should be defined using numeric values (e.g. `400` instead of `normal`, `700` rather than `bold`).
179+
- 0 values should not have units unless necessary, such as with `transition-duration`.
180+
- Line height should also be unit-less, unless necessary to be defined as a specific pixel value. This is more than just a style convention, but is worth mentioning here. More information: <https://meyerweb.com/eric/thoughts/2006/02/08/unitless-line-heights/>.
181+
- Use a leading zero for decimal values, including in `rgba()`.
182+
- Multiple comma-separated values for one property should be separated by either a space or a newline. For better readability newlines should be used for lengthier multi-part values such as those for shorthand properties like `box-shadow` and `text-shadow`, including before the first value. Values should then be indented one level in from the property.
183+
- Lists of values within a value, like within `rgba()`, should be separated by a space.
184+
177185
Correct:
178186

179187
```css
@@ -226,16 +234,14 @@ Incorrect:
226234
}
227235
```
228236

229-
<h2>Media Queries</h2>
237+
## Media Queries
238+
230239
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.
231-
<ul>
232-
<li>It is generally advisable to keep media queries grouped by media at the bottom of the stylesheet.
233-
<ul>
234-
<li>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.</li>
235-
</ul>
236-
</li>
237-
<li>Rule sets for media queries should be indented one level in.</li>
238-
</ul>
240+
241+
- It is generally advisable to keep media queries grouped by media at the bottom of the stylesheet.
242+
- 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.
243+
- Rule sets for media queries should be indented one level in.
244+
239245
Example:
240246

241247
```css
@@ -244,12 +250,12 @@ Example:
244250
}
245251
```
246252

247-
<h2>Commenting</h2>
248-
<ul>
249-
<li>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.</li>
250-
<li>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.</li>
251-
<li>Comments should be formatted much as PHPDoc is. The <a href="http://web.archive.org/web/20070601200419/http://cssdoc.net/">CSSDoc</a> 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.</li>
252-
</ul>
253+
## Commenting
254+
255+
- 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.
256+
- 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.
257+
- 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.
258+
253259
For sections and subsections:
254260

255261
```css
@@ -274,19 +280,20 @@ For inline:
274280
}
275281
```
276282

277-
<h2>Best Practices</h2>
283+
## Best Practices
284+
278285
Stylesheets tend to grow in length and complexity, and as they grow the chance of redundancy increases. By following some best practices we can help our CSS maintain focus and flexibility as it evolves:
279-
<ul>
280-
<li>If you are attempting to fix an issue, attempt to remove code before adding more.</li>
281-
<li>Magic Numbers are unlucky. These are numbers that are used as quick fixes on a one-off basis. Example: <code>.box { margin-top: 37px }</code>.</li>
282-
<li>DOM will change over time, target the element you want to use as opposed to "finding it" through its parents. Example: Use <code>.highlight</code> on the element as opposed to <code>.highlight a</code> (where the selector is on the parent)</li>
283-
<li>Know when to use the height property. It should be used when you are including outside elements (such as images). Otherwise use line-height for more flexibility.</li>
284-
<li>Do not restate default property &amp; value combinations (for instance <code>display: block;</code> on block-level elements).</li>
285-
</ul>
286-
287-
<h3>WP Admin CSS</h3>
288-
Check out the <a href="https://wordpress.github.io/css-audit/public/wp-admin">WP Admin CSS Audit</a>, a report generated to document the health of the WP Admin CSS code. Read more in <a href="https://github.com/WordPress/css-audit/blob/trunk/README.md">the repository's README</a>.
289-
<h2>Related Links</h2>
290-
<ul>
291-
<li>Principles of writing consistent, idiomatic CSS: <a href="https://github.com/necolas/idiomatic-css">https://github.com/necolas/idiomatic-css</a></li>
292-
</ul>
286+
287+
- If you are attempting to fix an issue, attempt to remove code before adding more.
288+
- Magic Numbers are unlucky. These are numbers that are used as quick fixes on a one-off basis. Example: `.box { margin-top: 37px }`.
289+
- DOM will change over time, target the element you want to use as opposed to "finding it" through its parents. Example: Use `.highlight` on the element as opposed to `.highlight a` (where the selector is on the parent)
290+
- Know when to use the `height` property. It should be used when you are including outside elements (such as images). Otherwise use `line-height` for more flexibility.
291+
- Do not restate default property and value combinations (for instance `display: block;` on block-level elements).
292+
293+
### WP Admin CSS
294+
295+
Check out the [WP Admin CSS Audit](https://wordpress.github.io/css-audit/public/wp-admin), a report generated to document the health of the WP Admin CSS code. Read more in [the repository's README](https://github.com/WordPress/css-audit/blob/trunk/README.md).
296+
297+
## Related Links
298+
299+
- Principles of writing consistent, idiomatic CSS: [https://github.com/necolas/idiomatic-css](https://github.com/necolas/idiomatic-css).

0 commit comments

Comments
 (0)