CSS コーディング規約

他のコーディング規約同様「WordPress CSS コーディング規約」も WordPress オープンソースプロジェクトおよびコミュニティでのコラボレーションやレビューのベースラインであり、その適用範囲はコアコードからテーマ、プラグインに至ります。プロジェクト内のすべてのファイルが一人のプログラマーが開発したかのように見える必要があります。読みやすく、意味のある、一貫した美しいコードを目標にしてください。

コアのスタイルシートの中にはコーディングスタイルに合致しないものがいくつかあります。WordPress ではこれらに対処するため、CSS コーディング規約に従ったパッチやコミットになるよう努めています。なお、本ガイドの適用範囲を超える詳細情報、および UI やフロントエンド開発への貢献については、別のガイドラインを作成予定です。

スタイルシートの構造化については多くの方法があります。このうちコアの CSS では読みやすさが何よりも重要です。読みやすい CSS であれば、他のコントリビューターもドキュメントの流れをクリアに理解できます。

• インデントはタブです。各プロパティのインデントにはスペースでなく、タブを使用してください。
• セクションとセクションの間には空白行を2行挿入してください。セクション内のブロック間には空白行を1行挿入してください。
• セレクタは1行に1つ書き、行末はコンマ、または開始の波括弧「{」で終えてください。プロパティと値のセットも1行ずつ書き、1つのタブでインデントして始め、セミコロンで終えます。終了の波括弧「}」は改行した新しい行に、開始の波括弧と同じインデントレベルで書きます。

正しい:

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

間違い:

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

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

セレクタの詳細度には、責任が伴います。スコープの広いセレクタを使用すれば効率的ですが、テストが十分でないと逆の結果になるでしょう。局所的なセレクタを使用すると時間の節約にはなりますが、すぐに混乱したスタイルシートが生まれるでしょう。最大限の判断力を駆使し、スタイル全体への貢献と DOM のレイアウトとの間で正しいバランスを取ったセレクタを作成してください。

• セレクタの命名では「WordPress PHP コーディング規約」のファイル名の命名規則と同じく、小文字の英単語をハイフンでつないでください。キャメルケースやアンダースコアは禁止です。
• 対象の要素を表した、人間が読んで分かるセレクタ名を使用してください。
• 属性セレクタは、値の前後にダブルクオートを使用してください。
• 過剰に修飾したセレクタを使用しないでください。例えば「div.container」は単純に「.container」と書けます。

正しい:

#comment-form {
    margin: 1em 0;
}

input[type="text"] {
    line-height: 1.1;
}

間違い:

#commentForm { /* キャメルケースは使わない */
    margin: 0;
}
 
#comment_form { /* アンダースコアは使わない */
    margin: 0;
}
 
div#comment_form { /* 過剰に修飾しない */
    margin: 0;
}
 
#c1-xr { /* 「c1-xr」って何?! もっとよい名前があるはず */
    margin: 0;
}
 
input[type=text] { /* [type="text"] とすべき */
    line-height: 110% /* 二重に間違い */
}

セレクタと同様プロパティも細かすぎるとデザインの柔軟性を損ないます。少ないに越したことはありません。またスタイルを繰り返したり、固定のサイズを指定しないでください。相対値で指定する、流動的なソリューションを推奨します。

• プロパティの後にはコロンとスペースを置いてください。
• すべてのプロパティと値は小文字です。例外はフォント名とベンダー固有のプロパティです。
• 色は16進コード、opacity が必要であれば rgba() を使用してください。RGB フォーマット、大文字は避けてください。可能であれば値は縮めてください。例えば #FFFFFF ではなく #fff。
• スタイルを上書きする場合を除き、可能な限りショートハンド (短縮形) を使用してください。「background」「border」「font」「list-style」「margin」「padding」。ショートハンドの詳細については「CSS Shorthand」を参照してください。

正しい:

#selector-1 {
    background: #fff;
    display: block;
    margin: 0;
    margin-left: 20px;
}

間違い:

#selector-1 {
    background:#FFFFFF;
    display: BLOCK;
    margin-left: 20PX;
    margin: 0;
}

“プロパティは、特に数が多い場合、グループにしてください。” — Nacin

最低限、何らかの意味のある方法を使用してグループ化してください。ランダムな順番はカオスであり、詩的ではありません。WordPress コアの中では、論理的にグループ化した順序を採用しています。プロパティは意味でグループ化され、グループ内で順番に並べられます。グループ内のプロパティもセクション間で流れができるよう並べられます。たとえば background は color の直前です。順序の基準は以下のとおりです。

• 画面
• 位置
• ボックスモデル
• 色とフォント
• その他

コア内部で未使用の、例えば CSS3 animation などは上の順序に規定されていませんが、論理的な方法でどこかには挿入できるはずです。CSS が進化するように、この規約も進化します。

「margin」 などの関連するプロパティ、対応する値の順序についてはTop/Right/Bottom/Left の順序 (TRBL「トラブル」と覚える) を使用してください。「border-radius-–」などの四隅の指定の順番は「top-left」「top-right」「bottom-right」「bottom-left」です。これはショートハンドの指定順から来ています。

例:

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

別の方法は Automattic や WordPress.com テーマチームを含む多くのグループで採用されている、例外のあるなしに関係なくアルファベット順にプロパティを並べる方法です。

例:

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

2014年2月13日、27174 後に更新。

