Skip to main content

https://gds.blog.gov.uk/2025/04/01/creating-interactive-design-documentation-for-gov-uk-one-login/

Creating interactive design documentation for GOV.UK One Login

Two pages from the GOV.UK One Login prototype. The left page explains the prototype’s purpose and key features, with a button labelled 'Start an end-to-end journey.' The right page shows a list of user journey options, including creating an account, proving identity, and accessing services.

Background

GOV.UK One Login lets users sign in and prove their identity so they can access government services quickly and easily. User-centred design (UCD) is at the core of our work, ensuring we meet real user needs while tackling complex inclusion and accessibility challenges

To help government services integrate with GOV.UK One Login, their service teams need to understand how it works. This can be challenging, as our service isn’t a single, linear journey but a multi-channel journey that involves a collection of triage pages and interrupted journeys. It also evolves constantly, with frequent updates to meet diverse user and service needs. This pace of change can make it challenging for other government department service teams to stay up to date and understand what they need to integrate with.

Challenge

Our challenge was to maintain a single source of truth that offered enough detail to guide our service teams. While we share user journeys through tools like Figma and presentation slides, these can be difficult to follow for those unfamiliar with our service. Keeping them updated also takes considerable effort, meaning they don’t always reflect the latest version.

Service teams can explore GOV.UK One Login in our integration environment, but this requires technical expertise and includes field-level validation, making it difficult to navigate quickly. Internal tools like Mural and our staging environment offered some support but faced similar challenges with usability and maintenance. Additionally, teams—including those who directly support users—need a clear understanding of the journey.

To address this, we needed a solution that was easy to explore, kept pace with our evolving service, and provided teams with a clear, up-to-date view of user journeys—helping them stay aligned with minimal effort.

Our approach

Our goal was to make our service visible and help service teams and our internal teams interact with it.  

To guide the work and keep a holistic perspective, we started with 3 principles:

Make it realistic - create an experience that looks and behaves like the real thing.

Keep it simple - make it straightforward to use and update, so it’s accessible to everyone.

Start small and iterate - begin with key features and improve gradually as the service evolves.

Based on these principles, we decided to build an HTML prototype using the GOV.UK Prototype Kit. This approach offered several benefits:

  • easily adding components and patterns from the GOV.UK Design System
  • showing different pages based on user input
  • sharing the prototype via a web browser
  • making it easy for others to contribute or reuse in their own projects

We started by building the primary user journey through the service and gathering feedback. This helped us add secondary journeys and make incremental improvements as the service evolved. To make sure the prototype was effective and easy to work with, we:

  • made only essential branching questions mandatory
  • simplified navigation for frequent users
  • structured our code to be easy to update and use progressive enhancement
Two pages from the GOV.UK One Login prototype. The left page is an interstitial page explaining how users can prove their identity at a Post Office, including details about scanning photo ID and receiving results via email. The right page shows a mobile frame on a desktop, displaying an app interface that instructs users to prepare their phone and photo ID, with a button to 'Start photo capture.'

“You’ve clearly not just emulated a user prototype. It’s really evident and very helpful, the content is obviously built for us.”

(Usability session participant feedback, Senior Product Manager)

Designing the solution

This wasn’t just about building a prototype. We wanted others to explore and understand how the service works without confusion about what is and isn’t part of the live journey.

We approached this by:

  • designing a clear visual language to distinguish the live journey from the tool, avoiding misinterpretation
  • offering flexible navigation options, including scenario-based exploration and a page index for jumping to specific points
  • providing contextual guidance through instructions, highlighting channel shifts and alternative routes, with interstitial pages to help users absorb key details
  • creating accessible HTML versions of the iOS and Android app journeys, with a responsive mobile frame to reflect the app experience for desktop users
  • adding a user journey library, allowing teams to quickly explore scenarios where things don’t go as expected when using GOV.UK One Login

To keep it up to date, we set up a simple maintenance process. Teams can report issues via a feedback form, and updates follow a federated model, allowing anyone with prototyping skills to contribute. Changes are reviewed through pull requests, guided by a runbook. We have used GitHub not only to host the prototype but also to serve as living documentation through release notes, making it easy for anyone to track the evolution of the service.

"This tool has been a game-changer for our engagement with service teams. It makes complex journeys much easier to understand and gives teams the confidence to see how GOV.UK One Login fits into their service."

Lead Product manager, GOV.UK One Login

Two pages from the GOV.UK One Login prototype. The left page is a page index with links to sections like entering document details, going through a fraud check, and managing login details. The right page is a user journey library that outlines 'Unexpected journeys,' including scenarios where users encounter alternative or error paths when using the service.

Delivering value 

The tool has soon become an essential resource not only for external service teams but also internally for our user-centred design colleagues, product teams and most importantly, our Contact Centre. For example:

  • contact centre staff use it for onboarding and training, helping them understand the journey and resolve queries faster
  • internal product teams use it as a cross-referencing tool, which has helped identify service inconsistencies and gaps, driving a shift toward pattern-based design
  • designers use it to build their own research prototypes, speeding up their process and ensuring they use the latest designs during research
  • technical colleagues use it to quickly test ideas and build proofs of concept
  • user researchers use it to gain deeper insights during cross-channel research, particularly when testing web-to-mobile handovers, as it provides a more realistic experience than tools like Figma or TestFlight

"The tool has transformed how we train and support staff. It’s reduced the time it takes to resolve user queries, helped us deliver better service overall, and enables our Agents to guide users through their journey independently, mitigating fraud risks associated with co-browsing."

Contact Centre Lead

The tool has evolved into a vital resource for delivering a joined-up user experience and as GOV.UK One Login continues to grow and change, the tool will evolve alongside it — adapting to meet the needs of teams across government.

If you’d like to explore the tool, you can request access via https://www.sign-in.service.gov.uk/documentation/end-to-end-prototype/identity-journeys

Sharing and comments

Share this page

1 comment

  1. Comment by Mrs Dias posted on

    Thank you this is really helpful!

    Reply

Leave a comment

We only ask for your email address so we know you're a real person

By submitting a comment you understand it may be published on this public website. Please read our privacy notice to see how the GOV.UK blogging platform handles your information.