clauda/css_guideline.md

## css_guideline.md

      
    Raw
  

              css_guideline.md
            
          
    Guia para desenvolvimento de folhas de estilo no site do Quero Bolsa.
Antes de começar...

Utilize arquivos com extensão .scss

Utilizamos SASS no projeto.
Utilize indentação de 2 espaços (não utilize tab)

Respeite os níveis de indentação.
Nomes em inglês

Tudo no projeto está em inglês, vamos manter assim.
Prefira aspas duplas

Exceto quando houver url(), então não é necessário usar aspas.
Comente/Documente seu código

Sempre que possível explique o que a regra faz e onde ela está sendo aplicada.
Prefira a notação do scss: // comentário
Estrutura

Definimos uma estrutura de arquivos base. Separa estrutura da página (layout) dos elementos de design (components ou modules) e arquivos que são comuns a estes. Estes arquivos devem conter pequenos pedaços de código, específicos daquele elemento.
  stylesheets/
  ├── components/
  │   ├── _buttons.scss
  │   ├── _search.scss
  │   ├── _sidebar.scss
  │   └── _forms.scss
  ├── layout/
  │   ├── _base.scss
  │   ├── _footer.scss
  │   └── _header.scss
  ├── globals/
  │   ├── _helpers.scss
  │   ├── _media_queries.scss
  │   └── _variables.scss
  ├── modules/
  │   ├── _info_bar.scss
  │   ├── _location_bar.scss
  │   └── _proposal_box.scss
  └── _framework.scss
      

Arquivo exemplo _framework.scss
  // base
  @import "variables"
  @import "helpers"

  // layout
  @import "header"
  @import "footer"

  // componentes
  @import "buttons"
  @import "search"

Para entender esta estrutura você precisa saber que..

No diretório layout ficam elementos estruturais das páginas, tais como cabeçalho, rodapé, grid, sidebar, caixa de busca, etc.. Aqui não deve existir grandes mudanças. (laranja)
Em components devem ficar elementos menores de design que são padrão e serão reutilizados em outras partes do site, mas não estrutura o site, como input de formulários, botões, notificações, etc. (verde)
Em modules ficam elementos específicos de páginas específicas, não reutilizáveis. (vermelho)
Em globals ficam elementos, mixins, helpers, variáveis, que serão compartilhadas em outros arquivos.

Quando for criar estes arquivos prefira nomeá-los com o mesmo nome do elemento pai. Na dúvida sobre onde colocar ou como nomear, peça opinião a alguém do time.
Boas Práticas

Sempre use o bom senso.
Nomeando classes e ids


Opte por criar classes ao invés de IDs. IDs são únicos na página, quer dizer que o estilo não pode ser repetido, mas classes o estilo poderá ser reutilizado.
Utilize nomenclatura consistente, prefira dar nomes de acordo com a finalidade e não com a aparência ou posição. Evite nomes grandes.
Nomeie com letras minúsculas e separadas por hífen - (kebab-case).

  // Não
  .towerOfPisa {
    font-style: italic;
  }

  // Não
  .tower_of_pisa {
    font-style: italic;
  }

  // SIM
  .tower-of-pisa {
    font-style: italic;
  }
Agrupe tags com estilo comuns

  // Sempre que possível
  .eminem,
  .jayz {
    word-spacing: 0;
  }

  // Ao invês...
  .eminem {
    word-spacing: 0;
  }
  .jayz {
    word-spacing: 0;
  }
Nomeie regras com significado semântico

O estilo não deve ser afetado por mudanças no HTML.
  // Não
  .icon a:first-child { 
    background: url(facebook.png);
  }

  // NUNCA
  .margin-10 { 
    margin: 20px;
  }

  // Sim
  .icon-facebook { 
    background: url(facebook.png);
  }
Não utilize CSS inline ou incorporado

É mais eficiente aplicar regras de estilo a vários elementos em uma folha de estilo separada, porque permite que essas regras sejam reutilizadas. Isso também mantêm o HTML limpo e separa a marcação do estilo. Reduzindo o HTML e o CSS, diminui o tempo de carregamento da página.
Salvo quando precisar esconder/mostrar com display:none 👍
  <!-- NUNCA -->
  <style>
    .box { margin-top: 20px; }
  </style>

  <!-- JAMAIS -->
  <div style="margin-top:20px"></div>
Não adicione classes ou IDs com tags

Atribuir com tags afeta a performance e engessa o estilo ao HTML.
  // Não
  div.alien {
    display: none;
  }

  // Não
  div#titanic {
    float: none;
  }

  // Não
  ul li .error {
    margin: 0;
  }

  // SIM
  .delorean {
    z-index: -1955;
  }
Evite heraquia com tags

O navegador lê o html da direita para esquerda. Procurar por tags primeiro e verificar o elemento pai depois afeta o desempenho. E tenha cuidado ao utilizar parentesco: Sai mais caro calcular o parentesco das tags do que verificar a hierarquia. Seletores decendentes são de longe os mais caros de serem calculados.
  // Não
  .iceberg a {
    position: fixed;
  }

  // Não
  ul > li > a {
    color: #fff;
  }

  // SIM
  .link {
    color: #fff;
  }
Use unidades flexíveis

Isso vai fazer seu design ser flexível, responsivo. Valores em pixels deixam o site estático.
Para elementos tipográficos ou afetados pela tipografia, use em como medida flexível.
  // Não
  .column { 
    width: 140px 
  }

  // SIM
  .column { 
    width: 20%;
  }
Use cores com valores hexadecimais em letras minúsculas

Prefira utilizar valores de cores em hexadecimal ou em rgba() quando houver opacidade.
  // Não
  body {
    color: white;
  }

  // Não
  body {
    color: #FFFFFF;
  }
  
  // Sim
  body {
    color: #fff;
  }
ProTips


Estilo no CSS, função no HTML;
Melhor .button-default a .button-blue porque você pode querer mudar a cor do seu botão padrão.


Ao refatorar, remova antes de adicionar. Não deixe código legado;


Evite sobrescrever as regras de CSS;


Evite !important;


Utilize nomenclatura específica para elementos atrelados a comportamento javascript sem estilo. O prefixo js- para identificar seletores com js dependente;
.js-close {}
.js-show {}


Regras compartilhadas com estilo e comportamento js podem ter o prefixo is- ;


Documente bem as exceções.


Linter

Utilize a gem scss-linter para varrer seu código e evitar code smells.

https://github.com/brigade/scss-lint
https://github.com/appfolio/ruby_css_lint