Airbnb CSS / Sass 指南

用更合理的方式寫 CSS 和 Sass

術語

規則宣告

我們把包含一組屬性的一個（或多個組合的）選擇器稱之為 “規則宣告”。舉個例子：

.listing {
  font-size: 18px;
  line-height: 1.2;
}

選擇器

在規則宣告中，“選擇器” 決定了 DOM 樹中的哪些元素將被定義的屬性所修飾。選擇器可以配對 HTML 元素，也可以配對一个元素的類別名稱、ID, 或者元素擁有的屬性。以下是選擇器的例子：

.my-element-class {
  /* ... */
}

[aria-hidden] {
  /* ... */
}

屬性

最後，屬性決定了規則宣告裡面被選擇的元素將會得到何種樣式。屬性以 key-value pairs 形式存在，一個規則宣告可以包含一或多個屬性宣告。屬性宣告如下：

/* some selector */ {
  background: #f1f1f1;
  color: #333;
}

CSS

格式

使用 soft tabs (兩個空格）作為縮排。
類別名稱建議使用 dashes 代替 camelCasing。如果你使用 BEM，也可以使用底線或 PascalCasing（參考下面的 OOCSS 和 BEM）。
不要使用 ID 選擇器。
在一個規則宣告中，若同時使用多個選擇器時，讓每個選擇器各佔一行。
在規則宣告的左大括弧 { 前加上一個空格。
在屬性設定的冒號 : 後面加上一個空格，前面不要加空格。
讓規則宣告的結束右大括弧 } 獨自一行。
每個規則宣告之間用空白行隔開。

Bad

.avatar{
    border-radius:50%;
    border:2px solid white; }
.no, .nope, .not_good {
    // ...
}
#lol-no {
  // ...
}

Good

.avatar {
  border-radius: 50%;
  border: 2px solid white;
}

.one,
.selector,
.per-line {
  // ...
}

註解

