Building accessible, mobile-friendly, fast-loading, attractive website components, and templates

It starts with atomic design

We are using atomic design principles to organise our vast number of components and design patterns. These take the form of:

• Atoms – these are the most basic building blocks within the pattern library and include elements such as buttons, colours, lists, and for inputs like radio buttons
• Molecules – are created when we put together two atoms from the design system such as a search bar, alert banners, and accordions
• Organisms – collections of molecules make up organisms and include things like a hero panel that sits at the top of a page
• Templates – similar to organisms except that they are site-wide components such as the website’s header and footer
• Pages – these are the highest level of fidelity with the pattern library, and contain all of the above and serve up actual static content for the user to have a preview of what all these components look like with actual content

The components are held in a ‘pattern library’ using a tool called Pattern Lab. This pattern library is a major part of our new design system; it’s the single source of truth for our design work. It will give us consistency across all future projects and enable us to continually improve over time.

Below is an example of the button’s atom in Sketch, the app we use for designing components and patterns:

Handing over to development

From Sketch, the designs are imported into an online collaboration tool called Zeplin. It enables designers and developers (who are often working across different teams and even countries) to ensure that design handoffs are implemented correctly with accurate specs, assets, and code. It brings clarity to a complex and fast-moving project.

Zeplin allows designers to add annotations to help developers understand what the component should do, as well as the different ‘states’ (for example, a form field that has an error).

This tool also provides the exact padding, margins, heights and widths on a component to save time going back and forth between development and design.

The above screenshots show the padding requirements, button colour, box shadow specs, and more.

Building components and patterns

Once approved in Zeplin, we can now move onto the front-end build within the pattern library. Our code for the pattern library lives in a repository on GitLab. Each component is broken into separate tasks and assigned to a developer as shown below:

When a new component is being built, a developer will then create a new ‘branch’. This allows them to work on just that thing, without effecting anything else that other people are working on at the same time.

When the component is ready for someone to review it, a ‘merge request’ is created. This enables other developers to review the new component and suggest changes if required.

Approving a merge request allows it to be merged into the main development branch once all the tests have passed. We test against a set of ‘acceptance criteria’ that are written before development starts so it’s clear what the component should do and how it should look.

We use a tool called GitKraken to enable developers to easily view (and use) different branches. This makes it easy to see the status of each branch (which branches have been merged, what the developer has currently checked out, and even allows a user to view code and see what changes have been made).

What is a component made of?

Each component in the pattern library follows the same structure:

• Twig file – mark-up of the component, HTML and TWIG
• MD file – documentation of the component
• YML file – document variant and preview data
• SCSS file – to style the component
• JS file – JavaScript file added if required

If a pattern has many variables or variations and the developer wants to show a couple of variants in the pattern library they can add extra YAML files with the naming convention button~VARIANTNAME.yml. An example of the code setup for this is shown below in the screenshot:

The above shows the code for the primary and one variant. The above code will produce the following in the browser:

The user can also view the HTML/TWIG and description of the component via an accordion:

How is a component tested?

Once the new component has been coded, it is then time to start ‘visual regression testing’. This is handled by BackstopJS. Briefly, regression testing checks that a developer’s code changes (in our case, as part of a branch) have not adversely affected existing features.

The tests will show:

• Reference – these images should be the correct up-to-date components already in the pattern lab
• Test – these are the new images generated from new components or when there have been changes made to existing components
• Difference – provides an overlay of both the above images, highlights changes in purple

Currently the primary button colour is our brand orange. The tests will currently pass as it has the reference image of a primary button as the brand orange. If a developer were to change the colour of the button to brand blue, the tests would then fail as the test images would be different from the reference images. This change would also be highlighted in a 3^rd column showing the visual change. If this was a change that was needed to be made the developer would then simply run a command to approve the change and re-run the tests to update the reference images.

What happens when a component is ready?

Once the images are passing, it is then time to commit and push code to the specific component branch for a peer and code review of the component. Other developers will ideally pull down the branch, have a look at the code and check the component in the browser, check the component against the requirements in Zeplin and check the images produced by BackstopJS.

Once all is working and correct, approvers (usually other developers) on the branch/merge request will approve for the component to be merged into the main development branch. The new component will be merged into the already existing components along with the new reference images. From here, developers can then pull down these new components to their local machine via the main development branch.

