WordPress CSS 编码规范为 WordPress 核心、主题和插件的样式表协作与审查建立统一基线,目标是让代码可读、有意义、一致且美观。文档重点说明样式表结构、选择器与属性书写、属性排序、值格式、媒体查询、注释及最佳实践,以降低维护成本并提升可审查性。
#selector-1,
#selector-2,
#selector-3 {
background: #fff;
color: #000;
}
input[type="text"] {
line-height: 1.1;
}
#overlay {
position: absolute;
z-index: 1;
padding: 10px;
background: #fff;
color: #777;
}
@media all and (max-width: 699px) and (min-width: 520px) {
/* Your selectors */
}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.
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.
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.
Correct:
#selector-1,
#selector-2,
#selector-3 {
background: #fff;
color: #000;
}
Incorrect:
#selector-1, #selector-2, #selector-3 {
background: #fff;
color: #000;
}
#selector-1 { background: #fff; color: #000; }
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.
div.container can simply be stated as .container.Correct:
#comment-form {
margin: 1em 0;
}
input[type="text"] {
line-height: 1.1;
}
Incorrect:
#commentForm { /* Avoid camelcase. */
margin: 0;
}
#comment_form { /* Avoid underscores. */
margin: 0;
}
div#comment_form { /* Avoid over-qualification. */
margin: 0;
}
#c1-xr { /* What is a c1-xr?! Use a better name. */
margin: 0;
}
input[type=text] { /* Should be [type="text"] */
line-height: 110% /* Also doubly incorrect */
}
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).
rgba() if opacity is needed. Avoid RGB format and uppercase, and shorten values when possible: #fff instead of #FFFFFF.background, border, font, list-style, margin, and padding values as much as possible. For a shorthand reference, see CSS Shorthand.Correct:
#selector-1 {
background: #fff;
display: block;
margin: 0;
margin-left: 20px;
}
Incorrect:
#selector-1 {
background:#FFFFFF;
display: BLOCK;
margin-left: 20PX;
margin: 0;
}
“Group like properties together, especially if you have a lot of them.”
— Nacin
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:
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.
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.
Example:
#overlay {
position: absolute;
z-index: 1;
padding: 10px;
background: #fff;
color: #777;
}
Another method that is often used, including by the Automattic/WordPress.com Themes Team, is to order properties alphabetically, with or without certain exceptions.
Example:
#overlay {
background: #fff;
color: #777;
padding: 10px;
position: absolute;
z-index: 1;
}
Updated on 2014-02-13, after [27174]:
We use 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 the standards.
.sample-output {
-webkit-box-shadow: inset 0 0 1px 1px #eee;
-moz-box-shadow: inset 0 0 1px 1px #eee;
box-shadow: inset 0 0 1px 1px #eee;
}
There are numerous ways to input values for properties. Follow the guidelines below to help us retain a high degree of consistency.
content property.400 instead of normal, 700 rather than bold).transition-duration.rgba().box-shadow and text-shadow, including before the first value. Values should then be indented one level in from the property.rgba(), should be separated by a space.Correct:
.class { /* Correct usage of quotes */
background-image: url(images/bg.png);
font-family: "Helvetica Neue", sans-serif;
font-weight: 700;
}
.class { /* Correct usage of zero values */
font-family: Georgia, serif;
line-height: 1.4;
text-shadow:
0 -1px 0 rgba(0, 0, 0, 0.5),
0 1px 0 #fff;
}
.class { /* Correct usage of short and lengthier multi-part values */
font-family: Consolas, Monaco, monospace;
transition-property: opacity, background, color;
box-shadow:
0 0 0 1px #5b9dd9,
0 0 2px 1px rgba(30, 140, 190, 0.8);
}
Incorrect:
.class { /* Avoid missing space and semicolon */
background:#fff
}
.class { /* Avoid adding a unit on a zero value */
margin: 0px 0px 20px 0px;
}
.class {
font-family: Times New Roman, serif; /* Quote font names when required */
font-weight: bold; /* Avoid named font weights */
line-height: 1.4em; /* Avoid adding a unit for line height */
}
.class { /* Incorrect usage of multi-part values */
text-shadow: 0 1px 0 rgba(0, 0, 0, 0.5),
0 1px 0 #fff;
box-shadow: 0 1px 0 rgba(0, 0,
0, 0.5),
0 1px 0 rgba(0,0,0,0.5);
}
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.
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.Example:
@media all and (max-width: 699px) and (min-width: 520px) {
/* Your selectors */
}
SCRIPT_DEBUG constant. Long comments should manually break the line length at 80 characters.1.0, 1.1, 2.0, etc.) aids in searching and jumping to a location.For sections and subsections:
/**
* #.# Section title
*
* Description of section, whether or not it has media queries, etc.
*/
.selector {
float: left;
}
For inline:
/* This is a comment about this selector */
.another-selector {
position: absolute;
top: 0 !important; /* I should explain why this is so !important */
}
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:
.box { margin-top: 37px }..highlight on the element as opposed to .highlight a (where the selector is on the parent)height property. It should be used when you are including outside elements (such as images). Otherwise use line-height for more flexibility.display: block; on block-level elements).Check out the WP Admin CSS Audit, a report generated to document the health of the WP Admin CSS code. Read more in the repository’s README.