rules.md

CSS Styleguide

Lets try to stick to these rules which have been adapted for our needs from Github's styleguide.

Spacing

• Use soft-tabs with a two space indent. Spaces are the only way to guarantee code renders the same in any person's environment.
• Put spaces after : in property declarations.
• Put spaces before { in rule declarations.
• Put line breaks between rulesets.
• When grouping selectors, keep individual selectors to a single line.
• Place closing braces of declaration blocks on a new line.
• Each declaration should appear on its own line for more accurate error reporting.

##Formatting

• Use hex color codes #000 to define LESS variables.
• Use // for comment blocks (instead of /* */).
• Avoid specifying units for zero values, e.g., margin: 0; instead of margin: 0px;.
• Strive to limit use of shorthand declarations to instances where you must explicitly set all the available values.

Misc

• As a rule of thumb, avoid unnecessary nesting in LESS. At most, aim for three levels. If you cannot help it, step back and rethink your overall strategy (either the specificity needed, or the layout of the nesting).

Examples

Some good examples:

@black: #000;
@blue: #00ADEF;
@border-color: rgba(0, 0, 0, 0.5);

// Example of good basic formatting practices
.styleguide-format {
  color: @black;
  background-color: @border-color;
  border: 1px solid @blue;
}

// Example of individual selectors getting their own lines (for error reporting)
.multiple,
.classes,
.get-new-lines {
  display: block;
}

// Avoid unnecessary shorthand declarations
.not-so-good {
  margin: 0 0 20px;
}
.good {
  margin-bottom: 20px;
}

File organisation

Try to create components that are shared through the common.web module. And only use namespace files to overwrite/modify the exisiting components. If it can be reused elsewhere in the app, put it in common.

A nice to have would be the following:

styles
├── components
│   ├── comments.scss
│   └── listings.scss
├── globals
│   ├── browser_helpers.scss
│   ├── responsive_helpers.scss
│   └── variables.scss
├── plugins
│   ├── jquery.fancybox-1.3.4.css
│   └── reset.scss
├── sections
│   ├── issues.scss
│   └── profile.scss
└── shared
    ├── forms.scss
    └── markdown.scss

Specificity (classes vs. ids)

Elements that occur exactly once inside a page should use IDs, otherwise, use classes. When in doubt, use a class name.

• Good candidates for ids: header, footer, modal popups.
• Bad candidates for ids: navigation, item listings, item view pages (ex: issue view).

When styling a component, start with an element + class namespace (prefer class names over ids), prefer direct descendant selectors by default, and use as little specificity as possible. Here is a good example:

<ul class="category-list">
  <li class="item">Category 1</li>
  <li class="item">Category 2</li>
  <li class="item">Category 3</li>
</ul>

.category-list { // element + class namespace

  // Direct descendant selector > for list items
  > li {
    list-style-type: disc;
  }

  // Minimal specificity for all links
  a {
    color: #f00;
  }
}

CSS Specificity guidelines

• If you must use an id selector (#selector) make sure that you have no more than one in your rule declaration. A rule like #header .search #quicksearch { ... } is considered harmful.
• When modifying an existing element for a specific use, try to use specific class names. Instead of .listings-layout.bigger use rules like .listings-layout.listings-bigger. Think about ack/greping your code in the future.
• The class names disabled, mousedown, danger, hover, selected, and active should always be namespaced by a class (button.selected is a good example).