NML

General front-end and HTML guidelines

Overview

This document details the guidelines and standards for front-end development at NML, and all web applications built should take these into consideration. It is an evolving document and should be reviewed as and when required to keep up with changes in technology and best practice.

These gudelines draw on previous work done by Isobar, CSS Wizardry and TMW Agency.

Principles

  • Front-end code should display clear separation of presentation, content, and behaviour.
  • Markup should be well formed, semantically correct and valid.
  • JavaScript should progressively enhance the experience.

Readme

Always include a readme document (in markdown format) documenting any code dependencies and build processes.


Frameworks

CSS frameworks (Bootstrap, Foundation, etc) are not encouraged for production code but may be used for rapid prototyping.

NML’s own lightweight scalable, responsive SASS framework should be used for creating all sites and applications.

Javascript frameworks and libraries should be considered on a case by case basis and only where necessary. Currently we mostly make use of:

  • jQuery
  • ReactJS
  • Backbone with Marionette
  • Angular

but other frameworks may be considered based on context.

As a number of our clients still require IE8 support an appropriate version of jQuery is best in those cases.


Responsive design

All sites should be built mobile first and optimised for a range of devices.

Feature detection is always preferable to device detection.

All work is considered in a responsive, mobile first, way unless the project dictates otherwise.

Responsive design isn't just a way of developing, it is a way of thinking that needs to flow through the entire site development process from content, UX, design and development.

It is recommended to read Ethan Marcotte's excellent book, Responsive Web Design as well as the related A List Apart article on the subject.

It is out of the scope of this document to go through the specifics of developing responsively, but some suggested techniques to be used during development are talked about in Sass – Mobile First.

Performance

The NML custom build process, currently using Grunt, for front-end code should always be used for image optimisation, minification and concatenation. Additional documentation about performance required here.


Accessibility

  • Markup and code should be written in a way that is inherently accessible.
  • Designers and developers should strive always for organisation of content and clarity of navigation.
  • Content should be marked up in a logical reading order.
  • Background and text should have enough contrast to be readable even without colour.
  • No information should be conveyed by sound alone.
  • All websites should be navigable via the keyboard.
  • Specify roles for areas using WAI-ARIA document landmark roles.
  • Ensure form inputs all have labels.
  • Ensure all images have alt tags.

Indentation and spacing

  • For all languages, indent your code with spaces.
  • For all indents use 2 spaces.
  • Use Unix line endings

Readability vs Compression

We encourage readability over file-size when it comes to maintaining existing files. Plenty of white-space is encouraged, along with ASCII art, where appropriate. There is no need for any developer to purposefully compress HTML or CSS, nor obfuscate JavaScript.

We will use server-side or build processes to automatically minify and gzip all static client-side files, such as CSS and JavaScript.


Browser Support

  • Internet Explorer 8+
  • Firefox
  • Google Chrome
  • Safari
  • Opera

We test in the latest 3 versions of Firefox, Chrome and Safari due to them using incremental auto-updates.


Markup

HTML5

The HTML5 Doctype and HTML5 features will be used on all web projects.

To ensure HTML5 markup compatibility with older browsers, use HTML5shiv to ensure markup compatibility

We will test our markup against the W3C validator, to ensure that the markup is well formed. 100% valid code is not a goal, but validation certainly helps to write more maintainable sites as well as debugging code. We need not guarantee markup is 100% valid, but instead assure the cross-browser experience is consistent.

General Markup Guidelines

The following are general guidelines for structuring your HTML markup. Authors are reminded to always use markup which represents the semantics of the content in the document being created.

  • Use <p> elements for paragraph delimiters NEVER multiple <br /> tags.
  • Create space between elements with CSS margins NEVER multiple <br /> tags.
  • Items in list form should always be housed in a <ul>, <ol>, or <dl>, never a set of <div>s or <p>s.
  • Place an HTML comment around DIV tags that contain a larger amount of markup to indicate the element you're closing. It will help when there is a lot of nesting and indentation. For example:
<!-- Start of .content -->
<div class="content">
//some markup goes here
</div>
<!-- End of .content -->
  • Make use of <thead>, <tbody>, and <th> tags (and Scope attribute) when appropriate.
  • Make use of <dl> (definition lists) and <blockquote>, when appropriate.
  • Use <label> fields to label each form field. The for attribute should associate itself with the input field, so users can click the labels and obtain focus.
  • Do not use the size attribute on your input fields. The size attribute is relative to the font-size of the text inside the input. Apply a width via CSS if required instead.
  • Always use title-case for headers and titles. Do not use all caps or all lowercase titles in markup, instead apply the CSS property text-transform: uppercase/lowercase.
  • Use microformats and/or Microdata where appropriate, specifically hCard and adr.
  • Tables shouldn't ever be used for page layout – only for tabular data.

Quoting Attributes

While the HTML5 specification defines quotes around attributes as optional for consistency with attributes that accept whitespace, all attributes should be quoted.

<a href="mylink.html" title="My Link Title" data-attribute="32">This is my Link</a>

Character Encoding

All markup should be delivered as UTF-8, as it's the most friendly for internationalization. It should be designated in both the HTTP header and the head of the document.

Set the character set using <meta> tags:

<meta charset="utf-8">

Also make sure that your IDE is saving as UTF-8.