CSS.md

Resource CSS Style Guide

The "Resource Way" of writing legible, scalable, and useful CSS.

Table of Contents

1. Comments
2. Declaration Blocks
3. White Space
4. Selectors
5. Value Formatting
6. Typography
7. Icons and Imagery
8. Browser Compatibility
9. Accessibility
10. Architecture
11. References

---

Comments

Comments should be useful and should provide clarity. Use comments to divide sets of rules into groups, or to explain potentially confusing rule declarations.

Avoid Over Commenting

Don't over comment, as most CSS should be self-explanatory. Too much commenting detracts from readability.

/* bad */
.selector {
    height: 100px; /* set height to 100px */
    width: 100px; /* set width the same as height */
    color: #ff0000; /* red */
}


/* good */
/* selector block */
.selector {
    height: 100px;
    width: 100px;
    color: #ff000;
}

Comment Formatting

Multiple Line

/**
 * Multiple
 * lines
 */

Single Line

/* Single line */

Declaration Blocks

Opening brackets should start on the same line; closing bracket on a new line.

/* bad */
.selector { ... }

/* bad */
.selector {
... }

/* good */
.selector {
   ...
}

Separate multiple selectors with a new line.

/* bad */
.selector, .another-selector {
   ...
}

/* good */
.selector,
.another-selector {
   ...
}

Each rule declaration on it's own line.

/* bad */
.selector {
    width: 100px; height: 100px;
    margin: 13px; padding: 42px;
}

/* bad */
.selector { height: 100px; }

/* good */
.selector {
    margin: 13px;
    padding: 42px;
    width: 100px;
    height: 100px;
}

Keep similar properties grouped together. Use CSScomb with the .csscomb.json settings included in this repo.

/* bad */
.selector {
    height: 100px;
    top: 0;
    z-index: 2;
    width: 100px;
    position: absolute;
    right: 0;
}

/* good */
.selector {
    position: absolute;
    top: 0;
    right: 0;
    z-index: 2;
    width: 100px;
    height: 100px;
}

Separate declaration blocks with a blank line.

/* bad */
.selector {
    ...
}
.another-selector {
    ...
}

/* good */
.selector {
    ...
}
↩
.another-selector {
    ...
}

White Space

Use one space between the selector and the opening bracket.

/* bad */
.selector{
    ...
}

/* good */
.selector•{
    ...
}

Use one space between the property key and value declaration.

/* bad */
.selector {
    float:left;
}

/* bad */
.selector {
    float•:•left;
}

/* good */
.selector {
    float:•left;
}

Use tabs to indent.

/* bad */
.selector {
••float: left;
}

/* good */
.selector {
    float: left;
}

Avoid pseudo-nesting declaration blocks.

/* bad */
.selector {
    ...
}
    .another-selector {
       ...
    }

/* good */
.selector {
    ...
}

.another-selector {
   ...
}

Selectors

Naming

Adhere to the design language of the brand when naming selectors.

Selectors never contain uppercase letters.

/* bad */
.Selector {
    ...
}

/* bad */
.SELECTOR {
    ...
}

/* bad */
.selectorName {
    ...
}

/* good */
.selector {
    ...
}

Selectors should be dash-delimited.

/* bad */
.super_cool_selector {
    ...
}

/* good */
.super-cool-selector {
    ...
}

Exception: underscores are OK when using BEM or any other modifier schema.

/* BEM - OK */
.block__element--modifier {
    background-color: #fff;
}

Avoid overly-semantic selector names.

/* bad */
.cart-item-blue {
    ...
}

.post-text-large {
    ...
}

/* good */
.cart-item-selected {
    ...
}

.post-title {
    ...
}

/* ok - helper class */
.margin-left--small {
    ...
}

Specificity

Avoid using overly-specific selectors. Understand specificity and how it works.

/* bad */
div.media {
    ...
}

.media #video-1 {
    ...
}

/* good */
.media {
    ...
}

.video:first-child {
    ...
}

Use ID selectors sparingly.

/* bad */
#walnut-promo {
    ...
}

#maple-promo {
    ...
}

#hickory-promo {
    ...
}

/* good */
.promo {
    ...
}

.promo-walnut {
    ...
}

.promo-maple {
    ...
}

.promo-hickory {
    ...
}

Efficiency

Avoid inefficient selectors by understanding how selectors are parsed.

