CSS Coding Standards

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.

いずれのコーディング規約と同様、WordPressのCSSコーディング規約の目的は、コアコードからテーマやプラグインまで、WordPressオープンソースのプロジェクトとコミュニティの様々な場面における共同作業とレビューのベースラインを作ることにあります。

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.

私たちはこれらの問題に取り組んでおり、CSSコーディング規約に沿った修正と関与に全力を尽くしています。

More information on the above and contributing to UI/front-end development will be forthcoming in a separate set of guidelines.

更なる情報を踏まえて、UI・フロントエンドの開発の独立したガイドラインに役立てる予定です。

Structure

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.

コアのCSSは、高い可読性を維持することが重要です。

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.
• 各セクションの間には2行の空白を、セクション内のブロックには1行の空白を入れてください。
• 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.
• それぞれのセレクターはコンマまたは開いた中カッコで終わらせます。一組のプロパティと値は1つのタブでインデントされ、セミコロンで終了します。閉じカッコはセレクタの開始と同じインデントレベルで、左揃えにします。

Correct:

#selector-1,
#selector-2,
#selector-3 {
    background: #fff;
    color: #000;
}

Incorrect:

#selector-1, #selector-2, #selector-3 {
    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 judgement to create selectors that find the right balance between contributing to the overall style and layout of the DOM.

全体のスタイルとDOMのレイアウトのバランスの取れたセレクタの制作に対し、最善の判断を行うための訓練を積んでください。

• Similar to the WordPress Coding Standards for file names, use lowercase and separate words with hyphens when naming selectors.
• ファイル名は WordPress Coding Standards に従い、セレクタの命名には小文字でハイフンで区切られた単語を用いてください。
• Avoid camelcase and underscores.
• キャメルケースとアンダースコアは避けてください。
• Use human readable selectors that describe what element(s) they style.
• 要素とそれらのスタイルは人が読めるセレクタを用いてください。
• Attribute selectors should use double quotes around values
• 属性セレクタは、値を二重引用符で囲んでください。
• Refrain from using over-qualified selectors, div.container can simply be stated as .container
• 過剰な修飾セレクタの使用は控えてください。div.containerは.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. c1-xrとはなんでしょうか？より良い名前を使ってください */
    margin: 0;
}
 
input[type=text] { /* Should be [type="text"]　と書くべきです。 */
    line-height: 110% /* Also doubly incorrect　2重に間違っています */
}

Properties

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.
• 色は16進コードか、半透明が必要な場合はrgba()を用います。RGBフォーマットと大文字は避け、可能ならば短くします。例えば、#FFFFFFのかわりに#fffというように。
• 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.)
• background, border, font, list-stile, margin, padding の値には可能な限りショートハンド（まとめて指定する）を使用します。（ショートハンドのリファレンスは CSS Shorthandを確認してください。）

Property Ordering

“Group like properties together, especially if you have a lot of them.”
— Nacin

プロパティがたくさんある場合は特に、まとめてグループ化を－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.

プロパティはまた、colorの直前にbackgroundを配置する、というように戦略的にグループを決めています。

The baseline for ordering is:

順序のベースは以下のようです。

• Display
• Positioning
• Box model
• 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.

CSS3のアニメーションのようにコアにまだ使われていないものは、定められた場所がまだありまりませんが、論理的なマナーに則って上記の一つに収まるでしょう。

Just as CSS is evolving, so our standards will evolve with it.

CSSは進化し続けており、私たちの基準もそれに伴い進化していきます。

Top/Right/Bottom/Left (TRBL/trouble) should be the order for any relevant properties (e.g. margin), much as the order goes in values.

関係するプロパティ（marginのような）に合わせて、Top/Right/Bottom/Left (TRBL/trouble)の順で値を記録します。

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.

border-radiusのような角の指定は、top-left, top-right, bottom-right, bottom-left（左上、右上、右下、左下）の順で行います。これはショートハンドの順番と同じです。

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.

自動整形やWordPress.comも含め、よく使われるほかの方法は、アルファベット順にすることです。

Example:

#overlay {
    background: #fff;
    color: #777;
    padding: 10px;
    position: absolute;
    z-index: 1;
}

Vendor Prefixes

Updated on 2/13/2014, after [27174]:

We use grunt-autoprefixer as a pre-commit tool to easily manage necessary browser prefixes, thus making the majority of this section moot.

私たちはこのセクションの議論の大部分を形作るものとして、 grunt-autoprefixer をブラウザのプレフィクスの管理に使用することを前提としています。

For those interested in following that output without using Grunt, vendor prefixes should go longest (-webkit-) to shortest (unprefixed).

