├── .gitignore ├── chapters ├── 5.CSS Selectors.md ├── 4.ii.b.More-Layers.md ├── 4.i.Hyphen-Delimited.md ├── 2.i.Multiple-Files.md ├── 1.ii.Disclaimers.md ├── 2.vii.Indenting.md ├── 5.ii.Reusability.md ├── 2.vii.a.Indenting-Sass.md ├── 2.vii.b.Alignment.md ├── 4.Naming-Conventions.md ├── 2.iii.80-Characters-Wide.md ├── 4.iv.JavaScript-Hooks.md ├── 1.Introduction.md ├── 2.Syntax-and-Formatting.md ├── 3.i.High-level.md ├── 2.viii.Meaningfull-Whitespace.md ├── 3.i.a.Object–Extension_Pointers.md ├── 4.ii.BEM-like-Naming.md ├── 4.ii.a.Starting-Context.md ├── 1.i.The-Importance-of-a-Styleguide.md ├── 2.iv.Titling.md ├── 3.Commenting.md ├── 2.v.Anatomy-of-a-Ruleset.md ├── 5.i.Selector Intent.md ├── 2.ix.HTML.md └── 3.ii.Low-level.md ├── README.md └── CONTRIBUTING.md /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs and databases # 2 | ###################### 3 | *.log 4 | *.sql 5 | *.sqlite 6 | 7 | # OS generated files # 8 | ###################### 9 | .DS_Store 10 | .DS_Store? 11 | ._* 12 | .Spotlight-V100 13 | .Trashes 14 | .idea 15 | ehthumbs.db 16 | Thumbs.db -------------------------------------------------------------------------------- /chapters/5.CSS Selectors.md: -------------------------------------------------------------------------------- 1 | # Seletores CSS 2 | 3 | Talvez um tanto surpreendentemente, um dos aspectos fundamentais mais críticos para uma escrita CSS mutável e escalável são os seletores. Sua especificidade, sua portabilidade e sua reutilização, todos tem um impacto direto no raio de ação que vamos descobrir no nosso CSS, e as dores de cabeça que pode nos trazer. 4 | -------------------------------------------------------------------------------- /chapters/4.ii.b.More-Layers.md: -------------------------------------------------------------------------------- 1 | # Mais Camadas 2 | 3 | Se nós adicionarmos um outro Elemento — chamado, vamos dizer, **.person__eye {}** — para esse componente **.person {}**, nós não precisaríamos passar por todas as camadas do DOM. Isto é, a notação correta seria **.person__eye {}**, e não **.person__head__eye {}**. Suas classes não refletirão a trilha completa do DOM. 4 | -------------------------------------------------------------------------------- /chapters/4.i.Hyphen-Delimited.md: -------------------------------------------------------------------------------- 1 | # Hífen Delimitador 2 | 3 | Todas strings em classes são delimitadas com o hífen (-), como em: 4 | 5 | ```css 6 | .page-head { } 7 | 8 | .sub-content { } 9 | ``` 10 | 11 | CamelCase e underline não são usados para classes regulares; os exemplos a seguir estão incorretos: 12 | 13 | ```css 14 | .pageHead { } 15 | 16 | .sub_content { } 17 | ``` 18 | -------------------------------------------------------------------------------- /chapters/2.i.Multiple-Files.md: -------------------------------------------------------------------------------- 1 | # Múltiplos Arquivos 2 | 3 | Com a recente ascensão meteorica dos pre-processadores, é mais comum separar o CSS em múltiplos arquivos. 4 | 5 | Mesmo se você não estiver usando um pré-processador, é uma boa ideia separar pedaços de código em seus próprios arquivos, que vão ser concatenados durante o processo de build. 6 | 7 | Se, por algum motivo, você não estiver trabalhando com múltiplos arquivos, as próximas seções podem exigir do seu setup uma adequação. 8 | -------------------------------------------------------------------------------- /chapters/1.ii.Disclaimers.md: -------------------------------------------------------------------------------- 1 | # Avisos 2 | 3 | *CSS Guidelines* é um guia de estilo, e não é o guia de estilo. O guia contém metodologias, técnicas e dicas que eu com certeza recomendaria aos meus clientes e equipes, porém seus gostos e circunstâncias podem ser diferentes. Isso pode ser diferente de acordo com sua situação, ou de acordo com sua experiência. 4 | 5 | Esses guias são obstinados, porém eles foram repetidamente testados, sobrecarregados, aprimorados, quebrados, refeitos, e reutilizados em vários anos durante alguns projetos de todos os tamanhos. 6 | -------------------------------------------------------------------------------- /chapters/2.vii.Indenting.md: -------------------------------------------------------------------------------- 1 | # Indentação 2 | 3 | Assim como declarações individuais identadas, regras completas de identação sinaliza relações entre elas, por exemplo: 4 | 5 | ```css 6 | .foo { } 7 | 8 | .foo__bar { } 9 | 10 | .for__baz { } 11 | ``` 12 | 13 | Ao fazer isso, um desenvolvedor pode ver num relance que \.foo\__baz {} vive dentro de \.foo\__bar {} que vive dentro de \.foo {}. 14 | 15 | Esta quase replicação do DOM diz muito aos desenvolvedores sobre aonde esperam que as classes serão usadas sem terem de referir a um trecho de HTML. 16 | -------------------------------------------------------------------------------- /chapters/5.ii.Reusability.md: -------------------------------------------------------------------------------- 1 | # Reutilização 2 | 3 | Com um movimento para uma abordagem mais baseada em componentes para construir UIs, a idéia de reutilização é primordial. 4 | Queremos que a opção seja capaz de mover, reciclar, duplicar e distribuir componentes em todos os nossos projetos. 5 | 6 | Para este fim, Fazemos uso pesado de classes. ID's, Além de ser excessivamente específico, Não podem ser usados mais de 7 | uma vez em qualquer página. Enquanto que as classes podem ser reutilizadas infinitas vezes. Tudo o que você escolher, 8 | do tipo de seletor para o seu nome, deve se emprestar para ser reutilizado. -------------------------------------------------------------------------------- /chapters/2.vii.a.Indenting-Sass.md: -------------------------------------------------------------------------------- 1 | # Indentação no Sass 2 | 3 | Sass provê a funcionalidade de herança. Isto é, escrevendo assim: 4 | 5 | ```sass 6 | .foo { 7 | color: red; 8 | 9 | .bar { 10 | color: blue; 11 | } 12 | } 13 | ``` 14 | 15 | ...ficaremos com este CSS compilado 16 | 17 | ```css 18 | .foo { color: red; } 19 | .foo .bar { color: blue; } 20 | ``` 21 | 22 | Quando identamos em Sass, nós afixamos os mesmos 2 (dois) espaços, e nós também deixaremos uma linha em branco antes e depois do conjunto de regras de herança. 23 | 24 | **N.B.** Herança em Sass deve ser evitado quando possível. Veja a [seção sobre Especificidade](#specificity) para mais detalhes. 25 | -------------------------------------------------------------------------------- /chapters/2.vii.b.Alignment.md: -------------------------------------------------------------------------------- 1 | # Alinhamento 2 | 3 | Tente alinhar declarações de palavras identicas e comuns, por exemplo: 4 | 5 | ```css 6 | .foo { 7 | -webkit-border-radius: 3px; 8 | -moz-border-radius: 3px; 9 | border-radius: 3px; 10 | } 11 | 12 | .bar { 13 | position: absolute; 14 | top: 0; 15 | right: 0; 16 | bottom: 0; 17 | left: 0; 18 | margin-right: -10px; 19 | margin-left: -10px; 20 | padding-right: 10px; 21 | padding-left: 10px; 22 | } 23 | ``` 24 | 25 | Isto faz a vida um pouco mais fácil para desenvolvedores cujos editores de texto suportam edição por coluna, o que lhes permite mudar várias linhas identicas e alinhadas de uma só vez. 26 | -------------------------------------------------------------------------------- /chapters/4.Naming-Conventions.md: -------------------------------------------------------------------------------- 1 | # Convenções de Nomenclatura 2 | 3 | Convenções de Nomenclatura em CSS são extremamente úteis para fazer seu código mais estrito, mais transparente e mais informativo. 4 | 5 | Uma boa convenção de nomenclatura dirá a você e sua equipe: 6 | 7 | - que tipo de coisa uma classe faz; 8 | - onde uma classe pode ser usada; 9 | - que (mais) uma classe pode estar relacionada com outra; 10 | 11 | A convenção de nomenclatura que sigo é muito simples: hífen (-) delimita strings, com BEM-like nomeando para o pedaço de código mais complexo. 12 | 13 | É pior não ter nada que uma convenção de nomenclatura que não é normalmente útil no desenvolvimento de CSS-side (lado do CSS); Eles realmente mostram sua verdadeira utilidade quando visto no HTML. 14 | -------------------------------------------------------------------------------- /chapters/2.iii.80-Characters-Wide.md: -------------------------------------------------------------------------------- 1 | # 80 Caracteres de Largura 2 | Sempre que possível, limite a largura de seus arquivos CSS em 80 caracteres. Razões para isso incluem: 3 | - A possibilidade se de ter múltiplos arquivos abertos lado a lado; 4 | - Visualizar o CSS em sites como o GitHub, ou em janelas do terminal; 5 | - Proporcionar um comprimento de linha confortável para os comentários. 6 | ``` 7 | /** 8 | * Sou um longo comentário. Eu descrevo, em detalhes, O CSS após o comentário. 9 | * Sou um comentário tão longo que posso facilmente quebrar o limite de 80 10 | * caracteres, então estou disperso em várias linhas. 11 | */ 12 | ``` 13 | Haverão exceções inevitáveis para essa regra — como URLs, ou sintaxe de gradientes — mas você não precisará se preocupar com isso. 14 | -------------------------------------------------------------------------------- /chapters/4.iv.JavaScript-Hooks.md: -------------------------------------------------------------------------------- 1 | # JavaScript Ganchos 2 | 3 | Como uma regra, não é prudente vincular seu CSS e seu JS para a mesma classe no seu HTML. Isso é porque fazer isso significa que você não pode ter (ou remover) um sem (remover) o outro. É muito mais claro, muito mais transparente e muito mais sustentável vincular seu JS a classes específicas. 4 | 5 | Eu já passei por ocasiões antes na qual quando tentei refatorar algum CSS, involuntariamente removi a funcionalidade JS, porque as duas estavam amarrados um ao outro, era impossível ter um sem o outro. 6 | 7 | Normalmente, essas são classes prefixadas com **js-**, por exemplo: 8 | 9 | ```html 10 | 11 | ``` 12 | 13 | Isso significa que podemos ter um elemento em outro lugar que pode carregar com estilo de **.btn {}**, mas sem o comportamento de **.js-btn**. 14 | -------------------------------------------------------------------------------- /chapters/1.Introduction.md: -------------------------------------------------------------------------------- 1 | # Introdução 2 | 3 | CSS não é uma linguagem bonita. Apesar de ser simples para começar e aprender, mas logo vai se tornar problemático em qualquer escala razoável de código. Não há nada que podemos fazer para mudar como CSS funciona, porém nós podemos fazer mudanças na maneira que escrevemos e estruturamos o código. 4 | 5 | Em grandes e longos projetos, que estão em produção, com vários desenvolvedores com diferente especialidades e habilidades,é importante que todos trabalhem de maneira unificada com as outras coisas. 6 | 7 | - Manter a folha de estilo sustentável; 8 | - Manter o código transparente, robusto e legível; 9 | - Manter a folha de estilo escalável. 10 | 11 | Tem várias técnicas que devemos empregar para atender esses requisitos, e o CSS Guidelines é um documento com recomendações e abordagens que vão nos ajudar a atender esses requisitos. 12 | -------------------------------------------------------------------------------- /chapters/2.Syntax-and-Formatting.md: -------------------------------------------------------------------------------- 1 | # Sintaxe e Formatação 2 | 3 | Uma das formas mais simples de um guia é um conjunto de regras a respeito da sintaxe e formatação. Com uma forma padrão de escrita(literalmente escrita) do CSS, o código sempre vai parecer e dar a impressão de ser familiar a todos os membros do time. 4 | 5 | Além disso, o código vai parecer limpo e dar a impressão de estar limpo. É um ecossistema muito melhor para se trabalhar, e faz com que outro membro da equipe mantenha o padrão de limpeza que foi encontrado. Código feio deixa aberto o precedente para continuar feio. 6 | 7 | Em um nível alto, nós queremos: 8 | 9 | * dois(2) espaços para identação, sem tabulação; 10 | * 80 caracteres de largura nas colunas; 11 | * multi-linhas de CSS; 12 | * uso de espaços em branco que tenham significado. 13 | 14 | Porém, como qualquer coisa, a especificação é irrelevante, consistência é a chave. 15 | -------------------------------------------------------------------------------- /chapters/3.i.High-level.md: -------------------------------------------------------------------------------- 1 | # Alto nível 2 | 3 | Para comentários grandes que documentam seções ou componentes inteiros, nós usamos um *DocBlock-esque* multilinhas que se ajuste à nossa largura de 80 colunas. 4 | 5 | Aqui está um exemplo real de um CSS que estiliza o cabeçalho da página [CSS Wizardry](http://csswizardry.com/) 6 | 7 | ````css 8 | /** 9 | * O cabeçalho de uma página principal pode ter dois estados diferentes 10 | * 11 | * 1) Um cabeçalho regular com nenhum ou extra tratamentos, só contendo a logo 12 | * e a navegação. 13 | * 2) Uma masthead que tem uma largura flúida (ficando fixo após um certo ponto) 14 | * que tem um imagem de fundo larga, e algum texto de suporte. 15 | * 16 | * O cabeçalho de página é extremamente simples, mas a versão masthead tem uma 17 | * dependência levemente confundida com o wrapper que vive dentro dela. 18 | */ 19 | ```` 20 | 21 | Este nível de detalhes deveria ser a norma para todos os códigos não triviais - descrição de estados, permutações, condições e tratamentos. 22 | -------------------------------------------------------------------------------- /chapters/2.viii.Meaningfull-Whitespace.md: -------------------------------------------------------------------------------- 1 | # Compreendendo espaços em branco 2 | 3 | Assim com a identação, nós podemos fornecer muita informação por meio de uso liberal e criterioso de espaços embranco entre os conjuntos de regras. Nós usamos: 4 | 5 | - Uma (1) linha vazia entre conjunto de regras intimamente relacionadas. 6 | - Duas (2) linhas vazias entre conjunto de regras vagamente relacionadas. 7 | - Cinco (5) linhas vazias entre seções inteiramente novas. 8 | 9 | Por exemplo: 10 | 11 | ```css 12 | /*------------------------------------*\ 13 | #FOO 14 | \*------------------------------------*/ 15 | 16 | .foo { } 17 | 18 | .foo__bar { } 19 | 20 | 21 | .foo--baz { } 22 | 23 | 24 | 25 | 26 | 27 | /*------------------------------------*\ 28 | #BAR 29 | \*------------------------------------*/ 30 | 31 | .bar { } 32 | 33 | .bar__baz { } 34 | 35 | .bar__foo { } 36 | ``` 37 | 38 | Não deve haver numca um cenário em que dois conjunto de regras não tem uma linha vazia entre eles. Isto deveria ser incorreto: 39 | 40 | ```css 41 | .foo { } 42 | .foo__bar { } 43 | .foo--baz { } 44 | ``` 45 | -------------------------------------------------------------------------------- /chapters/3.i.a.Object–Extension_Pointers.md: -------------------------------------------------------------------------------- 1 | # Pontos de extensão de objeto 2 | 3 | Quando se trabalha com múltiplos arquivos, ou a uma maneira OOCSS(Object Oriented CSS ou CSS Orientado a objeto), você encontrará frequentemente regras que podem trabalhar em conjunto umas com as outras e nem sempre estarão no mesmo arquivo ou local. Por exemplo, você tem um objeto botão genérico - que somente fornece o estilo estrutural - que deve ser estendido por um componente parcial que adicionará estilos. Ele se traduz em um ponto de extensão de objeto. Neste arquivo: 4 | 5 | ````css 6 | /** 7 | * Estende `.btn {}` em _components.buttons.scss. 8 | */ 9 | 10 | .btn {} 11 | ```` 12 | 13 | Adicionando seu arquivo de temas: 14 | 15 | ````css 16 | /** 17 | * Estas regras estendem `.btn {}` em objects.buttons.scss. 18 | */ 19 | 20 | .btn--positive {} 21 | .btn--negative {} 22 | ```` 23 | 24 | Esse comentário simples e de baixo esforço pode fazer muita diferença para os desenvolvedores que não têm conhecimento do relacionamentos entre projetos ou que desejam saber como, por que e de onde outros estilos podem estar sendo herdados. 25 | -------------------------------------------------------------------------------- /chapters/4.ii.BEM-like-Naming.md: -------------------------------------------------------------------------------- 1 | # Nomenclatura BEM-like 2 | 3 | Para maiores e mais inter-relacionadas partes de UI que exigem um número de classes, nós utilizamos a convenção de nomenclatura BEM-like. 4 | BEM, significa _Block_, _Element_, _Modifier_ (Bloco, Elemento, Modificador), é uma metodologia de front-end inventada por desenvolvedores que trabalhavam na Yandex. Enquanto BEM é uma metodologia completa, aqui nós estamos apenas preocupados com a convenção de nomenclatura. Mais, a convenção de nomenclatura aqui apenas é BEM-_like_; O princípio é exatamente o mesmo, mas a atual sintaxe difere levemente. 5 | BEM divide os componentes em classes em três grupos: 6 | 7 | - Block: A única raíz do componente. 8 | - Element: Um componente do Block. 9 | - Modifier: Uma variante ou extensão do Block. 10 | 11 | Fique com esta analogia (note, não é um exemplo): 12 | 13 | ```css 14 | .person { } 15 | .person__head { } 16 | .person--tall { } 17 | ``` 18 | 19 | Elements são delimitados com dois (2) sublinhados (_ _), e Modifiers são delimitados com dois (2) hífens (--). 20 | 21 | Aqui nós podemos ver que **.person { }** é o Block; ele é a raíz de uma entidade distinta. **.person__head { }** é um Element; ele é uma pequena parte do Block **.person { }**. Finalmente, **.person--tall { }** é um Modifier; ele é uma variante específico do Block **.person { }**. -------------------------------------------------------------------------------- /chapters/4.ii.a.Starting-Context.md: -------------------------------------------------------------------------------- 1 | # Contexto Inicial 2 | 3 | Seu contexto inicial Block (Bloco) começa na localização mais lógica, autônoma e discreta. Para continuar com nossas analogias baseadas em pessoas, nós não teríamos classes como **.room__person {}**, como o quarto é outro, contexto muito mais elevado. Nós provavelmente separariamos os Blocos, como em: 4 | 5 | ``` css 6 | .room { } 7 | .room__door { } 8 | 9 | .room--kitchen { } 10 | 11 | .person { } 12 | .person__head { } 13 | ``` 14 | 15 | Se nós quisessemos indicar uma **.person {}** dentro de **.room {}**, seria mais correto usar seletores como **.room .person{}** que faz ponto entre dois Blocos aumentando o alcance dos Blocos e Elementos existentes. 16 | 17 | O exemplo mais realista de Blocos devidamente delimitados pode parecer algo assim, onde cada pedaço de código representa seu próprio Bloco: 18 | 19 | ```css 20 | .page { } 21 | 22 | .content { } 23 | 24 | .sub-content { } 25 | 26 | .footer { } 27 | .footer__copyright { } 28 | ``` 29 | 30 | Uma notação incorreta para isso seria: 31 | 32 | ``` css 33 | .page { } 34 | .page__content { } 35 | .page__sub-content { } 36 | .page__footer { } 37 | .page__copyright { } 38 | ``` 39 | 40 | 41 | É importante saber quando o escopo BEM inicia e para. Como regra, o BEM aplica-se de forma autônoma em partes discretas da interface do usuário (UI). 42 | -------------------------------------------------------------------------------- /chapters/1.i.The-Importance-of-a-Styleguide.md: -------------------------------------------------------------------------------- 1 | # A Importância de um Guia de Estilo 2 | 3 | Um guia de estilos de código (note, este não é um guia de estilo visual) é uma ferramenta valiosa para equipes que: 4 | 5 | - desenvolvem e mantém produtos por um período de tempo razoável; 6 | - possuem desenvolvedores com diferentes habilidades e especialidades; 7 | - possuem um número de desenvolvedores diferentes trabalhando em um produto a qualquer momento; 8 | - adicionam novos membros para a equipe regularmente; 9 | - tem uma quantia de bases de código que desenvolvedores estão sempre utilizando. 10 | 11 | Embora guias de estilo são tipicamente mais adequados para equipes de desenvolvimento de produtos — que possuem um grande número de código em projetos de longa duração e em evolução, com vários desenvolvedores contribuindo ao longo de períodos prolongados de tempo — todos os desenvolvedores devem se esforçar para que haja um grau de normalização em seu código. 12 | 13 | Um bom guia de estilos, quando obedecido, poderá: 14 | 15 | - definir o padrão de qualidade do código através de uma base de código; 16 | - promover a consistência em bases de código; 17 | - conceder aos desenvolvedores uma sensação de familiaridade em todas as bases de código; 18 | - aumentar a produtividade. 19 | 20 | Guias de estilos devem ser aprendidos, compreendidos e implementados durante todas as etapas em um projeto, e qualquer desvio deverá ser devidamente fundamentado. 21 | -------------------------------------------------------------------------------- /chapters/2.iv.Titling.md: -------------------------------------------------------------------------------- 1 | # Titulações 2 | Inicie cada nova seção principal de um projeto CSS com um título: 3 | ``` 4 | /*------------------------------------*\ 5 | #TÍTULO-DA-SEÇÃO 6 | \*------------------------------------*/ 7 | 8 | .seletor { } 9 | ``` 10 | O título da seção é prefixado com um símbolo cardinal (**#**), para que possamos realizar pesquisas mais específicas (por exemplo **grep**, etc.): ao invés de pesquisar apenas **TÍTULO-DA-SEÇÃO** — o que pode retornar muitos resultados — uma pesquisa mais direta como **#TÍTULO-DA-SEÇÃO** deve retornar apenas a seção em questão. 11 | 12 | Pule uma linha entre este título e a próxima linha de código (seja ela um comentário, códigos como SASS, ou código CSS). 13 | 14 | Se você estiver trabalhando em um projeto onde cada seção possui seu próprio arquivo, este título deve aparecer no início de cada um dos arquivos. Se estiver trabalhando em um projeto com várias seções por arquivo, cada novo título deve possuir cinco (5) linhas de espaço em branco acima dele. Este espaço em branco, juntamente com um título, faz com que seja muito mais fácil encontrar seções dentro de arquivos maiores: 15 | ``` 16 | /*------------------------------------*\ 17 | #UMA-SEÇÃO 18 | \*------------------------------------*/ 19 | 20 | .seletor { } 21 | 22 | 23 | 24 | 25 | 26 | /*------------------------------------*\ 27 | #OUTRA-SEÇÃO 28 | \*------------------------------------*/ 29 | 30 | /** 31 | * Comentário 32 | */ 33 | 34 | .outro-seletor { } 35 | ``` 36 | -------------------------------------------------------------------------------- /chapters/3.Commenting.md: -------------------------------------------------------------------------------- 1 | # Comentando 2 | 3 | A sobrecarga cognitiva de se trabalhar com CSS é enorme. Com tanta coisa para se estar ciente, e tantas nuancias de projeto para se lembrar, a pior situação que a maioria dos desenvolvedores encontram consigo mesmos está na pessoa-que-não-escreveu-este-código. Lembrar suas próprias classes, regras, objetos, e *helpers* é gerenciável até certo ponto, mas qualquer um que herde uma mal CSS tem uma chance. 4 | 5 | **CSS precisa de mais comentários** 6 | 7 | Como CSS é algo de uma linguagem declarativa que realmente não deixa uma trilha de papel, muitas vezes é difícil discernir - só de olhar para um CSS sozinho: 8 | 9 | + Se algum CSS depende de algum código em algum outro lugar; 10 | + Que efeito uma mudança de código trará em outro lugar; 11 | + Onde mais algum CSS poderá ser usado; 12 | + Quais estilos podem herdar (intencionalmente ou não); 13 | + Quais estilos passam (intencionalmente ou não); 14 | + Onde um autor pretendia usar um pedaço de CSS; 15 | 16 | Isto nem leva em conta algumas peculiaridade do CSS - como varios estados de **overflow** que disparam formatações de contexto de bloco, ou certas transformações de propriedade que disparam aceleração do hardware - que tornam ainda mais desorientador para os desenvolvedores herdarem em seus processos. 17 | 18 | Como resultado do CSS não contar sua história muito bem, é uma linguagem que realmente se beneficia de ser fortemente comentada. 19 | 20 | Como regra, você deverá comentar qualquer coisa que não seja imediatamente óbvia no seu código sozinho. Isso quer dizer, não há necessidade para dizer a alguém que **color: red;** vai fazer algo ficar vermelho, mas se você está usando **overflow: hidden;** para limpar floats - em vez de cortar o overflow de um elemento - este é provavelmente algo que vale a pena comentar. 21 | -------------------------------------------------------------------------------- /chapters/2.v.Anatomy-of-a-Ruleset.md: -------------------------------------------------------------------------------- 1 | # Anatomia de um Conjunto de Regras 2 | Antes de demonstrar como podemos escrever o nosso conjunto de regras, devemos primeiro nos familiarizar com a terminologia relevante: 3 | ``` 4 | [seletor] { 5 | [propriedade]: [valor]; 6 | [<--declaração--->] 7 | } 8 | ``` 9 | 10 | Como por exemplo: 11 | ``` 12 | .foo, .foo--bar, 13 | .baz { 14 | display: block; 15 | background-color: green; 16 | color: red; 17 | } 18 | ``` 19 | Aqui, você pode ver que temos: 20 | - Seletores relacionados na mesma linha; seletores não relacionadas em novas linhas; 21 | - Um espaço antes da nossa chave de abertura (**{**); 22 | - Propriedades e valores na mesma linha; 23 | - Um espaço após os dois pontos (**:**) de nossa propriedade e antes de nosso valor; 24 | - Cada declaração em sua própria nova linha; 25 | - A chave de abertura (**{**) na mesma linha de nosso último seletor; 26 | - A nossa primeira declaração em uma nova linha após a chave de abertura (**{**); 27 | - A nossa chave de fechamento (**}**) em sua própria nova linha; 28 | - Cada declaração indentada por dois (**2**) espaços antes dela; 29 | - Um ponto e vírgula (**;**) ao final de cada declaração. 30 | 31 | Este formato é, em grande maioria, o padrão universal (exceto para variações no número de espaços para indentar o código; contudo, a maior parte dos desenvolvedores prefere utilizar (2) dois). 32 | 33 | Dessa forma, o seguinte seria incorreto: 34 | ``` 35 | .foo, .foo--bar, .baz 36 | { 37 | display:block; 38 | background-color:green; 39 | color:red } 40 | ``` 41 | Os problemas deste trecho incluem: 42 | - Tabs ao invés de espaços; 43 | - Seletores não relacionados na mesma linha; 44 | - A chave de abertura (**{**) em uma linha abaixo dos seletores; 45 | - A chave de fechamento (**}**) não está em sua própria linha; 46 | - O ponto-e-vírgula (**;**) após o último valor do seletor (e, neste caso, opcional) está faltando; 47 | - Não há um espaço após os dois pontos (**:**). 48 | -------------------------------------------------------------------------------- /chapters/5.i.Selector Intent.md: -------------------------------------------------------------------------------- 1 | # Intenção do seletor 2 | 3 | Ao escrever CSS, é importante que nós consigamos alcançar nosso seletores corretamente, e que estamos selecionando as coisas certas para as razões corretas. 4 | Intenção do seletor é um processo de Decisão e definição que você quer para estilo e como você vai seleciona-lo. 5 | Por exemplo, se você está querendo um estilo para o menu de navegação principal do seu site, um seletor como este seria 6 | muito imprudente: 7 | 8 | header ul { } 9 | 10 | A intenção deste seletor é estilizar qualquer UL dentro de algum elemento HEADER, enquanto que nossa intenção era estilar a navegação principal do site. Esta é um Intenção de Seletor pobre: 11 | Você pode ter qualquer número de elementos HEADER em uma página, e eles por sua vez, pode abrigar qualquer número de UL(s), assim um seletor como este corre o risco de aplicar um estilo específico a um grande número de elementos. 12 | Isto resultará em ter que escrever mais CSS para desfazer o resultado de um tal seletor. 13 | 14 | Uma abordagem melhor seria um seletor como: 15 | 16 | .site-nav { } 17 | 18 | Um seletor inequívoco e explícito com boa intenção de seletor. Nós estamos selecionando explicitamente a coisa certa 19 | para exatamente o motivo certo. 20 | Seletores de intenção pobres, é uma das grandes razões para dores de cabeça em projetos CSS. Escrevendo regras que 21 | são muito gananciosas -- e que aplicam tratamentos muito específicos através de seletores de alcance muito grande-- 22 | provoca efeitos colaterais inesperados e leva a folhas de estilo muito emaranhadas, com seletores ultrapassando 23 | suas intenções e interferindo num conjunto de regras de outra forma não relacionados. 24 | 25 | CSS não pode ser encapsulado, mas nós podemos mitigar alguns destes efeitos por não escrever isso em seletores que operam globalmente: Seus seletores devem ser tão explícitos e bem fundamentados como sua razão para querer selecionar algo. 26 | -------------------------------------------------------------------------------- /chapters/2.ix.HTML.md: -------------------------------------------------------------------------------- 1 | # HTML 2 | 3 | HTML e CSS dada a natureza de serem intrisecamente conectados, seria negligência minha não cobrir algumas orientações sintáticas e formatações para a marcação. 4 | 5 | Sempre coloque aspas em atributos, mesmo se eles iriam trabalhar sem. Isto reduz a chance de acidentes, e o formato é mais familiar para a maioria dos desenvolvedores. Por tudo isso, iria funcionar (e é válido): 6 | 7 | ```html 8 |
9 | ``` 10 | 11 | ... este formato é preferencial: 12 | 13 | ```html 14 |
15 | ``` 16 | 17 | As aspas não são requeridas aqui, mas é mais seguro incluí-las. 18 | Quando escrevemos múltiplos valores em um atributo de class, as separamos com dois espaços, assim: 19 | 20 | ```html 21 |
22 | ``` 23 | 24 | Quando múltiplas classes são relacionadas entre si, considere agrupá-las em colchetes ([ e ]), igual a: 25 | 26 | ```html 27 |
28 | ``` 29 | 30 | Isto não é uma firme recomendação, e é algo que ainda estou experimentado comigo mesmo, mas acarreta uma série de benefícios. Leia mais em Agrupando classes relacioandas em sua marcação (link). 31 | Tal como acontece com os nossos conjuntos de regras, é possível usar significativos espaços em branco em seu HTML. Você pode denotar quebras temáticas no conteúdo com 5 linhas de espaços, por exemplo: 32 | 33 | ```html 34 |
35 | ... 36 |
37 | 38 | 39 | 40 | 41 | 42 |
43 | ... 44 |
45 | 46 | 47 | 48 | 49 | 50 |
51 | ... 52 |
53 | ``` 54 | 55 | Separe trechos relacioados vagamente em sua marcação com uma simples linha vazia, por exemplo: 56 | 57 | ```html 58 | 79 | ``` 80 | 81 | Isto permite aos desenvolvedores detectarem partes separadas do DOM em um relance, e também permite que certos editores de tetxo - como o Vim, por exemplo - possam manipular blocos de linhas vazias delimitadas da sua marcação. 82 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Tradução do CSS Guideline criado por Harry Roberts 2 | 3 | ## Content 4 | 5 | 1. [Introduction](chapters/1.Introduction.md) 6 | 1. [The Importance of a Styleguide](chapters/1.i.The-Importance-of-a-Styleguide.md) 7 | 2. [Disclaimers](chapters/1.ii.Disclaimers.md) 8 | 2. [Syntax and Formatting](chapters/2.Syntax-and-Formatting.md) 9 | 1. [Multiple Files](chapters/2.i.Multiple-Files.md) 10 | 2. Table of Contents 11 | 3. [80 Characters Wide](chapters/2.iii.80-Characters-Wide.md) 12 | 4. [Titling](chapters/2.iv.Titling.md) 13 | 5. [Anatomy of a Ruleset](chapters/2.v.Anatomy-of-a-Ruleset.md) 14 | 6. Multi-line CSS 15 | 7. [Indenting](chapters/2.vii.Indenting.md) 16 | 1. [Indenting Sass](chapters/2.vii.a.Indenting-Sass.md) 17 | 2. [Alignment](chapters/2.vii.b.Alignment.md) 18 | 8. [Meaningful Whitespace](chapters/2.viii.Meaningfull-Whitespace.md) 19 | 9. [HTML](chapters/2.ix.HTML.md) 20 | 3. [Commenting](chapters/3.Commenting.md) 21 | 1. [High-level](chapters/3.i.High-level.md) 22 | 1. [Object–Extension Pointers](chapters/3.i.a.Object–Extension_Pointers.md) 23 | 2. [Low-level](chapters/3.ii.Low-level.md) 24 | 3. Preprocessor Comments 25 | 4. Removing Comments 26 | 4. [Naming Conventions](chapters/4.Naming-Conventions.md) 27 | 1. [Hyphen Delimited](chapters/4.i.Hyphen-Delimited.md) 28 | 2. [BEM-like Naming](chapters/4.ii.BEM-like-Naming.md) 29 | 1. [Starting Context](chapters/4.ii.a.Starting-Context.md) 30 | 2. [More Layers](chapters/4.ii.b.More-Layers.md) 31 | 3. Modifying Elements 32 | 3. Naming Conventions in HTML 33 | 4. [JavaScript Hooks](chapters/4.iv.JavaScript-Hooks.md) 34 | 1. data-\* Attributes 35 | 5. Taking It Further 36 | 5. CSS Selectors 37 | 1. Selector Intent 38 | 2. Reusability 39 | 3. Location Independence 40 | 4. Portability 41 | 1. Quasi-Qualified Selectors 42 | 5. Naming 43 | 1. Naming UI Components 44 | 6. Selector Performance 45 | 1. The Key Selector 46 | 7. General Rules 47 | 6. Specificity 48 | 1. IDs in CSS 49 | 2. Nesting 50 | 3. !important 51 | 4. Hacking Specificity 52 | 7. Architectural Principles 53 | 1. High-level Overview 54 | 2. Object-orientation 55 | 3. The Single Responsibility Principle 56 | 4. The Open/Closed Principle 57 | 5. DRY 58 | 6. Composition over Inheritance 59 | 7.The Separation of Concerns 1. Misconceptions 60 | 61 | ## Contribuindo com a tradução 62 | 63 | [Aqui](CONTRIBUTING.md) você pode visualizar o nosso guia de contribuição. 64 | 65 | ## Informações 66 | 67 | Guia em [inglês](http://cssguidelin.es/) 68 | -------------------------------------------------------------------------------- /chapters/3.ii.Low-level.md: -------------------------------------------------------------------------------- 1 | # Baixo Nível 2 | 3 | Muitas vezes queremos comentar específicas declarações em nosso conjunto de regras. Para isso, usamos um tipo de nota de rodapé reversa. Aqui está um comentário mais complexo detalhando os cabeçalhos de site maiores mencionados acima: 4 | 5 | ```css 6 | /** 7 | * Large site headers act more like mastheads. They have a faux-fluid-height 8 | * which is controlled by the wrapping element inside it. 9 | * 10 | * 1. Mastheads will typically have dark backgrounds, so we need to make sure 11 | * the contrast is okay. This value is subject to change as the background 12 | * image changes. 13 | * 2. We need to delegate a lot of the masthead’s layout to its wrapper element 14 | * rather than the masthead itself: it is to this wrapper that most things 15 | * are positioned. 16 | * 3. The wrapper needs positioning context for us to lay our nav and masthead 17 | * text in. 18 | * 4. Faux-fluid-height technique: simply create the illusion of fluid height by 19 | * creating space via a percentage padding, and then position everything over 20 | * the top of that. This percentage gives us a 16:9 ratio. 21 | * 5. When the viewport is at 758px wide, our 16:9 ratio means that the masthead 22 | * is currently rendered at 480px high. Let’s… 23 | * 6. …seamlessly snip off the fluid feature at this height, and… 24 | * 7. …fix the height at 480px. This means that we should see no jumps in height 25 | * as the masthead moves from fluid to fixed. This actual value takes into 26 | * account the padding and the top border on the header itself. 27 | */ 28 | 29 | .page-head--masthead { 30 | margin-bottom: 0; 31 | background: url(/img/css/masthead.jpg) center center #2e2620; 32 | @include vendor(background-size, cover); 33 | color: $color-masthead; /* [1] */ 34 | border-top-color: $color-masthead; 35 | border-bottom-width: 0; 36 | box-shadow: 0 0 10px rgba(0, 0, 0, 0.1) inset; 37 | 38 | @include media-query(lap-and-up) { 39 | background-image: url(/img/css/masthead-medium.jpg); 40 | } 41 | 42 | @include media-query(desk) { 43 | background-image: url(/img/css/masthead-large.jpg); 44 | } 45 | 46 | > .wrapper { /* [2] */ 47 | position: relative; /* [3] */ 48 | padding-top: 56.25%; /* [4] */ 49 | 50 | @media screen and (min-width: 758px) { /* [5] */ 51 | padding-top: 0; /* [6] */ 52 | height: $header-max-height - double($spacing-unit) - $header-border-width; /* [7] */ 53 | } 54 | 55 | } 56 | 57 | } 58 | ``` 59 | 60 | Este tipo de comentário nos ajuda a manter tudo de nossa documentação em um só lugar enquanto nos referimos às partes de nosso conjunto de regras a que pertencem. 61 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | #Guia de Contribuição 2 | 3 | ##Organização das Pastas 4 | 5 | Como perceberam no [README](README.md) do repositório, a organização dos capítulos é feita por pastas e dentro das pastas tem os arquivos que são as explicações dos tópicos. 6 | 7 | ##Como começar? 8 | 9 | Bom, se você quer cooperar com a tradução da documentação, basta você ir na seção de ```issues``` do repositório que fica bem aqui. Lá, você vai ver que as ```issues``` na verdade são os capítulos da documentação original. 10 | 11 | Basta você entrar numa ```issue``` e comentar qual tópico ou quais tópicos você pretende ter a responsabilidade de traduzir. Pedimos que essa parte seja levada bem à sério, já que, uma vez separada a tradução do tópico para você, outra pessoa não irá fazer. 12 | 13 | A partir do seu comentário, um dos nossos contribuidores vai colocar seu usuário na frente do tópico escolhido. 14 | 15 | Depois disso, é só você ```forkar``` o nosso repositório e escrever suas traduções. 16 | 17 | ##Enviando as traduções 18 | 19 | ###Commits 20 | Commitar apenas os arquivos que estão sendo modificados, NÃO utilizar ```git add .``` e SIM ```git add nome_arquivo```. Assim poderemos evitar possíveis conflitos na hora do PR. 21 | 22 | ###Pull request 23 | 24 | Depois que tiver terminado suas traduções, você só precisa fazer um ```pull request``` para nosso repositório. 25 | 26 | Em relação aos ```pull requests```, pedimos que sejam enviados da forma mais simples possível. O que queremos dizer é que seja enviando tópico por tópico. Dessa forma, tornamos o processo de revisão e correção mais dinâmico e mais rápido possível. 27 | 28 | Ao criar um novo PR, seguir os padrões abaixo: 29 | 30 | **1. Nome do PR:** Para um novo PR com sua tradução pronta para revisão, utilizar os termos a seguir como padrão para o nome do PR > **[Para Revisão] - [Número do Capítulo e ou subcapítulo]Nome do Capítulo**. Ex: 1.2 - The Importance of a Styleguide, ou 3.1.1 - Object–Extension Pointers. 31 | 32 | **1.1 Nome do PR:** Caso seja solicitado correções em sua tradução, por favor, feche o PR atual, efetue as devidas correções, e, ao encerrá-las, crie um novo PR com os termos a seguir como padrão para o nome do PR > **[Correções] - [Número do Capítulo e ou subcapítulo]Nome do Capítulo**. Ex: 1.2 - The Importance of a Styleguide, ou 3.1.1 - Object–Extension Pointers. 33 | 34 | **2. Conversation:** Mencionar o @lucasktrindade,@gabrielclima no PR 35 | 36 | **Não é necessário linkar no README principal e também no README de cada capítulo.** Apenas enviem em seu PR o capítulo traduzido, conforme mencionado anteriormente. 37 | 38 | Lembrando, não creim PR que possuam conflitos. Caso, ao criar seu PR seja encontrado algum conflito, por favor, resolvam os conflitos primeiramente antes de criar o PR. Só serão aceitos PR para revisão hábeis para merge, com confitos serão fechados imediatamente. 39 | 40 | 41 | ###Revisão 42 | 43 | Em seguida, um de nossos contribuidores vai analisar todo o texto para ver se está tudo correto. Passando dessa parte, é feito um ```merge``` da sua tradução. 44 | --------------------------------------------------------------------------------