CSS Style Guide

MercadoLibre CSS Style Guide.

Intro

The main goal of this guide is to set standards for writing our CSS files and components, helping the readability and maintainability of our code. By doing this, we can significantly reduce the time required to understand any front-end implementation.

By writing clean code, we are able to:

• achieve a code that’s easier to understand;
• detect errors and potential problems;
• easily identify what code can be reused;
• build or update any functionality on any code already implemented;
• work on any file regardless of who wrote it.

"Consistent code, even when written by a team, should look like one person wrote it." by Addy Osmani

Table of contents

• File Names
• General Formatting
• Selectors
• Properties
• Comments
• Tools

File Names

• Don't name your files as your project.

   /* DON'T */
   sales.css
   checkout.css

   /* DO */
   base.css
   component-name.css

• Name your stylesheet as your component name.

   /* DON'T */
   styles.css
   main.css
   mobile.css
   full-page.css
   meli.css
   sandra.css /* ;) */
   a.css

   /* DO */
   payment-methods.css
   message-boxes.css
   categories.css
   search-result.css

• Use base.css as a name for your application basic styles, such as titles, typography, etc.

• Separate the component name with Hyphen. Don't use camelCase or underline.

   /* DON'T */
   message_boxes.css
   paymentMethods.css

   /* DO */
   message-boxes.css
   payment-methods.css

• Extend your components by adding a .sufix in the filename.

  Extensions are specific styles that extend a given component.

   /* DO */
   payment-methods.css
   payment-methods.mla.css

• Separate your modifiers stylesheets with doble underscore.

  Modifiers are stylesheets with styles that modify a component. For example: styles within mediaqueries for different screen resolution target or an specific browsers.

   /* DO */
   payment-methods__large.css /* mediaqueries for big screens */
   payment-methods__small.css /* mediaqueries for mobile devices */
   payment-methods__ie8.css /* "hacks" for ie8 */

  Note: use conditional comments in your html file for referencing IE stylesheets.

General Formatting

Spacing

• Use 4 spaces for indentation. Don't use tab. (Follow these instructions to configure Sublime Text 2)

• Don't mix spaces and tabs.

• Remove all spaces at the end of the line.

• Use space between the selector and the bracket.

• Use space between property and value.

• Always leave a blank line between rules

Selectors & Properties

• Write one selector per line.

   /* DO */
   .selector1,
   .selector2,
   .selector3 {
       property: value;
   }

• Write one property per line.

   /* DO */
   .selector1 {
   	property: value;
       property: value;
   }

Selectors

• Only in English.

• Separate words with Hyphen. Don't use camelCase or underline.

   /* DON'T */
   .homePage
   .box_registracion

   /* DO */
   .home-page
   .registration-box

• Use app-prefixes ONLY for cross-application stylesheets or reusable widgets.

   /* DON'T */
   .cho-header
   .myml-sales

   /* DO */
   .commons-header
   .ml-footer

• Avoid ID selectors as much as you can.

  Declarations defined for an ID selector can't be reused.

• Avoid tag selectors unless is for extending another selector.

  Tag selectors are not specific enough.

Properties

• Alphabetize declarations.

• Whenever possible, use shorthands.

   /* DON'T */
   .selector {
   	padding-bottom: 2em;
   	padding-left: 1em;
   	padding-right: 1em;
   	padding-top: 0;
   }

   /* DO */
   .selector {
   	padding: 0 1em 2em;
   }

• Omit unit specification when value is "0".

   /* DON'T */
   margin: 0em;
   padding: 0px;

   /* DO */
   margin: 0;
   padding: 0;

• Omit the "0" when value is between 0 and 1.

   /* DON'T */
   margin: 0.5em;

   /* DO */
   margin: .5em;

• Always use simple quotation marks.

   /* DON'T */
   background-image: url(sprite.png);
   background-image: url("sprite.png");

   /* DO */
   background-image: url('sprite.png');

• Use Hexadecimal code for colors.

• Use rgba for background colors.

  Take advantage of the opacity feature.

• Always use ; at the end of every declaration.

• Don't use !important.

Comments

• All your code should be documented.

• Use single-line comment to add hints, notes, suggestions or warnings.

• Comment whenever necessary to explain the code.

• Don't comment on vendor-prefixes.

   /* DON'T */
   .selector {
   	-webkit-border-radius: 3px; /* Safari */
   }

Comments types

• Component header

  Use this as a header for every stylesheet or component

    /**
     * Component Name
     * @authors: pmontesano, hmammana, ndevalle
     * @description: small description of what the component does, where is used, etc.
     */

• Block separator

  Use this format for meaningful separations of code.

   /* Sidebar
   ---------------------------------------------------------------*/

• Inline comment

  Use regular comment formatting for small descriptions of properties or rules.

   .ch-price {
   	line-height: 1em; /* 16px */
   }

  Always comment values that might seem "magic":

   .form-actions {
       margin-left: 175px; /* label width + 15px */
   }

  And properties that apparently make no sense:

   .payment-methods {
       display: inline-block;
       height: 20px; /* default value, exceptions added to each logo */
       text-align: left; /* just in case the container has text-align:right */
   }

Tools

• Can I use... Compatibility tables for support for HTML5, CSS3, SVG and more in desktop and mobile browsers.
• CSS BEAUTIFIER Beautifies your CSS to be consistent and easy to read
• CSSLint is an open source CSS code quality tool.
• Daturi is a tool for converting images to Base64.
• Dust-Me Selectors is a development tool that scans your website to find unused CSS selectors.
• Helium is a tool for discovering unused CSS across many pages on a web site.
• ProCSSor is an advanced CSS Prettifier.
• Spritemapper is a command line CSS spritemap generator.
• The W3C CSS Validation Service
• #CSSCreator is a list of CSS properties and selectors with the first browser versions that support them.

## License

Licensed under the MIT license.

Copyright (c) 2013 MercadoLibre, http://www.mercadolibre.com/