User Interface Standards and Guidelines

Abstract

This document defines best practices for HTML, CSS, and JavaScript development, as well as other industry wide best practices that have been adopted by TMP Worldwide designers and developers. This document seeks to foster a standard approach to user interace development and should be shared with any designers and developers who produce user interfaces within our company as well as with vendors who produce interfaces for TMP Worldwide.

Please note that this is a living document that changes frequently. You may bookmark it and check back on regular basis or subscribe to notifications for this repository.

Help us make this document even better! Contributions are encouraged!

Table of Contents

1. General Concepts

At TMP Worldwide, we embrace web standards and keep up-to-date with the latest developments within the web industry. We are committed to giving users the best experience possible by using the latest methods and techniques, while also sticking to core principles, such as Progressive Enhancement and Resilient Design. In this endeavor, we use the following front-end languages in the majority of our work:

  • HTML5
  • CSS3
  • JavaScript (ES5/ES6)
  • jQuery (Latest)

1.1 Accessibility

All of your prospective job candidates, regardless of physical or technological capabilities, have the right to learn more about your company and access all job listings. To preserve users’ right of universal access, our baseline development standards for all of our web offerings attempt to meet WCAG 2.0 Level AA guidelines at all times.

1.2 Operating System Support

TMP supports applications on the following operating systems:

See TMP Support for more details.

1.3 Browser Support

TMP supports the current and prior major release versions of all browsers. Corresponding to the date in which your project has launched, we test all development in the following:

See TMP Support for more details.

1.4 File Naming Conventions

  • Only use lowercase alphanumeric characters and hyphens.
    • Non-indexable files (such as SASS) may also contain underscores.
  • Names should be descriptive of the file’s contents or image.
<!-- Not recommended -->
Banner Home Background.jpg
logo_1.png
doc-How_To_Apply.pdf
coffee.shop.jpg

<!-- Recommended -->
home-banner-background.jpg
logo-1.png
doc-how-to-apply.pdf
coffee-shop.jpg

Return to Table of Contents

2. Optimization

2.1 Validation

Code validation is an easy way to spot small issues that you might have missed without having to examine every element. Things like accessibility issues can easily be identified and fixed without much time wasted.

Check each completed project using the W3C Markup Validation Service to scan for issues.

Accessibility Testing

A really great tool to have at your disposal is Deque System’s aXe extension. If you are interested in including aXe testing within your local development or build process, please see Accessibility Testing with aXe-core.

2.2 Page Load Speed

Loading time is a major contributing factor to page abandonment. After completion of a site, each user interface developer should test their site using the Google Developers PageSpeed Insights or Pingdom for more detailed results. It is as easy as copying and pasting the URL into the text field.

Our desired score should be anything above 70/100, however our absolute lowest score should not fall below 60/100 on both mobile and desktop tests.

While it might not be possible to always achieve a perfect or near-perfect score, we should strive for a site that has the best possible score while maintaining the client requirements. Some issues might be out of our control as user interface developers, but we can take other precautions in order to develop the most efficient site possible.

2.3 Performance Budget

As part of our commitment to provide users with the best experience possible, we adhere to a performance budget for sites that we develop. Each user interface developer should monitor site performance during development, and each site goes through a performance audit during the QA process.

Our performance budget is:

  • HTTP Requests: ~70-80
  • Cumulative Page Weight: ~1 and 1.2 MB

2.4 Image Compression

All images should be run through an image optimization tool in order to reduce their file sizes for the web. In many cases, image file sizes can be drastically reduced, resulting in faster load times and helping to deliver the best experience possible to the user. This will also contribute to adhering to our Performance Budget. There are various tools for this including (but not limited to):

2.5 Minify

2.5.1 HTML

Do not minify HTML.

2.5.2 CSS

CSS should be minified if saving memory is worth sacrificing readability. Such occasions would include extremely large CSS files, or when minifying the code would push the site size under the designated performance budget and all other optimizations have been exhausted.

2.5.3 Sass (SCSS)

SCSS should never be minified. If the server has the ability to tie in a CSS preprocessor, no CSS output file should exist. However, if server-side CSS preprocessing is not available, all compiled CSS should be minified.

2.5.4 JavaScript

JavaScript should be minified if saving memory is worth sacrificing readability. Such occasions would include extremely large JS files, or when minifying the code would push the site size under the designated performance budget and all other optimizations have been exhausted. Another occasion would include a custom library commonly used on many sites with a solid understanding of how to implement it among all team members.

2.5.5 Third-Party Libraries

