はじめに
社内で使いたいと思っているフロントエンドのコーディングガイドラインの草案を載せてみました。
「ここはこうあるべきじゃない？」などいろんな人からツッコミもらえたら嬉しいです。
アウトラインはこんな感じです。
フロントエンドコーディングガイドライン
基本仕様
- HTML5(Last Call WD)
- CSS3/CSS2.1
- Javascript
HTML
基本ルール
- 要素の終了タグは省略しない
- 空要素のスラッシュ付けない
- および終了タグが不要なタグ(ex.
inputmetaimg)の末尾スラッシュは付けない - コーディングフォーマットは Google HTML/CSS Style Guide に従う。
Google HTML/CSS Style Guide
http://google-styleguide.googlecode.com/svn/trunk/htmlcssguide.xml
Doctype宣言
<!DOCTYPE html>
エンコード/改行コード
UTF-8、LF を使用します
大文字/小文字
小文字のみを使用する
ただしalt属性など値が文字列の場合は使用可能
- <A HREF="/">Home</A>
+ <a href="/">Home</a>
スペース
必要のないスペースは入れない
- <p >text</p>
+ <p>text</p>
コメント
HTML/PHPコード中のコメントは <!-- comment --> 書式で書きます。
重要なラッパーなどの閉じタグに <!-- /wrapper --> などと入れることが多いですが、
昨今のエディタでは、開始/終了タグの対応を視覚的なハイライトで得ることができるため、
必要最小限にすることを推奨します。
また <!-- の後、および -->の前には半角スペースを入れることを推奨します。
<!-- .global-footer -->
<footer class="global-footer">
<div class="container">
:
<!--の直後に#を記述しないでください。SSIのコマンドと誤認されてしまうことがあります。
- <!--#header-->
+ <!-- #header -->
インデント
インデントは使用しません。
共通ソースコードのインクルード化やphpテンプレート化する際に整合性が保てなくなるためです。
ファイルパスの記述
同一サイト内のリソース
ドキュメントルートからの相対パスで記述する
- <a href="img/common/hd_title.png">
- <a href="../img/common/hd_title.png">
- <a href="http://mysite.com/img/common/hd_title.png">
+ <a href="/img/common/hd_title.png">
外部ドメインのリソース
プロトコルを省略した絶対パスで記述する
+ <a href="//othersite.com/img/common/hoge.png">
ディレクトリとファイル
ディレクトリの命名規則
| No | ディレクトリ名 | 配置ファイル |
|---|---|---|
| 1 | css | cssファイル |
| 2 | js | Javascriptファイル |
| 3 | img | png, jpg, gif, svg |
| 4 | data | xml, jsonファイル |
※ 詳しくはディレクトリ構成図を参照
ファイルの命名規則
- ファイルはすべてアルファベットの小文字と数字、アンダースコア(_)、ハイフン(-)で構成する
- ドット(.)は拡張子以外では原則使用しない
- 名前に複数の単語を含む場合はハイフン(-)で連結する
※ 各コンテンツの具体的なディレクトリ名はURL設計書に定義されている語に従う
画像
ファイルの命名規則
(接頭辞)_(名前)_(番号/ステート/色).拡張子
- 語をつなぐためのハイフン(-)は使用しない
- 節同士（接尾辞、接頭辞をつける場合）はアンダースコア(_)で連結する
- ボタンなどのステートを表す場合はアンダースコア(_)+状態名を付属する
- 明示的に順番が必要なものはアンダースコア(_)+番号(ゼロ埋めはしない)をつけることが可能(a,bなど数字以外の序列表現は避ける)
- 色のバリエーションがあるものもアンダースコア(_)で接尾する
- キャメルタイプは使用しない
接頭詞
画像の用途/分類を明示する下記接頭詞をつける
| 接頭詞 | 意味 |
|---|---|
| icon | アイコン |
| btn | ボタン |
| bg | 背景 |
| img | 図版・写真 |
接尾詞
画像の状態を明示する下記接尾詞をつける
| 接尾詞 | 意味 |
|---|---|
| focus | フォーカス(マウスオーバー) |
| active | アクティブ(タップダウン) |
| disabled | 非活性 |
| open | 開いている |
| checked | チェックされている |
| selected | 選択されている |
| progress | 途中 |
| error | エラー |
CSS/Sass
SCSSのファイル構成
SMACSSのように、Base, Layout, Module, State, Theme のレイヤーに分けて各SCSSを管理、更新する。(Stateレイヤーについては後述)
├ frontend_src/
│ └ scss/
│ ├ lib/ //【Lib 層】
│ │ ├ _variables.scss // SCSS全体で使用する定数など定義
│ │ ├ _mixins.scss // SCSS全体で使用する各mixinのimporter
│ │ └ mixins/ // SCSS全体で使用する各mixin
│ │
│ ├ shared/
│ │ ├ base/ //【Base 層】: サニタイズ, 印刷スタイル
│ │ ├ layout/ //【Layout 層】: 基本ゾーニング, 共通テンプレート
│ │ ├ develop/ //【Develop層】: 開発中のみ使うパーシャルを入れる
│ │ ├ module/ //【Module 層】: 書式, ボタンなど汎用パーツ
│ │ ├ base.scss // Base,Layout,Develop層のimporter
│ │ └ module.scss // Module層のimporter
│ │
│ └ {category}/ //【Theme 層】: 固有スタイル
│ ├ {page}.scss
│ └ {page}.scss
│
└ public/ // 公開領域(ドキュメントルート)
└ css/ // コンパイルされたCSS
├ shared/
├ {category}/
├ {category}/
：
SCSSのimporterとpartialの定義
-
module.scssのように他のSCSSをimportして同ファイル名でCSS出力されるものをScssの「importer(母体)」と呼ぶ - 一方で、母体から
@importされる「_」から始まるファイル名のものをscssの「Partial(パーシャル)」と呼ぶ
母体となるSCSSファイルでは、かならず文頭でライブラリ層のvariableとmixinをimportし、プロジェクト全体で共通の定数やmixinが呼び出せるようにする。
@charset "UTF-8";
@import "../lib/variables";
@import "../lib/mixins";
// ---------------------------------------------------
// your code here
この文頭を定型化するため、原則的にSCSS母体になるSCSSファイルは、同じ階層に置く。
scss/
lib/ // 各SCSS母体から lib への相対パスが等しい
shared/
base.scss
module.scss
category/
page.scss
一方、パーシャルたちはこのような必須import等を必要としない。
// ---------------------------------------------------
// your code here
SCSSの基本文法
基本的な記述ルールについては Google HTML/CSS Style Guide に準拠する
http://google-styleguide.googlecode.com/svn/trunk/htmlcssguide.xml#CSS_Style_Rules
h1,
h2, // カンマ区切りで複数セレクタを指定する場合は改行
.title { // セレクタと開始ブラケットの間は半角スペースを開ける
font-weight: bold; // インデントは2スペースとし、Tab文字は仕様しない
color: #999; // プロパティの後のコロンと、値の間は半角スペースをあける
} // 閉じブラケットは改行する
// 宣言同士は１行アキを入れる
h3 {
color: #666; // 省略可能であれば色値は3ケタに
border: 1px solid dotted; // 可能であればショートハンドで書く
}
- h1,h2,.title{
- font-weight:bold;}
ただしコードの可読性を高め、ルールのメンテナンス性を保つ必要のある場合は例外とするが、積極的に使う必要はない。
&.home { background-image: url(/img/common/img_home.png); }
&.products { background-image: url(/img/common/img_products.png); }
&.history { background-image: url(/img/common/img_history.png); }
&.support { background-image: url(/img/common/img_support.png); }
&.about { background-image: url(/img/common/img_about.png); }
SCSSファイルでのコメント
- Sassのコンパイルでは
//コメントは削除されるが、/**/コメントはCSSに出力されてしまう。したがって、原則は//コメントのみを使用する。 - ただし、デバッグのしやすさの観点で、ルールレイヤーの途切れ目などに必要最小限で
/**/コメントを残すことは可能とする。
SCSSファイルの命名規則
モジュールファイル
- 名前に複数の単語を含む場合はハイフンで連結する
- 接尾詞、接頭詞をつける場合も基本はハイフンで連結する
class名の命名規則
IDではなくClassで
コンテンツエリア内では使うパーツにはIDは原則使わず、classで定義する(ぺージで１回しか使用しないものもclassとする)
- #list-article
+ .list-article
連結子は単数ハイフン(-)のみ
キャメルタイプやアンダースコアは使用しない
- .listArticle
- .list_Article
+ .list-article
BEM記法のようなダブルハイフンやダブルアンダースコアは使用しない
部分的なオーバーライドやスタイリングをするためのOOCSSクラスを用いることは可能
- .list--Article__compact
+ .list-article .compact
複数英単語でもClassとして１つの節であれば１語にする
下記例の場合、typefaceとして一つのまとまり(節)になるので１語にする
- type-face-list
+ typeface-list
意味が通らなくなる略語は使用しない
略語は個人差が出て表記ゆれになってしまう。文字列の短さよりも意味の明瞭さを重視する
- .atcl-ttl
- .artcl-ti
+ .article-title
事業や製品名、カテゴリに紐づくclass名をつけるときはURL設計の語彙にしたがう
例：組版製品という意味ですでにディレクトリ名でtypesettingという語が使われているため、新しい語を用いるべきではない
- .composition
+ .typesetting
状態や特性によるスタイルをオーバーライドする場合は、下記classを掛け合わせる
SMACSS命名規則にあるような、is-等の接頭辞は使用せず、
.active // 選択されている, 消えているものが表示されている状態
.focus // フォーカスされている状態
.disabled // 非活性になっている状態
.touched // タップ中
.compact // 小さい版
.open // 開いている
:
※英語として副詞(形容詞)であればそのままの語を用い(例：open)、他動詞であれば受動態にする(例：touched)にする。またhtml要素の属性名が存在するものは、なるべく同じものを用いる(例：disabledselectedchecked)
ただしこれらは元のClassと掛けあわせて使用する前提で汎用的な語にしていますので、Class単独でスタイル定義をしないようにしてください。
(したがってこの思想ではSMACSSにあるStateレイヤーを必要としない)
- .touched { // そのものに指定すると影響範囲が大きすぎる
- opacity: .5;
- }
+ .article-title { // かならず掛け合わせで使う
+ &.touched {
+ opacity: .5;
+ }
+ }