A mostly reasonable approach to CSS and Sass

1. Terminology - Rule Declaration - Selectors - Properties
2. CSS - Formatting - Comments - OOCSS and BEM - ID Selectors - JavaScript hooks - Border
3. Sass - Syntax - Ordering - Variables - Mixins - Extend directive - Nested selectors
4. Translation

A “rule declaration” is the name given to a selector (or a group of selectors) with an accompanying group of properties. Here's an example:

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

In a rule declaration, “selectors” are the bits that determine which elements in the DOM tree will be styled by the defined properties. Selectors can match HTML elements, as well as an element's class, ID, or any of its attributes. Here are some examples of selectors:

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

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

Finally, properties are what give the selected elements of a rule declaration their style. Properties are key-value pairs, and a rule declaration can contain one or more property declarations. Property declarations look like this:

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

• Use soft tabs (2 spaces) for indentation
• Prefer dashes over camelCasing in class names.
  • Underscores and PascalCasing are okay if you are using BEM (see OOCSS and BEM below).
• Do not use ID selectors
• When using multiple selectors in a rule declaration, give each selector its own line.
• Put a space before the opening brace { in rule declarations
• In properties, put a space after, but not before, the : character.
• Put closing braces } of rule declarations on a new line
• Put blank lines between rule declarations

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 {
  // ...
}

• Prefer line comments (// in Sass-land) to block comments.
• Prefer comments on their own line. Avoid end-of-line comments.
• Write detailed comments for code that isn't self-documenting:
  • Uses of z-index
  • Compatibility or browser-specific hacks

We encourage some combination of OOCSS and BEM for these reasons:

• It helps create clear, strict relationships between CSS and HTML
• It helps us create reusable, composable components
• It allows for less nesting and lower specificity
• It helps in building scalable stylesheets

OOCSS, or “Object Oriented CSS”, is an approach for writing CSS that encourages you to think about your stylesheets as a collection of “objects”: reusable, repeatable snippets that can be used independently throughout a website.

• Nicole Sullivan's OOCSS wiki
• Smashing Magazine's Introduction to OOCSS

BEM, or “Block-Element-Modifier”, is a naming convention for classes in HTML and CSS. It was originally developed by Yandex with large codebases and scalability in mind, and can serve as a solid set of guidelines for implementing OOCSS.

• CSS Trick's BEM 101
• Harry Roberts' introduction to BEM

We recommend a variant of BEM with PascalCased “blocks”, which works particularly well when combined with components (e.g. React). Underscores and dashes are still used for modifiers and children.

Example

// ListingCard.jsx
function ListingCard() {
  return (
    <article class="ListingCard ListingCard--featured">

      <h1 class="ListingCard__title">Adorable 2BR in the sunny Mission</h1>

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

    </article>
  );
}

/* ListingCard.css */
.ListingCard { }
.ListingCard--featured { }
.ListingCard__title { }
.ListingCard__content { }

• .ListingCard is the “block” and represents the higher-level component
• .ListingCard__title is an “element” and represents a descendant of .ListingCard that helps compose the block as a whole.
• .ListingCard--featured is a “modifier” and represents a different state or variation on the .ListingCard block.

While it is possible to select elements by ID in CSS, it should generally be considered an anti-pattern. ID selectors introduce an unnecessarily high level of specificity to your rule declarations, and they are not reusable.

For more on this subject, read CSS Wizardry's article on dealing with specificity.

Avoid binding to the same class in both your CSS and JavaScript. Conflating the two often leads to, at a minimum, time wasted during refactoring when a developer must cross-reference each class they are changing, and at its worst, developers being afraid to make changes for fear of breaking functionality.

We recommend creating JavaScript-specific classes to bind to, prefixed with .js-:

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

Use 0 instead of none to specify that a style has no border.

Bad

.foo {
  border: none;
}

Good

.foo {
  border: 0;
}

• 항상 .sass가 아닌 .scss 문법을 사용해주세요.
• 보통 CSS와 @include 선언은 논리적으로 순서를 정리해주세요. (아래 예시를 참조)

1. 속성 선언

   우선 표준 속성 선언을 먼저 작성합니다. @include 혹은 중첩 선택자는 아직 적지 않습니다.

   .btn-green {
     background: green;
     font-weight: bold;
     // ...
   }

2. @include 선언

   @include를 마지막에 모아놓으면 전체 선택자를 쉽게 독해할 수 있습니다.

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

3. 중첩 선택자

   중첩 선택자는 마지막에 위치합니다. 그리고 그 다음으로는 아무것도 오지 않습니다. 규칙 선언부와 중첩 선택자 사이에는 여백을 추가하며, 중첩 선택자 사이에도 마찬가치입니다. 중첩 선택자 내부 속성들 또한 위의 규칙을 따릅니다.

   .btn {
     background: green;
     font-weight: bold;
     @include transition(background 0.5s ease);
   
     .icon {
       margin-right: 10px;
     }
   }

변수 이름을 정할 때는 -를 사용하는 것을 권장합니다. 같은 파일 내에서만 사용될 변수에 한해서는 접두어를 추가해도 괜찮습니다. (예- $_my-variable).

Mixin은 코드를 DRY하게 하고 명료하게 하며, 복잡성을 줄이기 위해 사용해야 합니다. 인자를 받지 않는 Mixin은 이럴 때 유용합니다. 하지만 만약 당신이 페이로드(payload)를 압축하지 않는다면(예- gzip), 불필요한 코드 중복이 발생하게 됩니다.

@extend는 직관적이지 않고 특히 중첩 선택자와 함께 사용할 때 위험성이 있기 때문에 사용하지 않는 것을 권장합니다. 심지어 최상위 placeholder 선택자를 extend해도 선택자들의 순서가 바뀌게 되면 문제가 발생할 수 있습니다. @extend를 사용함으로써 얻을 수 있는 이점은 Gzip을 사용하면 해결될 뿐더러, 스타일시트를 DRY하게 만들기 위해서는 mixin을 사용하면 됩니다.

중첩은 최대 3번까지!

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

만약 선택자가 이렇게 길어진다면, 당신은 다음과 같은 CSS를 작성하고 있을 가능성이 높습니다:

• HTML과 밀접하게 엮여있다.(망가지기 쉬움)
• 너무 구체적이다.
• 재사용할 수 없다.

강조: 절대로 ID 선택자는 중첩하지 마세요!

어쩔 수 없이 ID 선택자를 사용해야한다면(사용하지 않는 것이 가장 좋습니다.), 절대로 중첩되지 않도록 유의하세요. 만약 중첩시키게 된다면, 왜 그렇게 특수한 케이스가 발생하는지 먼저 고민해보는 것이 좋습니다. 만약 당신이 잘 구성된 HTML과 CSS를 사용한다면 절대로 이렇게 할 필요가 없습니다.

이 스타일 가이드는 여러가지 언어로 번역 돼 있습니다:

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