SCSSスタイルガイド
このスタイル・ガイドでは、SCSSのベスト・プラクティスを推奨し、スタイルを読みやすく、メンテナーしやすく、エンドユーザーにとってパフォーマンスの高いものにします。
ルール
私たちのCSSは、最新のアプローチとレガシーなアプローチが混在しています。 つまり、このガイドに忠実に従うことが難しい場合があるということです。また、このガイドに従うことが、多大な努力を払わなければ難しい、あるいは不可能な例外に必ず遭遇するということです。 そのような場合、レビュアーやメンテナーと協力して、このルールに当てはまらないアプローチを特定するかもしれません。 このようなケースを制限するように努めてください。
ユーティリティクラス
サイトが大きくなるにつれてCSSが増えるのを抑えるために、新しいCSSを追加するよりもユーティリティ・クラスを使用することをお勧めします。 複雑なケースでは、CSSはコンポーネント・クラスを追加することでアドレスできます。
ユーティリティ・クラスはどこで定義されていますか?
GitLabUIで定義されているユーティリティクラスを使うことをお勧めします。 クラスの簡単なリストはUnpkgでも見ることができます。
utilities.scss
およびcommon.scss
のクラスは](https://gitlab.com/gitlab-org/gitlab/blob/master/app/assets/stylesheets/framework/common.scss) [非推奨となります。common.scss
のクラスで、設計システム以外の値を使用するものは避けるべきです。
Bootstrapのユーティリティ・クラスは避けてください。
新しいユーティリティ・クラスはどこに置くべきですか?
もし必要なクラスがGitLab UIに追加されていなければ、あなたが追加してください!ユーティリティファイルに書かれている命名パターンに従い、詳細、特にレスポンシブやステートフルなルールの追加についてはGitLab UIのCSSドキュメントを参照してください。
GitLab UIのアップデートを待つことができない場合(通常1日)、GitLab UIで文書化されているのと同じ命名規則に従ってutilities.scss
。クラスをGitLab UIにバックポートし、GitLabから削除するためのフォローアップイシューを開く必要があります。
いつコンポーネント・クラスを作成すべきですか?
私たちは「ユーティリティ・ファースト」のアプローチを推奨しています。
- ユーティリティクラスから始めましょう。
- ユーティリティ・クラスをコンポーネント・クラスにComposerすることで、コードの重複がなくなり、明確な責任がカプセル化されるのであれば、そうしてください。
また、”ユーティリティ・ファースト “から生まれるクラスは、ドメイン中心(例:.security-report-widget
、.commit-header-icon
)ではなく、デザイン中心(例:.button
、.alert
、.card
)になる傾向があります。
ユーティリティ・ファースト」で作られたコンポーネント・クラスの例には、以下のようなものがあります:
インスピレーション:
ネーミング
ファイル名はsnake_case
.
CSSクラスは、snake_case
やcamelCase
ではなく、lowercase-hyphenated
の形式を使うべきです。
// Bad
.class_name {
color: #fff;
}
// Bad
.className {
color: #fff;
}
// Good
.class-name {
color: #fff;
}
タグ名セレクタの代わりにクラス名を使うべきです。 CSSではタグ名セレクタの使用は推奨されません。 なぜなら、タグ名セレクタは階層内の意図しない要素に影響を与える可能性があるからです。 また、タグ名セレクタは意味のある名前ではないので、コードに意味を持たせることはできません。
// Bad
ul {
color: #fff;
}
// Good
.class-name {
color: #fff;
}
フォーマット
中括弧の前には必ずスペースを入れ、中括弧は同じ行に入れ、各プロパティはそれぞれ独立した行にし、プロパティとその値の間にはスペースを入れます。
// Bad
.container-item {
width: 100px; height: 100px;
margin-top: 0;
}
// Bad
.container-item
{
width: 100px;
height: 100px;
margin-top: 0;
}
// Bad
.container-item{
width:100px;
height:100px;
margin-top:0;
}
// Good
.container-item {
width: 100px;
height: 100px;
margin-top: 0;
}
なお、1行のルールセットには例外がありますが、通常は推奨されません。
p { margin: 0; padding: 0; }
カラーズ
HEX(16進数)カラーは可能な限り省略形を使用し、文字と数字を区別するために小文字を使用する必要があります。例えば、#E3E3E3
vs.#e3e3e3
。
// Bad
p {
color: #ffffff;
}
// Bad
p {
color: #FFFFFF;
}
// Good
p {
color: #fff;
}
インデンテーション
字下げは、各字下げレベルに対して常に2つのスペースを使用します。
// Bad, four spaces
p {
color: #f00;
}
// Good
p {
color: #f00;
}
セミコロン
各プロパティの後には必ずセミコロンを入れてください。 スタイルシートがミニファイされると、セミコロンは自動的に削除されます。
// Bad
.container-item {
width: 100px;
height: 100px
}
// Good
.container-item {
width: 100px;
height: 100px;
}
速記
短縮形は、それをサポートしているプロパティに使用する必要があります。
// Bad
margin: 10px 15px 10px 15px;
padding: 10px 10px 10px 10px;
// Good
margin: 10px 15px;
padding: 10px;
ゼロ・ユニット
ゼロ値の長さ単位は不要で、含まない方が若干パフォーマンスが高くなります。
// Bad
.item-with-padding {
padding: 0px;
}
// Good
.item-with-padding {
padding: 0;
}
js-
接頭辞を持つセレクタ
js-
というプレフィックスを持つセレクタは、 スタイリング目的で使用しないでください。 これらのセレクタは、 スタイリングを崩すことなく削除や名前の変更ができるよう、 JavaScriptでのみ使用することを意図しています。
身分証明書
CSSでIDセレクタを使用しないでください。
// Bad
#my-element {
padding: 0;
}
// Good
.my-element {
padding: 0;
}
変数
色やサイズの新しい変数を追加する前に、保証してください:
- すでにありません
- 代わりに使える似たようなものはないですか?
リンティング
SCSS Lintを使ってスタイルガイドの適合性をチェックします。SCSS Lintは.scss-lint.yml
にあるルールセットを使います。
あなたの変更によって警告が発生するかどうかをチェックするには、GitLabディレクトリでrake
scss_lint
。 SCSS LintはGitLab CI/CDでも実行され、警告をキャッチします。
Rakeタスクがよくわからない警告を出す場合は、SCSS Lintのドキュメントにリンターの完全なリストがあります。
イシューの修正
コードベースの大部分をSCSSスタイルガイドに準拠させるために変更を自動化したい場合は、CSSCombを使うことができます。まずNodeと Npmをインストールし、npm install csscomb -g
、CSSCombをグローバル(システム全体)にインストールします。CSS/SCSSのイシューを自動的に修正するために、csscomb app/assets/stylesheets
、GitLabディレクトリで実行します。
これですべての問題が解決するわけではありませんが、大半は解決するはずです。
イシューの無視
行または行のセットをリンターに無視させたい場合は、// scss-lint:disable RuleName
(詳細)を使用します:
// This lint rule is disabled because it is supported only in Chrome/Safari
// scss-lint:disable PropertySpelling
body {
text-decoration-skip: ink;
}
// scss-lint:enable PropertySpelling
disable
ルールの上の行にコメントが追加されていることを確認してください。そうしないと、リンターは警告を投げます。DisableLinterReason
は、スタイルガイドが無視されていないことを確認し、このインスタンスでスタイルガイドが無視されている理由を他の人に伝えるために有効になっています。