Guidelines for developing data visualisations on the web

Visualising data on the web is an elaborate task in an age where devices are multifarious, inclusive design is the responsible thing to do, and the multitude of tools and resources can become perplexing. This post describes the challenges that our team faced when working on a data visualisation project that needed to meet criteria such as: usable, responsive, visually compelling, interactive, compatible across browsers and operating systems, and very importantly, accessible. Based on our experiences, we have formulated a set of guidelines for developing data visualisations on the web.

Start with user needs

Firstly, identify the users to help shape the right solution. This means knowing the target audience and the devices they might interact with the data visualisations on. Our user-base is largely non-technical and in managerial roles, so the charts needed to communicate relevant and meaningful statistics, as well as include digestible written content. Statistically complex and heavily annotated system monitoring visualisations were clearly off the charts. The visualisations also needed to be supported on mobile, tablet, and desktop devices, and across a variety of operating systems and browsers.

Explore what’s out there

Second, doing some light experimentation with a handful of visualisation libraries can help narrow down implementation choices. It was certainly an exciting discovery to find the number of libraries that can produce beautiful interactive and responsive charts out-of-the-box with minimal effort. However, there was an interesting dilemma due to a dichotomy between using a library that offers a high level of control but comes with a high development effort, (eg D3.js), and a more constrained library that ships with pre-built and customisable charts (eg Chart.js, Highcharts) that allows faster development. We opted for the latter; I will describe why next.

Narrow down your explorations

Most libraries with pre-built charts are responsive, interactive, and cross-browser compatible, so these criteria can easily be ticked. One of the more defining implementation factors was the customisability of the charting library. For instance, we needed to adjust the charts to: apply branding styles, produce a specific range of visualisation types, apply custom annotations, and choose a library that was compatible with our software stack and data formats. If these can be achieved by customising pre-built charts, then the solution is clear-cut. But what narrowed down our choice even more was whether the library included out-of-the-box accessibility support, which leads nicely to the next guideline.

Inclusive design means accessible charts

Consider web accessibility and support for assistive technology. This is a legal, and therefore essential, requirement in our case. We typically follow the accessibility guidelines as defined by WCAG 2.1 (at the time of writing this post). For instance, we added screen-reader support, use of colour with consideration to visual impairments, and keyboard-only input functionality, among others.

Do the hard work to make it simple

Next, present the data in a clear and consistent way that’s right for the target audience. For example, we had multiple charts on a single page and therefore needed to include clear visual separation. We ensured that descriptive content surrounding the charts, labels on the charts, and the use of colour were consistent. Fortunately, the charting library we used included useful features such as annotations, toggle for data sets, and chart animations. Annotations helped us provide supporting content to data, for instance, we added a hover-over (and clickable) tooltip for each data point in our charts. This helps interrogate each data point in more detail, especially those that stand out amongst others. In addition, we included data set toggles (eg on a line chart) to help filter the data, and a modern aesthetic by using animations.

Build, measure, learn

Finally, test the charts with the right user base and iterate. We gathered feedback from the mock-up stage through to the functional prototype stage. This enabled us to gather useful feedback from the target audience and refine the charts so that the data visualisations were useful to the right people. When it comes to releasing, the charts do not need to be perfect. Creating releases early and often ensures that a wider range of target users are exposed to it sooner, and can provide useful feedback to iterate into the next releases.

To sum up

The above guidelines enabled us to develop a useful, usable, and compelling user experience. Although these are grounded within our project, we believe that the guidelines, as well as the challenges that we faced, can be generalised to other projects. Getting from start to finish can be challenging, but by building a good understanding of users, experimenting with existing technologies, adopting an iterative design and development process, and keeping things clear and simple, will certainly make life easier.

Designing design systems

“A design system can create value on at least two levels. At the team level, it can create a more streamlined, predictable process that reduces design and engineering time. At the UX level it helps deliver consistency and predictability in the interface, and to raise the quality of the experience overall when designers and engineers are freed up to think about higher-order tasks.” – Nick Stamas, Creative Lead at WeWork

What is a design system?

