User Interface Standards and Guidelines


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:

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.

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

Not Recommended

Banner Home Background.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.

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:

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

Video Captions

Did you know that all video needs to be captioned in order to meet basic accessibility guidelines (See Understanding Success Criterion 1.2.1)? If you are not hosting your video on Youtube, which can generate captions for you, then you will need to manually add captions. There are great services, like Rev, that can perform this task for you very easily.

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

3.1.2 HTML Formatting

3.1.3 HTML Semantics & Nesting

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

4.1.3 CSS Formatting

/* 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 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;


.one .two div {
display: block;
} Naming

Not Recommended

.parent__child {}
.parent_child {}
.left-box {}


.parent-name-child-name {}
.related-links {} Complexity

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

Return to Table of Contents


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

5.1.2 SASS Formatting

5.1.3 SASS Selectors

5.1.4 SASS Variables, Functions, and Mixins

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.

├── 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

6.1.2 JavaScript Formatting

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.

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

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.1 Editors

10.1.1 Editor Plugins

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

Return to Table of Contents

11. Publications

11.1 Required Reading

Return to Table of Contents

About the Author

Michael Spellacy

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.