The MarsBased CSS & HTML guidelines

Captain's log, stardate d406.y36/AB

Since we started MarsBased, we've completed a good share of projects. From all of them we've learnt something useful. But all this knowledge should be stored somewhere for further use, for instance, to train new developers.

Pretty much like we did with the release of the MarsBased blogging guide (part 1, part 2), we want to share what we have learnt about HTML5 & CSS3 with you all.

Things should not only work well. They can also look good.

Frontend developers, this one is for you.


Before we delve into the technologies we use, we will introduce our working methodologies here:

Task management

Trello is our tool of choice for managing tasks and weekly sprints.

We have one board for each project. Inside the project's board, you'll find columns for the present and coming weeks, along with Done, Review Pending, Bugs, Features, and Backlog. In projects that have been already rolled out, you will see some columns for the deploys management, too.

The Project Manager is in charge of assigning the layout & design tasks. You will see the cards assigned to you in the present week column. Once you have finished a task, you must add a new comment indicating the relevant pull request link, and move the card to the Review Pending column.

The Project Manager will review the implementations and move the card to Done, send it back to you (if there is something to fix) or forward it to the Development Team.

The weekly sprints are defined on Mondays, in an online meeting between you and the Project Manager. However, don't hesitate to get in touch with the Project Manager at any time, if you need to discuss anything or have any question.

Commits & Branches

We work with both Github and Bitbucket and we always have separate repositories for the layout implementation and the development, so you don't have to worry about breaking stuff or learning Ruby on Rails. In other words, you will have to deal with HTML, CSS, and JS, only.

Furthermore, we never work on the master branch, as it only contains reviewed and finished stuff. Usually, we create a new branch for each task. However, we sometimes group small and related tasks to use only one branch for them. Apply common sense and branch wisely!

The Project Manager will merge those branches into master after making the relevant reviews.

Finally, when we make commits, we always include the type of change we have made between brackets.

For example, if you've changed only the CSS code, you indicate:

[CSS] Replaced the body background color.

If you have changed the HTML and you have replaced some images, you will write:

[HTML+IMG] Replaced the default avatar.

You might want to include other indications like JS, README, CONFIG, etc. This way, our developers will be able to identify very quickly what they have to change in the development to replicate our work.


Quality is one of the founding values of MarsBased. A while back ago, we defined quality as "meeting and exceeding clients expectations while maintaining our own methodologies". For that reason, exhaustive and successful testing is critical in our day to day.

As a front end developer, you’re in charge of testing how the applications look in all the required browsers and devices.

Our testing workflow is plain and simple:

  • In new projects where we start the development from scratch, we leave the testing tasks for the end and we do them all at once.
  • In projects under maintenance (live products), we test each new feature or bug fix before sending the pull request to the development team.

Keep this in mind all the time: an excellent developer is not just someone who creates good code, but is also a good tester.

Tech Stack and Guidelines


Middleman is a static websites generator built with Ruby on Rails. It integrates all the state-of-the-art frameworks and tools for frontend development (like SASS, Modernizr, Compass, Autoprefixer…) and allows you to use templating languages such as ERB or Liquid.

All our new projects are developed using Middleman, but before that, we used Jekyll. Jekyll is very similar to Middleman, with only a few differences between them. While we used Liquid as the templating language in Jekyll, now we switched to ERB in Middleman.

In the project's README file, you will find instructions about how to install the required packages and run any of those tools.

Middleman Tools

  • Middleman lets you organize your code in layouts and partials. Do it wisely, we don't want to have to deal with tons of files. Use partials only for stuff that will appear in several pages, or to split the code of very long pages, but always remember that simpler is better.
  • We have developed our own Middleman template called MarsMan. We use it as a model to create new projects. It contains all the folders, SASS mixins, frameworks and libraries that we use in our projects. Marsman is an open source project, so you can use it for your personal stuff or even send it to other people. You can download the code from our Github profile{target="_blank"}.
  • We use the Middleman helper page_classes to define page-specific classes in the body tag of the HTML. Use them carefully, we don't want to create too many page dependencies in our CSS code.
  • Middleman has a very useful set of helpers that let you add random Lorem Ipsum content and image placeholders.
  • Middleman allows you to add Markdown content to a website by simply including a markdown file as a partial inside any other HTML file. We use Markdown files for text-only pages like Terms & Conditions, Privacy Policy or blog posts.

You can find more information about Middleman and Jekyll in their official websites.

Also, if you never had the chance to use ERB, you can find some examples in this blog post.


Most of our works are based on Bootstrap. It's a very well-known markup framework and it offers good compatibility with browsers and other components. Also, our developers are familiar with it and can reuse a lot of code.

