Code formatting


  • Use Polygot Markup with the following emphasis:
    • Use XHTML compliant Boolean attributes e.g. <input type="text" required="required" />.
    • Use double quotation marks for attributes.
    • Use the minimized tag syntax, with a space before the closing slash, for void elements, e.g. <br />.
  • Use consistent line breaks:
    • Add line breaks only between sibling sectioning elements & ARIA landmark roles.
    • Place inline tags on the same line.
    • Place block-level tags on a new line and indented.
    • Include templating serverside code as part of the nesting of elements.
    • Wrap long lines of text and treat as block-level elements, using 150 char length as a guide.


Example of style

/* header */
	.action .action-information,
	.button .information:last-child {
		background: url("../images/generic-logo.png") no-repeat center 0 #fff;
		border: 1px solid #000;
		-webkit-box-shadow: /* multiple properties on different lines */
			0 1px 3px rgba(0, 0, 0, .2),
			0 2px 6px rgba(0, 0, 0, .1);
			0 1px 3px rgba(0, 0, 0, .2),
			0 2px 6px rgba(0, 0, 0, .1);
			0 1px 3px rgba(0, 0, 0, .2),
			0 2px 6px rgba(0, 0, 0, .1);
			0 1px 3px rgba(0, 0, 0, .2),
			0 2px 6px rgba(0, 0, 0, .1);
			0 1px 3px rgba(0, 0, 0, .2),
			0 2px 6px rgba(0, 0, 0, .1);
		color: #333;
		display: block;
		font-family: Helmet, Freesans, sans-serif; /* bbc glue font stack /*
		font-size: 1.3em; /* only use ems for font-sizes (including on the body) */
		padding: 5px 0 2% 0;
		-webkit-transition: all 700ms ease; /* use ms for duration */
		-moz-transition:    all 700ms ease;
		-ms-transition:     all 700ms ease;
		-o-transition:      all 700ms ease;
		transition:         all 700ms ease;
		z-index: 3;

	.action a {
		color: rgba(0, 0, 0, .2);

Structure of a style

Use "semi-expanded" structure.


Selector naming

  • Use only lowercase.
  • Use only hyphens to separate words.

Property order

  • Alphabetical.
  • By the length of prefix (long to short) for vendor prefixed properties.
  • Carry on the alphabetical order for multiple properties (e.g. border-bottom, border-left...):
.download {
	border-bottom: 1px solid #000;
	border-left: 2px solid #000;
	border-right: 1px solid #000;
	border-top: 2px solid #000;

Property value order

  • background: [colour] ["url"] [scroll] [repeat] [position];
  • border: [size] [type] [colour];

Prefixed Property value spacing

.download {
	-webkit-transition: all 700ms ease;
	-moz-transition:    all 700ms ease;
	-ms-transition:     all 700ms ease;
	-o-transition:      all 700ms ease;
	transition:         all 700ms ease;

Text formatting

  • Use consistent, version-control-friendly text formatting:
    • Use tabs for indentation - length of 4 spaces.
    • Use UNIX-style line endings.
    • Trim trailing whitespace from lines.
    • Ensure all text-based files end with a newline character.

Media assets

Naming conventions

  • Use only lowercase.
  • Use only hyphens to separate words e.g. "home-logo.png".

Development Guidelines


Use HTML5 Boilerplate as a foundation:

  • Use modernizr.
  • Use the non-semantic helper classes:
    • Use the class="clearfix" approach to clearing floats.
    • Use the image replacement and text hiding classes.
  • Adhere to the W3C's Mobile best practises on every project.
  • Use polyfills.
  • Use HTML5 semantic tags e.g. sectioning and form elements.
  • Use Microformats and HTML5 microdata.
  • Use WAI-ARIA landmark roles - see this blog post for more information. Never use ARIA roles to target CSS styles.
  • Place all Javascript before the closing </body> tag, except modernizr.
  • Use Classes over IDs with the exception of:
    • In-page navigation.

With the following exceptions:

  • Use an IE conditional class and "safe hacks".
  • Order the <head> as follows:
    1. <meta>
      1. Charset first.
      2. Then alphabetically ordered.
    2. <title>
    3. <link>
    4. <script>


Structure of a stylesheet

  1. fonts (including url to licence)
  2. normalise html5
  3. default styles (based on boilerplate/normalise)
    1. html
    2. body
    3. links: a, a:hover, a:active, a:visited
    4. sectioning content: aside, article, nav, section
    5. heading content: h1 – h6, hgroup
    6. text-level semantics: address, blockquote, code, em, pre, strong
    7. grouping content
      1. lists: dl, dt, dd, ul, ol, li
      2. paragraphs
      3. tables: table, thead, tr, th, tbody, td
    8. form content: form, fieldset, legend, label, input, textarea, select, option
    9. embedding content: audio, canvas, embed, iframe, img, object, video
  4. helper classes (non-semantic)
  5. shared states
  6. style patterns: ordered by complexity
  7. layout patterns (non-semantic)
  8. @media queries
    1. device width (linearised content first)
      1. default styles (based on boilerplate/normalise)
      2. helper classes (non-semantic)
      3. shared states
      4. style patterns: ordered by complexity
      5. layout patterns (non-semantic)
    2. print

Comments and indentation

Comment within a stylesheet to aid other developers.

  • Title
  • Colour swatch
  • Index
  • Sectioning comments
  • Property comments
 * standards and conventions
 * colour swatch:
 * light blue = #005
 * dark blue = #00C
 * index:
 * 1. fonts
 * 2. normalise html5
 * 3. default styles (based on boilerplate/normalise)
 * 4. helper classes (non-semantic)
 * 5. shared states
 * 6. style patterns
 * 7. layout patterns (non-semantic)
 * 8. @mediaqueries

Use indentation and comments to section a stylesheet. There are two types of comments:

  1. Sectioning comments.
  2. Property comments.
/* sectioning comment e.g. "header" */
	header {
		margin: 0;

	/* sectioning comment e.g. "primary navigation" */
		header nav {
			float: left;

	/* sectioning comment e.g. "search box" */
		header search {
			display: inline; /* property comment e.g. ie double margin fix */

Selector naming

  • Use:
    • Plurals for groupings.
    • Nouns for specific objects.
    • Adjectives (where possible) or verbs for variations
    • Past-participle verbs for states.
    • The following for pattern parts:
      • <pattern name>–inner → for inner wrapper
      • <pattern name>–item → for the most common and repeating element in the pattern
      • <pattern name>–content → for containing both media and text
      • <pattern name>–media → for targeting imgs, swf, video
      • <pattern name>–copy → for containing only text e.g. headings and paragraphs
  • Do not mimic tag names when naming classes, unless they are prefixed. e.g. .component-body.
.actions (grouping - plural)
	.action (pattern - noun) .action-collapse (sub pattern - verb)
		.action-inner (pattern part)
			.action-item (pattern part)
				.action-content (pattern part)
					.action-media (pattern part)
					.action-copy (pattern part)

.folder .is-collapsed (state - past participle)

Progressive enhancement in CSS


  • Use forward-facing support (i.e. assume feature support and target lack of with the "no-" classes") with the exceptions of:
    • JS → assume no JS and target support with the "js" class.
    • Touch → assume a no-touch device and target support with the "touch" class.

Backgrounds (language feature)

.text-area {
	background: url("/images/background-000-50.png") repeat; /* IE fix */
	background: rgba(0, 0, 0, 0.5);
  • Start with fall back definition to support older browsers.
  • Implement newer definition last.

Fonts and Font Face

Use tweaked (letter/word spacing etc) web-safe fonts first. Then webfonts, but sparingly, with the following caveats:

  • Ensure the font is correctly licensed. Find a licence using a webfont service.
  • Ensure the rendering quality of the font is acceptable in all browsers.
  • Ensure acceptable loading times are maintained as fonts are added.
  • Ensure the correct font weights are included and linked correctly.

Media assets

File structure

  • Limit of 10 files per folder before subfolder is created
  • All vendor/3rd Party scripts to be found in "/vendor" including all assets.
  • Creation of child folders within structure below are on a per project basis



Use spritesheets only for grouped sets of icons.

Image Formats

  • Use JPEG for photos and complex images/icons.
  • Use PNG 8 for small and simple images/icons.
  • Use PNG 24 for multi-channel transparency.


  • Adhere to the WCAG Samurai checklist.
  • Do not check using accessibility validators.

Development Process

  1. Annotate designs to:
    1. Identify a colour palette.
    2. Identify the "base styles" using a "typography-first" approach:
      1. Identify the body copy (the most common block of copy) and its following properties:
        • Font family.
        • Font size.
        • Line height.
      2. Identify text-based grouping elements (and their box models):
        • Paragraphs.
        • Lists.
        • Heading groups.
      3. Identify six levels of headings.
      4. Identify form elements
        • Legends.
        • Labels.
        • Inputs.
    3. Identify style patterns, subpatterns and pattern parts (starting with most common and smallest first):
      • Actions
      • Navigation
      • Content blocks
      • etc...
    4. Identify layout patterns:
      • Grids
      • Positioning
      • etc...
    5. Identify animation patterns:
      • Colour transitions (e.g. on simple links)
      • Show & hide (e.g. reveals, slides, fades)
      • etc...
    6. Identify interaction patterns:
      • Clicks
      • Drags
      • Hovers (including simple links)
      • etc...
  2. Produce a draft mapping of the relationships between patterns in each set.
  3. Build a toolkit:
    • with the following sections:
      • Base styles
      • Demo of style patterns.
      • Demo of layout patterns.
      • Demo of animation patterns.
      • Demo of interaction patterns.
      • Components built from the patterns.
    • and with the following features:
      • Self-annotating and with common language between design and development.
      • A reference for default typography, padding, margin etc.
      • Built-in relationship mapping.
      • Testable.