A design system offers a library of visual style, components, and other concerns documented and released by a team or community as design tools so that adopting products can be more efficient and cohesive. It is the canonical source of truth for product design and development. A design system breaks down the most fundamental and common parts of your interface such as colour, layers, typography, icons, interactions etc into simple, predictable elements that can be reused to build larger and more complex structures.


  • Increased velocity and time to market
    A element-based toolkit accessible in one place allows for a more ‘copy and paste’ Agile process, speeding up releases without compromising quality.
  • Increased product value
    Reusable components build upon each other, which creates a consistent look, feel, and behavior to the product. As consistency increases, so too does user efficiency.
  • Increased collaboration and knowledge sharing
    Because the shared design system includes approved assets and conventions, designers and developers are more autonomous without closing off into silos.
  • Less time and money wasted
    Because designers and developers aren’t caught up in redundant questions or repetitive work, they’re freed up for projects that deliver more business value.


Taken from Principals of designing systems

  1. Systems solve the easy problems so products can solve hard problems more easily
  2. Include what’s shared, omit what’s not
  3. Products own their destiny, systems equip them to realise that destiny
  4. Favour community over control
  5. Favour elegance of simple things over flexibility of complex things
  6. Make documentation first as a tool to use, then as pictures to show, then – if needed – as words to read
  7. Measure success on dependency
  8. Favour quality over quantity

What is the Jisc design system?

Our design system offers
visual style, UI components, and accessibility procedures
released as
Downloadable design assets, imagery and written guidance
This is documented at
and produced by
The ux team of 1 UX specialist (lead) and 2 UX developers,
in order to serve
≤ 5 web-based services currently, with the potential to grow to ~50
products and experiences.

This will cover

  • Principals – Our underpinning approach to design for the web
  • Grid – How elements are structured and flow within a responsive grid
  • Layers – How to build depth and visual hierarchy
  • Spacing – How to ensure consistent vertical and horizontal rhythm
  • Colour – What colours to apply in different contexts and use cases
  • Typography – Making pages clear and simple to understand
  • Icons – What icons we use for common / repeated interactions
  • Interaction – the states and motion of clickable elements

If you’d like to know more get in touch via or for further reading check out Nathan Curtis’ excellent medium posts.

Becoming a sticky note master


Sticky notes are an essential piece of kit for any UX practitioner, but sometimes we can miss the simple things that are right in front of us. At a customer experience mapping workshop last year Stavros Garzonis blew my mind, showing us how we’d been peeling off sticky notes the wrong way (keep reading to find out the correct way).

This got me thinking about what else I might be missing, doing wrong or forgetting about. In order to improve my collaborative sessions (inspired by this talk by Boon Sheridan) I started to create a list of things that help me focus on getting the most out of this powerful tool. Hopefully this list can help you with a few tips and set you on the path to become a master in the fine arts of the sticky note.

Putting pen to sticky

Everyone needs to be able to see and read what you’ve written. Whether this is someone at the back of the room or you the day after a workshop when you’re trying to read the notes from a photograph you took.

  • Always use marker style pens such as a Sharpie
  • Use simple words
  • As stickys get bigger, so should your pens
  • Keep the corners clear in case you need to add additional notes (or dots – see below)

Write, explain, place

Write down your idea, explain it to the group, stick it up. As a generalisation, no one should put up a note without explaining it first. Building a shared understanding is essential for collaboration.

The right way to peel

Instead of peeling from the bottom up, peel across the sticky strip. This stops the sticky curling up, making your note flatter and reducing the opportunity for it to fall off and easier to take photos of. Check out this video (complete with powerful 80s synth soundtrack)

Organising ideas

The power of sticky notes is their flexibility. You can use them to create information – generating ideas, exploring problems or attributes. Or to reduce information – identifying priorities and patterns. But with so much flexibility we need to remember the basic strategies for organising ideas (or stickys):

  • Lists – to prioritise or collect information about a topic
  • Clusters – to identify themes and patterns
  • Trees – for build a system flow or information architecture
  • Maps – to understand complex relationships


Sticky notes and dot stickers are best friends

Sticky dots are a fantastic way to help focus in on ideas that resonate or the things that are most important by using them as a voting system. You can also use them to mark out notes for special attention for eg when something is based on assumptions, not research.

Use colours and sizes appropriately

Sticky notes come in a wide variety of sizes and colours for good reason. Be sure to plan your activities and make sure you’re not missing out on valuable data that could be lost if not captured using different colours or shapes.

