Wego Engineering

This is a living draft, please feel free to submit pull requests (with use cases/reasons) for improvements to what are stated here.

Some of these guide lines are simple in theory but difficult in practice. Just try because they are not being followed very thoroughly at the moment either. (troll)

Philosophy

• Consistency
  • The ultimate goal of this guide is to produce a consistent set of conventions so future developers can hop in and start with minimum human intervention.
• Mobile first
  • Develop and test in the following order: mobile, tablet and then desktop.
• Keep styling in CSS and behavior in JavaScript.
  • Whenever possible, try adding class hooks to HTML (such as is-visible for accordion) and use CSS to style the opened and/or closed state instead of directly using JavaScript (something.hide()). This allows simpler styling through different media sizes instead of having to dig into JavaScript to perform many if-else statements based on screenState.
• DRY
  • Markup/style content as modules (or objects if you will) so the same set of markup can be re-used elsewhere. This will also remove (or hopefully reduce) any issue with making unintended changes. The resulting output (of HTML and CSS) might be slightly more bloated but it would be insignificant compared to the cost of maintenance otherwise.

HTML Style Guide

• To ease debugging with inspector, use $el.data('something') instead of $el.attr('data-something') only IF all of these are true:

  • data-something is read-only
  • data-something is JSON

• Use meaningful class names whenever it makes sense to. It doesn't hurt to be clearer.

  • Try to keep to noun-{verb,adjective} style.

// Not so good
<del>$50</del>
<ins>$20</ins>

del { color: red; }

// Better
<del class="rate-original">$50</del>
<ins class="rate-discounted">$20</ins>

.rate-original { color: red; }

• Avoid using presentational classes.
  • presentational classes (i.e. hide-for-*) will start haunting you once you re-use a partial in another page.
  • it might be easier starting out but in the long run, re-usability is greatly hindered

// partial.html.erb
<div class="room-rates">
  <span class="rates hide-for-medium-down">$100</span>
</div>

// show_rates_for_large_only.html
<%= render 'partial' %>

// show_rates_for_all_sizes.html, wait what.
<%= render 'partial' %>

• Use semantic classes that make sense no matter where the partial is included.

// Bad...
<a class="orange-round-button">...</a>
<a class="orange round-button">...</a>

// Because what if we want blue button for static page? :(
<a class="orange but_blue_for_static round button">...</a>

// Now we're talking.
<a class="button internal loading">loading button</a>

.button {
  // .. default button styles ...
  // orange, round, blah

  &.internal {
    // style for internal linking button
    // maybe diff shade of orange
  }
  &.external {
    // style for external linking
    // make it purple maybe?
  }
  &.loading {
    // patterns for when loading...
  }
}

• However, use the visibility class in Foundation.
  • if the element is to be hidden for a certain screen sizes (with no complex logic such as hiding in medium only if x is true)
  • the partial is definitely not shared

// Verbose
.example1 {
  @include respond-to(desktop) {
    display: none;
  }
}

.example2 {
  display: none;
  @include respond-to(desktop) {
    display: block;
  }
}

.example3 {
  display: none;
  @include respond-to(tablet) {
    display: block;
  }
  @include respond-to(desktop) {
    display: none;
  }
}

// Precise
<div class="example1 hide-for-large">...</div>
<div class="example2 show-for-large">...</div>
<div class="example3 hide-for-small hide-for-large">...</div>

• Use %placeholder instead of a CSS selector when @extending, see SASS Placeholders Versus Mixins and Extends

• Presentational class names are those that are modifiers and have no meaning on their own:

  • Presentational (adjective, verbs): blue, small, fade
  • Meaningful (nouns): book, reviews, button

• Use " instead of ' for HTML attributes.

• Wrap inline elements (such as icon fonts) in an inline element when using show-for-* and hide-for-* because these classes use inherit and will take block if the parent is a block. See Foundation discussion.

<span>
  <i class="icon-search show-for-small"></i>
</span>

• If the element has a id, try to give it a class of the same name if you need one.

<div id="help" class="help">halp!</div>

