Developing design agency front-end coding standards


As a design manager sometimes it’s important to look to the basics: are we all writing the best possible code? Establishing agency-wide coding standards is one way of making sure.

(Written in November, I collated this set of standards based on a number of popular sources plus our own internal discussions. These are not a definitive list – nor are they to be considered complete. Any good set of standards can be modified and updated as technology and methods change.)

The purpose of establishing a set of coding standards is to:

  • Define clear common structure & syntax
  • Increase readability
  • Minimise code reuse

As a consequence, properly established standards should:

  • Improve your general coding knowledge & understanding
  • Help speed up future code revisions
  • Aid in debugging and bugfixing
  • Make future feature additions easier to implement



Syntax & Formatting

Write semantic classes where possible. These should be structural and purposeful, rather than presentational.

Correct: "main-grid highlight"
Incorrect: "clrb blue largetext"

Always write in lowercase on tags and attributes.

Correct: <div class="hello">
Incorrect: <DIV CLASS="hello" DATA-TEXT="Howdy">

Use double quotes on your attributes.

Correct: <div class=”hello”>
Incorrect: <div class=’hello’>

Write classes with hyphens, not underscores or camelCase.

Correct: "my-class"
Incorrect: "my_class"
Incorrect: "myClass"

Use ID and class names that are as short as possible but as long as necessary.

Correct: class="main-grid"
Incorrect: class="mg"

Always give attributes quotes and a value.

Correct: <input disabled="disabled" />
Incorrect: <input disabled />

Self-closing tags should include a space preceding the slash.

Correct: <br />
Incorrect: <br/>

Never omit a closing tag – even if it’s optional.

Append the prefix js- to ID’s and classes that are used by Javascript.

Specify attributes in the following order:

  • class
  • id, name
  • data-*
  • src, for, type, href, value
  • title, alt



Use a proper indented structure.
Indents make parsing your code easier for both humans and software – merge tools, text editor highlighting.

Avoid using unclassed DIVs – employ HTML5 structural markup or classed DIVs.
Always consider using the leanest code you can.

Avoid “div soup” by considering the minimum viable code required.
Refactoring will help reduce unwanted markup.

Maintain a conscious constant awareness of the structural hierarchy of your elements.
E.g. This will help in keeping <h1>, <h2>, <h3> usage consistent.


UX & General Good Practice

Refactor your code!
Once you’ve finished markup & styling, consider refactoring to reduce unused or redundant markup to keep things clean.

Always validate!
Validation and lint tools should help pick up on small errors and keep code lean.

Install the HTML5 Shiv to ensure backwards compatibility with HTML5 structural elements in older browsers.
Note: IE10 and above do not support conditional tags.

Include tooltips or alt text for ambiguous icons/click events.
E.g. Twitter: ‘Follow Us’, Home: ‘Return to Home page’, back arrow: ‘Go Back to Previous Page’ etc.

Always consider retina screens when using images and icons.
Also consider retina @3x as well as @2x.

Icons should be loaded from a sprite or iconfont.
This will reduce server calls and hover state ‘lag’.

Consider schema/rich snippets when building pages with potentially rich data.
Always consider the potential added content value for your data.


Syntax & Formatting

Use a space between the selector and the bracket and values.

Correct: mycolour { color: blue; }
Incorrect: mycolour{color:blue}

End all property-values with semicolons regardless of position.

Correct: mycolour { color: blue; }
Incorrect: mycolour{color:blue}

Always write properties and values in lowercase. This includes colours.

Correct: mycolour { color: bada55; }
Incorrect: mycolour{color:BADA55}

Use single quotes in property attributes. This is particularly useful because it enables syntax highlighting in your text editor.

Correct: mybg { background-image: url(‘images/bg.jpg’); }
Incorrect: mybg { background-image: url(images/bg.jpg)}

Follow an agreed CSS properties order. E.g.:

  • Positioning
  • Box model
  • Colors and Typography
  • Visual
  • Other