How are patterns used by the Drupal content management system?

The pattern lab is a separate entity from a content management system. Our choice of content management system for the new website, Drupal, provides an easy way as to which to integrate a pattern library into a project. The pattern library is pulled into the Drupal project and using a set of pattern lab custom functions, a developer can easily pull in components from the pattern library to use in Drupal templates in order to display dynamic data. A screenshot of this is shown below:

The above code shows a secondary button being pulled into a Drupal template via the pattern lab function and having its variables declared so it can be used as a search results filter trigger for the end user to view a customised set of results.

Pattern Lab enables developers to easily pull in pre-styled components without having to worry about front-end code or design. If we need to make a change to a component in the pattern library, rather than update the code in the custom theme, all a developer needs to do is simply update the pattern library via a command line instruction that will then update styles in both the pattern lab and custom Drupal theme.

Working with Manifesto

As mentioned, peer and code reviews are a critical part of making sure that not only the requirements have been met, but the code is readable, easy to maintain, update and optimised for Drupal. The team at Manifesto were able to bring us up to speed with technologies we had not really used at University of Dundee, such as Twig and BackstopJS. When committing code to branches for peer review they were able to guide and give advice on our code to make sure it was the most efficient and reliable it could be.

Most communication was done via chats on the individual component branches and in the task board cards in Gitlab. Emails would be automatically triggered whenever a team member from either University of Dundee or Manifesto commented on something in GitLab. We communicated regularly on Slack also for quick questions and queries.

Testing, testing, testing

Testing is playing a major role in rolling out the pattern library to the wider audience at the University of Dundee. We already touched upon the BackstopJS for testing, but we need to take into consideration accessibility testing, cross browser and different operating system testing. Our plan for testing each component is shown below:

The requirements are checked against Zeplin and also the ticket in Gitlab which corresponds to the component a developer is working on. This is a visual check and also to check that the values for things like margin and padding are correct. Pattern lab also has an inbuilt tool which allows you to resize the browser windows to see a component on different screen sizes. Zeplin also contains designs for each component at different screen sizes.

Accessibility testing

We use a number of tools to check for accessibility including WAVE and AXE. Both are accessibility testing engines for websites and other HTML-based user interfaces. They test for different accessibility needs such as colour blindness, semantic HTML, labels for HTML elements, and for aspects such as alternative descriptions for missing images etc.

We also check our components on a screen reader such as ChromeVox, the NVDA screen reader for Windows, or the built-in macOS screen reader, VoiceOver. These tests ensure that people with eyesight impairments can navigate the website and understand the content on a page. This work will help ensure that every visitor can easily find the information they need or complete a common task on the website.

We use another tool to check the components and patterns across a number of operating systems, devices and browsers which is called Cross Browser Testing. This tool allows us to run a number of emulators to check for errors in different browsers such as Internet Explorer, Chrome, and Firefox. It allows us to test on operating systems like Windows, macOS, and Linux. It also provides a number of emulators such as Android and Apple devices for different screen sizes and mobile operating systems, and if need be on different network signals such as 4G and wifi. Such a test is shown below:

Once all tests have passed, the component is ready to go and is fully approved for use in the custom Drupal theme. If something is needing fixed we can create a new branch from the develop main branch and create a new branch/merge request for a bugfix or update. This branch will then again be peer reviewed by other developers and once working will be merged into the main branch.

Conclusion

A lot of excellent work from developers in different locations have come together and built a design system which is fast, expandable, accessible, and modern in a short space of time.

Advantages of such a system:

• It will standardise our brand
• It makes it easy to maintain our digital brand
• It’s easily portable
• It’s flexible
• Our back end developers’ job is made easier due to less back and forth feedback
• External agencies can easily access and build with the pattern library
• It’s built with accessibility in mind, making it available to a much wider audience

Our pattern library will continue to grow as we add more components which will solve a wide variety of problems. Carrying forward what we have learned from this experience in building such a system will not only benefit our team but other teams around the University as we continue to push our new digital brand onto the web and beyond.

If you would like to know more about the University of Dundee pattern lab please contact myself (Ryan Mclauchlan) at r.d.mclauchlan@dundee.ac.uk or Steve Burrows at s.y.burrows@dundee.ac.uk .