• ルール
  • ユーティリティクラス
    • ユーティリティクラスはどこで定義されていますか？
    • 新しいユーティリティ・クラスはどこに置くべきですか？
    • いつコンポーネントクラスを作成すべきですか？
    • ユーティリティ・ミキシン
  • 命名
  • js- プレフィックスを持つセレクタ
  • 変数
  • extend アットルールの使用
• リンティング

SCSSスタイルガイド

このスタイル・ガイドは、SCSSのベスト・プラクティスを推奨し、エンドユーザーにとって読みやすく、メンテナーしやすく、パフォーマンスの高いスタイルにするためのものです。

ルール

私たちのCSSは、現行のアプローチとレガシーなアプローチが混在しています。つまり、このガイドに忠実に従うことが難しい場合があるということです。例外に遭遇する可能性が高く、大きな努力をしなければガイドに従うことが難しい、あるいは不可能な場合があるということです。そのような場合、あなたはレビュアーやメンテナーと協力して、この規則に当てはまらないアプローチを特定するかもしれません。このようなケースはなるべく避けてください。

ユーティリティクラス

サイトが大きくなるにつれてCSSが増えるのを抑えるために、新しいCSSを追加するよりもユーティリティ・クラスを使用することをお勧めします。複雑なケースでは、コンポーネントクラスを追加することでCSSにアドレスができます。

ユーティリティクラスはどこで定義されていますか？

GitLab UI で定義されているユーティリティクラスを優先的に使用してください。

クラスの簡単なリストは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から削除するためのフォローアップイシューを開くべきです。

いつコンポーネントクラスを作成すべきですか？

私たちは「ユーティリティ・ファースト」のアプローチを推奨します。

1. ユーティリティ・クラスから始めましょう。
2. ユーティリティクラスをコンポーネントクラスにComposerすることで、コードの重複がなくなり、明確な責任をカプセル化できるのであれば、そうしてください。

これは、コンポーネントクラスの有機的な成長を促し、単発の再利用不可能なクラスの作成を防ぎます。また、「ユーティリティ・ファースト」から生まれるクラスは、ドメイン中心（たとえば、.security-report-widget 、.commit-header-icon）ではなく、デザイン中心（たとえば、.button 、.alert 、.card ）になる傾向があります。

インスピレーション

• https://tailwindcss.com/docs/utility-first
• https://tailwindcss.com/docs/extracting-components

ユーティリティ・ミキシン

GitLab UIはユーティリティクラスに加え、ユーティリティクラスにちなんだ名前のユーティリティミキシンを提供します。

例えば、ユーティリティクラス.gl-mt-3 には対応する mixingl-mt-3 があります。SCSSファイルでの使い方は以下の通りです：

.my-class {
  @include gl-mt-3;
}

これらのミキシンは、コード中の_マジックバリューを_置き換えるために使用します。たとえば、margin-top: 8px は@include gl-mt-3 mixin で置き換えるのに適した候補です。

定義済みの CSS キーワードにユーティリティ mixin を使うことは避けてください。たとえば、@include gl-display-flex よりもdisplay: flex の方がよいでしょう。ユーティリティ mixin は、デザインシステムをカプセル化するのに特に役立ちますが、単純なプロパティをカプセル化する必要はありません。

// Bad
.my-class {
  @include gl-display-flex;
}

// Good
.my-class {
  display: flex;
}

// Good
.my-class {
  @include gl-mt-3;
}

命名

ファイル名はsnake_case.

CSS クラスは、snake_case やcamelCase ではなく、lowercase-hyphenated 形式を使用してください。

// Bad
.class_name {
  color: #fff;
}

// Bad
.className {
  color: #fff;
}

// Good
.class-name {
  color: #fff;
}

タグ名セレクタの代わりにクラス名を使うべきです。タグ名セレクタの使用は、階層内の意図しない要素に影響を与える可能性があるため推奨されません。

// Bad
ul {
  color: #fff;
}

// Good
.class-name {
  color: #fff;
}

// Best
// prefer an existing utility class over adding existing styles

また、IDよりもクラス名の方が望ましいです。IDを使う規則は再利用できません。

// Bad
#my-element {
  padding: 0;
}

// Good
.my-element {
  padding: 0;
}

js- プレフィックスを持つセレクタ

js- をプレフィックスとするセレクタは、 スタイリング目的で使用しないでください。これらのセレクタは JavaScript でのみ使用することを意図しており、 スタイリングを崩すことなく削除や名前の変更ができるようになっています。

変数

色やサイズの新しい変数を追加する前に、保証してください：

• 既存の変数がないことを保証してください。
• 代わりに使える似たようなものはありません

extend アットルールの使用

extend アットルールの使用はメモリリークのため禁止されており、ルールは本来の動作をしません。代わりに mixin を使用してください：

// Bad
.gl-pt-3 {
  padding-top: 12px;
}

.my-element {
  @extend .gl-pt-3;
}

// compiles to
.gl-pt-3, .my-element {
  padding-top: 12px;
}

// Good
@mixin gl-pt-3 {
  padding-top: 12px;
}

.my-element {
  @include gl-pt-3;
}

// compiles to
.my-element {
  padding-top: 12px;
}

リンティング

stylelintを使ってスタイル・ガイドの適合性をチェックします。これは.stylelintrc SCSS設定の.stylelintrcルール.stylelintrc セットとルールを .stylelintrc使用します.stylelintrc 。 .stylelintrc

変更によって警告が発生したかどうかをチェックするには、GitLabディレクトリでyarn lint:stylelint 。StylelintはGitLab CI/CDでも実行され、警告をキャッチします。

Rake タスクがよくわからない警告を出す場合は、SCSS Lint のドキュメントにルールの完全なリストがあります。