All third-party libraries should be minified unless some sort of customization has been made to it and requires readability.

Return to Table of Contents

3. Markup

3.1 HTML Coding Style

3.1.1 HTML Spacing & Line Breaks

  • Use soft tabs with a 2-space indentation. This is important because it’s the only way to guarantee that the code will look the same in any development environment.
  • Do not leave white-space at the end of any lines.

3.1.2 HTML Formatting

  • Use double-quotes around attributes.
  • Classes should be used instead of IDs unless you need to link (anchor) to something specific on the page.
  • Place the id and class attributes first, respectively, within an opening tag.
    • E.g. <a id="foo" class="bar baz" href="#quux" ...>...</a>.
  • Do not use trailing slashes in self-closing elements.
    • E.g. <img src="..."> instead of <img src="..." />, <br> rather than <br />, and <hr> instead of <hr />.
  • Boolean attributes don’t require a value, so don’t set one.
    • E.g. <input type="text" required>.
  • Avoid writing closing tag comments.
    • E.g. <!-- /.class -->.

3.1.3 HTML Semantics & Nesting

  • HTML should be as semantic and purposeful as possible.
  • Take care not to unnecessarily nest elements.
  • Before you use an element purely for styling purposes, ask these questions:
    • Can the parent element or a parent sibling be styled, instead, to achieve the same effect?
    • Can a pseudo-element be used in place of a span or div?
    • Can the HTML be restructured to be just as semantic and easier to style?
/* Not recommended - using a span */
.nav-item {
  padding: .5em;

  span {
    background: url('https://fake.path/img/nav-item.png') no-repeat center;
    content: '';
    display: block;
    height: 20px;
    width: 20px;
  }
}

/* Recommended - using a pseudo-element */
.nav-item {
  padding: .5em;

  &:after {
    background: url('https://fake.path/img/nav-item.png') no-repeat center;
    content: '';
    display: block;
    height: 20px;
    width: 20px;
  }
}

Return to Table of Contents

4. CSS

4.1 CSS Coding Style

4.1.1 Author Comment Block

Always include an author comment block at the top of your CSS. This is an important resource for any developers who work on the code after you.

/**
 * Authored: 2014-06-18 John Foo <john.foo@tmp.com>
 * Modified: 2014-07-25 Jane Bar <jane.bar@tmp.com> [#12345] Edits to the color scheme
 *           2014-08-10 Jeff Baz <jeff.baz@tmp.com> [#23456, #34567] Added job matching
 */

4.1.2 CSS Spacing & Line Breaks

  • Use soft tabs with a 2-space indentation. This is important because it’s the only way to guarantee that the code will look the same in any environment.
  • Align all rule declarations to the left edge of the editor.
  • Do not leave white-space at the end of any lines.
  • Use a space before { in rule declarations.
  • Place each property declaration on a separate line.
  • Use one space after : in property declarations.
  • Place spaces after commas in lists.
    • E.g. color: rgba(0, 0, 0, .5);.
  • Put } in rule declarations on a separate line.
  • When grouping selectors, put each selector on a separate line.

4.1.3 CSS Formatting

  • Use hex codes for colors, unless using rgba() for alpha transparency.
  • Use the three-character color shorthand when possible.
    • E.g #000.
  • Do not specify a unit for a 0 value.
    • E.g. margin: 0;, not margin: 0em;.
  • Do not include a 0 for decimals less than 1.
    • E.g. margin: .5em;, not margin: 0.5em;.
  • Numeric values should not contain unnecessary fractions.
    • E.g margin: 1em;, not margin: 1.0em;.
  • Use shorthand values when possible.
    • E.g. margin: 1px 1px 0 1px; should be margin: 1px 1px 0;.
  • Use single quotes around strings (or URLs), unless the single quotes would need to be escaped.
    • E.g. url('hello-world.png'); or content: "'this has single quotes'";.
/* Example */
.box {
  background: #fff;
  box-shadow: 0 0 5px 0 rgba(0, 0, 0, .5);
  padding: .5em;
}

.box::before {
  content: 'Example';
  display: block;
}

.box + .box {
  margin-top: 1em;
}

4.1.4 Border-box

Use box-sizing: border-box with fallbacks on the HTML element along with box-sizing: inherit on the universal selector. When an element does not need border-box, you can apply box-sizing: content-box. Since the universal selector uses inheritance, when content-box is applied to an element, all of its descendants are converted as well.

