{"id":19373418,"url":"https://github.com/xop/css-codeguide","last_synced_at":"2025-06-17T22:33:41.143Z","repository":{"id":16098457,"uuid":"18843331","full_name":"XOP/css-codeguide","owner":"XOP","description":"Documentation for coding and maintaining the most transparent CSS ","archived":false,"fork":false,"pushed_at":"2016-11-21T17:53:47.000Z","size":223,"stargazers_count":12,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-23T16:35:06.054Z","etag":null,"topics":["bem","css","documentation","methodology"],"latest_commit_sha":null,"homepage":null,"language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/XOP.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-04-16T14:47:18.000Z","updated_at":"2018-12-07T15:34:43.000Z","dependencies_parsed_at":"2022-07-21T06:47:19.247Z","dependency_job_id":null,"html_url":"https://github.com/XOP/css-codeguide","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/XOP/css-codeguide","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XOP%2Fcss-codeguide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XOP%2Fcss-codeguide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XOP%2Fcss-codeguide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XOP%2Fcss-codeguide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/XOP","download_url":"https://codeload.github.com/XOP/css-codeguide/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XOP%2Fcss-codeguide/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260450201,"owners_count":23011024,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bem","css","documentation","methodology"],"created_at":"2024-11-10T08:28:14.374Z","updated_at":"2025-06-17T22:33:36.119Z","avatar_url":"https://github.com/XOP.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"CSS Codeguide\n=============\n\n\u003e Documentation for coding and maintaining the most transparent CSS.\n\u003e It is bringing the experience of multiple front-end teams.\n\n:construction::construction::construction::construction::construction::construction::construction::construction::construction::construction:\n\n\u003e :warning: WORK IN PROGRESS  \n\u003e some parts may be missing  \n\u003e another require revision  \n\u003e **stay tuned for major updates!**\n\n:construction::construction::construction::construction::construction::construction::construction::construction::construction::construction:\n\nCurrent code guide is designed for **experienced developers** in the first place, but hopefully could be a great source of knowledge for the beginners.\n\nBasically this documentation is about how to work in team with 250+ style files and feel comfortable about that.\n\nPlease be aware, that CSS fundamentals, selector performance or other common topics are not the part of this guide.\nOn the other hand there will be reviewed different aspects of CSS described with practical examples, recommendations and best practicies.\n\n\u003e All along the text there will be links to examples folder.\n\u003e In most cases it is invaluable for understanding the picture in total,\n\u003e so check it out before further reading and keep them opened just in case.\n\nLet's get started!\n\n\n\u003c!--mdMenu--\u003e\n## Table of Contents\n* [Intro](#intro)\n\t* [Why another Guide](#why-another-guide)\n\t* [About](#about)\n* [Main principles](#main-principles)\n\t* [The first](#the-first)\n\t* [The second](#the-second)\n\t* [What's more](#what's-more)\n* [Methodology](#methodology)\n\t* [Introduction](#introduction)\n\t* [Basics](#basics)\n\t* [Naming principles](#naming-principles)\n\t* [Modifiers and states](#modifiers-and-states)\n\t* [Utilities](#utilities)\n\t* [JS interactivity](#js-interactivity)\n\t* [Mixins (not a preprocessor thing yet)](#mixins-not-a-preprocessor-thing-yet)\n* [Structure of СSS/preprocessor file](#structure-of-сsspreprocessor-file)\n\t* [Files organizing](#files-organizing)\n\t* [Code organization within a file](#code-organization-within-a-file)\n* [Comments](#comments)\n\t* [Structural comments](#structural-comments)\n\t* [Document author](#document-author)\n\t* [CSSG](#cssg)\n\t* [Helpers: TODO / FIXME](#helpers-todo--fixme)\n\t* [How to comment code](#how-to-comment-code)\n\t* [Preprocessor syntax specifics](#preprocessor-syntax-specifics)\n\t* [Mandatory commenting](#mandatory-commenting)\n\t* [To recap](#to-recap)\n* [Syntax \u0026 formatting](#syntax--formatting)\n\t* [Basic formatting](#basic-formatting)\n\t* [Grouping of properties](#grouping-of-properties)\n\t* [Vendor prefixes](#vendor-prefixes)\n\t* [Best practices](#best-practices)\n\t* [Indentation](#indentation)\n\t* [@-rules](#@-rules)\n* [Syntax using preprocessors](#syntax-using-preprocessors)\n\t* [Common formatting rules](#common-formatting-rules)\n\t* [Variables naming](#variables-naming)\n\t* [Variables maintenance](#variables-maintenance)\n\t* [Mixins](#mixins)\n\t* [Extends](#extends)\n\t* [Nesting](#nesting)\n* [What's next?](#what's-next?)\n\n\u003c!--mdMenu--\u003e\n\n-----\n\n## Intro\n\n\n### Why another Guide\n\nThere is quiet a number of style/code- guides already, that can be divided into:\n\n**General guides**\n\n- [Idiomatic CSS](https://github.com/necolas/idiomatic-css)\n- [CSS {guide: lines;}](https://cssguidelin.es)\n- [SUIT CSS (codestyle only)](https://github.com/suitcss/suit/blob/master/doc/STYLE.md)\n- [SASS guidelines](https://sass-guidelin.es)\n\nAddress the large audience, covering all (sometimes almost encyclopedic) aspects.  \nGreat for insight and common knowledge, but less practical.\n\n**Company|Team-specific guides**\n\n- [ThinkUp](https://github.com/ThinkUpLLC/ThinkUp/wiki/Code-Style-Guide:-CSS)\n- [Wordpress](https://make.wordpress.org/core/handbook/best-practices/coding-standards/css/)\n- [Trello](https://gist.github.com/bobbygrace/9e961e8982f42eb91b80)\n- [Github Primer](http://primercss.io/guidelines/#scss)\n\nMuch more specific instructions and recommendations, from the companies or individuals sharing experience with the community.  \nPractical for sure and make more sense if you work there.\n\nSo, why not just use one of them?  \nNot taking it any further, this current guide focuses on the subject, leaving aside general issues.  \nAt the same time it contains methodology-specific features, [BEM](https://en.bem.info/), in particular.  \nThe core of it is brevity and common practical experience.\n\nBut anyhow, it would be a great thing to at least take a look at other examples before proceeding!\n\n\n### About\n\nCouple welcome words about code guide specifics to take the most from using it:\n\n1\\. Documentation is written with regards on using CSS preprocessor. \nAs the most popular and widespread one, **[SASS](http://sass-lang.com/) (SCSS syntax)** is used for illustrating purposes.  \nPlease notice, that common conceptions are also valid for **vanilla CSS** in the first place.\n\n:bulb:  \nIf you are not into preprocessors yet, check out the following popular tools you will most certainly find useful:\n\n- [SASS/SCSS](http://sass-lang.com/)\n- [LESS](http://lesscss.org/)\n- [Stylus](https://learnboost.github.io/stylus/)\n- [PostCSS](https://github.com/postcss/postcss)\n\n2\\. Current code guide is the result of several front-end teams experience, so it might have project-specific and environment assumptions. To make it more friendly there will be plenty of useful links to cover blank spots and useful tips on some topics.\n\nHere's the legend:  \n:bulb: - useful tip  \n:zap: - warning or attention required  \n:page_with_curl: - code follow-up\n\n3\\. \"I'm reading and yet can not understand a thing!\". Well I've been there too. Let's have a talk about it. Waiting for [your questions](https://github.com/XOP/css-codeguide/issues)! \n\n4\\. Feedback is much appreciated as well!  \nOne of the main goals here is to help other front-end teams combat there problems with documentation. So don't hesitate and [contact](https://github.com/XOP/css-codeguide/issues) at ease.\n\n\n## Main principles\n\nAs it comes from the title, this chapter is about principal ways to do CSS.\n\nThere are **two major trends** nowadays.\n\n\n### The first \n\n...is the oldest school and thus most popular.  \nIt can be described with the following statements:\n\n- one or several stylesheets in the `\u003chead\u003e` via the `\u003clink\u003e` tag\n- `normalize.css` or `reset.css` prior to the main CSS\n- some rules may be inlined in `\u003cstyle\u003e` to deal with the _browser issues_ \n- the order of rules is extremely important \n- the cascade takes it's toll as well\n- inline styling is far less prominent and used only for specific features\n\n\n### The second\n\n...is heavily influenced by developing of JS frameworks, namely [React JS](https://facebook.github.io/react/) and the following spreading of corresponding CSS conceptions - [Radium](https://github.com/FormidableLabs/radium), [CSS modules](https://github.com/css-modules/css-modules) and some others.\n\nWhat is this all about?\n\n- CSS is controlled and maintained via JS\n- inline styles over traditional external ones\n- cascade and rules order almost do not matter\n\nIn fact, [here](https://speakerdeck.com/vjeux/react-css-in-js) is the presentation, covering all relevant moments.\n\n\n### What's more\n\nOf course different combinations of the mentioned practices exist and appear from time to time.  \nFurther in the guide we'll stick to the _classic_ approach.\n\nTwo reasons for backing this up:\n\n1. Traditional system is way more popular and requires more attention\n2. Second model is playing mostly on the JS field and slightly off the topic\n \nThis does not mean that supporters of the latter won't find anything useful here.  \nIn many ways CSS remains the same and these systems have many points of contact. \n\n\n## Methodology\n\n\n### Introduction\n\nIn a nutshell, CSS methodology prescribes _how CSS should be written_, therefore defining the scalability, maintainability and architecture in total.  \nIn fact, architecture is often named methodology and vice versa.\n\nIt also important to mention that this all does not make any sense if in the end results in productivity deterioration. Consider architecture in terms of convenience and development speed as well.\n\nThere is quiet a number of methodologies to choose from:\n- [OOCSS](https://github.com/stubbornella/oocss/wiki)\n- [BEM](http://getbem.com/)\n- [SMACSS](https://smacss.com/)\n- [Atomic CSS](http://acss.io/)\n- [Suit CSS](http://suitcss.github.io/)\n- [MCSS](http://operatino.github.io/MCSS/en/)\n\n...and this is only the majority.\n\nSome of them just provide rules and instructions, others propose the whole workflow to acquire.\n\nCurrent guide takes advantage of common [BEM principles](https://css-tricks.com/bem-101/) and also has few traits from [Suit CSS](http://suitcss.github.io/).\n\nIf you feel yourself pretty confident around methodologies and BEM in particular, jump right to [file-structure](#structure-of-сsspreprocessor-file) section.  \nNevertheless it is highly advised to go through this path of knowledge.\n\n\n### Basics\n\nThere's more than enough said about BEM, so it's no need to generate duplication.  \nOne important thing to remember, though: like everything else, BEM is a living system, approach, that deals with architecture issues. Since environments evolve, architecture adapts. And so does BEM (or other methodology of your choice).  \nIt has become very natural to see different takes on the same problem using same methodology.\n\n:zap:  \nThis is actually very important, because it helps to grasp further materials in depth.  \nSo don't mind to to read through that part again and again until it becomes clear.\n\n\n### Naming principles\n\nIn respect of naming patterns' variety (dashes, underscores, camel-/snake-/kebab-/etc- case) you may end up with hundreds of variations.\n\nThis is why it is important to define these fundamentals _before_ getting feet wet.\n\nThrough all the code there's **dash-binding syntax** being used:\n```\n.element\n.element-long-name\n```\n\nThe same applies to **element descendants** and everything else.\n\nCSS example: \n```css\n.media-component {\n}\n\n.layout-column {\n}\n```\n\nThis is also valid for the variables:\n\nSCSS example: \n```scss\n$color-brand-primary: yellow;\n\n$line-height-regular: 1.5;\n```\n\n:bulb:\nPlease note that variables'-specific naming principles fully covered in the [corresponding chapter](#variables-naming).\n\n**Child elements** are determined by '__' - separator:\n```\n.element__child\n.element__child-long-name\n.element__child__grandchild\n```\n\nCSS example: \n```css\n.section {\n}\n\n.section__text {\n   font-size: 12px;\n}\n```\n\nHTML example:\n```html\n\u003csection class=\"section\"\u003e\n    \u003cp class=\"section__text\"\u003e\n        \u003cspan class=\"section__text__icon\"\u003e\u003c/span\u003e\n        Section text\n    \u003c/p\u003e\n\u003c/section\u003e\n```\n\n\n### Modifiers and states\n\nTo help to get your head around the following:  \n**modifiers** - illustrate added or, well, _modified_ features of element   \nand **states** - are mostly about interactions.\n\nExamples:  \nModifiers: 'decorated', 'large size', 'secondary type' etc.  \nStates: 'disabled', 'in progress', 'hidden for user' etc.\n\n:bulb:\nIf you are not confident with the type of the feature - just use modifier and change it later when things get clear.\n\n**Modifiers** are determined by '--' - separator:\n```\n.element--mod\n.element--complex-name-mod\n```\n\nCSS example: \n```css\n.header--main {\n    background: red;\n}\n```\n\nHTML example:\n```html\n\u003cheader class=\"header header--main\"\u003eTitle\u003c/header\u003e\n```\n\n**States** are determined by `is-` namespace:\n```\n.is-state\n```\n\nCSS example: \n```css\n.button {\n}\n\n.button.is-disabled {\n    cursor: default;\n}\n```\n\nHTML example:\n```html\n\u003cbutton class=\"button is-disabled\"\u003eSorry, can't do\u003c/button\u003e\n```\n\nSo far it can be very tempting to use `.is-disabled` on it's own, though it shouldn't happen. Best way to guarantee this is prevent the states from having their own CSS rules. Use them only in combination with component classes.\n\nTo clarify some things:  \nModifier and State are the same things in terms of BEM, the only thing that differs is the semantics.  \nThis is the reason some other methodologies deviate from BEM pattern.\n\n:bulb:  \nThere are several ways to define modifier-/state- classnames as well!\n\nPattern A:\n```css\n.button {\n}\n\n/* modifier */\n.button--main {\n}\n\n/* state */\n.button--disabled {\n}\n\n/* also a state! */\n.button--is-disabled {\n}\n```\n\nPattern B:\n```css\n.button {\n}\n\n/* modifier */\n.button.--main {\n}\n\n/* state */\n.button.--disabled {\n}\n\n/* and another way */\n.button.--is-disabled {\n}\n```\n\nPros:  \nA - lesser specificity\nB - flexible application\n\nCons:\nA - hard times combining classes\nB - common namespace, harder to maintain\n\nRecommendations are pretty straightforward:  \nuse pattern A unless encounter a solid reason for switching to pattern B. \n\n:zap:\nThere's a bit more about states and modifiers. Check out the markup for the more complex example:\n\n```html\n\u003cdiv class=\"input [state]\"\u003e\n    \u003cdiv class=\"input__name [state]\"\u003e\n        Search\n    \u003c/div\u003e\n    \u003cinput class=\"input__element [state]\" type=\"text\" placeholder=\"Find\"/\u003e\n\u003c/div\u003e\n```\n\nFrom here there are two popular options for handling state change in CSS (consider the same logic for modification):\n\n- A - provide state for each component's descendant\n- B - stylize descendants depending on parent's state\n\nThis can be illustrated with the following code:\n\nPattern A:\n\n```html\n\u003cdiv class=\"input\"\u003e\n    \u003cdiv class=\"input__name is-disabled\"\u003e\n        Search\n    \u003c/div\u003e\n    \u003cinput class=\"input__element is-disabled\" type=\"text\" placeholder=\"Find\"/\u003e\n\u003c/div\u003e\n```\n\n```css\n.input__name {\n    color: #333;\n}\n\n.input__name.is-disabled {\n    color: #999;\n}\n\n.input__element {\n    background: #fff;\n}\n\n.input__element.is-disabled {\n    background: #aaa;\n}\n```\n\nPattern B:\n\n```html\n\u003cdiv class=\"input is-disabled\"\u003e\n    \u003cdiv class=\"input__name\"\u003e\n        Search\n    \u003c/div\u003e\n    \u003cinput class=\"input__element\" type=\"text\" placeholder=\"Find\"/\u003e\n\u003c/div\u003e\n```\n\n```css\n.input__name {\n    color: #333;\n}\n\n.input__element {\n    background: #fff;\n}\n\n.input.is-disabled .input__name {\n    color: #999;\n}\n\n.input.is-disabled .input__element {\n    background: #aaa;\n}\n```\n\nGeneral recommendation is to use Pattern A over Pattern B. However, in some situations (and this one in particular) Pattern B is more beneficial, since it's easier to maintain the code and control states. \n\n\n### Utilities\n\nAnother concept to grasp - **utility classes**.  \nWith some respect to Atomic CSS this is the last stand between your CSS and production code. In other words - they can override other CSS properties and you won't want to override them.\n\nBasic rule - they should complete only one simple task - hiding element, changing font-size - and nothing else. This means one-two declarations and generally no nesting.\n\nAnother rule - they can't be mixed with other classes or be included into other components - not in CSS.  \nPretty often they get assigned via JS.\n\nAnd finally, utilities should never be overwritten. Think about them in the key of somewhat `!important` value.\n\nUtilities are determined by `u-` namespace:\n```\n.u-hidden\n```\n\nCSS example: \n```css\n.u-hidden {\n    display: none;\n}\n\n.u-hidden-visually {\n    visibility: hidden;\n}\n```\n\nHTML example:\n```html\n\u003csection class=\"menu js-menu u-hidden-visually\"\u003e...\u003c/section\u003e\n```\n\n\n### JS interactivity\n\nJS-related classnames, which begin with the namespace `js-` are also called 'JS hooks' sometimes.  \nHooks are basically pointers or selectors and thus - can't have CSS rules applied to them.\n\nThe reason to use this approach is the separation of concerns. It's easier to debug and maintain the markup apart from the script logic.\n\nOf course, it's a bit different story when using frameworks like [React](https://facebook.github.io/react/) or [Angular](https://angularjs.org/), so this point can be just passed.\n\nCSS example: \n```scss\n// may present in stylesheet \n// but no styling applied\n// .js-test {}\n```\n\nHTML example:\n```html\n\u003ca class=\"link js-test\"\u003ePseudo-link\u003c/a\u003e\n```\n\nJS example:\n```js\ndocument\n    .querySelectorAll('.js-test')\n    .classList.add('u-hidden');\n```\n\nOne extra recommendation - use a descriptive classname enough. For instance, `.js-navigation` is just an element hook, whereas `.js-navigation-open` is pointing to a corresponding trigger of sort. \n\n\n### Mixins (not a preprocessor thing yet)\n\nMixing in terms of methodology means blending properties of one component to another.  \nSay, you have a _list item_, but you also need it to be _selectable item_.  \nThere are different ways of achieving this, certainly. \n\nThe \"mixin\" way allows to avoid extra styling. On the other hand, it's harder to maintain layout and there's probability of getting into code mess.\nAlso, if you rely on component approach, this is not what you need to acquire.\n\nDescription here is given for understanding principles. But this approach is **not recommended**.  \nSimply put - avoid until unavoidable.\n\nCSS example: \n```scss\n\n.list-item {\n    padding: 2rem 0;\n}\n\n.selectable-item {\n    outline: 1rem solid #f00;\n}\n\n.list-item.selectable-item {\n    outline-offset: 1rem;\n}\n\n```\n\nHTML example:\n```html\n\u003cul\u003e\n    \u003cli class=\"list-item selectable-item\"\u003e\n        List-Item selectable content\n    \u003c/li\u003e\n\u003c/ul\u003e\n```\n\n\n## Structure of СSS/preprocessor file\n\nCSS structure is the kernel of the architecture.   \nDifferent methodologies propose different ways of organizing CSS files.  \nPros and cons of these approaches are beyond the topic, so let's touch it slightly and focus on structure of single CSS file. \n\nPrinciples described below can be successfully adopted and integrated into existing system.\n\n\n### Files organizing\n\n:page_with_curl: **[Code follow-up](example/)**\n\nThe very basic option is to organize all code within _one_ file.  \nThis approach will work fine for small or/and one-time projects, that do not require maintainability whatsoever.\n```\nroot/\n    styles.css\n```\n\nFor the sake of the guide goals and sanity this approach is not considered any further.\n\nConsider file a CSS component.  \nComponents form the system:\n```\ncss/\n    navigation.css\n    header.css\n    layout.css\n    ...\n```\n\nLarge components may consist of multiple parts for the sake of readability:\n```\ncss/\n    header/\n        header-layout.css (*)\n        header-logo.css\n        header-navigation.css\n        ...\n    ...\n```\n(*) notice the main component prefix, \"header-\" in this case. This is optional, but may solve search issues in IDE.\n\nIt can also be convenient to separate core modules - \"atoms\" and \"molecules\" - components, that consist of other components *or* unique and used just once:\n```\ncss/\n    base/\n        icon.css\n        logo.css\n        navigation.css\n        ...\n    project/\n        shopping-cart.css\n        article-section.css\n        ...\n    ...\n```\n\nPure CSS modules rely on full encapsulation on all levels:\n```\ncss/\n   header/\n       header.css\n       Header.jsx\n   article/\n       article.css\n       Article.jsx\n   ...\n```\n\n\n### Code organization within a file\n\n:page_with_curl: **[Code follow-up](example/_component-1.scss)**\n\nOrganization here is mostly about [comments](#comments) and consistency.  \nGenerally, as you can see, CSS component structure is pretty straightforward:\n\n- [File data](#document-author)\n- Component title\n- [CSSG](#cssg)\n- [Variables](#variables)\n- Layout\n- Parts\n- Modifiers\n- States\n\nPlease notice, that except for Component title _all_ other parts can be omitted, according to the situation:\n\n**[File data](#document-author)** is the privilege of the team preferences, it might be excessive when working alone.\n\n**[CSSG](#cssg)** is not needed when component consists of one element and almost \"flat\" in terms of cascade.\n\n**[Variables](#variables)** have nothing to do with CSS yet (except for [--custom-properties](https://drafts.csswg.org/css-variables/)) and pretty much optional if there are no local overrides or any other local properties.\n\n**Layout** is basically a component wrapper or skeleton, which might have modifiers applied to the descendants. It makes most sense when component itself is relatively complex.\n\n**Parts**, **Modifiers** and **States** however are also optional, when component consists of one element, like button or link and relatively plain.\n\n:bulb: Media-query-specific rules are not decoupled from the main ones. There's more about media-queries handling in [one of the following](#@-rules) chapters.\n\n\n## Comments\n\nComments are _vital_ and sadly often underestimated.\n\nIn total, all code, that potentially might raise questions later, should be commented.  \nComments have to be short, capacious and up-to-date. Avoid excessive (unnecessary) commenting.\n\nThere are generally _two_ types of comments:  \n- Structural comments - were briefly introduced in [previous chapter](#code-organization-within-a-file)\n- All other comments - will be covered right away!\n\n\n### Structural comments\n\n:page_with_curl: **[Code follow-up](example/_component-1.scss)**\n\nThese comments help to keep your CSS (modules) organized, consistent and way more readable.\nConsider each inner level a deeper nested element or modifier - this metaphor helps to get the image.\n\n**Level 1** is typically a component / file title.\n\n```css\n/* Level 1\n---------------------------------------------------------------------------------- */\n\n/* code */\n\n/* /Level 1\n---------------------------------------------------------------------------------- */\n```\n\nAt the moment there might be questions:\n\n- where _exactly_ to place the code?\n- is the block padding a normal thing?  \n\nAs it comes to practical side - this is the matter of choice, habit and team preferences.  \nThis may work for you...\n\n```css\n/* Element title\n---------------------------------------------------------------------------------- */\n.element {\n    \n}\n/* /Element title\n---------------------------------------------------------------------------------- */\n```\n\n...as fine as this:\n```css\n/* Element title\n---------------------------------------------------------------------------------- */\n\n.element {\n    \n}\n\n/* /Element title\n---------------------------------------------------------------------------------- */\n```\n\nFor this code guide we'll stick with the **second** option.\n\nBut generally it does not matter.  \nChoose the style and stick with it. Working in team implies identical code-styling, and different code examples should look like written by one person.\n\n**Level 2** is for structure per se. Variables, Layout, component parts: Head, generic Right part, Content section etc.  \n\n```css\n/* Level 2\n-------------------------------------------------- */\n\n/* code */\n\n/* /Level 2\n-------------------------------------------------- */\n```\n\n**Level 3** and **Level 4** normally would be used seldom. However, you may consider them for more complex component structures, something like part of a part of a part.\n\n**Level 3:**\n\n```css\n/* Level 3 */\n\n/* code */\n\n/* /Level 3 */\n```\n\n**Level 4:**\n\n```css\n/* Level 4 */\n/* code */\n```\n\nCommon rules for structural comments:\n- Respect _level order_ - Level 2 should be placed only inside Level 1, Level 4 only inside Level 3 etc.\n- Indentation is prohibited, that means each new comment block organizes a \"caret return\" (this will be demonstrated later)\n\nTo improve readability use 2 whitespaces between level 1 and level 2 blocks. Use 1 whitespace between all others.  \nAgain, it's only a recommendation. Stick with what works best for you.\n\nHere is an example:\n\n```css\n/* Module\n---------------------------------------------------------------------------------- */\n\n/* Module - Core\n-------------------------------------------------- */\n\n.module {\n\n}\n\n/* /Module - Core\n-------------------------------------------------- */\n\n\n/* Module - Part 1\n-------------------------------------------------- */\n\n/* Base */\n\n.module__part-1 {\n\n}\n\n/* /Base */\n\n\n/* Modifications */\n\n.module__part-1--modifier {\n\n}\n\n/* /Modifications */\n\n/* /Module - Part 1\n-------------------------------------------------- */\n\n\n/* Module - Part 2\n-------------------------------------------------- */\n\n.module__part-2 {\n\n}\n\n/*/ Module - Part 2\n-------------------------------------------------- */\n\n/* /Module\n---------------------------------------------------------------------------------- */\n```\n\n:bulb:  \n\nIt's not convenient to type these slashes and dashes by hand or copy-paste the pieces of code all the time.  \nThere's a bunch of tools to bring fun to the boredom.\n\nFor instance, there are snippets from [IDE cross-project live templates repo](https://github.com/XOP/live-templates). Based on [Live Templates](https://www.jetbrains.com/idea/help/live-templates.html) they are compliant with most of [Jetbrains](https://www.jetbrains.com/) products.\n\n:zap: \n\nSnippets for Sublime Text is the work in progress.\n\n\n### Document author\n\nHaving this piece of code at the top of the file immediately answers many questions, especially when the file is to be seen for the first time.  \n\n```scss\n/**\n* author:       S Griffin | IM : contactme69 | e-mail : wdybih@gmail.com\n* spec:         http://link\n* created:      11/02/2013\n*\n* comments:\t\tIt's a nice example of CSS styleguide\n* @project class:\t.somecode\n* @project colors:\t#f0f0f0, #ffe1e1\n**/\n```\n\nSeems redundant, but you've got the idea.  \nLong intro is not always welcome (for instance in teams with _history_),\n so it's just a suggestion. Fields can easily be added ot removed at the every stage of code-style integration.\n\nThere's also a snippet for that in [live templates repo](https://github.com/XOP/live-templates).\n\n\n### CSSG\n\n[CSSG](http://cssg.rocks) stands for CSS-O-Gram, meta-language for documenting markup structure with CSS comments.\n\nThe main idea behind this conception is to bring extra transparency to the common CSS codebase.\n\nHere's an example:\n\n```css\n/*\ncssg\n\n\tmedia                       --special | --custom\n\t    media__header\n\t        ...\n\t        \n\t    media__content\n\t        a . media__link\n\t            \u003cicon\u003e\n\t            \n\t        media__text\n\t            ...\n\n*/\n```\n\nIt's pretty easy to start and hard to resist hereafter.\n\nSeems obvious now, but there's a snippet for that as well in the [live templates repo](https://github.com/XOP/live-templates).  \nIn fact, there's a common `bs` (bootstrap) template that just gets you ready with all basic things. \n\n\n### Helpers: TODO / FIXME\n\nMany IDEs obtain nice feature providing support (at least code highlighting) for TODO or FIXME comment keyword.\n\nThis code guide suggests providing additional info along with the directives.  \nConsider the following:  \n\n*Author name* - allows to easily detect responsible person, even having Git annotate.\n\n```css\n/*\n    TODO: stewie.griffin@acmecorp.com\n*/\n```\n\n*Crux of the matter* - allows get the whole picture with ease.\n```css\n/*\n    TODO: replace with variables\n*/\n\n/*\n    FIXME: this value does not belong here\n*/\n```\n\n*Due date* - it us pretty useful to understand the urgency or/and point of no return for this current code.\n```css\n/*\n    FIXME: 17.08.2015\n*/\n```\n\nOf course these things could be easily combined:\n```css\n/*\n    TODO: stewie.griffin@acmecorp.com - cleanup with the feature \"PhotoMarks\" - 21.09.2015\n    check and fix dependent components\n*/\n```\n\nOne extra healthy point here is to limit the number of **\"todo\"** expressions due to better organization.\n\n\n### How to comment code\n\nSo far it should be pretty clear how to create structure in CSS file, leave author notes and prepare ground for the code landing.  \n\nSince code appears, your main concern with regards to styleguide, will be code maintainability. Respect some basic rules and you will be safe:\n\n- leave comments to improve readability\n- avoid unnecessary comments that harm readability\n- too many 'TODO'-s - it's time to refactor the whole thing\n\nAlso, there is a couple of best practices, that worth mentioning:\n\n- always comment magic numbers and tricky approaches\n- separate variables' and values' concerns\n\nSome clarification is needed here:\n\n**Always comment \"magic numbers\" and tricky approaches**\n\nNot mentioning typical hacks, some rules deserve being noticed.\nIf values like `z-index: 14;` or `margin: -137px auto;` make total sense today - try to figure it out after a month (clue - you'll never do).\n\n```scss\n.project-class {\n    margin-top: 13px; // pixel-moving, probably?\n    font-size: 1.66rem; // reason for non-standard value\n    }\n```\n\n**Values and Variables - separation of concerns**\n\nWhen using variables it is important to pay attention to values that just _do not fit_.\nGenerally it's a _bad idea_ to combine variables with regular units.\n\nAvoid situations like this:\n\n```scss\n$offset = 10px;\n\n.project-class {\n    padding: $offset ($offset + 3px); // by design\n\t}\n```\n\n\n### Preprocessor syntax specifics\n\nPreprocessors introduce JS-style of comments:\n\n```scss\n/* traditional comment */\n.foo {\n}\n\n// \"inline\" comment\n.bar {\n}\n```\n\n\"Inline\" comments can be used in the absolutely same manner along with the \"block\" comments.\nPossible, but _not desired_ outcome of that:\n\n```scss\n//\n// Foo component\n.foo {\n    overflow: hidden !important; // need this to override inline\n\n    color: $color-main;\n\n\n    /* parent context */\n    .bar \u0026 {\n        padding: 1rem;\n    }\n}\n\n/*\n    todo: replace Foo with Tar\n*/\n.bar {\n    padding: 0 calc(100% - 980px); /* page restrictions */\n}\n```\n\nThis example is exaggerated on purpose.\nThe point is - to prevent visual pollution some code-guide conventions required.\n\nHere's the proposition:\n\n1. _Everywhere but inside_ of curly braces (consider \"rule scope\") use \"block\" comments. Practical examples can be found [earlier in this chapter](#structural-comments).\n2. On the contrary, use \"inline\" comments only _inside_ of curly braces. This will come more and more handy with intensive using of preprocessor features - nesting, \"\u0026\" - selection etc.\n\nWith this in mind, let's \"fix\" the previous example:\n\n```scss\n/* Foo\n-------------------------------------------------- */\n\n.foo {\n    overflow: hidden !important; // need this to override inline\n\n    color: $color-main;\n\n    // parent context\n    .bar \u0026 {\n        padding: 1rem;\n    }\n}\n\n/* /Foo\n-------------------------------------------------- */\n\n\n/* Bar\n-------------------------------------------------- */\n\n/* TODO: replace with Tar */\n\n.bar {\n    padding: 0 calc(100% - 980px); // page restrictions\n}\n\n/* /Bar\n-------------------------------------------------- */\n```\n\nDon't mind the \"\u0026\"-usage, nesting and all other formatting specifics yet.\nThis is the scope of the [following chapter](#syntax--formatting).\n\n\n### Mandatory commenting\n\nSome CSS rules _deserve_ to be commented. This practice has been proved by time.\nThere is pretty brief list of such rules, which sure is not dogmatic.  \nEach uncommented property is a time bomb, and the countdown exponentially speeds up with the project size.\n\nTake a look at the **recommended list** and feel free to augment it with the problematic properties of your choice.\n\n\n**`position`**  \nThis one seems pretty harmless right up to the moment of debugging nested containers case and having trouble putting some element to the uppper level.  \nWhilst `position: absolute / fixed / static` seems to be pretty self-explanatory, `position: relative` needs most attention.\n\nUsually it is sufficient to use comment like this:\n```scss\n.foo {\n    position: relative; // context for .bar\n} \n ```\n\n\n**`z-index`**  \nIt might be a good idea to keep track of all z-index usages with _Z-index map_, that can be simply a [variables](#variables-maintenance) set:\n```scss\n$z-index-base: 0;\n$z-index-dropdown: 500;\n$z-index-modal: 1000;\n$z-index-notification: 2000;\n```\n\n... or the map:\n```scss\n$z-index: (\n    base: 0,\n    dropdown: 500,\n    modal: 1000,\n    notification: 2000\n);\n```\n\nThus when met in code - they won't require extra comments.  \nHowever, this won't apply for the local context. Consider:\n```scss\n.foo {\n    position: relative; // context for .bar\n}\n\n.boo {\n    // ...\n}\n\n.bar {\n    position: absolute;\n    z-index: 1; // always above .boo\n}\n```\n\n\n**`margin (with negative value)`**  \nUsing negative values for margins implies something hacky that can't be achieved with normal simple methods. It requires as well a lot of attention and testing. It is better be documented as well.\n\n```scss\n.foo {\n    padding: $offset-n;\n    margin: -$offset-n; // compensating paddings\n}\n```\n\n\n**`overflow: hidden`**  \nOverflow is a \"no-way-back\" for some children elements. That's why in most cases it stands as the last hope for proper sollution. But generally it is not clear whether it's cropping the background or something different.\n\n```scss\n.bar {\n    // ...\n\n    overflow: hidden;\n    overflow-y: scroll;\n}\n\n.boo {\n    // ...\n\n    height: $boo-height;\n\n    overflow: hidden; // assuring the correct height\n}\n```\n\n\n**`translate3d(0)`** or **`-webkit-backface-visibility`**  \nGenerally it is recommended to move specific fixes as such to the preprocessor mixin. This will take care of all misunderstanding. If this is not possible, use comment to distinguish hacks from regular intentions.\n\n```scss\n.foo {\n    transform: translate3d(0); // fixes Chrome glitch ...\n}\n\n// or (preferred)\n\n.boo {\n    @include gpu-fix();\n}\n```\n\n\n### To recap\n\nFollow a common rule:\n\n\u003e _Do not_ rely on your memory or memory of your colleagues\n\nJust comment suspicious values.  \nThank yourself later.\n\n\n## Syntax \u0026 formatting\n\n### Basic formatting\n\ntodo: code follow-up\n\nLet's define the very basics for formatting.  \nMost of these rules are supported by linters in various IDEs:\n\n- 4 spaces for indentation step\n- new line for each declaration ('block'-notation)\n- new line for each selector\n- two lines between rules\n- every declaration ends with semicolon\n- single space between the property and value\n- no space between property name and semicolon\n- double quotes where needed (dropped for single font-family names)\n- prefer shorthands over multiple properties\n- curly braces: _opening_ on the line with selector, _closing_ on the new line after all rules\n- single space between selector and curly brace\n\nThis can be simply illustrated with the following code:\n\n```css\n.foo {\n    margin: 0;\n    padding: 1rem 2rem;\n    background: #333 no-repeat url(\"images/foo.png\");\n    font-family: \"Custom Font\", Arial, sans-serif;\n}\n\n.bar-first,\n.bar-second {\n    position: relative;\n    background: transparent;\n}\n\n.tar {\n    visibility: hidden;\n}\n```\n\n\n### Grouping of properties\n\nGrouping is one extra step on the organization ladder.\n\nThere are at least 3 possible ways to handle declarations in the rule scope:\n\n1. No particular order (that's not helping)\n2. Alphabetical order\n3. Grouping by some attribute\n\n**Alphabetical order** is the \"better than nothing\" option. It is mostly useful for developers who seldom touch CSS. But for the long run there is a room for improvement.\n\nGrouping of properties allow faster allocating of certain properties. Simply put, you know that \"position\" should be on top along with other position-related properties, i.e. \"top\", \"left\" etc. So you look for it in certain places instead of going through the list with no particular understanding.\n\nProperties can be divided into following groups or categories:\n\n1. Position\n2. Display\n3. Flex\n4. Box model\n5. Background\n6. Color\n7. Typography\n8. Visibility\n9. Transform\n10. Animation\n11. Anything else\n\nOf course there can be different exceptions, so feel free to extend the list basing on this starting point.\n\n...\n\n```css\n.class {\n\tposition: relative;\n\tright: 0;\n\tleft: 0;\n\tz-index: 77;\n\n\tdisplay: inline-block;\n\twidth:100%;\n\theight: 100%;\n\toverflow: hidden;\n\tmargin: 0;\n\tpadding: 4px 5px 5px;\n\n\tborder: #ccc solid 1px;\n\tborder-top-color: #999;\n\tbackground: #fff;\n\tbackground-image: url(/images/icon.png);\n\n\tcolor: #333;\n\tline-height: 15px;\n\tfont: 12px Arial, Helvetica, sans-serif;\n\t}\n```\n\n\n### Vendor prefixes\n\nIt is much better to rely on [autoprefixer](https://github.com/postcss/autoprefixer) with this one.\nAnyhow, here is recommended style:\n\n```css\n.foo {\n\t-webkit-user-select: none;\n\t-moz-user-select: none;\n\t-ms-user-select: none;\n\tuser-select: none;\n}\n\n.bar {\n\t-webkit-animation-duration: 1s;\n\tanimation-duration: 1s;\n\n\t-webkit-animation-name: myAnimation;\n\tanimation-name: myAnimation;\n}\n```\n\n\n### Best practices\n\nThe following list summarizes frequently used best practices for writing and maintaining CSS:\n\n- prefer `rem`-s or/and `pixel` values over `em`-s\n- prefer component approach over random and overall\n- keep component-specific styles in separate files\n- break-up complex components\n\nPreprocessor-related:\n\n- keep global variables in one or multiple _variable_-only files\n- avoid local/custom variables\n- if needed, keep them clearly commented and separated from globals\n- avoid variable mutations\n\n\n### Indentation\n\nTypically indentation used in stylesheets to illustrate the cascade, or how HTML is structured.\n\nSomething like this:\n```css\n.menu {\n    margin: 0;\n}\n\n    .item {\n        margin: 10px 0;\n        padding: 10px 20px;\n        \n        background: #ddd;\n    }\n    \n        .item a {\n            text-decoration: none;\n        }\n        \n            .item a:hover {\n                text-decoration: underline;\n            }\n```\n\nThis might work for a micro-stylesheet, but will fail in anything bigger, and here's why:\n\n- indentation system should stick to HTML structure, otherwise it will only be confusing, which makes maintaining a tedious task \n- reading comfort decreases with every other indented block, so everything after 3 indent levels considered hard to read\n- imagine appearing of wrapper for `menu` element, and remember to indent the whole structure in order to match the principles\n- hard times understanding whether it is the direct descendant of the element or a cascade taking place\n- and so on...\n\nGenerally, relying on the current guide principles, this recommendations will be out of scope. [Component approach](), [BEM naming principles]() and even [CSSG]() make indentation totally useless.\n\nRevised version of the same code sample could look like (structural comments dropped for brevity):\n```css\n/* \ncssg\n\nmenu\n    menu__item +\n\n        item\n            a . item__link\n*/\n\n.menu {\n    margin: 0;\n}\n\n.menu__item {\n    margin: 10px 0;\n}\n\n.item {\n    padding: 10px 20px;\n            \n    background: #ddd;\n}\n\n.item__link {\n    text-decoration: none;\n}\n\n.item__link:hover {\n    text-decoration: underline;\n}\n```\n\nConsider using preprocessor, isolating code in separate files and you'll never want to use traditional indentation again.\n\n:bulb: if you are using vanilla CSS, the following tip might be helpful:\nUse indentation only for pseudo-elements, pseudo-classes and in context- (browser-) specific cases.\n\nNotice also, that there is no empty line between main selector and descendants.\n \n```css\n.item {\n    padding: 10px 20px;\n            \n    background: #ddd;\n}\n\n.item__link {\n    text-decoration: none;\n}\n    .item__link:before {\n        content: \"link: \";\n    }\n    .item__link:hover {\n        text-decoration: underline;\n    }\n        .item__link:hover:before {\n            color: transparent;\n        }\n        \n.item__image {\n    padding: 10px;\n}\n```\n\n\n### @-rules\n\nThere is nothing extraordinary about syntax here. Same indentation, formatting etc. with only one extra indentation level.\n\nTypical example:\n```css\n.item {\n    flex: 1 0 100%;\n}\n\n@media screen and (min-width: 40em) {\n    .item {\n        flex: 1 1 auto;\n    }    \n}\n```\n\nOr:\n```css\n.foo {\n    border: 1px solid black;\n    padding: 1px;\n}\n\n@supports (box-shadow: 0 0 2px black inset) {\n    .foo {\n        box-shadow: 0 0 2px black inset;\n        \n        /* override the rule above the @supports rule */\n        border: none;\n        padding: 2px;\n    }\n}\n```\n\nRegarding `@media`-rules there are two simple practices of writing:\n\n1. Specific rules for each selector (as in the first example)\n2. Common block for all selectors in the end of file or logical section\n\nGuidance here is simple as well: use the first approach until second one is _required_. Usually the latter is less convenient and more error-prone.\n\n\n## Syntax using preprocessors\n\nAs it was [mentioned](#about), this documentation is written with regards of [SASS](http://sass-lang.com/) (SCSS syntax) syntax. \n\nNowadays it's hard to imagine writing and maintaining CSS without preprocessor engaged. It's a powerful tool for everyday frontend development. However, power is also responsibility, so it is important to sustain balance of productivity and language intricacy. \n\nGuide recommendations is to limit usage of preprocessor features to the following (in order of relevance):  \n\n- Variables\n- Nesting (\\\u0026 - specific syntax)\n- Mixins (includes)\n- SASS helper functions\n\n:page_with_curl: Check the [examples folder](example/) for the descriptive code samples. [Variables](example/_variables.scss) and [Mixins](example/_mixins.scss) will be used through this chapter as well. \n\n\n### Common formatting rules\n\nFollowing SCSS syntax, preprocessor formatting is mostly identical to the [CSS syntax](#basic-formatting).\n\nHere is the basic example of preprocessor syntax ([structural comments](#structural-comments) are dropped for brevity):\n\n```scss\n.component-name {\n    @include trunc();\n    \n    margin: $offset-n 0;\n    padding: $offset-xs;\n    \n    color: $color-text;\n    \n    \u0026:hover {\n        color: $color-text-light;\n    }\n}\n\n.component-name__descendant {\n    text-decoration: underline;\n}\n```\n\nHere is somewhat complex version of this example:\n\n```scss\n.component-name {\n    @include trunc();\n    \n    position: relative;\n    \n    margin: $offset-n 0;\n    padding: $offset-xs;\n    \n    color: $color-text;\n    \n    \u0026:hover {\n        color: $color-text-light;\n    }\n    \n    // component overlay\n    \u0026:after {\n        @include cover();\n        \n        content: \"\";\n        \n        display: none; // hidden on mobile\n    }\n    \n    @include respond($mq-desktop) {\n        \u0026:after {\n            display: block;\n            \n            background: opacify($color-brand-secondary, .8);\n        }\n    }\n}\n\n.component-name__descendant {\n    text-decoration: underline;\n    \n    @include respond($mq-desktop) {\n        font-size: $font-size-l;\n    }\n}\n```\n\nCompared to the CSS formatting, there are some differences, or better say, complements:\n\n- variables' usage\n- mixins' usage\n- sass functions' usage\n- nesting specifics\n\nWe'll go through all these points in the following sections.\n\n\n### Variables naming\n\n:bulb: Depending on the preprocessor, variable name might need to begin with the key symbol, like `$` or `@`. In [Stylus](http://stylus-lang.com/docs/variables.html), however, this is optional. Due to the SASS syntax let's stick with the `$`-based naming.\n\nIt makes more sense for variables naming to inherit from [classnames naming](#naming-principles), following the same methodology pattern. Here is the basic example:\n\n```scss\n$color-light: #666;\n\n$font-size-s: .6rem;\n\n$offset-xxl: 4rem;\n```\n\nThe naming pattern is:\n```\n[$]-[property-name]-[type] \n```\n\nIt can be extended further according to the project needs:\n```scss\n$color-main-dark: #3a1101;\n```\n\nor\n\n```scss\n$bg-color-secondary-75: #ea02dd;\n```\n\n...following the pattern:\n```\n[$]-[property-name]-[type]-[grade]\n```\n\nThe latter might be more applicable to colors, since they are tricky to handle and usually require diverse approach.\n\nVariables can be used to define another variables! This may be useful for creating offset- or typographic- system. A piece of a good advice will be - keep at simple, avoid complicated calculations.\n\nOne of the best practices of using variables for defining variables will be (no big surprise!) creating color scheme.\n\n\n### Variables maintenance\n\ntodo\n\n:bulb: Some complicated calculations might require local variables usage. In order not to mess with global variable namespace better idea would be to encapsulate them: \n\n```scss\n.textarea {\n    $textareaSumHeight: 3 * $font-size-n * $line-height-regular + (2 * $offset-s);\n    $textareaSumBorderWidth: 2 * $form-border-width;\n    \n    @include form-element();\n    \n    height: calc(#{$textareaSumHeight} - #{$textareaSumBorderWidth});\n    padding: $offset-s;\n    \n    width: 100%;\n}\n```\n\nPlease mind the order of local variables. They should be defined at the very top of the declarations list.\n\nNaming is also different (camelCase in this, hm, _case_, but can be any other). The main intention is to differ local vars from the globals. This also can be achieved with the prefixes.\n\n\n### Mixins\n\nMixins (paired with includes) are pretty useful and often save the day. To maintain your stylesheets _sane and clear_ keep close to this set of rules:\n\n- Mixin should do _one thing_ and do it good\n- Avoid large set of parameters (up to 3 is optimum)\n- Provide defaults for the variables\n- Use them wisely: restrain amount of available helpers to a minimum\n- Avoid one-line mixins\n\n**Good** example:\n\n```scss\n@mixin cover ($position: absolute) {\n    position: $position;\n    top: 0;\n    bottom: 0;\n    left: 0;\n    right: 0;\n    }\n```\n\n**Not good** examples:\n\n```scss\n// many variables to handle\n@mixin common-font ($font-family, $font-size, $line-height, $font-style) {\n    font: $font-style #{$font-size}/#{$line-height} $font-family, sans-serif;\n}\n\n// no default value\n// name does not match the function\n@mixin color ($color) {\n    color: $color;\n    background-color: black;\n}\n\n// single-line mixin\n@mixin float-left () {\n    float: left;\n}\n```\n\nHere's usage examples illustrating formatting specifics:\n\n```scss\n.foo {\n    @include cover(fixed);\n    \n    z-index: $z-index-modal;\n}\n\n.bar {\n    @include cover();\n    @include trunc();\n    \n    color: $color-text-light;\n}\n\n.tar {\n    color: $link-color;\n    \n    \u0026:hover {\n        @include link-hover();\n        \n        color: $link-color-hover;\n    }\n}\n```\n\nStick to the rules: \n\n- Define includes on top of the declaration list\n- 1 blank line between includes and other code\n- Same is valid for the nested elements\n\n:zap: There can be an exception to the common practice! Consider the mixin, containing `media-query` rule - in most cases you won't want it to be on top of the ruleset. To separate them from the others, you might want to introduce special namespace, like `media-[mixin-name]`. \nBut usually they just stand out due to their syntax:\n \n ```scss\n .foo {\n    @include cover();\n    \n    padding: 2rem;\n    \n    @include media-respond-to($breakpoints-desktop) {\n        padding: 4rem;\n    }\n }\n ```\n\n\n### Extends\n\nAs it was noticed, **mixins** are preferred over **extends**.\n\nWhy is that?\n\n_Basically_, for saving yourselves from debugging convoluted code. Extends backed by nesting often lead to something excessively unwelcome.\n\nSo if there is no _really hard_ need, avoid using extends.\n\n:bulb: What's more? In short, it is all about the strings repeatability and compression algorithms. Fact is, mixins provide a lot of repeating code blocks here and there, which altogether result in bigger size of uncompressed CSS file compared with the same file, generated with the help of extends. But results of the gzip-compressed files are the opposite, because of gzip specifics.\n[Here is great article](http://csswizardry.com/2016/02/mixins-better-for-performance/) covering other valuable points.\n\nHere is the list of articles totally worth reading before touching extends:\n\n- [When to use @extend; when to use a mixin](http://csswizardry.com/2014/11/when-to-use-extend-when-to-use-a-mixin/)\n- [Sass Mixins vs Extends: The Data](https://tech.bellycard.com/blog/sass-mixins-vs-extends-the-data/)\n- [Why You Should Avoid Sass @extend](http://www.sitepoint.com/avoid-sass-extend/)\n\n\n### Nesting\n\nAvoid using unnecessary nesting and deeper than **3** levels. We use nesting only for:\n\n* Pseudo elements\n* Context classes\n* Refactoring/redesign issues\n\nAll other cases rely on MCSS. One more thing we want to mention is never use composite class names using nesting.\nIt makes impossible to find classes in your project.\n\n```scss\n/* awful */\n.module {\n    ...\n\n    \u0026_block {}\n}\n\n/* bad */\n.module {\n    ...\n\n    .module_block {}\n    }\n\n.module:after {\n    ...\n    }\n\n.module_block:hover {\n    ...\n    }\n\n/* good */\n.module {\n    ...\n\n    \u0026:after {\n        ...\n        }\n    }\n\n    .module_block {\n        \u0026:hover {\n            ...\n            }\n        }\n```\n\nDo not use `\u0026` as a child in nesting except context classes.\n\n```scss\n/* bad */\n.block {\n    .module \u0026 {\n        ...\n        }\n    }\n\n/* good */\n.block {\n    .ie9 \u0026 {\n        ...\n        }\n    }\n```\n\nSometimes you make refactoring/redesign of some code. Common practice for that is to use modificators, such as `__v2` or `__redesign`.\nIn this way you can use nesting for all selectors inside. Also it is possible to use `\u0026` before selectors to show this is nesting.\nJust choose your own way and follow it everywhere.\n*Note: We are not using `\u0026`.*\n\n```scss\n/* good */\n.block.__v2 {\n    // ...\n    // very long code, we don't see parent on the screen\n\n    .module {\n        ...\n        }\n\n    // ...\n    }\n\n/* good */\n.block.__v2 {\n    // ...\n    // very long code, we don't see parent on the screen\n\n    \u0026 .module {\n        ...\n        }\n\n    // ...\n    }\n```\n\nDo not use structural comments inside nesting. If you want to do that - check out your logic, something wrong with it.\n\n```scss\n/* bad */\n.block {\n    /* Module\n    -------------------------------------------------- */\n    .module {\n        ...\n        }\n    /* /Module\n    -------------------------------------------------- */\n    }\n\n/* good */\n/* Module\n-------------------------------------------------- */\n.block {\n\n    .module {\n        ...\n        }\n\n    }\n/* /Module\n-------------------------------------------------- */\n```\n\n\n\n\n## What's next?\n\nCongrats, you did it, great job!\n\nI hope you did some notes along the reading or even implemented some best-practices described here. If not - here's a nice starting list of what you can start or proceed with:\n\n- Analyze your (your team) needs. Through the flaws and error-prone areas in your code get the list of what has to be improved in the first place.\n- Remember your product needs and environment specifics! You most probably will not need _all_ techniques and features from this document.\n- Start with module approach. Break your code into smaller chunks until it feels right and comfortable.\n- Consider methodology (BEM or BEM-specific of your choice) your companion on this not-so-light path.\n- Choose the preprocessor. SCSS is the main recommendation.\n- Establish a set of mixins that your modules can share.\n- Incorporate tools for linting your CSS. Generally it takes some time to make it look fit for the first time. But later on it goes smoothly!\n\nAnd the last, but simply the **most important thing**, that defines the success:\n\n\u003e Common code should look like it has been written by one person.\n\n\n-----\n\nThank you for reading!\n\nThis is the living document, content is regularly updated, so come back in a month or so. And [star or watch](https://github.com/XOP/css-codeguide) this thing just in case!\n\nYour questions are welcome in the [issues](https://github.com/XOP/css-codeguide/issues). You also can try reach author and main maintainer via [email](mailto:stewiekillsloiss@gmail.com).\n\nContent of the current guide is under [MIT License](LICENSE).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxop%2Fcss-codeguide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxop%2Fcss-codeguide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxop%2Fcss-codeguide/lists"}