diff --git a/README.md b/README.md index 859e4e6..c0b41c9 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,36 @@ # Airbnb CSS / Sass Styleguide -*A mostly reasonable approach to CSS and Sass* - -## Table of Contents - -1. [Terminology](#terminology) - - [Rule Declaration](#rule-declaration) - - [Selectors](#selectors) - - [Properties](#properties) -1. [CSS](#css) - - [Formatting](#formatting) - - [Comments](#comments) - - [OOCSS and BEM](#oocss-and-bem) - - [ID Selectors](#id-selectors) - - [JavaScript hooks](#javascript-hooks) - - [Border](#border) -1. [Sass](#sass) - - [Syntax](#syntax) - - [Ordering](#ordering-of-property-declarations) - - [Variables](#variables) - - [Mixins](#mixins) - - [Extend directive](#extend-directive) - - [Nested selectors](#nested-selectors) -1. [Translation](#translation) -1. [License](#license) - -## Terminology - -### Rule declaration - -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: - +*Наиболее разумный подход к написанию CSS и Sass* + +## Навигация + +1. [Терминология](#Терминология) + - [Объявление правил](#Объявление-правил) + - [Селекторы](#Селекторы) + - [Свойства](#Свойства) +2. [CSS](#css) + - [Форматирование](#Форматирование) + - [Комментарии](#Комментарии) + - [OOCSS и BEM](#oocss-и-bem) + - [Селекторы id](#Селекторы-id) + - [JavaScript хуки](#javascript-хуки) + - [Свойство Border](#Свойство-border) +3. [Sass](#sass) + - [Синтаксис](#Синтаксис) + - [Сортировка свойств](#Сортировка-свойств) + - [Переменные](#Переменные) + - [Миксины](#Миксины) + - [Директива @extend](#Директива-extend) + - [Вложенные селекторы](#Вложенные-селекторы) +4. [Лицензия](#Лицензия) + +## Терминология + +### Объявление правил + +Правило — это имя селектора (или группы селекторов) с определённой группой свойств. + +Пример: ```css .listing { font-size: 18px; @@ -38,9 +38,11 @@ A “rule declaration” is the name given to a selector (or a group of selector } ``` -### Selectors +### Селекторы + +В объявлении правила «селекторы» означают элементы в DOM, к которым будут применены объявленные свойства. Селекторы могут соответствовать HTML-тэгам, классам элементов, id или атрибутам. -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: +Пример использования селекторов: ```css .my-element-class { @@ -52,9 +54,11 @@ In a rule declaration, “selectors” are the bits that determine which element } ``` -### Properties +### Свойства -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: +Наконец, свойства — это то, что описывает стиль выбранных элементов. Свойства указываются в виде `ключ:значение`. Правила могут содержать одно или более объявленных свойств. + +Выглядит это так: ```css /* some selector */ { @@ -63,23 +67,23 @@ Finally, properties are what give the selected elements of a rule declaration th } ``` -**[⬆ back to top](#table-of-contents)** +**[⬆ К навигации](#Навигация)** ## CSS -### Formatting +### Форматирование -* 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](#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 +* Используйте мягкую табуляцию (2 пробела) для отступов. +* Kebab-case предпочтительнее camelCase в названии классов. + - Snake_case и PascalCase можно использовать при работе с BEM (подробнее [OOCSS и BEM](#oocss-и-bem)). +* Не используйте селекторы #id. +* При использовании нескольких селекторов для одного правила каждое начинается с новой строки. +* Перед `{` ставим пробел в объявлении правила. +* В свойствах после `:` добавляем пробел. +* В конце объявления правила символ `}` должен переноситься на новую строку. +* Между объявлениями правил добавляйте пустую строку. -**Bad** +**Плохо** ```css .avatar{ @@ -93,7 +97,7 @@ Finally, properties are what give the selected elements of a rule declaration th } ``` -**Good** +**Хорошо** ```css .avatar { @@ -108,36 +112,36 @@ Finally, properties are what give the selected elements of a rule declaration th } ``` -### Comments +### Комментарии -* 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 +* Предпочитайте однострочные комментарии (`// в Sass`) многострочным. +* Комментарий должен находиться на отдельной строке. Избегайте комментариев в конце строки. +* Пишите детальные комментарии для неочевидных вещей: + - для z-index; + - CSS-хаков для отдельных браузеров и совместимости. -### OOCSS and BEM +### OOCSS и BEM -We encourage some combination of OOCSS and BEM for these reasons: +Мы поощряем некоторые комбинации OOCSS и BEM, вот почему: - * 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 + * это позволяет создавать чистую и строгую связь между CSS и HTML; + * это помогает нам создавать многоразовые, составные компоненты; + * меньше вложенностей, низкая специфичность правил; + * это помогает создавать масштабируемые таблицы стилей. -**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. +**OOCSS**, или «Объектно-ориентированный CSS» — это подход к написанию CSS, который призывает думать о таблице стилей как о коллекции «объектов»: многоразовых, повторяемых фрагментах кода, которые могут использоваться независимо друг от друга на всём сайте. * Nicole Sullivan's [OOCSS wiki](https://github.com/stubbornella/oocss/wiki) * Smashing Magazine's [Introduction to OOCSS](http://www.smashingmagazine.com/2011/12/12/an-introduction-to-object-oriented-css-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. +**BEM**, или «Блок-Элемент-Модификатор» - это соглашение об именовании классов в HTML и CSS. Разработано Яндексом с прицелом на большие объёмы кода и масштабируемость. Может послужить как солидный набор правил для использования OOCSS. * CSS Trick's [BEM 101](https://css-tricks.com/bem-101/) * Harry Roberts' [introduction to BEM](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/) -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. +Мы рекомендуем вариант БЭМ, в котором используются PascalCased «блоки», отлично работающие в связке с компонентами (например, React). Подчёркивания и тире по-прежнему используются для модификаторов и элементов. -**Example** +**Пример** ```jsx // ListingCard.jsx @@ -164,31 +168,31 @@ function ListingCard() { .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. +* `.ListingCard` — это «блок» и он представляет из себя компонент верхнего уровня. +* `.ListingCard__title` — это «элемент» и он является дочерним компонентом `.ListingCard`. Из «элементов» состоит «блок». +* `.ListingCard--featured` — это «модификатор» и он предствляет различные состояния «блока» `.ListingCard`. -### ID selectors +### Селекторы id -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](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) to your rule declarations, and they are not reusable. +Хоть в CSS и можно находить элемент по ID, это является плохой практикой. Селекторы ID вводят излишне высокий уровень [специфичности](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) для ваших правил и лишают возможности их переиспользовать. -For more on this subject, read [CSS Wizardry's article](http://csswizardry.com/2014/07/hacks-for-dealing-with-specificity/) on dealing with specificity. +Более подробная статья на эту тему: [CSS Wizardry's article](http://csswizardry.com/2014/07/hacks-for-dealing-with-specificity/) -### JavaScript hooks +### JavaScript-хуки -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. +Избегайте привязки к одному классу одновременно в CSS и Javascript. Это может привести как минимум к трате времени при рефакторинге, а также боязни разработчика сломать функционал вводом новых изменений. -We recommend creating JavaScript-specific classes to bind to, prefixed with `.js-`: +Мы рекомендуем использовать префикс `.js-`, для тех элементов, которые будут задействованы в Javascript: ```html ``` -### Border +### Свойство Border -Use `0` instead of `none` to specify that a style has no border. +Вместо `none` используйте `0` для свойства border: -**Bad** +**Плохо** ```css .foo { @@ -196,27 +200,27 @@ Use `0` instead of `none` to specify that a style has no border. } ``` -**Good** +**Хорошо** ```css .foo { border: 0; } ``` -**[⬆ back to top](#table-of-contents)** +**[⬆ К навигации](#Навигация)** ## Sass -### Syntax +### Синтаксис -* Use the `.scss` syntax, never the original `.sass` syntax -* Order your regular CSS and `@include` declarations logically (see below) +* Используйте синтаксис `.scss` вместо оригинального `.sass` синтаксиса. +* Упорядочивайте обычный CSS и `@include`-объявления логически. -### Ordering of property declarations +### Сортировка свойств -1. Property declarations +1. Объявление свойств - List all standard property declarations, anything that isn't an `@include` or a nested selector. + Перечисляйте все стандартные свойства, не являющиеся `@include` или вложенными селекторами. ```scss .btn-green { @@ -226,9 +230,9 @@ Use `0` instead of `none` to specify that a style has no border. } ``` -2. `@include` declarations +2. Объявление `@include` - Grouping `@include`s at the end makes it easier to read the entire selector. + Группировка `@include` в конце правила делает код более читаемым. ```scss .btn-green { @@ -239,81 +243,63 @@ Use `0` instead of `none` to specify that a style has no border. } ``` -3. Nested selectors +3. Вложенные селекторы - Nested selectors, _if necessary_, go last, and nothing goes after them. Add whitespace between your rule declarations and nested selectors, as well as between adjacent nested selectors. Apply the same guidelines as above to your nested selectors. +Вложенные селекторы (_если они небходимы_) идут в самом конце, и ничего не должно идти после них. Добавляйте пустую строку между свойствами правила и вложенными селекторами, а также между смежными вложенными селекторами. Применяйте эти правила ко всем вложенным селекторам. - ```scss - .btn { - background: green; - font-weight: bold; - @include transition(background 0.5s ease); +```scss +.btn { + background: green; + font-weight: bold; + @include transition(background 0.5s ease); - .icon { - margin-right: 10px; - } - } - ``` + .icon { + margin-right: 10px; + } +} +``` -### Variables +### Переменные -Prefer dash-cased variable names (e.g. `$my-variable`) over camelCased or snake_cased variable names. It is acceptable to prefix variable names that are intended to be used only within the same file with an underscore (e.g. `$_my-variable`). +Предпочитайте kebab-case именование переменных (напр. `$my-variable`) camelCase или snake_cased именованию. Допускается использовать знак нижнего подчеркивания для обозначения переменной, используемой в пределах одного файла (напр. `$_my-variable`). -### Mixins +### Миксины -Mixins should be used to DRY up your code, add clarity, or abstract complexity--in much the same way as well-named functions. Mixins that accept no arguments can be useful for this, but note that if you are not compressing your payload (e.g. gzip), this may contribute to unnecessary code duplication in the resulting styles. +Миксины делают ваш код более чистым и понятным и позволяют поддерживать абстрактную сложность, так же как и хорошо названные функции. Миксины, не принимающие аргументов, могут быть полезны для этого, но нужно помнить, что если вы не сжимаете свои файлы (например, gzip), то это может привести к лишнему повторению кода. -### Extend directive +### Директива @extend -`@extend` should be avoided because it has unintuitive and potentially dangerous behavior, especially when used with nested selectors. Even extending top-level placeholder selectors can cause problems if the order of selectors ends up changing later (e.g. if they are in other files and the order the files are loaded shifts). Gzipping should handle most of the savings you would have gained by using `@extend`, and you can DRY up your stylesheets nicely with mixins. +`@extend` следует избегать, поскольку он имеет неинтуитивное и потенциально опасное поведение, особенно при использовании с вложенными селекторами. Даже наследование селекторов верхнего уровня может создать проблемы, если в будущем будет изменён порядок селекторов. Сжатие компенсирует экономию, которую вы получили бы с помощью наследования. -### Nested selectors +### Вложенные селекторы -**Do not nest selectors more than three levels deep!** +**Вложенность селекторов не должна быть больше 3!** ```scss .page-container { .content { .profile { - // STOP! + // Стоп! } } } ``` -When selectors become this long, you're likely writing CSS that is: - -* Strongly coupled to the HTML (fragile) *—OR—* -* Overly specific (powerful) *—OR—* -* Not reusable - - -Again: **never nest ID selectors!** +Когда вы пишите такие длинные селекторы, вы, вероятно, пишите CSS который: -If you must use an ID selector in the first place (and you should really try not to), they should never be nested. If you find yourself doing this, you need to revisit your markup, or figure out why such strong specificity is needed. If you are writing well formed HTML and CSS, you should **never** need to do this. +* слишком сильно привязан к HTML (хрупкий); *—или—* +* чрезмерно специфичный; *—или—* +* не переиспользуемый. -**[⬆ back to top](#table-of-contents)** -## Translation +Ещё раз: **никаких вложенных ID селекторов!** - This style guide is also available in other languages: +Если всё-таки пришлось использовать селекторы ID (а этого на самом деле лучше избегать), они никогда не должны быть вложенными. Если такое происходит, вам требуется пересмотреть свою разметку и выяснить, зачем нужна такая сильная специфика. Если у вас правильно структурирован HTML-код и CSS-стили, вам **никогда** не придётся это делать. - - ![id](https://raw.githubusercontent.com/gosquared/flags/master/flags/flags/shiny/24/Indonesia.png) **Bahasa Indonesia**: [mazipan/css-style-guide](https://github.com/mazipan/css-style-guide) - - ![tw](https://raw.githubusercontent.com/gosquared/flags/master/flags/flags/shiny/24/Taiwan.png) **Chinese (Traditional)**: [ArvinH/css-style-guide](https://github.com/ArvinH/css-style-guide) - - ![cn](https://raw.githubusercontent.com/gosquared/flags/master/flags/flags/shiny/24/China.png) **Chinese (Simplified)**: [Zhangjd/css-style-guide](https://github.com/Zhangjd/css-style-guide) - - ![fr](https://raw.githubusercontent.com/gosquared/flags/master/flags/flags/shiny/24/France.png) **French**: [mat-u/css-style-guide](https://github.com/mat-u/css-style-guide) - - ![ja](https://raw.githubusercontent.com/gosquared/flags/master/flags/flags/shiny/24/Japan.png) **Japanese**: [nao215/css-style-guide](https://github.com/nao215/css-style-guide) - - ![ko](https://raw.githubusercontent.com/gosquared/flags/master/flags/flags/shiny/24/South-Korea.png) **Korean**: [CodeMakeBros/css-style-guide](https://github.com/CodeMakeBros/css-style-guide) - - ![PT-BR](https://raw.githubusercontent.com/gosquared/flags/master/flags/flags/shiny/24/Brazil.png) **Portuguese (Brazil)**: [felipevolpatto/css-style-guide](https://github.com/felipevolpatto/css-style-guide) - - ![pt-PT](https://raw.githubusercontent.com/gosquared/flags/master/flags/flags/shiny/24/Portugal.png) **Portuguese (Portugal)**: [SandroMiguel/airbnb-css-style-guide](https://github.com/SandroMiguel/airbnb-css-style-guide) - - ![ru](https://raw.githubusercontent.com/gosquared/flags/master/flags/flags/shiny/24/Russia.png) **Russian**: [Nekorsis/css-style-guide](https://github.com/Nekorsis/css-style-guide) - - ![es](https://raw.githubusercontent.com/gosquared/flags/master/flags/flags/shiny/24/Spain.png) **Spanish**: [ismamz/guia-de-estilo-css](https://github.com/ismamz/guia-de-estilo-css) - - ![vn](https://raw.githubusercontent.com/gosquared/flags/master/flags/flags/shiny/24/Vietnam.png) **Vietnamese**: [trungk18/css-style-guide](https://github.com/trungk18/css-style-guide) - - ![vn](https://raw.githubusercontent.com/gosquared/flags/master/flags/flags/shiny/24/Italy.png) **Italian**: [antoniofull/linee-guida-css](https://github.com/antoniofull/linee-guida-css) -**[⬆ back to top](#table-of-contents)** +**[⬆ К навигации](#Навигация)** -## License +## Лицензия (The MIT License) @@ -325,4 +311,4 @@ The above copyright notice and this permission notice shall be included in all c THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -**[⬆ back to top](#table-of-contents)** +**[⬆ К навигации](#Навигация)**