• Use columns and not column.
• Use div for styling block-level elements. Use the element section only if you answer yes to the following:
  • Will you consider the content in the element a new chapter in a book?
• Use table if the content is tabular data. Don't abuse ul, ol or dl.
• Use class row when:
  • the element is a wrapper for a series of child elements with class columns.
  • you want to restrict the max-width of an element (usually the most parent container) to avoid true liquid layout.
• Use class columns when there is accompanying small-*, medium-*, or large-* in the same element.
• Use id for elements used throughout the app.
  • Shared stuffs like header, footer.
  • Any HTML defined in carebear?
• Use <i> for icon fonts.
• Use <span> or <div> for styling purposes. Most other elements have meanings.
  • Don't abuse <b>, <a> or <em> just because they're shorter to type.
• Avoid href="#" or href="javascript:void(0)" for fake links (those that don't change the page URLs) because it'll affect SEO.
  • Use tags with no semantic: div, span, i, b
  • Use em or strong ONLY if they should be emphasized.
• Use .js- prefixed class names only for JS stuff. Don't reference it from CSS files.
• Use .is-, .has- prefixed class names for state rules that are shared between CSS and JS.

SASS Style Guide

• Never rely on declaration ordering to overwrite another style. Increase specificity instead.

// nope
.test {
  display: none;
}

.test {
  display: block;
}

// yes
.test {
  display: none;
}

span.test {
  display: block;
}

• Use .segment_name-page_name instead of .page_name .segment_name
  • Easier to re-use between pages (not hooked on to class of body/html/parent element/etc.)
  • Easier to locate the style (i.e. star-related will be in stars.scss)

// Not so good
.listings .stars {}
// Good
.stars.stars-listings {}

// Not so good
.hotels .card
// Good
.card.card-hotels

.card { &.card-hotel {} &.card-airfare {} }

.stars {} ```

• With the exception of respond-to, add all @include mixins; at the top of declaration to avoid unintentional overwriting.

.breadcrumbs {
  @include something;
  @include else;

  text-align: right;
}

• Avoid styling ids, try to stick to using classes so we can re-use them (whether or not we do, is another issue).
• Avoid using overflow: hidden to clear floats, use @include clearfix instead.

.help {
  @include clearfix;
  ...
}

• Use px for font-size.
  • Whenever possible, apply the px directly on the element since px doesn't inherit from the parent unlike em.
• Use em for others: margin, padding, left, etc.
• All colours should be a SASS $variable.
  • $money-color: #FAFAFA;
  • .money { color: $money-color; }
  • Add these $variables into _variables.scss so it can be re-used in different apps.
• Put spaces after : in property declarations
• Use - to delimit classes/ids:
  • Good: long-name
  • Bad: long_name
  • Worst: longName
  • WTF?: LoNgNaMeHeHe
• Use // for comment blocks, instead of /* */.
• Maximum Nesting: Three(3) Levels Deep.
• Use respond-to() top-down in source order - mobile, tablet, desktop.
• respond-to(mobile) is implied when no respond-to is used, so omit it.
• Split mixins arguments into different lines:

@include section(
  $section-type: accordion,
  $title-color: $primary-color
);

• Disregard pixels and acquire emCalc without unit..

// Good
padding: emCalc(10, 1);
padding: emCalc(10);

// Not so good
padding: emCalc(10px) emCalc(11px);

• Add a space after :, , and before {.

.subheader {
  @include respond-to(mobile) {
    font-size: emCalc(16, 10);
    border-bottom: 1px solid;
  }
}

• Float with $start or $end. $start and $end is left and right respectively in LTR orientation and vice versa in RTL.
• Never use right or left class because RTL.

External Resources

Must-Reads

• SMACSS
• Sass Style Guide
• Creating Living Style Guides to Improve Performance - OOCSS-oriented
• Going Both Ways
• JavaScript style guide

Optional reads/visits

• CSS developer guide
• CSS Architecture
• shame.css
• CSS Hacks
• MindBEMding
• Screensiz.es