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 Radancy 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 Radancy.

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

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

1. General Concepts

At Radancy, we embrace web standards and keep up-to-date with the latest developments within the web industry. We are committed to giving all 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 (ES6/ES5)
• 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 a users right to universal access, our baseline development standards for all of our web offerings attempt to meet WCAG 2.1 Level AA guidelines at all times.

• WCAG 2.1 Documentation
• How to Meet WCAG 2.1
• Understanding WCAG 2.1
• Techniques for WCAG 2.1

1.2 Operating System Support

Radancy supports websites and applications on the following operating systems:

See Radancy Support for more details.

1.3 Browser Support

Radancy 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 Radancy 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 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.

Many browser add-ons and development tools have validation built right in, so be sure to use them.

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: ~75-85
• Cumulative Page Weight: ~1.5 and 2MB

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):

• Tiny PNG (Online Tool, not only png)
• Compressor.io (Online Tool)
• JPEGmini (Online Tool, jpg only)
• RIOT (Standalone Application)

2.5 Video Optimization

Make all efforts to optimize video as much as possible—especially if it is being self-hosted. Handbrake is a very useful tool for this task. There are lots of great tutorials on the web that can teach you how to use Handbrake and tighten up the screws for optimal video streaming and playback.

2.6 Minify

2.6.1 HTML

Do not minify HTML.

2.6.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.6.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.6.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.6.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('../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('../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.

/*!

Title: [Project Title]
Author: [Company & Office Name]
Developer: Full Name (Email Address)
Ticket: [Ticket Number]
Creation Date: [YYYY-MM-DD]

****** Change Log ******

Ticket: [Ticket Number]
Developer: Full Name (Email Address)
Manager: PSS or DPM Name (Email Address)
Date: [YYYY-MM-DD]
Comments: [Succinct description of tasks performed]

*/

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-color: #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 CSS Selectors

4.1.4.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;
}

4.1.4.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.4.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 Radancy 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
└── global.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.

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 our community or just plain common sense, we have come to discover what works better for users on on the web and what does not. This section is dedicated to sharing some of this conventional wisdom.

9.1 New Window Links

If new windows must be opened, please ensure they are being implemented properly, otherwise it is often best to avoid the practice entirely. Before making a decision, please read The Last Word (Maybe) on Opening New Windows.

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. Recommended Tools

10.1 Editors

• Sublime Text
• Atom

10.1.1 Editor Plugins

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

10.1.1.1 Sublime Text

• Package Control
• EditorConfig
  • Download our standard EditorConfig file, rename it to .editorconfig, and place it in your project root.
• Emmet
• HTML-CSS-JS Prettify
• Nettuts+ Fetch
• SASS
• SublimeLinter
  • SublimeLinter-contrib-scss-lint
  • SublimeLinter-csslint
  • SublimeLinter-html-tidy
  • SublimeLinter-jshint

Return to Table of Contents

11. Publications

11.1 Required Reading

• A Dao of Web Design by John Allsopp
• Ethical Design Manifesto
• Resilient Web Design by Jeremy Keith

11.2 (Highly) Recommended Reading

• Accessibility for Everyone by Laura Kalbag
• Adaptive Web Design (1st Edition) by Aaron Gustafson
• Anything written by Scott O’Hara
• DOM Scripting: Web Design with JavaScript and the Document Object Model by Jeremy Keith and Jeffery Sambells
• Designing with Progressive Enhancement: Building the Web that Works for Everyone by Todd Parker, Scott Jehl, Maggie Costello Wachs, Patty Toland
• Designing with Web Standards (3rd Edition) by Jeffery Zeldman
• Developing with Web Standards by John Allsopp
• Don’t Make Me Think: A Common Sense Approach to Web Usability (3rd Edition) by Steve Krug
• Inclusive Design Patterns by Heydon Pickering
• JavaScript: The Good Parts by Douglas Crockford
• Mobile First by Luke Wroblewski
• Responsive Web Design (2nd Edition) by Ethan Marcotte
• Using ARIA by Steve Faulkner and David MacDonald

Return to Table of Contents

About the Author

Michael "Spell" Spellacy is the Director of Accessibility at Radancy. If you have any questions, feel free to contact him on Github or see what he is up to on his blog.