Three 11 Flows

# CSS Conventions

# 1.1 Class names

  1. Keep classes lowercase and use dashes (not underscores or camelCase). Dashes serve as natural breaks in related class (e.g., .btn and .btn-danger).

    /* Bad example */
.pageHead {
}
.sub_content {
}

    /* Good example */
.page-head {
}
.sub-content {
}

  2. Class Naming/ BEM Convention (opens new window)

  • Avoid excessive and arbitrary shorthand notation. .btn is useful for button, but .s doesn't mean anything. Keep classes as short and succinct as possible.
  • Use meaningful names; use structural or purposeful names over presentational.
/* Bad example */
.t {
}
.red {
}
.big {
}

/* Good example */
.article {
}
.article__title {
}
.nav {
}
.nav-primary {
}
  • Use BEM methodology(block__element--modifier).

block
block--modifier
block__element
block__element--modifier

  1. Use .js-* classes to denote behavior (as opposed to style), but keep these classes out of your CSS.
/* example */
.js-scroll {
}
.js-toggle {
}
  1. Not location-based.

Never use location-based styling. This means a block is never styled different because it is within another block. Objects should have "modifiers" instead of location-related styles .block--large {} instead of #sidebar .block {}. When styling block, keep styles encapsulated, this mean: don't add styles for this block on it's elements through other selectors example for .nav:

/* Bad example */
ul .nav {
}
div .nav {
}
header .nav {
}

/* Good example */
.nav {
}
.card {
}
.intro {
}

# 1.2 Styles Declaration order

  1. Related property declarations should be grouped together following the order:
  • Positioning
  • Box model
  • Typographic
  • Visual
  • Misc
.declaration-order {
	/* Positioning */
	position: absolute;
	top: 0;
	right: 0;
	bottom: 0;
	left: 0;
	z-index: 100;

	/* Box-model */
	display: block;
	float: right;
	width: 100px;
	height: 100px;

	/* Typography */
	font-family: 'Helvetica Neue', sans-serif;
	font-size: 13px;
	font-weight: 700;
	line-height: 1.5;
	color: #333;
	text-align: center;

	/* Visual */
	background-color: #f5f5f5;
	border: 1px solid #e5e5e5;
	border-radius: 3px;

	/* Misc */
	opacity: 1;
}
  1. Positioning comes first because it can remove an element from the normal flow of the document and override box model related styles.
  2. The box model comes next as it dictates a component's dimensions and placement.
  3. Everything else takes place inside the component or without impacting the previous two sections, and thus they come last.

# 1.3 Positioning components within containers

  1. Components within a container shouldn’t care about their positioning at all.
  2. The container should position the components it contains.This also means that containers are in charge of spacing their components away from each other properly. E.g. by using flex-box.

# 1.4 ITCSS Conventions

based on ITCSS (opens new window)

  1. Settings – used with pre-processors and contain fonts, colors definitions, etc. or so called variables.
  2. Tools - globally used mixins and functions. It’s important not to output any CSS in the first 2 layers.
  3. Generic - reset and/or normalize styles, box-sizing definition, etc. This is the first layer which generates actual CSS.
  4. Elements - styling for bare HTML elements (like H1, A, etc.). These come with default styling from the browser so we can redefine them here.
  5. Objects - (.o-object) - Those are giving layout
  6. Components – (.c-component-name) specific UI components. This is where majority of our work takes place and our UI components are often composed of Objects and Components
  7. Utilities - place for utility classes (.alignleft, .alignright, .text-left, .text-right, etc). Those should have one or two declaration at most.

# 1.5 Internal CSS rules

  1. All SVG icons' style is stored in the /assets/styles/components/_svg.scss file. This includes the dimensions of the icons and their colors. If a modifier is needed, it is also added in this file.
  2. All PNG icons' style is generated automatically by the PNG Sprite Generator and Webpack. All PNG files should be prefixed with the ico- prefix and used with this prefix in the HTML (<i class="ico-test">)
  3. The most common text styles should be set as variables in the /assets/styles/settings/_text.scss file.
  4. Text related properties for headings should be set in the assets/styles/elements/_headings.scss file. This includes font-family, font-size, line-height, font-weight but not color or any box model properties.
  5. All colors must be set as variables in the assets/styles/settings/_colors.scss file. It is not allowed to use hex, rgb(a) or hsl(a) values outside of this file. If you need to create a semi-transparent color out of a variable, use the SASS' built in rgba() function.
  6. The width of the site container element (shell) should be set in the assets/styles/settings/_variables.scss file.
  7. Prefer usage of flexbox for layout and use the available mixins found in the assets/styles/tools/_flexbox.scss file.
  8. Always add :hover states using the @include hover statement. The media query can be found in the assets/styles/tools/_mixins.scss file.
  9. All components should be stored in the assets/styles/components folder and each component should have its own file.
  10. All objects should be stored in the assets/styles/objects folder and each object should have its own file. Ideally you don't need to add more objects than what we have right now.
  11. All lists (unordered or ordered) are stored inside the assets/styles/components/_lists.scss file and are prefixed with the c-list- prefix.

# Resources

Google HTML/CSS Style Guide (opens new window)
Principles of writing consistent/, idiomatic CSS (opens new window)
Code Guide (opens new window)
Css guidelines (opens new window)
Sass style guide (opens new window)
Sass-guidelin (opens new window)

← Deployment Guide →