- Introduction
- Syntax & Formatting
- Architecture / Folder Structure
- Importing Files
- Comments
- Naming Conventions
- Tools
- Other
All CSS is written in Sass (SCSS)
### Acknowledgements This guide is a combination of opinion, experience, and a lot of borrowing. Below are articles and resources that have influenced these guidelines. - [SASS Guidelines](https://sass-guidelin.es) - [Airbnb CSS / Sass Stylegguide](https://github.com/) - [codeguide.co](http://codeguide.co) - [cssguidelin.es](http://cssguidelin.es) ## Syntax & Formatting ### Whitespace & Punctuation - Use soft tabs with two (2) spaces. No hard tabs. - Try to keep lines short. Less than 80 characters is ideal - Include line breaks between new elements and styles - Use single quotes (') instead of double quotes (") ### CSS Ruleset (Slightly modified from [cssguidelin.es](http://cssguidelin.es/#anatomy-of-a-ruleset) & [sass-guidelin.es](https://sass-guidelin.es/?ref=producthunt#syntax--formatting)- each selector on its own line
- the opening brace ({) spaced from the last selector by a single space
- each declaration on its own new line
- a space after the colon (:) (exception if you are declaring variables and using align-by)
- a trailing semi-colon (;) at the end of all declarations;
- the closing brace (}) on its own new line;
- a new line after the closing brace }.
// Bad
.alpha, .beta,
.gamma {
display: inline-block;
margin: 0 auto;
padding: 0}
// Good
.alpha,
.beta,
.gamma {
display: inline-block;
margin: 0 auto;
padding: 0;
}
// Bad
.alpha {
display: inline-block;
margin: 0 auto;
padding: 0;
@extend %property;
@include container;
@media (max-width: 600px) {
display: none;
}
.nested {
...
}
&::before {
…
}
&:hover,
&:focus,
&.is-active {
…
}
}
// Good
.alpha {
@extend %property;
@include container;
display: inline-block;
margin: 0 auto;
padding: 0;
&:hover,
&:focus,
&.is-active {
…
}
&::before {
…
}
.nested {
...
}
@media (max-width: 600px) {
display: none;
}
}
This guide does not state a preferences for declaration sorting. THis can be left up to the individual (random, alphabetical, type etc)
### Nesting - Avoid selector nesting as much as possible. - Avoid using neseting to create clever BEM naming conventions. Simply create a new declaration. - If nesting is necessary, avoid nesting any more than 3 levels deep - It is better to create a new class than to nest several layers. This will keep code readable and maintainable. - An exception is that you can and should nest pseudo elements, pseudo classes and state hooks ## Architecture / Folder Structure The recommended folder structure is a variation of the The 7-1 Pattern. File partials should have an underscore (_) at the beginning of the file name so that it is obvious that they are partials. ```scss scss/ |- util/ | |-mixins // Folder of mixins to keep things modular | | |- _math.scss | | |- z-index.scss | |- _util.scss | |- _mixins.scss //calls everything in /mixins | |- ... | |- base/ | |- _typography.scss | |- _variables.scss | |- _body.scss | |- _fonts.scss | |- ... | |- Components/ | |- _buttons.scss | |- _carosusel.scss | |- ... | |- _layouts/ | |- _grid.scss | |- _header.scss | |- _footer.scss | |- _navigation.scss | |- ... | |- _pages/ | |- _home.scss | |- _contact.scss | |- ... | |- _vendor/ // NPM is preferable, but vendor items can go here | |- _normalize.scss | |- ... | |- shame.scss // Crappy CSS/SCSS that should be fixed at a later time |- style.scss // Main scss file that imports everything ``` ## Importing Files// example:
@charset 'utf-8';
// Dependancies & Utilities
@import 'util/mixins';
@import 'util/util';
@import 'util/whitespace';
Things to note:
- Declare
@charset 'utf-8'
at the top of the main file because reasons - Provide a short title for the various sections (base, components, etc)
- file extensions and leading underscores should be omitted
- Declare variables, then vendors, then utilities, then everything else
Stylesheet header:
// ----------------------------------------------------------------------------
// Header
// ----------------------------------------------------------------------------
Section Title:
// Variables
// -------------------------
Documentation (located just under the stylesheet header):
/**
This is to help create a simple system for whitespace for blocks. It needs a
single variable: $whitespace
Shorthand Description:
m Margin
p Padding
...
EX: (assuming $whitespace = 12px)
.mt4 == margin-top: 48px;
.pl1 == padding-left: 12px;
.py2 == padding-top: 24; padding-bottom: 24px;
...
*/
Resources to learn more:
Example:
<div class="hero hero--featured">
<h1 class="hero__title">This is a title</h1>
<h2 class="hero__subtitle">
This is a subtitle
</h2>
</div>
<ul class="main-nav">
<li class="main-nav__item">
<a class="main-nav__link">
test
</a>
</li>
</ul>
.hero { ... } // block
.hero__title { ... } // element
.hero__subtitle { ... } // element
.hero--featured { ... } // modifier
.main-nav { ... } // block
.main-nav__item { ... } // element
.main-nav__link { ... } // modifier
As shown in the example above, you do not need to chain elements names (ex: main-nav__item__link). Elements can share a block, but be nested in other elements. Chaining element names is discouraged.
### Variables Variable names should be dash-cased. Avoid underscore and CamelCase. Variables that are used within the same file should start with an underscore: (eg: $_variable) ```scss // Bad: $font_size: 12px $FontSize: 12px//Good: $font-size: 12px;
<a name="id"/>
### ID Selectors
ID selectors are not reusable and should never be necssary. Avoid them.
<a name="autoprefixer"/>
### Autoprefixer
Never write vendor prefixes in your code. Use Autoprefixer when compiling your Sass to handle that for you.
<a name="jshooks"/>
### JS Hooks
Avoid using the same class for both css and JavaScript.
Prefix JavaScript specific classes with ```.js-```
```html
<button class="button-primary js-purchase">
State hooks should always be scoped to the selector they are being applied to.
For example:
.nav-menu__link {
color: #fff;
&.is-active {
color: #000;
}
Which compiles to:
.nav-menu__link {
color: #ffffff
}
.nav-menu__link.is-active {
.color: #000000
}
An editor config file (.editorconfig) is included to help maintain consistency between files and developers. You will need to install a package for your text editor to utilize. It has been customized to maintain rules such as:
- indent size of 2 spaces
- indent style = space
- ...more