/* bad */
ul li a.menu-link {
    ...
}

/* good */
.menu-link {
    ...
}

Avoid unnecessary selectors; keep them as short as possible. Adhere to the "Inception" rule.

/* bad */
.one.too .many .levels .here {
    ...
}

/* good */
.too .levels {
    ...
}

Avoid element selectors (outside of normalization).

/* bad */
div {
    background-color: #000;
}

/* good */
.selector {
    background-color: #000;
}

Value Formatting

Use hex or rgba. Use hex shortcuts when possible.

/* bad */
.selector {
    color: blue;
}

/* ok */
.selector {
    color: #0000ff;
}

/* good */
.selector {
    color: #00f;
}

.selector-alt {
    color: rgba(0, 0, 255, 1);
}

Use lowercase for hex values

/* bad */
.selector {
    color: #CCC;
}

/* good */
.selector {
    color: #ccc;
}

Avoid named shortcuts.

/* bad */
.text-bold {
  font-weight: bold;
}

/* good */
.text-bold {
  font-weight: 700;
}

Avoid using units when declaring 0 as a value.

/* bad */
.no-margin-left {
    margin-left: 0px;
}

/* good */
.no-margin-left {
    margin-left: 0;
}

Avoid quotes and absolute paths in url() values.

/* bad */
.selector {
  background-image: url("../img/frown.png");
}

/* bad */
.selector {
  background-image: url(/img/frown.png);
}

/* good */
.selector {
  background-image: url(../img/rainbow.png);
}

Typography

Use em for font-size.

Use unit-less values for line-height.

/* bad */
.selector {
    font-size: 1em;
    line-height: 1.3em;
}

/* good */
.selector {
    font-size: 1em;
    line-height: 1.3;
}

Use the "bullet proof" method for font-face declarations.

/* example */
@font-face {
    font-family: "My-Font-Family";
    src: url(../fonts/custom-webfont.eot);
    src: url(../fonts/custom-webfont.eot?#iefix) format("embedded-opentype"),
         url(../fonts/custom-webfont.woff) format("woff"),
         url(../fonts/custom-webfont.ttf) format("truetype"),
         url(../fonts/custom-webfont.svg#My-Font-Family) format("svg");
    font-weight: 400;
    font-style: normal;
}

Icons and Imagery

Use SVG for icons and vector imagery. Avoid icon fonts.

Browser Compatibility

Use vendor prefixes for experimental or non-spec properties.

.selector {
    display: -webkit-box;
    display: -webkit-flex;
    display: -moz-box;
    display: -ms-flexbox;
    display: flex
}

Use fallbacks when necessary.

/* good */
.future-stuff {
    color: #ccc;
    color: rgba(0, 0, 0, 0.5);
}

Accessibility

Avoid low contrast color combinations. Use Contrast Ratio to verify accessibility.

Avoid outline: none.

Avoid display: none when hiding content.

/* bad */
.hidden-visually {
   display: none;
}

/* good */
.hidden-visually {
    position: absolute;
    overflow: hidden;
    clip: rect(0 0 0 0);
    margin: -1px;
    padding: 0;
    width: 1px;
    height: 1px;
    border: 0;
}

References

Declarations and Values

• CSScomb
• Common Website & Web Design Terms

Specificity

• Inception Rule
• Don’t use IDs in CSS selectors?
• 10 Best CSS Practices to Improve Your Code
• Specificity - How is it calculated?
• CSS Specificity: Things You Should Know
• Specificity Wars

Efficiency

• Efficiently Rendering CSS

CSS Architecture

• BEM
  • BEM Methodology
• OOCSS
  • An Introduction to Object Oriented CSS
  • Object Oriented CSS: Separating Skin From Structure
• DRY CSS
  • DRY CSS: Don’t Repeat Your CSS
• Normalize.css
  • A modern, HTML5-ready alternative to CSS resets

Typography

• PXtoEM.com: PX to EM conversion made simple.
• Unitless line-heights
• Bulletproof font face
• Definitive Guide to Webfonts

Icons and Imagery

• Resource's guide for creating icon fonts

Browser Compatibility

• CSS Fallback Properties for Better Cross-browser Compatibility

Accessibility

• Contrast Ratio: Easily calculate color contrast ratios. Passing WCAG was never this easy!
• CSS outline property - outline: none and outline: 0
• Hiding Content for Accessibility