html {
  -webkit-box-sizing: border-box;
  -moz-box-sizing: border-box;
  box-sizing: border-box;
}
*,
*:before,
*:after {
  box-sizing: inherit;
}

4.1.5 CSS Selectors

4.1.5.1 Specificity

At most, aim for three levels or less of selector specificity, not counting pseudo selectors or media queries.

/* Not recommended */
.one .two .three .four div {
  display: block;
}

/* Recommended */
.one .two div {
  display: block;
}

.one .two div:hover {
  display: none;
}

4.1.5.2 Naming
  • CSS selectors should be semantic, describing the elements’ function. Semantic names do not include:
    • the name of a person.
    • an elements’ placement on the page, such as .left or .top.
  • Selectors should use hyphens to separate levels.
    • E.g. .job-group-title.
  • Selectors should not include underscores or any uncommon Unicode characters.
  • Selectors should not use camelCase.

/* Not recommended */
.parent__child {}
.parent_child {}
.left-box {}

/* Recommended */
.parent-name-child-name {}
.related-links {}

4.1.5.3 Complexity
  • Avoid using overly complex selector combinations and naming schemes.
  • Use as few selectors as possible to apply styling, while also keeping the CSS modular and flexible.
  • Avoid littering HTML class attributes with selectors that only apply one or two lines of CSS.

<!-- Not recommended -->
<ul class="floatLeft paddingT10 paddingB10 nav-parent">
  <li class="caps paddingL10 paddingR10 marginT10"><a class="bold textRed" href="#link-1">Link 1</a></li>
  <li class="caps paddingL10 paddingR10 marginT10"><a class="bold textRed" href="#link-2">Link 2</a></li>
  <li class="caps paddingL10 paddingR10 marginT10"><a class="bold textRed" href="#link-3">Link 3</a></li>
  <li class="caps paddingL10 paddingR10 marginT10"><a class="bold textRed" href="#link-4">Link 4</a></li>
</ul>

<!-- Recommended -->
<ul class="nav-parent">
  <li><a href="#link-1">Link 1</a></li>
  <li><a href="#link-2">Link 2</a></li>
  <li><a href="#link-3">Link 3</a></li>
  <li><a href="#link-4">Link 4</a></li>
</ul>

Return to Table of Contents

5. SASS

SASS is the preprocessor of choice for TMP developers. All preprocessed CSS should be written in SASS to ensure the interoperability of the code.

5.1 SASS Coding Style

The same rules for CSS also apply to SASS, unless specified below.

5.1.1 SASS Spacing & Line Breaks

  • Align first-level rule declarations to the left edge of the editor.
  • Nested rule declarations should have two-space indentation from the edge of the parent.
  • Put one blank line between property declarations and nested rule declarations.

5.1.2 SASS Formatting

  • Always put imports (@import) at the top of the document.
  • Always place mixins (@include) at the top of rule declarations, unless it must go somewhere else.

5.1.3 SASS Selectors

  • At most, aim for three levels of selector specificity, not counting pseudo selectors, media queries, or mixins.

5.1.4 SASS Variables, Functions, and Mixins

  • Variables, functions, and mixins should follow the same naming rules as CSS selectors.
  • Variables, functions, and mixins should be kept together in their respective groupings.
    • E.g. variables.scss, functions.scss, mixins.scss.

5.2 SASS Directory Structure

It is very important that all UI Developers have a consistent and uniform structure for their SASS directories. You will find yourself using the same base SASS files for multiple projects.

scss/
├── core/        Variables, functions, mixins
├── partials/    Global styles
├── vendor/      Vendor-provided styles, e.g. Flexslider
├── views/       Page-specific styles
└── main.scss    Primary SASS file

Return to Table of Contents

6. JavaScript

6.1 JavaScript Coding Style

6.1.1 JavaScript Spacing & Line-Breaks

  • Use soft tabs with a 2-space indentation. This is important because it’s the only way to guarantee that the code will look the same in any environment.
  • Do not leave white-space at the end of any lines.
  • Separate function declarations and control statements (if, switch, etc.) with a blank line, unless the function is a closure.
  • Curly braces ({}) can be omitted in if statements if the statement can comfortably fit on one line.
    • E.g. if(x == 1) return true;.
  • There should be no space between the name of a function or control statement and the opening (.
  • Use a space before { in function declarations and control statements.
  • Closing } (}) for closures) for functions and control statements should be on a separate line.

6.1.2 JavaScript Formatting

  • Use single-quotes around strings.
  • Declare new variables with var.
  • Use the following conventions for naming:
    • variableOrFunctionName (camelCase)
    • ClassName (PascalCase/CapitalCase)
    • CONSTANT_NAME (UPPER_CASE)
  • End all variable assignments, function calls, and return statements with a ;.

