CSS Guide

A collection of guidelines for handling CSS.


  • Remove your technical debt before the end of each sprint. Don't depend on some future sprint to do it.

  • With each new feature, find opportunities to streamline, variablize and generalize code - less is more.

  • Comment your code as if you had retrograde amnesia - tell a story about how the code maps to the feature, don't just leave breadcrumbs.

  • Think mobile-first and journey-driven.


Build like you are building a commercial product. Think modular, not custom. Avoid one-off solutions. Reduce cognitive load by keeping code simple, expressive, and consistent.
(HTML) Make sure URLs are hackable, human readable, and persistent (don't break the implicit contract with people who bookmark the link). Don't expose the technology. Don't make it complex.

External References

Google Design Standards
Google Style Guide
Apple's IOS Human Interface Guidelines
Bootstrap Framework
The New Code


Object Oriented CSS (OOCSS).
Scalable and Modular Architecture for CSS (SMACSS).


Use the LESS or SASS dynamic preprocessor style sheet language which compiles into cascading style sheets.


Avoid descendant selectors (i.e. don’t use .sidebar h3).
Avoid IDs as styling hooks.
Avoid attaching classes to elements (i.e. don’t do div.header or h1.title).
Avoid using !important, except in rare cases.


Collect and organize CSS in separate files. Order is important.

Base - contains reset, default element styles and base styles for controls such as buttons, grids etc. which can be overwritten later in the document under specific circumstances.
Variables - contains all LESS variables, selectors, mixins, maps.
Font Variables - the downloaded IcoMoon font variables for LESS.
Theme - any styles that are related to theming and global Appkit overrides.
Layout - content containers, navigation, breadcrumbs, sitemaps.
Blocks or Modules - area specific styles such as contact form styles, homepage tiles, product listing.
IE11 Overrides - if you still use this.


Use named wrapper (container) and block classes to shape w/ width, height, overflow around base class elements.

.thisthat-wrapper {
	display: flex;
	margin: 0 auto; 
	.thisthat-block {
		color: red;
		.this {
			font-size:  1rem;
		.that {
			font-size: .5rem;

Variablize repeating elements like:

Media queries / breakpoints
  • Colors
  • Border-radius
  • Box-shadow
  • Gradients
  • Fonts
  • Font Icons
  • General Rules
  • Avoid ALL inline styles. Use a LESS or SASS compiler to manage CSS.

Take a mobile-first approach where the base styles are written for mobile devices and overridden using media queries for progressively larger displays. Turn these media query breakpoints into variables. Add media queries alongside the base styles being modified.

//35.5em / 568px
@phone: ~"screen and (min-width: 35.5em)";
//48em / 768px
@tablet: ~"screen and (min-width: 48em)";
//64em / 1024px
@desktop: ~"screen and (min-width: 64em)";
//80em / 1280px
@widescreen: ~"screen and (min-width: 80em)";
//112em / 1792px
@superwide: ~"screen and (min-width: 112em)";

Hex is acceptable for simple grayscale elements. Just try to avoid using black, and keep the byte count low by using the three-digit shorthand syntax. For other colors, use HSL rather than Hex or RGB, for programmatic color control and repeatable consistency across products.

// Primary hues
@hueR: 10;
@hueO: 29;
@hueY: 42;
@hueG: 111.7;
@hueB: 210;
@hue0: 0;

// Theme color mix
@color-blu: hsl(@hueB, 84%, 39%);
@color-yel: hsl(@hueY, 95%, 63%);
@color-orn: hsl(@hueO, 86.5%, 59%);
@color-grn: lighten(hsl(@hueG, 42%, 42%),15%);
@color-red: lighten(hsl(@hueR, 100%, 50%), 25%);

// Base color variables
@color-background: hsl(@hue0, 0%, 97%); //#F7F7F7
@color-blu-light: lighten(@color-blu, 10%);
@color-blu-dark: darken(@color-blu, 10%);
@color-nav: @color-blu;
@color-nav-active: darken(@color-blu, 10%);
@color-link: lighten(@color-blu, 10%);
@color-icon: lighten(@color-blu, 20%);

Use rem font-size units relative to a root "font size" of 10px specified in the <body> element. Sizing in multiples of ten don't need a calculator.

Choose a typographic scale for font sizing based on classic proportions like 1:2, 2:3, 2:5, 5:8 (1:1.618).

Note: this site uses a Minor Third scale for five header sizes. Not all sites need that many.

For example, the following chart shows how a rounded Minor Third typographic scale can apply to tag types and grow proportionally with Mobile (default), Laptop (700px), and Desktop (1200) displays, where 1rem = 10px:



Use font icons like IcoMoon (with the online IcoMoon App instead of PNG, JPG, SVG images or sprites.

  • Naming convention - icomoon
  • Build icons as single SVG files
  • Size - 512 x 512px
  • Grid - 8px
  • Color - black
  • Version icon set releases
@import "icomoon-variables.less";

@font-face {
    font-display: block;
    font-family: '@{icomoon-font-family}';
    font-style: normal;
    font-weight: normal;
    src: local('☺'),
    url('@{icomoon-font-path}/@{icomoon-font-family}.ttf?@{icomoon-version}') format('truetype'),
    url('@{icomoon-font-path}/@{icomoon-font-family}.woff?@{icomoon-version}') format('woff'),
    url('@{icomoon-font-path}/@{icomoon-font-family}.svg?@{icomoon-version}#@{icomoon-font-family}') format('svg');

// declare IcoMoon vector font icons globally
[class*="icomoon-"] {
    font-style: normal;
    font-weight: normal;
    font-variant: normal;
    text-transform: none;
    line-height: 1;
    -webkit-font-smoothing: antialiased;
    -moz-osx-font-smoothing: grayscale;
    &:after {
        font-family: '@{icomoon-font-family}' !important;
        text-decoration: none !important;