以下にGrountを使わない場合の出力を示します。ベンダープレフィクスはもっとも長いもの (-webkit-) から短いものへ (unprefixed)の順とします。

All other spacing remains as per the rest of 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;
}

Values

There are numerous ways to input values for properties. Follow the guidelines below to help us retain a high degree of consistency.

プロパティの値の入力方法は数種類あります。高い一貫性を維持するために、次のガイドラインに従ってください。

• Space before the value, after the colon
• 値の直前、コロンの後にスペースを設ける。
• Do not pad parentheses with spaces
• スペースで（）を埋めないでください。
• Always end in a semicolon
• 常にセミコロンで終了してください。
• Use double quotes rather than single quotes, and only when needed, such as when a font name has a space.
• スペースを持つフォント名のような必要性が無い限り、単一引用符よりも二重引用符を用いてください。
• 0 values should not have units unless necessary, such as with transition-duration.
• 0の値はtransition-durationのように、必要が無い限り、単位をつけないでください。
• 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:http://meyerweb.com/eric/thoughts/2006/02/08/unitless-line-heights/
• line heightは特別なピクセル値が必要でない限り、単位をつけないでください。これは単なるスタイルの慣習を超えており、詳しくはhttp://meyerweb.com/eric/thoughts/2006/02/08/unitless-line-heights/を参照してください。
• Use a leading zero for decimal values, including in rgba().
• 小数点以下の値はrgba()も含め、0を付けてください。
• Multiple comma-separated values for one property should be separated by either a space or a newline, including within rgba(). Newlines should be used for lengthier multi-part values such as those for shorthand properties like box-shadow and text-shadow. Each subsequent value after the first should then be on a new line, indented to the same level as the selector and then spaced over to left-align with the previous value.
• 複数のコンマで分けられた値は、rgba()も含め、スペースか新しい行で分けてください。新しい行を使うときはbox-shadowやtext-shadowのようなプロパティのショートハンドのような値に用いるべきです。

Correct:

.class { /* Correct usage of quotes */
    background-image: url(images/bg.png);
    font-family: "Helvetica Neue", sans-serif;
}
 
.class { /* Correct usage of zero values */
    font-family: Georgia, serif;
    text-shadow: 0 -1px 0 rgba(0, 0, 0, 0.5),
                       0 1px 0 #fff;
}

Incorrect:

.class { /* Avoid missing space and semicolon */
    background:#fff
}
 
.class { /* Avoid adding a unit on a zero value */
    margin: 0px 0px 20px 0px;
}

Media Queries

Media queries allow us to gracefully degrade the DOM for different screen sizes.

メディアクエリは、異なるスクリーンサイズのためのDOMをきれいに縮小化することができます。

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.
• 一般的に、スタイルシートの最下部でメディアクエリをまとめることを勧めます。
  • 一つの例外は、コアのwp-admin.cssファイル用に作られたもので、それぞれのセクションで要点を表示します。メディアクエリはそれゆえ、そのセクションの下部に追加されます。
• Rule sets for media queries should be indented one level in.
• メディアクエリのルールセットは一段落としてください。

Example:

@media all and (max-width: 699px) and (min-width: 520px) {
 
        /* Your selectors */
}

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.
• コメントは自由です。ファイルサイズの懸念がある場合は、縮小化ファイルとSCRIPT_DEBUG定数を用います。長いコメントは手動で80字で改行する必要があります。
• 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 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.
• コメントはPHPDocの形式で書きましょう。CSSDoc基準は必ずしも広く受け入れられていませんが、将来は採用されるかもしれません。セクションとサブセクションのヘッダーは、その前後に改行が必要です。インラインコメントは空白行で分離せずそれに関係するコメントを記述します。

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　!importantが必要な理由を記述します。 */
}

Best Practices

Stylesheets tend to get long in length.

スタイルシートは長くなる傾向があります。

Focus slowly gets lost whilst intended goals start repeating and overlapping.

繰り返しと上書きにより、目的とは緩やかに失われていきます。

Writing smart code from the outset helps us retain the overview whilst remaining flexible throughout change.

賢くコードを書くことは、変化の間、柔軟さを失わず概要を維持することを助けるスタートになります。

• If you are attempting to fix an issue, attempt to remove code before adding more.
• あなたが問題を解決しようとするならば、コードを追加する前に削除しましょう。
• Magic Numbers are unlucky. These are numbers that are used as quick fixes on a one-off basis. Example: .box { margin-top: 37px }.
• マジックナンバーは不遇です。それらは一度限りしか使われません。例：.box { margin-top: 37px; }
• 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)
• DOMは将来変更されます。ターゲットのエレメントはその親を通して見つけられるようにします。例えば、要素上の.highlightは.highlight a に対して、そのセレクターを通しています。
• 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.
• hightプロパティを使う際には、画像のように、そのエレメントの外側を囲んでいなければならない。他方、line-heightを使うほうが柔軟です。
• Do not restate default property & value combinations (for instance display: block; on block-level elements).
• デフォルトのプロパティと値の組合せを書き直してはいけません。（例えば、ブロックレベル要素にdisplay: block; を指定するなど）