Return to Table of Contents

7. Images

7.1 Image File Types

While extracting images from a creative design, it’s important to consider which file type to use. Not all file types are created equal and while some offer images that are smaller, others are better suited to different situations.

  • .jpg — The JPEG format is recommended for most of the images that you will come across in a design. They offer lossy compression (reduced file size) while keeping decent image quality, depending on your settings. The JPEG format does not support transparency. Depending on the detail in the image, a Photoshop JPEG compression setting between 60 (High) and 80 (Very High) is recommended to keep a good balance between image quality and file size. Use your best judgement.
  • .png — PNG is a lossless format (larger file size) and is recommended in situations where the quality of the image is important, or where transparency is required. A possible use-case for a PNG image is a clients’ logo, where the quality of the logo is important and may contain transparent sections around it.
  • .svg — SVG is an older vector image format that has recently become a more viable option for the web. SVG is recommended for more simple images that need to scale or retain sharpness on a number of different screen densities. SVG also supports transparency. A great use-case for the SVG format would be, again, a logo or icons.

Alternative Text

Alternative text is very important to assistive technology users. If an image has text in it or is relevant to the surrounding content, then these are cases where alternative text is typically required. Images within hyperlinks also require alternative text. If you are not sure about when to add alternative text, then check out this handy Alternative Text Decision Tree.

7.2 Image Sprites

To aid in adhering to our Performance Budget, it’s recommended that logos, icons, and other small images be combined into a sprite. This results in a reduction in page requests, as well as a small reduction in file size.

If you’re not using a build tool, such as Grunt, you can create a sprite in an image editing program or use a sprite generator.

Return to Table of Contents

8. Git

8.1 Git Commits

When committing changes to a repository, use the standardized commit message template to detail your changes.

To configure Git to use the commit template:

  1. Download the standardized commit message template and place it in a permanent location on your local hard drive.
  2. From your shell, type git config --global commit.template path/to/commit/message. Be sure to replace path/to/commit/message with the actual path to the commit message template.

When you make a new commit, do not use the -m option. Instead just use git commit and let Git create a new commit message using the template.

Return to Table of Contents

9. Patterns & Anti-patterns

Through the trial and errors of others or just plain common sense, we have come to know what works on the web and what does not. This section will be dedicated to sharing some of this conventional wisdom.

Inappropriate use of spawning new windows may actually confuse users or make the experience unnecessarily complex or unpleasant. There are, of course, some good reasons to spawn new windows, but for the most part, the decision to open a link in a window should almost always be left up to the end user to decide.

Accessibility & New Windows

Indicating that a new window can be opened can help avoid creating a confusing or disorienting experience for all users. This is especially true for those users who may be using assitive technology to navigate your site or application. There are a few ways to do this. Here is one example:

<a href="https://www.tmp.com/" target="_blank" aria-describedby="new-window">TMP Worldwide</a>

...

<div hidden id="new-window">Opens New Window</div>

The aria-describedby attribute on the hyperlink can then be used as a styling hook for a visual enhancement, such as an icon, that indicates that the link opens up a new window.

9.2 Focus Outlines

The decision to remove outlines from focusable elements must be carefully considered. Users with low-vision may depend on outlines to navigate through the page they are visiting in their browser. Please note that many browsers may render outlines differently. If these default outlines are not desirable, a new default outline can be designed, but should be just as clear in bringing attention to the element that is being interacted with. Before taking this approach, keep in mind that many users may expect outlines to look and behave the same way that they do when they visit other websites, so changing outlines could have a negative impact on the user experience.

Return to Table of Contents

10.1 Editors

10.1.1 Editor Plugins

Below are recommended plugins listed for each recommended editor (if they support plugins).

10.1.1.1 Sublime Text

Return to Table of Contents

11. Publications

11.1 Required Reading

Return to Table of Contents

Moderators

Contributors

If you wish to contribute, fork this project, make some changes, and create a pull request.

New to GitHub? Learn the basics with the guide and learn the GitHub flow.

Quality Assurance and Accessibility

All patterns, layouts, and functionality are tested against our supported browsers. We also look for accessibility issues via automated and manual testing tools. TMP is committed to the accessibility of its websites and products and strives to meet as much of WCAG 2.0 Level AA as possible. If you discover any problems with our work, please open up an issue and let us know about it or contact Michael Spellacy.

Return to top