Boas práticas

Geralmente a pior condição de trabalho para algum desenvolvedor, são trabalhos já existentes, pois normalmente cada desenvolvedor tem seu estilo próprio, nesse guia, criamos uma série de dicas que podem ajudar você e sua equipe a padronizar seu código. Tambem selecionamos algumas dicas e referências de acessibilidade para tornar seus sites acessíveis para aqueles que utilizam tecnologia assistiva.

Conteúdo

Acessibilidade

É importante seguir padrões comuns web, — com um pouco de esforço — pode-se criar sites acessíveis para aqueles que utilizam TA.

Pular navegação

Se a navegação conter muitos links e vir antes do conteúdo principal da página, adicione um link Pular para conteúdo principal antes da navegação (para uma explicação simples, consulte este Artigo Projeto A11y - Como usar link pular navegação (em inglês)). Ao usar a classe .sr-only irá ocultar visualmente o link âncora, e a classe .sr-only-focusable irá garantir que o elemento só se tornará visível uma vez focada (para usuários que navegam com o teclado).

Devido a problemas de longa data / bugs no Chrome (veja a issue 262171 in the Chromium bug tracker) e Internet Explorer (veja o artigo in-page links and focus order), Você vai precisar ter certeza de que o elemento de destino do seu link ancora é, esteja preparado para isso, para isso, basta adicionar o código tabindex="-1". Além disso, você pode não querer criar uma indicação explicita de que o elemento destino esteja realmente em foco com #content:focus { outline: none; }. Note que este bug também afetará qualquer outro link ancora em seu site possa estar usando, tornando-os inúteis para usuários de teclado.

<body>
  <a href="#content" class="sr-only sr-only-focusable">Pular para conteúdo principal</a>
  ...
  <div id="content" tabindex="-1">
    <!-- Conteúdo principal da página -->
  </div>
</body>

Hierarquia de cabeçalhos

Quando criamos uma hierarquia de cabeçalho (<h1> - <h6>), em seu documento, o cabeçalho principal deve ser <h1>. Em seguida cabeçalhos <h2> - <h6> devem vir de forma lógica, de tal modo que os leitores de telas consigam criar uma tabela de conteúdo para suas páginas.

Leia mais sobre Cabeçalhos nível 1, sections e acessibilidade e Entendendo o Outline do HTML.

Recursos adicionais

EditorConfig

O EditorConfig ajuda a definir e manter estilos de códigos consistentes entre diversos editores. Ele é um simples arquivo que guarda as configurações de estilo do código, o seu editor predileto lê estas configurações e entende exatamente qual a configuração utilizar para cada formato de arquivo. Leia mais sobre o editorconfig.

Configuração padrão do CPS Front-end.

# editorconfig.org

root = true

[*]
charset = utf-8
end_of_line = lf
indent_size = 2
indent_style = space
insert_final_newline = true
trim_trailing_whitespace = true

[*.md]
trim_trailing_whitespace = false

[*.py]
indent_size = 4

HTML

Dicas de formatação para deixar seu código HTML mais organizado, legível e semântico. Procure sempre usar a ferramenta de validação da W3C, eles sabem o que fazem.

Formatação geral

  • Use tabulação com dois espaço de identação.
  • Parágrafos de texto devem ser sempre colocados dentro da tag <p>. Nunca use várias vezes a tag <br>.
  • Itens em formato de lista devem estar sempre em <ul>, <ol> ou <dl>. Nunca use um conjunto de <div> ou <p>.
  • Cada campo do formulário que tem o texto anexado deve utilizar a tag <label>. Especialmente os tipo radio ou elementos checkbox.
  • Apesar das aspas em torno do atributos ser opcional, sempre coloque aspas em torno dos atributos para facilitar a leitura.
  • Evite escrever comentários de fechamento da tag, como <!-- /.element -->. Isso só acrescenta mais tempo de carregamento da página..
  • Evite adicionar barra em elementos de fecho automático. Por exemplo, <br>, <hr>, <img>, e <input>.

Atributos booleanos

Muitos atributos não necessitam de um valor para ser usado. Como disabled ou checked, então não use-os.

<!-- Ruim -->
<input type="text" disabled="disabled">

<input type="checkbox" value="1" checked="checked">

<select>
  <option value="1" selected="selected">1</option>
</select>

<!-- Bom -->
<input type="text" disabled>

<input type="checkbox" value="1" checked>

<select>
  <option value="1" selected>1</option>
</select>

CSS

Escreva código CSS de forma consciente.

Prefixos de Nomenclatura

Usamos o prefixo cps- para todas as classes do CPS Front-end. Isso nos ajuda a evitar conflitos com o CSS do produto de terceiros ou com outros frameworks.

Utilização (classes vs. ids)

Devemos usar IDs para elementos que aparecem exatamente uma única vez em uma página, caso contrário, use classes. Em caso de dúvida, use um nome de classe.

  • Bons candidatos para IDs são: cabeçalho, rodapé, janela modal.
  • Ruins candidatos para IDs são: navegações, lista de itens, títulos.

Aspas

Utilize aspas duplas.

/* Ruim */
input[type='text'] { ... }
div:after { content: '...'; }

/* Bom */
input[type="text"] { ... }
div:after { content: "..."; }