We tend to use always the last stable version of Bootstrap, in their SASS distribution. Since we also use SASS as our CSS framework of choice, you will be able to replace the Bootstrap variables and adapt them to each project. Do it whenever possible, instead of overwriting the Bootstrap properties. You can find the complete list of variables in the Bootstrap SASS Github page.

Finally, Bootstrap has a very powerful grid system. It can be used by simply including classes in the HTML markup, such as .row or .col-xs-6. However, instead of using those classes to define rows and columns, we prefer to use the Bootstrap mixins. They also allow you to define rows and columns, but you can do it directly in the SASS files, without dirtying the HTML code. Following this approach, we can completely separate the markup of a website from its styles and we make the application easier to maintain.

In other words, instead of doing:

<div class="container">
  <div class="results row">
    <div class="item col-xs-12 col-sm-6 col-md-4">
      The Martian

We prefer to do:

<div class="container">
  <div class="results">
    <div class="item">
      The Martian



You can see the mixins used in the grid system also in Github.


SASS is a CSS preprocessor that lets you use variables, functions, operations, and other useful stuff inside your CSS stylesheets. You can learn how to use SASS in their official website. We're sure you'll find it very easy!


We organize our SASS code in partials that we later import in a single file called application.sass.

These partials are organized in folders. Take a look at this example:






The /utils folder is where we store our helpers, mixins and keyframes - coding tools that we use in our HTML and SASS files. We also have a file called _variables.sass that contains generic variables like color or typography definitions. However, page- or module-specific variables are not stored here but inside the corresponding layout or module file (you can find an example a couple of paragraphs from here).

The /modules folder contains the styles of the different components that compose each page. And finally, we use the /layouts folder to include styles we need to apply to specific pages.

If the difference between layouts and modules is still not clear for you, have a look at the following example.

Let's say that we have to develop a marketplace with a results page, where each result is an item. Some of these items will also appear in the Home page.

We would create a _items.sass file inside /modules and we would put there all the styles that apply to the items.

// modules/_item.sass


  $item-primary-color: #000000 // Variable specific to this module!

  padding: 20px
  background-color: #f4f4f4

    color: $item-primary-color

Now consider that these items have to look differently in the Homepage than in the Results view. In that case, we would create a _home.sass file inside /layouts with the following styles:

// modules/_home.sass

    background-color: inherit

Naming Conventions

In order to name our elements and classes, we follow the modular approach explained in this article from The SASS Way. However, we don't apply the parent-child rules, as we prefer to use nesting for such cases. In any case, if you ever have to define parent-child relations, use a dash (-) as a separator instead of an underscore (_) or any other symbol.

Finally, in order to differentiate keyframes (animations) from classes or IDs, we name them without dashes or underscores:

// Keyframes

@keyframes fadeIn
    opacity: 0
    opacity: 1

@keyframes fadeOut
    opacity: 1
    opacity: 0

Other Guidelines

  • You can create your own mixins, but do it only when they will save you a lot of time, without adding too much complexity to the project. We don't want to increase the application complexity because other less experienced coders might have to work on it at some point.
  • Nesting is one of the most powerful tools of SASS. However, it can be counterproductive if not used wisely. We follow the Inception Rule defined in The SASS Way. It says that you can't go more than four levels deep. It also explains how to organize the different selectors and properties in site-wide rules, page specific rules and objects.
  • In projects where we don't have to support IE8 or lower, we use REM units to define font sizes, margins, heights, widths, etc. REM units work in a similar way than EMs, but they are proportional to the HTML tag font-size. Bootstrap defines the HTML font-size to 10px, so using REM units is very easy: 1rem will always be equal to 10px, 1.4rem will be equal to 14px, 0.8rem will be equal to 8px, and so on.

Autoprefixer, Modernizr, and Compass

Autoprefixer is a plugin that parses the CSS files and adds browser specific prefixes to the properties that require them. This means that you don't have to worry about adding prefixes such as -webkit-, -moz- or -ms- because Autoprefixer does it for you.

Modernizr is a JavaScript library that detects if the user's browser supports HTML5 and CSS3 features or not. You can use it to build fallbacks for modern features that old browsers might not support.

Compass is another CSS framework included in our Middleman projects. We prefer to use Autoprefixer to add browser specific prefixes, but you might want to use Compass for other things, like its vast library of reliable mixins.

Images and icons

Vectorial Images

For logos, icons and small images we prefer to use SVG files instead of PNGs or JPGs because SVGs are made from vectors and can be resized without losing quality.

To include SVG files in the HTML code, drop the SVG files in the shapes directory. All SVG files are formatted in XML. Make sure that they don't have more data than the necessary (some apps like Adobe Illustrator include irrelevant information inside the SVG files that can produce errors).

Afterwards, you will have to execute a job that will take all the SVG files from the shapes directory and produce a file called shapes.html:

