Front End Development Guide

Repository containing the VinoTrust development guide

Introduction:

A progressive enhancement approach

In acknowledgement of the web's inherent variability this development guide describes an approach based on the principle of progressive enhancement. In practice this means building the interface of a website or application in layers:

If the user’s browser only supports HTML they get content and the abilities to navigate and interact using forms.
If the user’s browser also supports CSS the application looks better.
If it can run JavaScript (and/or supports newer technologies colloquially known as HTML5 and ESNext) the experience will be enhanced by those capabilities.

The important points are that:

only the core HTML is required to meet users’ basic needs, and;
CSS, JavaScript and JavaScript APIs should be applied in such a way that they do not 'break' the experience for those clients that cannot support them.

Here are some resources to help new developers appreciate and communicate the value of progressive enhancement:

the Everyone has JavaScript, right? site which describes several scenarios that might result in your JavaScript not running
Jeremy Keith's Resilience: Building a Robust Web That Lasts from An Event Apart 2018
The book Adaptive Web Design by Aaron Gustafson

An emphasis on accessibility

Developers will also notice an emphasis upon accessibility throughout this guide. This is intentional and reflects the central importance of ensuring our services are accessible to users.

Make sure your technology, infrastructure and systems are accessible for users.

You can read the detail of this requirement in the W3C Accessibility Standards Overview

Checkpoint 1: Coding standards

This guide has a focus on the HTML, CSS and JavaScript code that is delivered to a user's browser and related client-side architectural considerations.

Client-side architectural considerations

The Resource Oriented Client Architecture describes a number of recommendations that should be reflected in the applications we produce, as appropriate. Some key considerations which are not represented elsewhere in this guide are:

All application logic resides on the server
A user must be able to link to a specific piece of information
Browser 'back' and 'forward' buttons should work as expected. There is a recommendation related to this regarding the History API
All JavaScript and CSS code must be static, and must not be dynamically generated by the server in a form specific to the resource requested. (Note that this does not prohibit the use of preprocessors like Babel or SASS, as the respective code is usually pre-compiled as part of the release process.)

Security considerations for front-end development

Development decisions can have significant reputational and financial implications for an organisation. Developers have a responsibility to ensure their code is sufficiently secure and provides adequate protection for assets. Developers should consider the security implications of all development choices and, where there is doubt, approach a senior or lead engineer for advice. Concerns that are of particular importance for front-end development are:

The need to sanitize and validate input, and escape output:
- Sanitize refers to escaping or removing unsafe characters from input data before it reaches an application storage layer
- Validate refers to ensuring the received data matches expectations
- Escape refers to preventing malicious code from being rendered and inadvertently executed by application users
Recognition that client-side technologies alone are insufficient to protect against malicious behaviour (for example, client-side form validation must be accompanied by server-side validation)
Recognition that resources sent to a browser can be obtained by users (for example, relying on CSS or JavaScript to obfuscate an image is not sufficient).

Checkpoint 2: We meet needs using HTML

General HTML principles

There are a few principles which we follow for all HTML we produce. The peer review will check that:

HTML5 Document type is used and the <html> tag includes an appropriate 'lang' attribute (typically en)
HTML validates (W3C validation tool options include http://validator.w3.org/ or the newer, but still experimental - as of September 2018 - http://validator.w3.org/nu/)
The <title> tag is present and follows pattern {h1} - The National Archives
Source code is properly indented to reflect its structure

HTML5 syntax style

HTML5 has considerably relaxed the syntax rules for HTML. To ensure consistency across projects we have agreed upon a house syntax style. The peer review will check that:

Optional tags are used
All tags are closed, even where HTML5 might allow them not to be (as is the case for <li> and <p> tags)
Full attribute syntax is used and all attributes are quoted. See the W3C description of quoted attribute syntax
All tag names and attributes are in lower case

There is an appropriate HTML outline

HTML outlines are an important means for navigating pages with assistive technologies. All digital services we produce should have a logical document outline with one <h1> tag, and each subsequent <h*> serving to 'section' the content below it. Because - as of December 2017 - the HTML5 outlining algorithm is not implemented in any graphical browsers or assistive technology user agents, we do not rely on HTML5 sectioning elements for outlines.

The peer review will check that:

The HTML outline is logical and based on an appropriate heading structure
All content appears in the correct part of the outline

Appropriate semantics are used

We use HTML elements for their intended purpose, ensuring valid semantics wherever possible. We do use HTML5 sectioning element semantics (<section>, <article>, <nav>, <aside>), but do so with care and avoid using them for document outlining.

We use WAI-ARIA landmark roles (application, banner, complementary, contentinfo, form, main, navigation, search) and a traditional document outline for structuring documents. The peer review will check that:

There should be one <main> element and role=main should be applied for compatibility with older browsers.
HTML5 sectioning elements are used for semantics not structure
HTML5 sectioning elements are not over used in place of <div> elements
All relevant WAI-ARIA landmarks have been applied

Note: Developers should use role="application" with caution as it signals to screen reading software to turn off normal web navigation controls. Refer to W3C guidance.

HTML is ordered to support user needs

Navigation will typically be before primary content, and secondary content after primary. The peer review will check that:

The order in which elements receive focus when a user tabs through the document supports user goals.
In-page navigation is facilitated with 'skip to content' and 'back to top' links where appropriate

Forms

We ensure our forms are accessible, usable and make best use of HTML5 and ARIA semantics. The peer review will check that:

Forms are fully accessible via keyboard alone
Forms are logically organised
Instructions (such as 'required' fields) and cues are clearly identified to users
Where appropriate, <fieldset> is used to group related inputs and <legend> is used to describe these groupings
Form elements are appropriately labelled, with labels having a 'for' attribute linking them to the corresponding input (we do not nest inputs in label elements)
Appropriate use is made of HTML5 form semantics (i.e. <input type="tel" />) so that user agents can assist users with an appropriate input mechanism
Good use is made of appropriate ARIA landmark roles (i.e. <form role="search"><input type="search" /></form>)
HTML5 form validation is used, supported by JavaScript validation for older browsers. This is covered in the JavaScript section of this document
Error messages are clearly visible and associated (both visually and within the DOM) to the corresponding input. This includes appropriate use of ARIA attributes.

Tables

Where appropriate, tabular data is placed in HTML <table> elements. We never use tables for layout and avoid re-purposing other elements to recreate table-like representations of data. WebAIM provide guidance on ensuring tables are accessible

The peer review will check that:

All tabular data is in <table> elements
A brief descriptive <caption> is provided for tables
Table headings are provided in <th> elements with an appropriate scope attribute

SVGs are accessible

Where appropriate images should be delivered in SVG format since this offers two significant accessibility benefits: the scalability of the image allows users with less than 20/20 vision to enjoy crisp images when zoomed, and; the inclusion of links within the SVG will allow for keyboard navigation by default.

Guidance for using SVG includes:

Use inline SVG where possible
Provide a title for the SVG in <title> tags and a description within <desc> tags
Use the <text> tag for any text to appear in the SVG
Use <a> tags for links within the SVG
Provide an ARIA role for the SVG
Provide a non-SVG alternative. If the SVG is purely graphical, the <title> and <desc> tags may suffice. If the SVG is interactive, an HTML alternative should be considered

Related resources are:

Tips for creating accessible SVG, by Leonie Watson

Where SVGs are used, they are used accessibly

Images

Decorative images should be implemented using the CSS background-image property, so that assistive technologies can ignore the images. If a decorative image must be implemented using the HTML <img> element, you must ensure that:

The element's title attribute is either absent or empty.
The element's alt attribute is empty (alt="").
The element's role attribute is set to presentation (role="presentation").

For more information, see:

Where appropriate and practical we do make use of the incoming srcset attribute on <img> elements.

There is good use of appropriate ARIA roles to support native semantics

While HTML5 provides a range of new semantic elements which are recognised by newer browsers, there is poor support (even in newer browsers) when it comes to reporting these elements to the Accessibility API. This, and the lack of semantics when these elements are polyfilled with JavaScript, makes ARIA an important tool. Because the HTML5 spec was updated in mid-2014 to indicate compatibility between elements and ARIA roles, developers can see the compatibility of an element with ARIA roles, states and properties by looking up the tag within the HTML5 specification.

Because we are focussed in Checkpoint 1 on the HTML delivered to the user's browser, developers should ensure that all relevant static ARIA roles have been applied (these being landmark, region, and speciality roles) as well as any relevant pseudo interactive roles (such as dialog). See ARIA role conformance matrices or ask a fellow developer for guidance if needed. At this stage it can be very helpful to think about the four 'rules of using ARIA in HTML' from W3C notes on ARIA use in HTML:

If you can use an HTML element with the required semantics and behaviour built in, then do so
Do not change native semantics, unless you really have to
All interactive ARIA controls must be usable with a keyboard
Do not use role="presentation" or aria-hidden="true" on a visible focusable element

Related resources are:

The peer review will check that ARIA roles are provided to support native semantics

Checkpoint 3: Enhance with CSS

General CSS principles

There are a number of principles which we adopt for all CSS. The peer review will check that:

CSS is valid
All CSS is placed in external stylesheets
Relative units are used where possible
ID and class names reflect the purpose of the element in question
!important is avoided unless absolutely necessary (which is almost never)
Styles targeting older IE are placed in IE specific stylesheets that are included using conditional comments
Hacks for other browsers are placed in the 'shame.css' file

User focus is clearly visible

It is important to ensure interactive elements have a distinct visual appearance when activated. The peer review will check that all interactive elements have a clearly differentiated visual appearance when they have focus (this can typically be achieved using :focus)

SASS guidelines

As we more routinely incorporate CSS-preprocessing into our workflow we need to ensure our approach is maintainable (so that future developers understand the code we're writing today) and as simple as possible. Some useful insights are provided at SASS guidelines but developers will need to exercise judgement about what is most appropriate in the specific circumstances. A useful principle to bear in mind (from the SASS guidelines) is that:

... CSS is a simple language. Sass, being intended to write CSS, should not get much more complex than regular CSS. The KISS principle (Keep It Simple Stupid) is key here and may even take precedence over the DRY principle (Don’t Repeat Yourself) in some circumstances.

Sometimes, it’s better to repeat a little to keep the code maintainable, rather than building a top-heavy, unwieldy, unnecessarily complicated system that is completely unmaintainable because it is overly complex.

Developers are strongly encouraged to contribute to this section of the development guide as we get more familiar with SASS

SASS/CSS formatting standards

To ensure consistency across developers and assist with the maintainability of our code base we adopt a number of general CSS code formatting standards. The peer review will check that:

Code blocks have consistent indentation to reflect their hierarchy
Rules are separated with new lines
All rules are closed with a semicolon

Print CSS

We need to ensure we have accounted for users printing our content. While modern browsers provide a facility to emulate and debug print from within Developer Tools, we have encountered issues where IE prints differently to other browsers. The peer review will check that:

The printed page is well formatted, with legible content
The printed page does not include unnecessary components like decorative images and form elements.
The printed page includes full hyperlink destinations (appending our domain where they are relative)
Print specific styles are contained within in a @media = print block

Checkpoint 4: Enhance with JavaScript

Transpiling new versions of ECMAScript to natively supported JavaScript

New releases of the ECMAScript are expected to be released every year from now on with versions being referred to by their publication year (ES2017, for example). While Firefox, Chrome, Edge and Safari offer good (over 96%) compliance with the ECMAScript 6 (ES6) specification, the use of a transpiler - such as BabelJS - remains essential for developers seeking to use any language feature beyond those available to the browsers we support. At the time of writing this is ES3.

Developers are encouraged to make use of the benefits provided by newer language features provided that usage is via a local build system (such as Webpack and Babel) which creates an output file that can be interpreted natively by supported browsers. Do not deliver unsupported code to the browser and rely upon including a script to transpile in the browser (these tools do exist but are intended for prototyping purposes only).

General JavaScript principles

There are a few principles which we follow for all JavaScript development. The peer review will check that:

JavaScript is logically organised and, where necessary, well commented to aid understanding
JavaScript is well formatted with consistent indentation
JavaScript does not cause any errors (including tests across older IE which do not support ECMAScript 5)
JavaScript is externalised into .js files. We do not place JavaScript in <script> tags or use native inline event handling (i.e. <a href="#" onclick="triggerAlert('Bad practice!'); return false;">Joe</a>)
JavaScript is minified and concatenated where possible
JavaScript dependent elements are created with JavaScript. For example, if a <button> is used to perform a JavaScript action only, that button should be created with JavaScript
Any DOM manipulation performed by JavaScript is accompanied by the application and management of relevant ARIA roles, states and properties. These should build upon the static and pseudo interactive roles applied during Checkpoint 2.
Server-side processing is used to ensure JavaScript is loaded only where needed

Relevant resources include:

Writing JavaScript with accessibility in mind

Please speak to the Lead Front-end Developer if you need guidance on meeting any of these requirements.

JavaScript Testing

JavaScript and jQuery code is tested using well established testing tools. Tools currently in use include Jest, QUnit, Jasmine and Mocha. We are open to exploring other options but please discuss this with all team members so that we can be considered and surefooted in our adoption of new tools.

We use established libraries for DOM abstraction

Established libraries such as jQuery, Angular and ReactJS provide an excellent means of managing the complexity of DOM manipulation across browsers and devices. Attempting all but the simplest DOM manipulation without a 'battle tested' framework needlessly exposes us to a large number of cross-browser bugs and inconsistencies.

In our experience many newer developers are unaware of this. To demonstrate, you can find out the number of cross browser bugs being addressed in the current version of jQuery (which has long since dropped support for older IE), for example, with

curl -L https://code.jquery.com/jquery-git2.js | grep Support: | wc -l

At the time of writing this reveals 109 cross browser bugs being managed in the current version of jQuery . While many of cross-browser bugs are traditionally related to older browsers there are many fixes in these libraries tackling inconsistencies where you might not expect them.

We therefore use only established frameworks for managing complex interactions with the DOM. If you are unsure about any of this please speak to the Lead Front End Developer.

Accessibility is a primary concern when using JavaScript to introduce rich interactions

It is essential that we consider the implications for users of assistive technologies when:

Writing JavaScript to provide rich interactions
Reviewing third-party plugins that provide non-standard user interface elements.

This will include:

Ensuring that suitable ARIA role and state management is provided
Ensuring the plug-in does not make the DOM inaccessible (the overwhelming majority of assistive technology users are likely to have JavaScript enabled)

We should not use plug-ins that do not provide suitable ARIA role and state management, unless they are available for open source contribution and we have the skills and resources to extend them in line with the WAI-ARIA authoring practices9.

For this reason, jQueryUI presents a good tool as its authors have worked hard to include the necessary ARIA role and state management in the library components. Nonetheless, we should test the accessibility of custom widgets before they are used.

JavaScript form validation

We provide JavaScript validation for user agents that do not support HTML5.

Checkpoint 5: pre-release checks

Release version is WCAG 2.0 compliant at AA

The peer reviewer will:

Check compliance with the Web Content Accessibility Guidelines (WCAG 2.0) using the W3C Quick Reference
Ensure the site remains accessible in the event that JavaScript and CSS are not available
Take a broad view of accessibility considerations that may be relevant, paying particular attention to ensuring we have done all that is possible to make things as accessible as possible. Resources to help with this judgement include:
- the Understanding disabilities and impairments: user profiles by GDS
- the (now archived) BBC case studies that illustrate how users with different abilities adapt the way they use the web
- an Alphabet of Accessibility Issues to consider how the implementation will meet the needs described.

Before any code from a feature branch is merged the peer reviewer should be satisfied that:

Code is WCAG compliant at AA, including appropriate use and management of ARIA roles and states
We have considered a broad range of different abilities
The service is accessible and usable without JavaScript and/or CSS

Useful tools for accessibility testing:

In addition to the W3C Quick Reference tools that may be useful are the:

aXe Chrome Extension which provides a developer tools panel that allows you to run an in-browser audit against a page, including a colour and contrast check. The extension features are described on the Google Chrome Developers channel on YouTube
Chrome accessibility Developer Tools. This does many of the same things as the aXe extension but also provides colour suggestions where contrast issues are found. This is also described on the Google Chrome Developers channel on YouTube

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
README.md		README.md

datahash/front-end-development-guide

Folders and files

Latest commit

History

Repository files navigation