SCSS style guide for creating and organising SCSS files in a project

1. 10/5/2016 Home · Wiki · uicoe / eg-empact-scss-styleguide · GitLab
http://dolnxprodvm1036/uicoe/eg-empact-scss-styleguide/wikis/home 1/5
Home (/uicoe/eg-empact-scss-styleguide/wikis/home)
Pages (/uicoe/eg-empact-scss-styleguide/wikis/pages)
Git Access (/uicoe/eg-empact-scss-styleguide/wikis/git_access)
Home · last edited by Karthikeyan Rajendran 8 months ago
A reference style guide to develop robust stylesheets in SCSS using any front-end framework
The point of having this style guide is to have a common vocabulary of coding across Emirates
projects, so people (esp. UI devs) can concentrate on what you’re saying rather than on how you’re
saying it. If the code you add to a file looks drastically different from the existing project code, it
throws the devs out of their rhythm when they go to read it. Avoid this.
If you’re editing the code, take a few minutes to look at the code around you and determine its style.
1. General Principles
2. Folder Structure
3. Importing Files
4. Naming conventions
5. Handling Breakpoints
6. Nesting
7. Categorizing CSS-Rules
Todo:
1. Comments
1. Consistent Indentation: 2 spaces per block
2. Consistent spacing before/a er braces/colons
3. One selector per line, one rule per line
4. List related properties together, follow CSS Modal: refer Categorizing CSS-Rules ( width/height,
margin/padding etc.)
5. Use SASS variables as per reusability
6. Remove any Trailing white-spaces as it can complicate diffs.
EG SCSS Style Guide
Table of Contents
General Principles

2. 10/5/2016 Home · Wiki · uicoe / eg-empact-scss-styleguide · GitLab
http://dolnxprodvm1036/uicoe/eg-empact-scss-styleguide/wikis/home 2/5
7. Closing brace should be on it's own line.
8. Avoid ID selectors & child selectors
9. Avoid !important
Try using the EG-SASS-SMACSS (http://dolnxprodvm1036/uicoe/eg-empact-smacss) folder
structure only if you are staring a fresh project.
Ignore the EG-SASS-SMACSS directory structure if you are writing styles for components, follow a
modular structure (eg: angular-seed structure) to maintain all the dependencies within the
components. Most importantly, provide a importable link from the components to the project’s
vendor/component structure.
If you have a big project with much modules and variants, then you come to the point to make
thoughts about the current structure. You blow up your file with a bunch of code and it's hard to
maintain it.
Because of this we need a small improvement of the structure and add some folders if you noticed,
that your module need to much lines of code. Then make more small partials and include it in one
main-file for this module.
If a project has multiple partials/template in a given module, always prefer to have one single file
like all.scss or index.scss indexed to the main-file main.scss and then include all
partials/templates. For this I created a structure like in this example:
// MAIN.scss
@import "search/all";
// search/_all.scss inside Search Module
@import "search.css",
"search_summary",
"search_results";
Structure in base, layouts and modules
For each section declare @import only once
Remove file-ending
Use BEM for naming conventions as its gives a lot of flexibility and readability down the line in a
huge project with multiple UI developers pushing out code. SMACSS makes sense on how to
structure and maintain a project, where as BEM relates as the code goes, BEM defines a set or rules
that makes life easier when it comes to reusability and maintainability of the existing code.
Combining these two methods is the best way for a huge team to handle naming conventions.
Folder Structure
Importing files
Brief :
Naming conventions (BEM)
Block, Element, Modifier

3. 10/5/2016 Home · Wiki · uicoe / eg-empact-scss-styleguide · GitLab
http://dolnxprodvm1036/uicoe/eg-empact-scss-styleguide/wikis/home 3/5
// Layouts
// Prefix "l-"
.l-default {}
// Modules
// Prefix "m-"
.m-accordion {}
// Child element of accordion
// Seperator: "__"
.m-accordion__trigger {}
// Modifier of accordion
// Seperator: "--"
.m-accordion--plain {}
// States
// Mostly with prefix like "is-"
.is-active {}
.is-hidden {}
"Element Queries" with Sass are so much better than traditional media queries. If you want to the
custom module to be responsive, you should declare the responsive behavior of it there itself, Not
in another file.
// Scss
.m-nav {
&:after {
@media screen and (min-width: $tab-breakpoint) {
content: '';
display: inline-block;
width: 100%;
}
}
li {
display: block;
@media screen and (min-width: tab-breakpoint) {
float: left;
}
}
}
Avoid writing new media queries if you are using any framework which has grid systems in it. Follow
the grid style which the framework uses rather than inventing a new grid system or writing vanilla
code for responsive design.
Handling Breakpoints: Element Queries
Nesting

4. 10/5/2016 Home · Wiki · uicoe / eg-empact-scss-styleguide · GitLab
http://dolnxprodvm1036/uicoe/eg-empact-scss-styleguide/wikis/home 4/5
Maximum nesting: three levels deep. Do not make the styles too reliant on HTML structure
(fragile), overly specific (too powerful), and not very reusable (not useful). It's also on the edge of
being difficult to understand & maintain.
The CSS code should be consistent and should be as per the CSS modal rules:
// Element-Base
.element {
margin: 10px;
padding: 10px;
border: 1px solid red;
background: blue;
color: white;
font-size: 16px;
-webkit-transform: translate3d(0,0,0);
}
Box
margin , padding , display , etc.
Border & Background
border , border-radius , background-color and so on
Text
color , font-size , text-transform , etc.
Other stuff
animations , transform 's, ...
Planning to implement SASSDoc (http://sassdoc.com/).
Categorizing CSS-Rules
Comments (Sassdoc)

5. 10/5/2016 Home · Wiki · uicoe / eg-empact-scss-styleguide · GitLab
http://dolnxprodvm1036/uicoe/eg-empact-scss-styleguide/wikis/home 5/5