Quality counts

Get the best ones you can, there’s nothing worse than your returning to work the day after to see a blank wall and a pile of sticky notes on the floor.

Location, location, location

Some surfaces and sticky notes just don’t want to play nice. If you have time ahead of your session then check the surfaces that you’re planning on using to make sure you’re not going to get a nasty surprise.

Sometimes it’s useful to use a transportable surface such as a whiteboard on wheels, magic cling or brown packing paper. This way you can take the work with you.

Putting it into practice

A customer experience map is a great example of how you can to utilise the power of the sticky note. This is the loose process that we followed in our workshop to create our maps and this hopefully gives you some ideas of how this can all be put into practice.

  • Start by capturing user tasks with no formal structure
  • Organise tasks into clusters to find the themes
  • Mark out and label themes with larger notes
  • Pull tasks into a logical order list under each theme and phase
  • Use different coloured notes to denote the good and bad experiences in your product
  • Use dots to denote where assumptions were made that require further validation.

Wireframe of a complete customer experience map

The value of online video subtitles

Adding subtitles or captions can make your online videos far more accessible and understandable – and it’s much easier and quicker to do this than you may think.
Video subtitles

Comprehension, concentration and clarity

An Ofcom study found that of 7.5m people who regularly use subtitles in the UK, only 1.5m of these are deaf or hard of hearing. The benefits of subtitles for those who aren’t hard of hearing include stronger comprehension of dialogue, increased concentration, and clarity of names or technical information. But there are also some important marketing reasons for using subtitles on your videos.

Capturing attention

As user attention spans continue to decrease and more and more content comes at us from all angles, it’s important to communicate your message and capture attention more quickly than ever. Short videos continue to dominate the mobile content consumption market, and including subtitles on yours gives them the best possible chance of both engaging a viewer within the critical first few seconds of viewing AND providing a better user experience for the duration of the video itself.

Luckily, YouTube has some handy built-in functionality for adding subtitles to your content quickly and effectively – and once complete you can export and apply the subtitles to the same video on Facebook in seconds. Here’s how.

  1. Upload your video to YouTube as normal, and then from the video manager select ‘subtitles and CC’ from the drop-down menu next to the ‘edit’ button.
  2. Select the appropriate video language from the drop-down menu that appears
  3. Select ‘add new subtitles or cc’ and again select the appropriate language from the menu
  4. Select ‘transcribe and auto-sync’. You can then play the video and type the words as they are spoken – make sure the ‘pause video while typing’ box is ticked so you can keep up with the dialogue. You don’t need to worry about formatting the text and it can be typed in one block or long paragraph – just make sure you use full stops and capital letters appropriately.
  5. When you have finished, select ‘set timings’ and sit back for a moment as YouTube matches the dialogue timing of the video to the words you have typed. Then click on the finished link under ‘my drafts’, make sure everything looks okay and if so click ‘publish’. And that’s it as far as YouTube is concerned!
  6. But some of the real value in having subtitles comes with Facebook – so go back to your published subtitles and select ‘download .srt’ from the ‘actions’ button.
  7. Upload your video to your Facebook page as usual then select the ‘captions’ tab. Choose the appropriate language and click ‘upload SRT file’.
  8. Navigate to your downloads folder and find the .srt file you just downloaded from YouTube. You may need to rename it – for example, if your Facebook language is set to ‘English (US)’ then your .srt file will need to be renamed with the format ‘’.
  9. Finally, select the appropriate option from the ‘default language’ drop-down and click ‘save’. All done – your subtitles will now appear on your Facebook video.

Even if your video is only going onto Facebook and not YouTube, you may find it easier to use the YouTube ‘transcribe and auto-sync’ option to generate the .srt file that you need for Facebook.

There’s no reason for not including subtitles on social media videos from now on!

Image: ‘Example of subtitles (Charade, 1963)

Access all areas

Graphic of a computer showing a simple grid template

When I first transitioned into a web team almost seven years ago, I started hearing terms that I knew were important to designers and developers, but didn’t necessarily associate with my content-based role. One of those terms was accessibility.

Making the connection