ブラウザー固有のベンダープレフィックスを簡単に管理するプレコミットツールとして WordPress では Autoprefixer を使用します。この結果、本節の大部分の議論は過去のものとなりました。Grunt を使わずに自力で出力と合わせる場合、ベンダープレフィックスは長いもの (「-webkit-」) から短いもの (プレフィックスなし) の順番で配置してください。その他は、規約の他の部分に準拠します。

.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;
}

プロパティへの値の入力には多くの方法があります。一貫性を高く保つため次のガイドに従ってください。

• 値の前、コロンの後にはスペースを置きます。
• 括弧にスペースを含めません。
• 常にセミコロンで終えます。
• シングルクオートでなくダブルクオートを、フォント名にスペースが含まれる場合など必要な場合のみ使用します。
• フォントのウエイトは数値を使用して定義します (例: 「normal」でなく「400」を、「bold」でなく「700」を使用します)。
• 「0」に単位を付けません。transition-duration など必要な場合のみ付けます。
• 特定のピクセル値が必要でなければ、行の高さにも単位は付けません。これには単なるスタイルのルールを越えた意味があります。詳細: http://meyerweb.com/eric/thoughts/2006/02/08/unitless-line-heights/
• rgba() の中も含め、小数値には先頭の「0」を付けます。
• 1つのプロパティに複数の値をコンマ区切りで指定する場合、rgba() の中も含め、スペースまたは改行を挿入します。ただし box-shadow や text-shadow のショートハンドプロパティのような非常に長い複数パーツについては、改行を使用します。2番目以降の値は、それぞれ前の値から改行し、セレクタおよび続くスペースの分をインデントし、前の値と同じレベルにします。

正しい:

.class { /* クオートの正しい用法 */
    background-image: url(images/bg.png);
    font-family: "Helvetica Neue", sans-serif;
    font-weight: 700;
}

.class { /* 値「0」の正しい用法 */
    font-family: Georgia, serif;
    line-height: 1.4;
    text-shadow:
        0 -1px 0 rgba(0, 0, 0, 0.5),
        0 1px 0 #fff;
}

.class { /* 複数パーツの短い形式、長い形式の正しい用法 */
    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);
}

間違い:

.class { /* スペースとセミコロンを忘れない */
    background:#fff
}

.class { /* 値「0」に単位を付けない */
    margin: 0px 0px 20px 0px;
}

.class {
    font-family: Times New Roman, serif; /* 必要であればフォント名はクォートで囲む */
    font-weight: bold; /* フォントウェイト名は避ける */
    line-height: 1.4em; /* line-height に単位を付けない */
}

.class { /* 複数パーツの誤った用法 */
    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);
}

メディアクエリを使用すると異なる画面サイズごとに DOM を分解できます。メディアクエリを追加する場合は対象のブレークポイントの前後で正しく動作することをテスト指定ください。

• 一般にメディアごとにメディアクエリをグループ化し、スタイルシート末尾に配置することが推奨されます。
  • 例外はコアの wp-admin.css ファイルで、ファイルサイズが大きく、各セクションは実質的に自身のスタイルシートを表しているためメディアクエリは適切なセクションの末尾に追加されています。
• メディアクエリのルールセットは1レベル分インデントします。

例:

@media all and (max-width: 699px) and (min-width: 520px) {
        /* あなたのセレクタ */
}

• コメントを書いてください。大量に書いてください。ファイルサイズが気になるならミニファイと SCRIPT_DEBUG 定数を使用します。長いコメントは80文字で改行します。
• 巨大なスタイルシート、特に複数のセクションがあるものには目次をつけます。見出し番号 (1.0、1.1、2.0等) を付けると検索しやすくなります。
• コメントはできる限り PHPDoc 風にフォーマットします。CSSDoc 標準はまだ広く受け入れられていません。ただし、いずれは浸透するかもしれません。セクション、サブセクションのヘッダーは前後に空白行を挿入します。インラインコメントは対象の項目のすぐ上の行に書き、空白行を挟みません。

セクションおよびサブセクション:

/**
 * #.# セクションのタイトル
 *
 * セクションの説明。メディアクエリを持つかどうかなど
 */

.selector {
    float: left;
}

インライン:

/* セレクタのコメントをここに書く */
.another-selector {
    position: absolute;
    top: 0 !important; /* なぜ !important なのか説明する */
}

スタイルシートは長く、複雑になりがちで、長くなればなるほど、冗長になる可能性が高くなります。以下のベストプラクティスに従うことで、本質を外さず、柔軟に CSS を管理できます。

• 問題を修正する場合、追加する前に削除することを考えます。
• マジックナンバーは不幸です。マジックナンバーとはその場限りの修正用の数字のことです。例: .box { margin-top: 37px }
• DOM は時間と共に変わるため、親から「たどって探す」のではなく使用する要素を設定します。例: セレクタが親にある場合、.highlight a ではなく、要素の .highlight を使用します
• height プロパティをいつ使用すべきかを熟知してください。すなわち画像のような外部の要素を含める場合に使用します。それ以外であれば line-height の方がより柔軟です。
• デフォルトのプロパティと値のペアを再宣言しないでください。たとえばブロックレベル要素の display: block;。

WP Admin CSS Audit を確認してください。これは WP Admin CSS コードの健康状態を文書化するために生成されたレポートです。詳細についてはリポジトリの README を参照してください。

• Principles of writing consistent, idiomatic CSS: https://github.com/necolas/idiomatic-css

原文 / 日本語訳

最終更新日: 2021年12月31日