Guia de estilo CSS / Sass da Airbnb

Uma abordagem mais razoável para CSS e Sass

Índice

1. Terminologia
   • Declaração de regra
   • Seletores
   • Propriedades
2. CSS
   • Formatação
   • Comentários
   • OOCSS e BEM
   • Seletores ID
   • JavaScript hooks
   • Border
3. Sass
   • Sintaxe
   • Ordenação
   • Variáveis
   • Mixins
   • Diretiva Extend
   • Seletores aninhados
4. Tradução

Terminologia

Declaração de regra

A “declaração de regra” é o nome dado ao seletor (ou a um grupo de seletores) acompanhados de um grupo de propriedades. Segue um exemplo:

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

Seletores

Na declaraçao de um regra, os “seletores” são os bits que determinam quais elementos na árvore do DOM serão estilizados pelas propriedades definidas. Os seletores podem ser de elementos HTML, classes, ID ou qualquer um de seus atributos. Seguem alguns exemplos de seletores:

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

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

Propriedades

Finalmente, as propriedades definem o estilos dos seletores. As propriedades são pares chave-valor, onde uma declaração de regra pode conter uma ou mais declarações de propriedades.

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

⬆ voltar ao início

CSS

Formatação

• Use soft tabs (2 espaços) para identação.
• Prefira dashes (-) em vez de camelCasing nos nomes das classes.
  • Underscores (_) e PascalCasing são aceites no caso de usar a metodologia BEM (veja OOCSS e BEM abaixo).
• Não use seletores ID.
• Quando usar múltiplos seletores numa declaração de regra, coloque um em cada linha.
• Coloque um espaço antes da chaveta de abertura { na declaração de regras.
• Nas propriedades, coloque um espaço depois, mas não antes do caractere :.
• Coloque a chaveta de fechamento } de uma declaração de regra numa nova linha.
• Coloque linhas em branco entre declarações de regra.

Incorreto

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

Correto

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

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

Comentários

• Prefira comentários de linha (// em Sass) a comentários em bloco.
• Prefira comentários na sua própria linha. Evite comentários no final da linha.
• Escreva comentários detalhados no código que não esteja suficientemente explícito:
  • Usos do z-index
  • Compatibilidade ou hacks específicos de browsers

OOCSS e BEM

Incentivamos algumas combinações de OOCSS e BEM por estas razões:

• Ajuda a criar relações claras e estritas entre CSS e HTML
• Ajuda-nos a criar componentes reutilizáveis e que podem ser combinados
• Permite menor aninhamento e especificidade
• Ajuda na construção de folhas de estilo escaláveis

OOCSS, ou “Object Oriented CSS”, é uma abordagem para escrita de CSS que o encoraja a pensar sobre as suas folhas de estilo como uma coleção de "objetos": snippets repetitivos reutilizáveis que podem ser usados de forma independente em todo o website.

• OOCSS wiki de Nicole Sullivan

• Introduction to OOCSS de Smashing Magazine

BEM, ou “Block-Element-Modifier”, é uma convenção de nomes para classes em HTML e CSS. Foi originalmente desenvolvido pela Yandex com grandes bases de código e escalabilidade em mente, e pode servir como um sólido conjunto de diretrizes para a implementação do OOCSS.

• BEM 101 de CSS Trick
• Introduction to BEM de Harry Roberts

Recomendamos uma variante do BEM com os “blocos” no formato PascalCase, que funciona particularmente bem quando combinado com componentes (ex.: React). Underscores e traços continuam a ser utilizados para modificadores e filhos.

Exemplo

// 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 é o “bloco” e representa o componente de nível mais alto.
• .ListingCard__title é um “elemento” e representa o descendente de .ListingCard que ajuda a compor o bloco como um todo.
• .ListingCard--featured é o “modificador” e representa um estado diferente ou variação no bloco .ListingCard.

Seletores ID

Embora seja possível selecionar elementos por ID no CSS, geralmente deve ser considerado um anti-pattern. Seletores ID introduzem um elevado nível de especificidade para as declarações de regra e não são reutilizáveis.

Para mais informações sobre este assunto, leia o artigo CSS Wizardry sobre o tratamento da especificidade.

JavaScript hooks

Evite vincular a mesma classe no CSS e no JavaScript. No mínimo, tal leva ao desperdício de tempo durante o refactoring, por exemplo, quando um programador deve fazer referência cruzada a cada classe que está a alterar e, no pior dos casos, leva os programadores a resistirem a fazer mudanças com receio de romper a funcionalidade.

Recomendamos a criação de classes específicas para JavaScript, com o prefixo .js-:

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

Border

Use o 0 em vez de none para especificar que um estilo não tem borda.

Incorreto

.foo {
  border: none;
}

Correto

.foo {
  border: 0;
}

⬆ voltar ao início

Sass

Sintaxe

• Use a sintaxe .scss, nunca a sintaxe original .sass
• Ordene o CSS e o @include com lógica (veja abaixo)

Ordenação das declarações de regra

1. Declaração de propriedades

   Listar todas as declarações de propriedades padrão, tudo o que não seja um @include ou um seletor aninhado.

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

2. Declarações @include

   Agrupar os @includes no final torna mais fácil a leitura de todo o seletor.

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

3. Seletores aninhados

   Os seletores aninhados, se necessário, são colocados no final e nada mais depois deles. Adicione um espaço entre a declaração de regra e os seletores aninhados, assim como entre os seletores aninhados adjacentes. Aplique as mesmas diretrizes acima para os seletores aninhados.

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

Variáveis

Tenha preferência por nomes de variáveis em dash-case (ex.: $my-variable) em vez de camelCase ou snake_case. É aceitável adicionar um "underscore" como prefíxo nos nomes de variáveis que se destinam a ser usadas dentro do mesmo arquivo (ex.: $_my-variable).

Mixins

Os Mixins devem ser usados para implementar no código o princípio DRY, adicionar clareza ou abstrair-nos da complexidade, assim como as funções bem nomeadas. Os Mixins que não aceitam argumentos podem ser úteis, mas tenha atenção que se não compactar o seu payload (ex.: gzip) isto pode contribuir para duplicação de código desnecessário nos estilos resultantes.

Diretiva Extend

O @extend deve ser evitado porque possui um comportamento não intuitivo e perigoso, especialmente quando usado nos seletores aninhados. Mesmo extendendo os seletores placeholder de nível superior, isto pode causar problemas se a ordem dos seletores mudar mais tarde (ex.: se estiverem noutros arquivos e a ordem de carregamento alternar). Ao usar o Gzip terá a maioria das economias que teria ganho usando @extend, e, além disso, pode tirar partido do princípio DRY através dos mixins.

Seletores aninhados

Não use seletores aninhados com mais de três níveis de profundidade!

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

Quando os seletores se tornam assim tão longos, provavelmente estará a escrever CSS assim:

• Fortemente acoplado ao HTML (frágil) —OU—
• Excessivamente específico (poderoso) —OU—
• Não reutilizável

Mais uma vez: nunca agrupe seletores ID!

Se precisar de utilizar um seletor ID (algo que não deve fazer!), ele nunca deve ser agrupado. Se tal acontecer, é necessário rever o código ou descobrir por que é necessária tal especificidade. Ao escrever corretamente HTML e CSS, nunca deverá ser necessário agrupar seletores ID!

⬆ voltar ao início

Tradução

Este guia de estilo também está disponível noutros idiomas:

• Bahasa Indonesia: mazipan/css-style-guide
• Chinese (Traditional): ArvinH/css-style-guide
• Chinese (Simplified): Zhangjd/css-style-guide
• French: mat-u/css-style-guide
• Japanese: nao215/css-style-guide
• Korean: CodeMakeBros/css-style-guide
• Portuguese (Brazil): felipevolpatto/css-style-guide
• Portuguese (Portugal): SandroMiguel/airbnb-css-style-guide
• Russian: Nekorsis/css-style-guide
• Spanish: ismamz/guia-de-estilo-css
• Vietnamese: trungk18/css-style-guide
• Italian: antoniofull/linee-guida-css

⬆ voltar ao início