Before joining the wonderful world of web, I helped organise university events, such as awards ceremonies. Our team would arrange accessible ramps for wheelchair users, British Sign Language (BSL) interpreters for students and delegates who were deaf or hard of hearing, and shift seating plans to accommodate students who had broken legs two days before graduation.

In all these cases, my role involved removing obstacles from getting those people from A to B. Web accessibility – and accessible content – is, in simple terms, no different.

Lightbulb moments

A few years ago I attended the Future of Web Design and heard, then head of accessibility at GDS, Josh Marshall’s particularly informative session (similar to this Hot Source Norwich talk) on accessibility.

It was a bit of a ‘duh’ (ok, maybe ‘lightbulb’) moment and made me realise that accessibility goes beyond disability. Sure, different browsers, devices and screen sizes make a difference, but what about the age of your user, not to mention their PC (remember these old Packard Bells?) These elements will all have an impact on how accessible your content is to your users.

Everyday accessibility

Some things are now so embedded into how I work that I forget they also tick the accessibility box.

Semantic markup of headings

I’ve lost count of the amount of times I’ve shared the parent:child metaphor for headings (and will now be checking and re-checking that I’ve done this justice on this post!)

In brief, headings and subheadings have two main uses (explained far more eloquently in this WebAIM resource on semantic structure):

  1. They help users to scan content
  2. (Most importantly) they give your content a clear easy-to-follow structure for screen readers

Download the NVDA screen reader for free and see them in action for yourself. Then test how well your web content is doing with the WAVE web accessibility evaluation tool.

Remember alt text

I remember a particularly memorable conversation with an accessibility enthusiast at UWE, who taught me to understand the importance of alt text on images (cheers Gavin).

When we redesigned the Jisc website back in 2013, we made sure alt text was a mandatory, integral part of the image uploading process. This, together with descriptive image naming, also comes with SEO bonus points – score! Google’s image publishing guidelines are an excellent bookmark.

We’re also encouraging people to give us text explanations for infographics. Pretty as they are, sometimes they convey much more meaning visually than you can fit into alt text. We’re making a start – see the maps on this learning analytics report for example – but there’s still room for improvement.

Write in plain English

Don’t even get me started (actually, I sort of already did in my web writing back to basics post).

I remember being told* the following: the higher your level of education, the more status you have, the more you have to do and so the less time you have to read stuff. It’s a good mantra to write by.

According to Readability Score (recommended by GDS in their social media playbook), any general content should aim for an (American) grade level of around 8. You can use their tool for free to test how well your writing is doing.

Publish all your information on web pages

Without wanting to sound too much like the scary TV licensing man, we’re closing in on pdfs and working towards getting all our guides onto the Jisc website.

Because pdfs are designed for print, this is often at the expense of on-screen readability. As Gerry McGovern said:

“PDFs are not a web format. They are a way of delivering print content using the web as a distribution channel.”

Use descriptive links

Spread the word. ‘Click here’ (50p in the swear jar) is not the way to help people when it comes to web links.

As Anthony T says in his blog for Smashing Magazine: ‘click’ puts too much emphasis on mouse mechanics (what if you’re using your finger, a keyboard, or even a stylus!), while ‘here’ conceals what users are clicking.

This second one in particular is a big no-no; not just for users of screen readers, but for everyone.

Spread the word – decorate your office

A few months ago, Benjamin shared these brilliant Home Office posters on accessibility. They clearly and succinctly lay out the dos and don’ts of accessible design and are an excellent reference for designers, developers and content teams alike – something for everyone.

We’re now displaying them proudly in the Jisc office in Bristol. They’re a great visual reminder never to be lazy when it comes to content design. Plus, they look pretty.

We’re proud to say that we’ve been working pretty closely to their standards for some time, but there’s always work to do. So please do get in touch with your comments and suggestions.

* Christine Cawthorne at Crocstar – I have a feeling I owe this one to you!

Conducting a remote empathy mapping workshop


As a small, agile, multi skilled and geographically dispersed team that works on multiple products, building a shared understanding of needs and priorities for our work is key. Furthermore building empathy with our users empowers us to be better designers.

“In the end, design is all about empathy. This is what leads to creativity, inspiration and breakthrough solutions to problems.” – Leon Segal

Part of my role as UX specialist is to ensure that our whole team builds this empathy which we can carry throughout our work. One of the best ways for us to do this is to collaboratively work on UX artifacts such as Empathy maps.

Why empathy maps

Along with many other UXers, I have started to favour empathy maps as an augmented  form of user persona, as they allow you to focus on what users are thinking and feeling. They help to paint a picture of why users make choices and decisions or take certain actions that users themselves may find hard to perceive and articulate.

We’ve found Paul Boag’s adaptation works better for our team – for the reasons he states in his post – than the standard Empathy map template. Completed maps seem to resonate more than standard user personas and are a great reference point that’s easy to dip in and out of when needed. Furthermore they are quick and simple to produce and easy for everyone in the team to collaborate on.

Collaboration is key

Any collaborative ideation or workshop session generally benefits from everyone being in the same room, but due to numerous constraints this a luxury we can’t always afford – and I very much doubt we’re alone here.

It’s all too easy to just involve the 2 or 3 people that are in the same location as yourself to create such artifacts. But they won’t always build a full picture, or the shared understanding that you’re looking for. Worse still, there’s the urge to assume that your team already has a shared understanding and just plough head first into your work.

Its essential that the whole team gets involved bringing their individual understanding, knowledge, skills and expertise. However running a remote workshop with a whole team can be tricky and requires planning, preparation and patience.

Making it work for a dispersed team

  • Where possible use face to face video conferencing
  • Create your map in an online tool such as google drawings that the whole team can access and contribute to – Here’s our template
  • Allow approx. 30 min per map you wish to create, plus 10 min at the start and end to introduce and wash-up the session
  • Make someone the map owner whose role is to make sure (a) Everyone understands each of the notes and are happy with the wording, and (b) any future edits are done at the consensus of the team
  • When adding notes to the map: Write, Explain, Place – It’s important that no one adds anything to the map without explaining it first
  • Adding photo to the map helps you to visualise a real person to build empathy with
  • Use colour to signify when notes support (green) or detract (red) from your products objectives

Hopefully these tips will come in helpful if you need to run a remote empathy map session. And I’d urge you to try. There are actually a few benefits to taking this approach. Your finished maps can be centrally stored, easy to access, edit and print out when needed. But more helpfully by creating them digitally in the workshop there’s no need to type up afterwards!

Responsive web design (RWD)

“Day by day, the number of devices, platforms, and browsers that need to work with your site grows. Responsive web design represents a fundamental shift in how we’ll build websites for the decade to come.”- Jeffrey Veen

What is responsive web design?

RWD is a web design technique aimed at creating sites that provide a consistent user experience across a wide range of devices and screen sizes. Content, navigation and features should be both accessible and usable, with a minimum of scrolling, panning or zooming regardless of device you use to access them. The basic premise is that the content (written text, images and features) of your site becomes like water.

“Empty your mind, be formless, shapeless — like water. Now you put water in a cup, it becomes the cup; You put water into a bottle it becomes the bottle; You put it in a teapot it becomes the teapot. Now water can flow or it can crash. Be water, my friend.” – Bruce Lee


Responsive web design is also the most efficient technique for making the same code work across multiple screen resolutions.

What does responsive web design mean for Jisc?

  • Small, medium, large… A single site for every screen
  • Start with user needs, and understand their context of use
  • Take a ‘mobile first’ approach to design and content creation
  • Stop designing page layouts and start designing the parts that make up those pages
  • Choose progressive enhancement over graceful degradation
  • Unobtrusive JavaScript
  • Use language that is appropriate for both touch and non-touch devices
  • Be modular, use design patterns

For further reading check out RESPONSIVE WEB DESIGN by Ethan Marcotte

Designing mobile first


Ever heard comments that have gone something like…

“The sort of tasks that users are performing are too complicated for mobile”
“Analytics show our primary audience is desktop”
“Users only want a desktop site”

When desktop use vastly outweighs mobile it seems obvious to prioritise that as the primary medium. And following a strategy that puts mobile design first seems utter madness.

Mobile isn’t an edge case any more.  

It’s well documented that mobile web browsing is rapidly on the rise – in 2014 it overtook desktop browsing – and continues to grow rapidly. The concepts of graceful degradation and progressive enhancement have been discussed at length online and there are advocates of both approaches. On the face of things they seem fairly equal… As long as you can get the information or perform the tasks you want to do on your chosen device, who cares.

