Style Guide: CSS (SCSS)

Architecture

All CSS/SASS files are located in app/assets/stylesheets/.

Stylesheets are further divided by layout and are located in the respective layout's folder. For example: app/assets/stylesheets/tylium

Within the layout folder, you will typically see 3 main directories:

• /SMACSS
  • We use a modified SMACSS (Scalable and Modular Architecture for CSS) framework to organize our CSS files. It is split into 4 categories as follows:
  • Base - These are the default styles across the entire app. Examples are: html, body, a, a:hover, h2, text, buttons, etc.
  • Layout - These styles divide the page into sections. Layouts hold one or more modules together. Examples are: main, footer, etc.
  • Module - These are the reusable styles and modular parts of our design. They are the alerts, the sidebar sections, navbar, forms, and so on. There is a corresponding /modules directory within the /smacss directory that contains styles for each individual module.
  • Variables - This are where we keep SASS variables, mainly for colors, padding, margins, fonts, etc.
• /vendor
  • This directory contains any CSS files not written by us, such as Bootstrap.
• theme.scss
  • This is the stylesheet manifest that is referenced in HTML and contains imports of all other stylesheets like SMACSS, Bootstrap, Font Awesome, etc.

Note: If the stylesheet is shared by multiple layouts (ie: Tylium, Application, and/or Setup, etc) the stylesheet is located in: app/assets/stylesheets/shared

Code

• Reference colors using the variables found in /smacss/variables.scss
• Sort selectors in CSS files alphabetically regardless if the selector is an element, class, attribute, or pseudo-selector (where it doesn't interfere with the order of the cascade)
• Don't use the id as a selector - it adds unnecessary specificity
• Sort all properties alphabetically so we naturally end up with alpha-ordered declaration blocks.
• Try your best to avoid using !important;, instead re-visit the CSS to see if it can be optimized.
• Do not use inline style attributes
• Avoid using px units and instead use rem/em/ch/etc
• To assign an image to a background do not use:

.some-class {
  background: url(/assets/image.png);
}

Instead, use:

.some-class {
  background: image-url('image.png');
}

• To reference a font, do not use:

@font-face {
   font-family: 'SomeFontName';
   src: url('SomeFontName.ttf');

Instead, use:

@font-face {
   font-family: 'SomeFontName';
   src: font-url('SomeFontName.ttf');