HTML Codeing Standards

HTML

Validation

All HTML pages should be verified against the W3C validator to ensure that the markup is well formed.

全てのHTMLページは、W3C validatorにて検証され、マークアップが正しく整形されていることを保障すべきです。

This in and of itself is not directly indicative of good code, but it helps to weed out problems that are able to be tested via automation.

それ自体はよいコードであることを直接保障するものではありませんが、自動テストにおいて問題を取り除く助けになります。

It is no substitute for manual code review.

これは手動でのコードレビューに変わるものではありません。

(For other validators, see HTML Validation in the Codex.)

他のバリデータについては、コーデックスの HTML Validationを見てください。

Self-closing Elements

All tags must be properly closed.

全てのタグは適切に閉じられていなければなりません。

For tags that can wrap nodes such as text or other elements, termination is a trivial enough task.

テキストや他の要素のようなノードをラップするために、タグを閉じる事は些細で十分な作業です。

For tags that are self-closing, the forward slash should have exactly one space preceding it:

空要素の場合、スラッシュの前にスペースを一つ空けます。

<br />

rather than the compact but incorrect:

これよりコンパクトですが、以下は正しくありません。

<br/>

The W3C specifies that a single space should precede the self-closing slash (source).

W3Cは、空要素のスラッシュの前にスペースを一つ書くことを定めています。

属性とタグ

All tags and attributes must be written in lowercase.

全てのタグと属性は小文字でかかれなければなりません。

Additionally, attribute values should be lowercase when the purpose of the text therein is only to be interpreted by machines.

加えて、機械によってのみ読まれる場合、属性の値も小文字を使うようにします。

For instances in which the data needs to be human readable, proper title capitalization should be followed.

そのデータを人が読めるようにする目的のにおいては、適切なタイトル属性を続けるべきである。

For machines:

<meta http-equiv="content-type" content="text/html; charset=utf-8" />

For humans:

<a href="http://example.com/" title="Description Here">Example.com</a>

Quotes

According to the W3C specifications for XHTML, all attributes must have a value, and must use double- or single-quotes (source).

XHTMLに関するW3Cの使用によると、全ての属性は値を持たなければならず、二重または単一引用符を用いなければなりません。

The following are examples of proper and improper usage of quotes and attribute/value pairs.

以下は引用符と属性・値の、適切および不適切な使用例である。

Correct:

<input type="text" name="email" disabled="disabled" />
<input type='text' name='email' disabled='disabled' />

Incorrect:

<input type=text name=email disabled>

In HTML, attributes do not all have to have values, and attribute values do not always have to be quoted.

HTMLにおいて、属性は全てが値を持つ必要はなく、また属性の値も常に引用符で囲む必要はありません。

While all of the examples above are valid HTML, failing to quote attributes can lead to security vulnerabilities. Always quote attributes.

上記の全ては有効なHTMLですが、属性の引用に失敗すると、セキュリティの脆弱性を引き起こす可能性があります。常に引用符を用いましょう。

Indentation

As with PHP, HTML indentation should always reflect logical structure. Use tabs and not spaces.

PHP同様、HTMLのインデントは常に論理構造を反映する必要があります。スペースではなくタブを用いてください。

When mixing PHP and HTML together, indent PHP blocks to match the surrounding HTML code.

PHPとHTMLが混在する場合、PHPブロックのインデントは周辺のHTMLコードと一致させます。

Closing PHP blocks should match the same indentation level as the opening block.

PHPブロックを閉じる際は、ブロックを開いたときと同じレベルにしなければなりません。

Correct:

<?php if ( ! have_posts() ) : ?>
    <div id="post-1" class="post">
        <h1 class="entry-title">Not Found</h1>
        <div class="entry-content">
            <p>Apologies, but no results were found.</p>
            <?php get_search_form(); ?>
        </div>
    </div>
<?php endif; ?>

Incorrect:

        <?php if ( ! have_posts() ) : ?>
        <div id="post-0" class="post error404 not-found">
            <h1 class="entry-title">Not Found</h1>
            <div class="entry-content">
            <p>Apologies, but no results were found.</p>
<?php get_search_form(); ?>
            </div>
        </div>
<?php endif; ?>