Standards and best practices

A suggested front-end approach

Individual developers will have their preferred methods for how they tackle their work, and it is not our intention to demand or enforce a specific approach.

Having said that, here we present a logical series of steps that, in conjunction with our documented best practices, should result in a simpler document structure, lighter CSS and JavaScript and a good level of accessibility and performance.

Plan out your task(s)

Unless you are rapidly putting together a prototype or testing a new technology, take the time to work out the best approach to building something before you start coding. Sketching something out on a bit of paper can be really helpful!

This is mostly about working out the best order in which to build the various elements of the website. The rule of thumb is to tackle items from most generic to most specific. The typical order is:

  1. Typography
  2. Colours
  3. Page framework (header, footer, main content container)
  4. Default page template
  5. Landing page template
  6. Listing pages
  7. (Other custom pages)
  8. Home page

If you are part of a big project team, a tech lead will facilitate the planning and help you coordinate with other team members.

Start with the HTML

In keeping with our HTML-first approach and our best practice of progressive enhancement, the pages we build should be functional with just the HTML. Translate the design visuals into markup, favouring semantic HTML elements over custom approaches. This HTML MDN article has a lot of good pointers, and the HTML Living Standard is helpful to check for valid combinations of HTML elements.

Structure your source order and document outline logically

The order of the markup should match the intended reading order of the page. There is an excellent page structure tutorial from W3C's Web Accessibility Initiative, but to summarise:

Consider the major landmark regions

Most web pages will consist of a header region, a main content region and a footer region. HTML5 provides specific HTML elements - header, main and footer - to use for each of these regions.

As developers they help us break down a page into logical chunks that we can hook onto later for styling.

For users of assistive technology they help to programatically define distinct areas of the page that are made visually apparent with placement, spacing, colour or borders. Indeed, it is a best practice for page content to be contained within a landmark region to help users of assistive technology navigate through a web page.

Define navigation regions

HTML5 provides us with the nav element to use for navigation regions. If there are multiple navigation regions on a page, for example global navigation and pagination, use a labelling technique so that assistive technology can distinguish between them.

Aim for a logical heading order

Heading elements construct a document outline that is helpful for people using assistive technology. Use them where it makes sense to add a heading, and not for purely visual design. Headings should be nested logically to label sections of web pages according to their relationships and importance. Taglines and subtitles below a heading do not generally warrant a new heading level.

Consider tab/focus order when introducing interactive controls

Placing a control directly ahead of the markup it will manipulate makes life easier for people navigating via keyboard.

For example, a button for toggling hidden content should be immediately followed by the content it will show or hide. If the button appears after the content (or if the hidden content is much further on in the markup) it becomes necessary to use JavaScript to move keyboard focus from the control to the newly revealed content.

Start with the "single column" version

There may be a need for grouping certain portions of the HTML into containers using additional markup, especially where the visual design calls for complex UI and multi-column layouts from certain viewport widths (working from smaller to larger). However, focusing on this aspect of the markup too early can easily result in bloated HTML.

A simple, unstyled HTML page is guaranteed to work on any device and browser. With the default width of 100%, it can be considered to be using a single-column, flexible grid - the perfect starting point for responsive design. Thereafter, try to add only what is absolutely necessary for the purposes of styling.

Ensure a native fallback for custom interactive items

You can use interactive elements, but there must be a fallback that allows for the same core functionality. For example, a dynamic autocomplete widget could fall back to a native select element, or similar.

Validate your HTML

With the essential markup in place, it is time to check the quality of your HTML using the W3C markup validation service. Focus on any errors that are reported - info and warning notices can be disregarded. Reach out to the Accessibility Lead if you have any concerns.

Re-check whenever your markup needs to change - it takes seconds and helps to eliminate silly errors.

Adding enhancements

Every time we add to our codebase - whether that be in the markup, the stylesheets or the JavaScript - we increase both page weight and complexity. Add only what you need to get the job done.

If using our Amplify front-end starter kit, a good first step is to review the list of SCSS partials that are imported for compiling into the final CSS stylesheets and comment out any that are irrelevant to your project. They can always be uncommented later if they are needed.

This also applies to Amplify's JavaScript files: review the imported files and starting contents of main.js and comment out anything unnecessary. For example, Amplify provides multiple examples of global navigation but you will only need the code for one of them. Also check the entries listed in webpack.config.js and remove any that create additional JavaScript files that are not needed for your work.

CSS

Be mindful that CSS has the potential to both help and harm accessibility. It can enhance typography, provide helpful focus styles and make UI components easier to interact with. However, it can:

JavaScript

JavaScript is incredibly helpful for making interactive components more accessible. It can help communicate changes in state to assistive technology, for example by managing certain ARIA attributes. However, it can also:

  • make it difficult or impossible to navigate using a keyboard or assistive technology,
  • make content inaccessible to assistive technology,
  • remove user control of automated content changes, and
  • confuse users by altering or disabling default browser functionality, or by triggering events the user may be unaware of.

Proceed with caution and pay attention to our JavaScript best practices.

WAI-ARIA

ARIA (Accessible Rich Internet Applications) can improve the accessibility of web pages and applications by providing extra information to screen readers, via HTML attributes. It is meant to act only as an extra descriptive layer for screen readers, providing additional context. It does not provide any functionality itself - that would need to be provided by JavaScript.

If used incorrectly, ARIA can do more harm than good.

  • Abide by the first rule of ARIA: "If you can use a native HTML element or attribute with the semantics and behaviour you require already built in, instead of re-purposing an element and adding an ARIA role, state or property to make it accessible, then do so."
  • Abide by the second rule of ARIA: "Do not change native semantics, unless you really have to."
  • Do not use ARIA to make up for poor choices of HTML elements
  • Do not use an ARIA role, state or property without a clear understanding of what it does - check out the articles on ARIA in our reading list
  • Do not use an ARIA role, state or property without testing with assistive technologies

Checking accessibility

Once you move beyond simple HTML it is highly recommended that you pay attention to our accessibility best practices while you work, and start using tools to test your code for accessibility issues.

It is expected that you will have performed accessibility checks on your work prior to raising pull requests for merging new work.

While working on discrete components or patterns, such as collapsible content or global navigation, use axe DevTools and/or WAVE to identify common issues. When you have a complete page layout, switch to Accessibility Insights for a more thorough check that will help you to test keyboard accessibility and focus order.

Testing with screen readers

If you have time to do so, any sort of screen reader testing is better than none at all. It is also enlightening to experience browsing the web from a different point of view!

There are many different screen readers available, and they do not all behave the same way. Some are free, some aren't. Some are tied to a specific OS environment. Many work best when used in conjunction with a specific OS/browser.

An accessibility professional recommended testing with screen readers in the following order, to limit the chances of going down "rabbit holes" that might be created by the "personality" of certain screen readers:

  • NVDA with Firefox,
  • then JAWS with Chrome,
  • then VoiceOver with Safari

NVDA is free, but requires a Windows environment. JAWS requires a paid licence. At Studio 24 we work in the macOS environment, so the only screen reader we can test with is VoiceOver with Safari - do not use VoiceOver with other browsers.

Here are some resources about using VoiceOver for screen reader testing: