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
Your site must be compliant with level AA of the Web Content Accessibility Guidelines 2.0. You should also try assistive technology tools as much as you can. However that’ll be far from giving you a complete view of the issues your service might have. With a bit of luck to will be assessed by proper accessibility experts (like the Digital Accessibility Centre). But don’t wait for it to happen to implement accessibility principles. Another helpful thing to do is automatic accessibility testing as part of your continuous integration.
- Automated Accessibility Testing in Rails with capybara-accessible:
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
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 (eg. modern.ie)
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.