When designing for a desktop first you logically use the screen real estate that’s available to you. The problem comes when you try and squeeze (or gracefully degrade) your awesome desktop UI into a smaller viewport. In the most part you’ll end up with either a watered down version of your desktop site or something that is frustratingly unusable on mobile. Either way it will no longer be awesome.

Mobile first is a design strategy, not a primary use case

When i hear comments like the ones mentioned earlier my instinct is to dig deeper.

Why are the tasks too complicated?
Why does your analytics show higher use for desktop?
Why do users say they want desktop only?

Without boiling down the issues it becomes self fulfilling prophecy.

Mobile first is hard

Taking a mobile first approach means you’re met with constraints straight from the word go, smaller screen, fewer resources, more headaches. It forces you to make tough decisions, be brutal with your content, test your assumptions and be completely user focussed.

Not everyone has the skill (or confidence) to take this approach–or facilitate the discussions that it throws up–but the only way you’ll learn is by jumping in and doing it. There will always be cases where mobile first isn’t the right solution, or a feature simply doesn’t work on mobile, but without validating, testing and taking a mobile first approach you’ll never know what you might be missing.

Tips for designing mobile first

Start with needs
Document the user and business need for every page. If you’re finding this difficult then chances are you don’t need the page.

Mobile first is content first
Mobile first is equally a content strategy. The limitations that come with designing mobile first mean you have to be ruthless with your content. Taking this approach means your design will become more content focused, and in turn more user focussed.

Draw your user flows (and prioritise mobile)
Mapping out how the user will flow through your system and identifying the key steps and interactions before you start designing is essential. For some practical tips take a look at A shorthand for designing UI flows.

Understand the context of use
You may be familiar with user stories, but i find job stories a much more powerful tool to help define the context in which a user wants to perform a task. Check out Alan Klement’s 5 Tips For Writing A Job Story for more info.

Split complex tasks into logical steps
Breaking up lengthy tasks (such as applying for a driving test) into steps will make them more manageable on mobile. Always provide context of where you are in the process eg step 2 of 5. And providing an brief overview of each next step (before you get there), will pre-arm the user and help them connect the smaller steps into the flow of the larger task.

Sketch out your ideas
Treat your sketches as experiments, record ideas quickly, make mistakes and find the right solution sooner. Wireframes will help to communicate and create a shared understanding of your ideas. Sketching is a very accessible format and keeping your ideas rough and ready allows the whole team to feel comfortable critiquing and collaborating on them.

How will it scale up, and back down again
Once you’ve got some mobile first concepts in the bag, scale them up to get the ‘bigger picture’. Designing your mobile concept up for larger screens will give you with more freedom–that may help you see new opportunities–which can in turn inform you mobile layout.

If you’re interesting in learning more check out Mobile first by Luke 

Creating a pattern index

UFV Graphic and Digital Design program

Following on from my previous post on taking a framework agnostic approach to documenting UI patterns I wanted to talk about creating a pattern index as a counterpart to a pattern library, or as a useful tool for anyone designing within a large web estate.

The spark

As with many things, an innocuous looking question sparked a train of thoughts and ideas that lead me down this road.

“What should we do in the event we need UI elements not covered by the pattern library?”

Our pattern library is a collection of user interface design patterns that solve common and recurring design problems. Tried and tested solutions that have been developed over time specifically for us, with both our brand and users in mind.

The best approach to developing a pattern library is to build from the ground up alongside a site as it developed, acting as the canonical design and technical specification of itself. However we had a need to create ours retrospectively, so logically started with the utilities (the grid, buttons, forms, icons, typography, navigation) and a few patterns (masthead and footer) that were required to give a distinct and consistent user experience to our web estate. We then have taken an iterative (agile) approach adding new patterns as needs emerge, allowing it to grow organically. All patterns have been ‘refactored’ directly from, improving code quality and design, as well as developing practical guidance on how, why and when to use.

However, has following this approach meant we have missed an opportunity? What about all the patterns queued up ready for ‘refactoring’ when their need arises? And what about the uncommon patterns that may never make it into our library? We always envisaged that as part of our guidance there would be an ‘in use’ section that would give examples of where patterns from our library have been implemented in our web estate. But what about all these other great patterns that are littered through our web estate?