grunt svg

This file should be included in all the app's pages as a partial:

<body class="<%= page_classes %>">
  <%= partial "partials/shapes" %>
  <%= yield %>
  <%= javascript_include_tag  :application %>

Now you can include any SVG image in your HTML by simply calling it. Use this markup to do it so:

<svg class="shape shape-filename">
  <use xlink:href="#shape-filename"></use>

Bootstrap Glyphicons and Font Awesome

If the design doesn't come with its own icons, we like to use the ones provided by Bootstrap and Font Awesome. If you don't find any suitable icon, try looking in websites like

Image Helpers

In some cases, we will have to deal with normal images like PNGs or JPGs. In that case, we use the image-url helper in the CSS files to point to files stored in the images folder:

  background: image-url('navbar-background.png')

In the HTML markup, however, we use another helper called image_tag:

<%= image_tag 'padrino.png', width: '35', class: 'logo pull-right' %>

You can find more examples of the image_tag helper in the Ruby on Rails API documentation.

JS libraries

Not all the JS libraries work well with Rails and Angular. For that reason, and also because we like to standardize the code of our projects, we have created a list of preferred libraries. If you ever have to use another library, consult our Development Team first.

  • Modals: ng-dialog (only in Angular projects) and Bootstrap.
  • Dropdown menus: Bootstrap.
  • Selects: Select2.
  • Tabs: Bootstrap.
  • Carousels: Slick.
  • Checkbox and radio buttons: Pure CSS (label after the input technique).
  • Charts: C3 & D3.
  • Autocomplete: Select2.
  • Range sliders: bootstrap-slider.
  • Scroll: Just the browser scrollbar (avoid using JS scrollbars like Perfect Scrollbar if possible).
  • Affix & Scrollspy: Bootstrap.
  • Tooltips & popovers: Bootstrap.
  • Alerts: Bootstrap + simple fade in with JS.
  • Text editors: TinyMCE.
  • Date management: MomentJS.
  • Datepickers: Pickadate.
  • Animations: Pure CSS. Velocity if more complex animations are needed.
  • Progress Bars: Pure CSS.
  • Maps: Leaflet or Google Maps.
  • Parallax: Pure CSS.
  • Image galleries: Slick.js inside a modal.
  • Chat mentions: AT.js.

Code spacing and formatting guidelines

80 Characters per line

It's not always possible, but in order to improve code legibility we try to make lines no longer than 80 characters (this applies to HTML, JS, and SASS too).

If you have to split an HTML tag, do it between attributes and indent the second line:

<a class="item-link" href=""
  MarsBased Website

Advanced text editors like Sublime Text allow you to add a ruler on your screen that mark where the 80 characters per line are reached.

HTML Files

We don’t include any extra line-breaks between divs and other elements. Also, we avoid using HTML comments unless they are completely necessary to explain how something is supposed to work.

For example, instead of doing:

<div class="results">

  <div class="item">
    <h2>MarsBased website</h2>
  </div><!-- .item -->

</div><!-- .results -->

We prefer to do:

<div class="results">
  <div class="item">
    <h2>MarsBased website</h2>

Bonus: there is a Sublime Text plugin called TrailingSpaces that detects unnecessary blank spaces in your code and deletes them all at once with a keyboard shortcut!

SASS Files

If a CSS selector doesn’t have any property inside it, we leave no space between the selector and the selector that comes next:

    border: 1px solid purple

On the other hand, if a selector has some properties, we add an extra line break between the last property and the next selector:

  padding: 10px 20px

  border: 1px solid purple


We follow the SEO best practices of naming all the elements with HTML5 semantic tags, when possible, like header, aside, section, nav, footer, article, etc.

Inside each of these tags, we try to respect a hierarchic structure of headings. It sounds obvious, but h1 elements must contain h2 and not the other way around.

Finally, we always add the title attribute to all the links and title and alt to all the images.

Have a look at this website for a complete guide of HTML5 elements.

Our layouts are used by our programmers to understand how they have to develop an application. However, our clients use them too to review the status of a project and to show the user interface to other people like investors or partners.

For that reason, we create navigational layouts linking all the pages and our projects can be used as a normal application (although the content is completely static). For example, if someone clicks the “Sign up” link of the navigation bar, we take him to the Sign Up page, where he will be able to check how it looks like.

That was a long read, indeed! Have you learnt something useful? Do you want to add something? Let us know in the comments section below!

Jordi Vendrell Farreny

Jordi Vendrell Farreny

Librarian turned into web developer. Jordi runs operations & financials at MarsBased. He is also in charge of putting quality and order in everything we do, not only in our projects. He's the Samurai of the company.

comments powered by Disqus

You're one step away from meeting your best partner in business.

Hire Us