建議使用單行註解 (在 Sass 中是 //) 代替區塊註解。
建議讓註解獨自一行，避免行末註解。
為沒有文件紀錄的程式碼寫上詳細註解，比如：
- z-index 的使用情境
- 兼容性處理或是針對特定瀏覽器的特殊寫法

OOCSS 和 BEM

由於以下原因，我們鼓勵使用 OOCSS 和 BEM 的某些組合：

可使 CSS 與 HTML 之間的關係更清晰且嚴謹。
可幫助我們創建出可重用、可重組的元件。
可以減少巢狀宣告，並降低特定性。
可以幫助我們創建出可擴展的樣式。

OOCSS，也就是 “Object Oriented CSS（物件導向的CSS）”，是一種寫 CSS 的方法，中心哲學就是鼓勵你把樣式表看成“物件”的集合：利用擁有可重用、可重組特性的程式碼，使你可以在整個網站中多次使用。

参考資料：

Nicole Sullivan 的 OOCSS wiki
Smashing Magazine 的 Introduction to OOCSS

BEM，也就是 “Block-Element-Modifier”，是一種用於 HTML 和 CSS 類別名稱的_命名约定_。BEM 最初由 Yandex 所提出，他們擁有大量的程式庫以及延展性。可以作為一套遵循 OOCSS 的實作參考規範。

CSS Trick 的 BEM 101
Harry Roberts 的 introduction to BEM

建議使用搭配 PascalCased "區塊"的變形 BEM，在與元件結合操作時特別適用 (e.g. React)。底線與破折號依然用在修飾符與子元件。

範例

<article class="listing-card listing-card--featured">

  <h1 class="listing-card__title">Adorable 2BR in the sunny Mission</h1>

  <div class="listing-card__content">
    <p>Vestibulum id ligula porta felis euismod semper.</p>
  </div>

</article>

.listing-card { }
.listing-card--featured { }
.listing-card__title { }
.listing-card__content { }

.listing-card 是一個區塊（block），代表高層次的元件。
.listing-card__title 是一個元素（element），它屬於 .listing-card 的一部份，因此區塊是由元素所組成。
.listing-card--featured 是一個修飾符（modifier），表示這個區塊與 .listing-card 有不同的狀態或變化。

ID 選擇器

雖然在 CSS 中，你可以透過 ID 選擇元素，但這種作法應該列為 anti-pattern。ID 選擇器為你的規則宣告帶來了不必要的高優先權級，而且 ID 選擇器不可重用。

想要了解更多關於這個主題的內容，請參考 CSS Wizardry 的文章，內有關於如何處理優先權級的文章。

JavaScript 掛鉤

避免在 CSS 和 Javascript 中綁定相同的類別。否則開發者在進行重構時容易出現問題，輕則浪費時間在相互對照尋找要修改的類別名稱，嚴重則因為害怕破壞功能而不敢進行更動。

我們推薦在創建用於 JavaScript 的類別名稱時，添加 .js- 前綴：

<button class="btn btn-primary js-request-to-book">Request to Book</button>

邊框

在定義無邊框樣式時，使用 0 代替 none。

Bad

.foo {
  border: none;
}

Good

.foo {
  border: 0;
}

Sass

語法

使用 .scss 的語法，不使用 .sass 原本的語法。
CSS 和 @include 宣告依照以下邏輯排序（詳見下文）

屬性宣告的排序

屬性宣告

列出除了 @include 與巢狀選擇器之外的所有屬性宣告。
```
.btn-green {
  background: green;
  font-weight: bold;
  // ...
}
```

@include 宣告

接著再放入 @include，這樣可以提高整個選擇器的可讀性。

.btn-green {
  background: green;
  font-weight: bold;
  @include transition(background 0.5s ease);
  // ...
}

巢狀選擇器

_如果有必要_用到巢狀選擇器，把它們放到最後。此外，規則宣告與巢狀選擇器之間要加上空白行。而巢狀選擇器中的內容也要遵循上述指引。
```
.btn {
  background: green;
  font-weight: bold;
  @include transition(background 0.5s ease);

  .icon {
    margin-right: 10px;
  }
}
```

變數

變數名稱建議使用破折號（例如 $my-variable）代替 camelCased 和 snake_cased 風格。可以在變數名稱之前添加底線前綴符，用以代表此變數只使用於當前文件。（例如 $_my-variable）。

Mixins

Mixins 可幫助你的代碼遵循 DRY 原則（Don't Repeat Yourself）、增加清晰度或抽象畫複雜度。這與使用良好命名的函數有異曲同工之妙。Mixins 可以不接收參數，但要注意的是，如果你不壓縮 payload（e.g. gzip），可能會導致最終的樣式表包含不必要的重複程式碼。

擴展指令

應避免使用 @extend 指令，因為他並不直觀，且具有潛在風險，特別是用在巢狀選擇器時。即使是針對在最上層的佔位符選擇器使用擴展，如果選擇器的順序最終會改變，也可能會導致問題。（比如，擴展的選擇器存在於別份文件，而其加載順序發生變化）。使用 @extend 所獲得的大部分優化效果，透過 gzip 縮就已經幫你做到了，而你可以再透過 mixin 來讓你的樣式表更符合 DRY 原則。

巢狀選擇器

請不要讓巢狀選擇器超過三層！

.page-container {
  .content {
    .profile {
      // STOP!
    }
  }
}

當上述情況發生時，你也許是這樣寫 CSS 的：

與 HTML 強耦合的（也是脆弱）—或者—
過於針對與具體（強大）—或者—
沒有重複使用程式碼

再說一遍: 永遠不要巢狀 ID 選擇器！

如果你真的必須使用 ID 選擇器（你真的不應該...），那他們也不該是巢狀的。如果你發現你正在這樣做，那你可能需要重新檢查你的 markup，或是說明這樣做的原因。如果你想要寫出良好風格的 HTML 和 CSS，你絕對不應該這麼做。

翻譯

這份 style guide 也被翻譯成以下語言:

Chinese (Traditional): ArvinH/css-style-guide
Chinese (Simplified): Zhangjd/css-style-guide
Japanese: nao215/css-style-guide
Korean: CodeMakeBros/css-style-guide
Portuguese: felipevolpatto/css-style-guide
Russian: Nekorsis/css-style-guide
Spanish: ismamz/guia-de-estilo-css

ArvinH / css-style-guide