Creating the guidance required to make all the UI patterns in any web estate reusable would be an enormous task, but creating a pattern index that collects examples and references is much more manageable.

A ‘pattern index’ defined

Wikipedia describes an index as:

“… a list of words or phrases (‘headings’) and associated pointers (‘locators’) to where useful material relating to that heading can be found in a document or on a page. In a traditional back-of-the-book index the headings will include names of people, places and events, and concepts selected by a person as being relevant and of interest to a possible reader of the book.”

I describe a pattern index as:

A list of UI patterns and associated examples to where useful material relating to that pattern can be found in a web estate. An index of patterns, interactions, transitions and concepts selected by a person(s) as being relevant and of interest to anyone working with its counterpart pattern library.

A pattern index is intended as a wayfinding tool, a place to find examples and references of where UI challenges have been met–much like–within your web estate. It should be as useful to those new to developing in your web estate as those responsible maintaining it. A pattern index should help to ensure consistency by documenting all the instances where patterns are used for quick reference, whether they’re in a library or not.

“You only need to visit any higher education site to see examples of this [inconsistent UX]. Navigation shifts position, form elements are formatted differently and even typography changes. This happens because it is easier to guess how a button might look then find out how it was styled in the past.” – Paul boag on How and why to create a pattern library.

Documenting UI design patterns

House plan

House plan

From the very beginning of the Jisc user experience and design project we knew that we didn’t want our pattern library to be just another framework. Bootstrap is widely used across our business and it’s fantastic for rapid development, but by its very nature it’s completely open to individuals interpretation of how to apply it. What we were creating had to add more value to the business than just another bootstrap.

At the start of this project CX partners undertook an expert review of high profile pattern libraries, style guides and frameworks. They plotted these on a perceptual map, and asked us to do the same for our vision of what we were creating. There was unanimous agreement that during the rollout phase of the project it needed to be more practical and structured, but as it matured and more sites starting using it that it should become more inspirational whilst still retaining its structure.

Position perceptual map

Position perceptual map

Knowing this structure was essential to the library, we identified two key types of documentation required for each pattern: how to use and how to implement. Bootstrap deals with the the how to implement part, but not how to use. If we wanted to create this balance of structure and practicality, whilst adding value to the business we needed to ensure we had not only the hard (technical implementation) guidance about a pattern, but the softer (UX and design rational) guidance.

I recently came across an article on UX Pin called How to Document Your Designs for Easier Reuse. This peaked my interests because the day before I’d picked up on a comment from a 3rd party back-end developer that was using the pattern library as a reference for how to solve a design problem about field labels. They weren’t actually using our CDN or our specific forms patterns, they were just using our library as a reference point for how solve a UI design problem – without asking a designer!

This made me think about what problem we’re actually solving with our pattern guidance. My belief is that it’s not how do I use this specific pattern, it’s how do I solve this UI design problem. Which is where I found the aforementioned article useful. Firstly it validated our logic for calling all the ‘things’ in our library ‘patterns’. They’re patterns because they are recurring solutions to common UI design problems.

“Patterns make websites and apps more learnable for users. Since they’ve already used the pattern on other sites, users can easily learn how to interact with them on yours.”

Secondly it lists the documentation that you will require to make your patterns reusable:

  • Name – The name of the pattern so you can all recognise it and find it within your patterns
  • Description – A short summary of its purpose
  • Context of use – Where and when you’re most likely to find the pattern put to use (a search box would appear on most pages of a content site, for example, perhaps at the top of the page)
  • Where used – This is a list of links to examples of it in action on a live website or app
  • How it works – A description of the actions a user takes and what happens as a result

We already use many of these themes in our how to use this pattern documentation, but I liked the explicit nature of these headings. It shouldn’t matter whether someone is using our library’s HTML, CSS and JS or that of Bootstrap or Foundation. Our documentation should be framework agnostic wherever possible.

There will always be examples where we need explicit guidance for a UI pattern. We have some patterns that signature to Jisc with a specific context of use, but we need to ensure that our documentation is relevant and reusable even when abstracted from the framework that accompanies it. As we add new patterns and continue the development of our library this is the key focus for all our guidance.