Use TRBL when splitting up properties.
Top Right Bottom Left order.

Avoid !important where possible. Always consider selector specificity.
This is particularly important with regards to refactoring and reducing overall CSS.

Use shorthand CSS properties where possible.

Correct: { background: url(‘images/bg.jpg’) left top no-repeat; }
Incorrect: { background-image: url(‘images/bg.jpg’); 
background-position: left top; …. }

Don’t prefix values with a leading zero.

Correct: width: .5em;
Incorrect: width: 0.5em;

Use relative (rem) units on type, instead of absolute units (px).

Use hex colour codes. Shorten to three characters if able.

Correct: color: #000;
Incorrect: color: #00000;
Incorrect: color: black;

Don’t include a unit specification if the value is 0.

Correct: width: 0;
Incorrect: width: 0rem;

Pseudo-classes should always be prefixed by a full selector.

Correct: .box a:hover { color: #fff; }
Incorrect: .box :hover { color: #fff; }


Use classes (not IDs) for styling, and set only one selector per line (i.e. when using listed selectors).

Avoid specificity creep. I.e. continually overriding selectors with gradually increasing hierarchy – ending up with a string of five selectors, IDs, !importants etc.
Refactoring should be used to reduce creep.

Generally, good code can avoid needing browser hacks. If you absolutely have to include a hack, always write a comment that explains what it’s there for.

Correct: // IE6 Fix corrects box model

Follow standard CSS layout when grouping selectors:

  • CSS Reset
  • Typography
  • Site wide/generic selectors
  • Master template selectors: wrappers, menu, footer
  • Key section selectors
  • Media Queries (separate responsive.css)


UX & General Good Practice

Build mobile-first and structure media queries scaling in order of screen size (otherwise the cascade will not work properly).
Media queries should scale in size to avoid overlap/overrides.

Never use -js prefixes as selectors.

Consider when selector context might change and avoid using selectors with relative/relational dependencies.
E.g. when styling with :first-child, :last-child, :nth-child consider that the structure of the page may change with a future revision.

Avoid using the direct descendant selector >
You can never guarantee that the positional structure of your elements will remain the same.

Consider structure/document flow and try to avoid removing items from flow (absolute or fixed) unless warranted by the situation.

Consider browser rendering before fixing an object by ‘1 pixel’ or any form of marginal nudging, padding, width, etc.
Try to find a more concise way of arranging something first and allow for rendering variances (particularly with regards to type).

If a piece of code is particularly tricky, always write a comment explaining what you’ve done.


Syntax & Formatting

Avoid using IDs for styling.

Use imports – partials, nested imports for common code blocks.

Use extends in common use cases.

.message { 
margin:0 auto; 
padding:20px; }
.error { 
@extend .message;


Nest grouped selectors.
This helps with mentally/visually grouping for clarity.

Avoid nesting over 3 levels deep.
Too much nesting makes it difficult to keep track of scope.

Try to keep nested code blocks to ~ 50 lines to preserve legibility.
If the nested block runs off the screen in your editor, it’s probably too long.

Variablise all colours that aren’t black and white.

$c8blue: #0e884e;
header a { color: $c8blue; }

Variablise common numbers.

$minpad: 14px;
header a { padding: $minpad; }

Use mixins for vendor prefixes.
Mixins are a great way of shortening long markup strings.

Comment your sections liberally and clearly.
Consider the next developer when writing your comments – make them clear and concise.

Write your variables in the generic > specific format. E.g.


Use ‘compact’ when compiling.
This keeps CSS file sizes down.

These were the core standards agreed on with the team. It’s worth mentioning that they were based on existing working practices so they might not be a perfect fit for everyone – however there are some important rules in the standards above that should apply universally.

No set of coding standards should ever be considered ‘complete’, however. A proper standard evolves as technology changes and our working practices improve.