Frontend Development Principles
This document lists some principles that developers at MOJ are strongly encouraged to follow when implementing a service’s frontend. These principles aren’t mandatory, but you should be able to provide a good argument if you choose to depart from them.
These principles are in addition to MoJ Development Principles
1. Follow Government Service Design Manual
The most important set of recommendations you really should follow is from the Government Service Design Manual, not only because the service you’re designing will be assessed against it 3 times before going Live, but also because it covers the broad principles and is generally right. What follows are MOJ-specific recommendations.
2. Make your service accessible
In the UK, the Public Sector Bodies Accessibility Regulations mean we are legally required to make sure our digital services meet level AA of the latest version of the Web Content Accessibility Guidelines.
You should make efforts to ensure what you are designing and developing is accessible as you go, rather than waiting until the end to think about and test for accessibility.
Some things you can do as a designer or developer include: - Using the GOV.UK design system components as much as possible. These have all been carefully built and tested to be as accessible as possible. - Using automated accessibility testing tools. These tools can help you catch 20-30% of accessibility issues early. The rest require manual testing by people. Links to popular options are provided in the further resources section. - Ensuring all of your colours provide good colour contrast. - Providing a descriptive page title on each page. - Using logical heading structures. - Writing meaningful link texts. - Ensuring images have appropriate alt text. - Making sure you can access all parts of your service just using the keyboard alone. - Making sure the site accommodates browser zooming up to 400% without any loss of content or functionality.
Further details on these points can be found in this guide to content accessibility.
If you feel comfortable, you should try testing your service using some of the assistive technologies built-into your computer. Testing with a screen reader is a good way to check for issues that might affect other assistive technologies as well.
These resources will help you get started with screen reader testing: - Desktop Screen Readers Survival Guide - Basic Keyboard Shortcuts - Desktop Screen Readers Forms Guide
MoJ Digital Accessibility Team
The MoJ has an in-house digital accessibility team that can support you with your accessibility needs. They provide consultancy, training and run an accessibility champions network. These services can be used at no cost to your team. They can also help you arrange a full accessibility audit using our approved external supplier. There is normally a cost for that service.
- Digital Accessibility Team - what we do
- Accessibility consultancy service
- Accessibility training courses
- Accessibility training recordings
- Accessibility Champions Network at MoJ
- Get an accessibility audit
Further resources
- What you need to know about the new version of the Web Content Accessibility Guidelines (WCAG)
- What projects and service teams need to do about accessibility
- How to test for accessibility
- Write an accessibility statement
- Axe accessibility testing tool
- Pa11y accessibility testing tool
- Accessibility Insights accessibility testing tool
- WAVE accessibility testing tool
3. Make it easy to change your code for copy and translation
All the user-facing text in your application should be in the same place in the code, typically in templates. This includes conditional content and error messages. It makes this easier for a content designer to check and modify the application’s copy. Also make sure your service is easy to translate in another language.
4. Support as many browsers as possible
Your site is expected to work on all the browsers listed in the Verified Browsers page in the service manual, but try to include as many browsers as possible on top of that list. A browser with 0.1% market share accounts for 50,000 visitors a month on GOV.UK. Avoid browser sniffing. Instead, use feature detection. That will also result in your site being forwards compatible.
5. Use responsive design
Make the content of your pages flow nicely with any screen size: use media queries, prefer relative units and use fluid grid layouts. Get some help from your team’s visual designer if you’re not sure what a page should look like at a specific resolution.
6. Use progressive enhancement
Design pages with the lowest common denominator of browser functionality in mind (ie, HTML4, no JavaScript, no CSS), then build styling and behaviour on top. Make sure that any scripting or styling you add isn’t essential to the use of the service.
7. Don’t optimise prematurely
Optimising web pages for speed can lead to very complex code that breaks fundamental principles like separation of style and content. Only optimise if you have evidence that current front-end performance is detrimental to the use of the service
8. Work with your team
You should establish a close relationship with your team’s visual designer and content designer. Things can get waterfally when you expect things to happen in order: designer designs designs, content designer provides copy, you implement. That doesn’t work. Constant feedback and interactions work much more efficiently.
You should make sure your designer provides multiple designs, or at least checks the various layouts you will implement for small screens, no JS, etc.
9. Don’t make too many assumptions on user behaviour
You are not the user. You can only make assumptions on how your site will be used by its intended audience. Often they’ll be wrong. If you’re not convinced, go to a user-testing session and you’ll understand. Listen to the user researcher in your team, they know more than you. Analytics also provides insight on site usage, but they don’t replace watching people use your service.
10. Be conservative in your choice of technology
(frameworks, build tools, languages)
There are many many possible technologies, tools or libraries you may be familiar with, or interested in trying out. Eg, SASS, Grunt, CoffeeScript, TypeScript, EcmaScript 6, Polymer, etc. Keep in mind that your code should still be maintainable long after you’ve left. You have to be confident that the technology you want to use is likely to still be around a few years into the future: whether devs will be familiar with it or will have heard of it, whether documentation will still exist, and new versions are backwards compatible, etc. If in doubt, ask the community. jQuery, Grunt and SASS are currently widely used across departments and are considered OK.
11. Beware of single-page apps
It’s very difficult to design single-page apps (SPAs) that are accessible, browser-independent, offer the benefit of progressive enhancement, and are search-engine friendly. That’s why they’re rare in Government. Before deciding to implement one you need to be absolutely sure that all your users will be able to use the service whatever their device. Most often SPAs will be implemented for internal services for which the lowest-common technology is somehow high enough to allow them.
12. Write unit tests
For fine-grained inputs-results tests of your JS functions, especially ones that don’t have side-effects like modifying the DOM (example from Send money to a prisoner). In general there won’t be much “pure” JS code in your app, so there won’t be many of these.
13. Write functional tests
ie, tests that replicate user journeys. Cover all possible journeys, not just the happy path. - There should be many of them and they should be run every code change. - They should be expressed in an easy-to-read form (Eg. Money to prisoners, Prison visits) - You should preferably use your back-end test harness (eg, rspec, unittest) so that all the application’s tests are in the same place. Most support browser-based tests using webdriver. - Don’t just check the text contents of a page, but also check the computed CSS (eg. Money to prisoners).
BDD (using cucumber or any other human-readable way to write tests) will only work if your team has the right workflow for it. Unless you have someone else (ideally your product manager) committed to writing the tests and checking that they pass, you’ll waste time writing code to translate your tests into code, instead of writing it directly.
Visual tests: automatically generating screenshots from a user journey script, and comparing with reference images. Ideal, but hard. You’ll have to regenerate your reference images every time the design changes, ideally from images supplied from your designer and not from your own implementation.
14. Use the right tools
When writing your code, you’ll be checking your results and debugging them in your favourite browser. Make sure you also check on the most common browsers. You may find that Firefox is best for debugging, but don’t forget to check Chrome and IE as often as possible. Use browsersync to try multiple browsers at once and use virtual machines for old browsers.
15. Implement SEO and semantic markup
Apart from internal sites and ones that are on service.gov.uk (which should block web spiders), you should make your pages easy for robots to understand. Following the service standards gives you the basics of SEO, but sometimes is makes sense to do more, like using semantic markup so that search engines are able to find things like a court’s opening time, an address. Schema.org is currently gaining in popularity and is worth looking into.