nhsuk / nhsuk-prototype-kit

NHS.UK prototype kit enables you to make interactive prototypes that will look like pages on NHS.UK. The prototypes you make are a great way to show ideas to others and for conducting user research.

NHS.UK prototype kit

Visit the NHS.UK prototype kit site to download the latest version and read the documentation.

About the NHS.UK prototype kit

The NHS.UK prototype kit enables you to make interactive prototypes that will look like pages on NHS.UK. The prototypes you make are a great way to show ideas to others and for conducting user research.

Security

If you publish your prototypes online, they must be protected by a username and password. This is to prevent members of the public finding prototypes and thinking they are real services.

You must protect user privacy at all times, even when using prototypes. Prototypes made with the kit look like NHS.UK, but do not have the same security provisions. Always make sure you are handling user data appropriately.

Installation instructions

• Install guide (non technical)
• Developer friendly install guide (technical)

Running the kit

Start the kit with npm run watch.

Contribute

If you want to contribute to the NHS.UK prototype kit, by reporting bugs, fixing bugs, suggesting new features or writing documentation, then read our contributing guidelines.

Development environment

Before running Gitpod, you must install the Gitpod.io application on your GitHub account.

Gitpod also requires access to public repositories. Enable this via Gitpod integrations. (Click on the 3 dots to edit permissions for your GitHub account. Gitpod may pre-select permissions. You need read/write access to code in the repos.)

Using your own GitHub credentials you can create, change, commit and push to branches on our Gitpod container via the "ready to code" button below.

Read an introduction to Gitpod (on Gitpod's website).

Release lifecycle

The below is only for maintainers of the prototype kit source code - these instructions aren't relevant if you're building your own prototype using the kit.

Testing

Run unit tests locally with npm run test.

Environments

Preview environment

Code pushed to the main branch will deploy on the Preview environment.

Live

The live NHS.UK prototype kit Live environment, accessible to the public.

Note: Live is behind a server side cache which results in changes not appearing immediately.

Versioning and deploying to live

• Merge required changes via PR into main branch
  • Ensure the version number in package.json and CHANGELOG.md match, with a summary of the changes included in the changelog
• Verify the changes in the Preview environment
• Pull down merged main branch to your local repository
• Create a tag with the version number from the latest commit on main
  • If the latest version you're looking to push is version "1.2.3", you can do this on the command line with
    • git tag v1.2.3
    • git push --tags
• Github actions will spring to life and create a release which will be visible on the releases tab of the repository.
• Finally, edit the description of the release to match the content entered into the changelog.
• To deploy the changes to Live, the promotion to Live from the Preview environment must have the appropriate approval in Azure.

Code Analysis

Code analysis results can be found in SonarQube.

Support

The NHS.UK prototype kit is maintained by NHS England. Email us, open a Github issue or get in touch on the NHS digital service manual Slack workspace.

nhsuk-prototype-kit's Issues

Add linting to the prototype kit

In order to keep the code quality on the prototype kit to a decent standard, it'd be useful to implement some linting tools.

These could be run locally and on a pull request workflow for Github.

We can possibly recycle the same tools and similar configs used in our other repos like nhsuk-frontend.

Force https when running in production

Most websites are now https and chrome gives you a warning if a website you are visiting isn't using http.

The prototype kit doesn't force this. So if you deploy to heroku you can have both a http and https version of the website. https is more secure.

In the app team we also noticed that when running the prototype kit as a PWA (to simulate the app) that if we used the http version a massive warning bar came up when a user used a field. This happened on every text input.

We should force (or allow the kit to force) https. More secure. Saves issues for people navigating and sharing the http version for testing and documentation.

Template for a NHS website start page

Description

When creating prototypes for coronavirus services I often find myself needing the code for an NHS website start page for the prototype. This includes the page content but also the Header and Footer (which may differ to the services usual Header and Footer eg. Transactional)

For example the Get a shielding note start page on the NHS website

I often just copy it from a previous prototype, however this might be useful to have in the prototype kit for easy access and if anything changes to the Start page template it can be updated centrally for everyones benefit.

Licensing

Bug Report

What is the issue?

Should this repo be licensed under the OGL? And have Crown Copywrite?

That is the recommended license for all public sector development I believe?

I can see that you've chosen an MIT license to match that of jQuery but certainly this wouldn't be acceptable to our organisations in most cases.

Prototype kit: tracking data analytics

What

At the minute we have no idea how many people are using (or how) the prototype kit (other than some manual research looking for them on public GitHub repos). We should investigate the use of (opt-in) analytics to give us an idea of usage so that we can make future improvements to the kit.

This is something that is done in the GOV.UK prototype kit using Google analytics: https://govuk-prototype-kit.herokuapp.com/docs/usage-data

• your anonymous ID number
• the Prototype Kit version number
• your operating system (for example 'Windows 10')
• your Node.js version

and is quite popular in JavaScript frameworks such as Next.js: https://nextjs.org/telemetry

• Command invoked (next build, next dev, or next export)
• Version of Next.js
• General machine information (e.g. number of CPUs, macOS/Windows/Linux, whether or not the command was run within CI)
• What Next.js plugins are present in your project
• Duration of next build and size of application (total number of pages)

Why

Tasks

• Look into how GOV.uk track their data

Azure pipelines releases not triggering automatically

Azure releases to live on tag doesn't seem to be triggering automatically, had to manually deploy the previous release. Deploying to preview on master seems to be working fine.

Test issue KMG

Bug Report

What is the issue?

What steps are required to reproduce the issue?

What was the environment where this issue occurred?

• Device:
• Operating System:
• Browser:

Is there anything else you think would be useful in recreating the issue?

Upgrade prototype-kit frontend version

Upgrade the prototype-kit to version 6.0.1

Fix breaking changes that come of this and then check that the components are functioning correctly

Set-up GitPods

• Add GitPods yml file - docs found here
• Add GitPods button to contribution section of README
• Add GitPods application to NHSUK Org in Github - scoped to nhsuk-prototype-kit
• Create Pre-build for prototype Gitpods

Broken links on mini hub page template

See http://nhsuk-prototype-kit.azurewebsites.net/templates/mini-hub

Add .DS_Store to .gitignore

Been making a prototype for NHS identity

Added their logo and image folder. On Mac so it created the .DS_Store files.

Got picked up by git. Probably worth adding

.DS_Store

To the gitignore file to stop this

Update the prototype kit to use NHSUK frontend v4.0.0

What

Once NHS.UK frontend 4.0.0 has been released, update the prototype kit to use it.

Why

So that the prototype kit reflects the latest release of NHS.UK frontend.

npm install fails on clean environment

Bug Report

What is the issue?

On a clean system, did the following:

git clone [email protected]:nhsuk/nhsuk-prototype-kit.git
npm install

Error:

> [email protected] postinstall C:\Projects\nhsuk-prototype-kit
> npm run build


> [email protected] build C:\Projects\nhsuk-prototype-kit
> gulp build

'gulp' is not recognized as an internal or external command,
operable program or batch file.
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] build: `gulp build`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the [email protected] build script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Users\Rob\AppData\Roaming\npm-cache\_logs\2022-03-31T09_57_54_044Z-debug.log
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] postinstall: `npm run build`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the [email protected] postinstall script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Users\Rob\AppData\Roaming\npm-cache\_logs\2022-03-31T09_57_54_085Z-debug.log

It appears that there's a requirement for gulp but that's not included anywhere in the instructions.

Followed both developer and non-developer instructions.

What was the environment where this issue occurred?

Doesn't matter as I tried it on Win 10, WSL Ubuntu and an npm based docker container.

Is there anything else you think would be useful in recreating the issue?

Ensure you have clean environment without Gulp installed.

As an aside...
Gulp is a technology that's been superseded by Webpack.

How to guide: Adding custom images and JavaScript - Enhancement

Images

Users can add custom image assets by putting image files in the app/assets/images folder, then referencing them in HTML with /images/filename.jpg. However, the images folder does not exist in assets and there is no guidance or examples for doing this.

JavaScript - Advanced guide?

Users can add custom JavaScript or ES6 modules by writing JavaScript (or using third party libraries) in the app/assets/javascript folder then referencing them in HTML in app/views/includes/scripts.html. There currently isn't any guidance or examples for doing this.

WIll users be wanting to add custom JavaScript?

Start using GitHub releases feature when doing releases

Description

Similar to how we release our other GitHub services, start using the GitHub releases functionality when we do a release so that we can keep track releases more easily. This is required for our reporting metrics on deployment frequency.

We may also be able to track prototype kit downloads through the .zip file within the release.

Change mini-hub example to two-thirds column

The mini-hub example currently uses a column of three quarters.

On the NHS website, and the rest of the kit, the layout is actually two-thirds. I'd expect it to match the identically.

Update these template files to copy the NHS website as default.

Relates to all the mini-hub templates:
https://github.com/nhsuk/nhsuk-prototype-kit/tree/master/docs/views/templates/mini-hub

Use the summary list component from the NHS.UK frontend library

Version 2.0.0 of the NHS.UK frontend library has the new summary list component, which is used in the prototype kit on the check your answers page. This is using custom styling specific to the prototype kit, so this could be removed and the official component used.

How to override the HTML background colour

Issue Report

What is the issue?

Adding a class to override the HTML background colour did not work.

What was the environment where this issue occurred?

• Device: Macbook Pro 15-inch 2017
• Operating System: macOS Big Sur Version 11.4
• Browser: Google Chrome

Is there anything else you think would be useful in recreating the issue?

I needed to remove the grey HTML background seen here on the NHS App prototype.

I tried the following:

.body {
background-colour: transparent;
}

.html {
background-colour: transparent;
}

.html {
background-colour: #F0F4F5;
}

I also tried adding important on each of these classes and it didn't work.

I then realised I needed to change it in views/template.html.

I added a variable:
<html lang="en" style="{{ html_style }}">

And set this variable on my layout file for the pages I wanted the background colour to change on:

{% set html_style = 'background-color: #f0f4f5;' %}

Review recent user research done on the prototype kit

Description

Before coronavirus we conducted user research on the NHS.UK prototype kit and came up with a number of findings, this got put on hold due to the pandemic. We should revisit and review these findings and come up with improvements to the prototype kit off the back of them.

Passing data example - check your answers checkbox display issue

Bug Report

What is the issue?

When you select only one checkbox on the passing data example, each letter of the answer on the check your answers page gets put into a <li>.

It's fine when two or more answers are selected.

https://nhsuk-prototype-kit.azurewebsites.net/examples/passing-data/passing-data-question-conditions

Add Gitpod install guide to the prototype-kit web app

Adding an installation guide to the prototype kit for Gitpods.

linked #197

Working branch

Preposed addition:
Install page - addition of Gitpod install guide

Option 1 numbered steps

Option 2 paragraphing

Also included on the page is installation information for use within the organisation, again numbered

Or paragraphing

Content is still to be to confirmed or improved.

error on my laptop

Prototype kit website pages link to download the prototype kit

Description

Now we are using GitHub releases to handle releasing the prototype kit (#180), update the links to download the prototype kit files to point at the latest release opposed to the master branch zip file. We will need to some logic to automatically populate the latest version in the URL from the package.json file.

eg. https://github.com/nhsuk/nhsuk-prototype-kit/archive/refs/tags/v4.6.1.zip ... /refs/tags/v${version}.zip

We can also then use the GitHub API to track downloads for usage.

Add information to REAME for Gitpod

We need to add some information in the README file around Gitpod so that contributors and future contributors understand how the tool works

• Speak with Content designer around what to add @sarawilcox
• add content to README

Unchecked items not removed from data

Bug Report

What is the issue?

Cannot remove unchecked items from "Check your answers" page when unchecking all previously selected items.
It should allow you to remove them all.

What steps are required to reproduce the issue?

• Go to http://nhsuk-prototype-kit.azurewebsites.net/examples/passing-data/passing-data-check-answers
• Add one or more checked items and save.
• Try changing answers by removing all of the checked items and hitting Continue
• Observe that the answers remain the same.
• You can remove them one at a time, but whenever you try to remove all at once, or the last item, you can't.

What was the environment where this issue occurred?

• Device: Lenovo ThinkPad
• Operating System: Linux
• Browser: Google Chrome

Is there anything else you think would be useful in recreating the issue?

Prototype kit usage analytics

Description

At the minute we have no idea how many people are using (or how) the prototype kit (other than some manual research looking for them on public GitHub repos). We should investigate the use of (opt-in) analytics to give us an idea of usage so that we can make future improvements to the kit.

This is something that is done in the GOV.UK prototype kit using Google analytics: https://govuk-prototype-kit.herokuapp.com/docs/usage-data

• your anonymous ID number
• the Prototype Kit version number
• your operating system (for example 'Windows 10')
• your Node.js version

and is quite popular in JavaScript frameworks such as Next.js: https://nextjs.org/telemetry

• Command invoked (next build, next dev, or next export)
• Version of Next.js
• General machine information (e.g. number of CPUs, macOS/Windows/Linux, whether or not the command was run within CI)
• What Next.js plugins are present in your project
• Duration of next build and size of application (total number of pages)

Enforce stricter password protection within code

Description

An increasing number of prototypes are removing the authentication code, resulting in unauthenticated prototypes being published to the web. There is a risk that members of the public will find these prototypes and think they are real services. This is particularly dangerous at a time when are seeing an increased amount of phishing and scam websites.

A rule of publishing prototypes online is that they must be protected by a username and password:

Security

If you publish your prototypes online, they must be protected by a username and password. This is to prevent members of the public finding prototypes and thinking they are real services.

You must protect user privacy at all times, even when using prototypes. Prototypes made with the kit look like NHS.UK, but do not have the same security provisions. Always make sure you are handling user data appropriately.

We need to look at how we make it more difficult for people to just simply remove the authentication middleware code and how could enforce these policies outside of code.

The username and password is currently set using environment variables (PROTOTYPE_USERNAME and PROTOTYPE_PASSWORD)

Some things to note ...

• Authentication middleware files can easily be deleted https://github.com/nhsuk/nhsuk-prototype-kit/blob/master/middleware/authentication.js
• Not all hosting providers set default NODE_ENV to production (Heroku does, Azure doesnt) so the check env === 'production' || env === 'staging' may accidentally be being bypassed

How to guides: Branching example - inconsistent header & footer

When using the Branching example, the Header and Footer aren't consistent throughout the journey.

You start with a transactional header with service name and a footer with 2 links in it.
https://nhsuk-prototype-kit.azurewebsites.net/examples/branching

But then get a page with a normal header with no service name and a footer with 0 links in it.
https://nhsuk-prototype-kit.azurewebsites.net/examples/branching/answer-yes
https://nhsuk-prototype-kit.azurewebsites.net/examples/branching/answer-no

Setup Codepaces or Gitpod with the prototype kit

Description

Setup Codespaces or Gitpod to allow for the prototype kit to be ran in IDE (Integrated Development Environment) in the browser. This will help reduce the barrier to entry and resolve any permission issues when installing Node.js on devices (which we often see on NHSD corporate devices).

Codespaces would be the preference if we can get access to the early BETA before its official launch. Setup the GitHub integration with the prototype kit and add any documentation for running the project within Codespaces.

docs.css overrides my custom CSS

Everything inside the app folder inherits from the layout file inside the docs folder.

However, this means that if you try and write some override SCSS in the main.scss file it will be overwritten by the docs folder.

Discovered this implementing the NDOP service and exploring an IA issue

// docs/views/layouts/layout.html
{% block headCSS %}
  <link href="/css/main.css" rel="stylesheet">
  <link href="/css/prism.css" rel="stylesheet">
  <link href="/css/docs.css" rel="stylesheet">
{% endblock %}

The doc.scss file imports the frontend library again meaning any exploration of a new component or adjustment is overridden.

options...

1. Change the order of this declaration.
2. Remove the import for the library inside the docs.scss file (knock-on issues here)
3. Returning a layout file to the app folder
4. Adding the headCSS block into the layout-nhsuk.html and layout-transactional.html layout file that cuts out the docs css etc.

I'm sure there are plenty of other ways to do it too.

I'd take option 4 though I appreciate it is a bit of a violation of the DRY principle

Allow access for Gitpod

Gitpod requires Org access to enable the ability to push up via a pod

• Raise issue with Infra
• Infra grant access to NHSUK org
• Test Gitpod has the ability to push up to Github

Kit Guidance - Windows users should run CLI/Shell as Administrator

Hi Team,

Brilliant work on the prototype kit :)

Small change though to the guidance doc. It should advise Windows users to run command as an administrator otherwise the user will be restricted from running the node package manager

Tidy up the layout.html and template.html files

There is a template.html file which contains all the HTML structure and metadata and also a layout.html which is imports all the Nunjucks macros. However, there is some overlap between the 2, such as the footer and page title being set in both.

We found that setting the footer in the layout.html file wouldn't update as it was overridden by the template.html file.

They could potentially be combined into 1 single file and make it clearer how to update common elements that change such as the Header, Page titles or Footer. As they could be set in multiple places such as page, template or layout and could get a bit messy and confusing.

The clear data page doesn't render in the passing data how to guide

Bug Report

What is the issue?

When going through the passing data example, if you click on the "Clear data" link in the footer, you get a page error.

What steps are required to reproduce the issue?

1. Go to: https://nhsuk-prototype-kit.azurewebsites.net/examples/passing-data/passing-data-question-name
2. Click on the "Clear data" link in the footer
3. Observe the error which includes: "Unable to call 'panel', which is undefined or falsey"

What was the environment where this issue occurred?

• Device: all
• Operating System: all
• Browser: all

Is there anything else you think would be useful in recreating the issue?

The promo component is no longer in use in the NHSUK frontend. Need to replace it with the card component.

Issue with looping through checkboxes answer as an array

Bug Report

What is the issue?

When looping through an array of answers to a checkbox question in the check my answer demo - the for loop will run through the selection as an array, however, if a single checkbox is selected, the for loop will run through it as a string, printing out each letter.

What steps are required to reproduce the issue?

Go to this step on the passing data flow select a single checkbox and click continue, you will see that each letter has been added into a list. See screenshot below.

What was the environment where this issue occurred?

• Device: Macbook
• Operating System: Big Sur 11.3.1
• Browser: Chrome

Is there anything else you think would be useful in recreating the issue?

A prototype version of the NHS website

What

We need to build a prototype version of the NHS website

Why

There is a growing request among designers to have a prototype version of the NHS website to help simulate journeys from and to the website from other services such as login and the app etc.

Who

@mcheung-nhs had volunteered to help build this for designers

Task

• Gather all web journeys
• Build journeys based on request

Can't run two versions of a prototype kit at once

Not a hot burning issue but something that caught me out.

I have a few prototypes for different parts of the programme and across NHS Digital.

Occasionally I find myself running two prototypes that either connect together or I need to evaluate against each other.

Doing this I noticed that you can't run two versions of the prototype kit at once.

It appears initially that you can (one running on port :3000 and :3001 but actually you are only getting port :2000 being proxied.

Prototype one

Prototype two

The proxy URLs are the different, but the proxied port is not. You see two prototypes running but only one is. This is the same in the browser. 2000, 3000 and 3001 are all the same prototype.

I could change this in one prototype manually to not run on 2000 in app/config.js, but I was wondering how easy it would be to run a check on 2000 and if used, run on 2001?

Findability of the prototype kit how to guides

What

Review the findability of the prototype kit 'how to' guides.

Why

People have difficulty finding the guides, resulting in time being wasted.

Add Github pages

Similarly to nhsuk-frontend, using Github pages removes the dependency on Azure DevOps, The free solution will enable us to build a site for the prototype kit identical to the current Azure DevOps application but without the need for external pipelines. This is better fitting to an open-source project.

Github pages

• Create the Github pages branch
• Add pages folder within the repository under app
• Build the current Azure DevOps app as Github pages
• Update the current prototype-kit site URL within the project Repository

Fix branching examples on Azure

They are currently broken. After clicking on the button https://nhsuk-prototype-kit.azurewebsites.net/examples/branching both options goes to a 404

The code in the routes.js file seems to correct on master on github.

So maybe an update needs to be pushed to azure?

Move main.js to below jQuery

Depending on what you're doing with jQuery long term of course...

But helped out Paul Hill today with an issue where he thought the main.js file would work with jQuery.

But the main.js file is included before and therefore he misunderstood and couldn't get his JavaScript to work.

I helped him make a change to the jQuery file in the template so it now works.

I'd suggest that whilst we have jQuery we put main.js to underneath it

Hard copy of jQuery?

Bug Report

What is the issue?

It looks like the kit contains a fixed copy of jQuery v3.3.1 minimised - surely this is a bad idea?

The current version is 3.5.1 and, when developing, I would want the non-minimised version as well for debugging.

It would surely be better to include jQuery as a dependency in package.json and configure webpack accordingly?

What steps are required to reproduce the issue?

Download the current zip from the website.

What was the environment where this issue occurred?

Any.

Is there anything else you think would be useful in recreating the issue?

N/A

how to swich on my localhost

What to do every time that I switch on my laptop to connect my local host and the heroku app thing

Promote, grow and maintain the collection of prototype examples

Description

We have a GitHub repo utilising the README file to list a range of different prototypes created using the NHS.UK prototype kit. This is particularly useful for being able to see what others have done and reuse common code (saving time and money). It also allows people to see what the prototype kit is capable of.

We should investigate how we can actively promote, grow and maintain this list.

Kit doesn't work with v12 of node.js

Bug Report

What is the issue?

I was helping someone setup a new machine and get setup with the prototype kit and they were getting errors, turns our it was the node.js version, downgraded them to the same version I had (v10.x) and all worked fine.

What steps are required to reproduce the issue?

Install latest version of node.js and try to install node packages and run the toolkit.

What was the environment where this issue occurred?

MacBook Air, Catalina, Node.js 12.x

Is there anything else you think would be useful?

Update guidance to make it clear which version currently works. At the moment it says 8+.

Test issue - Prototype kit

What

What it is.

Why

Why it needs doing.

Further detail

Further information to support the work.

Relates to

• Issue 638

Depends on

• Issue 269

Who needs to know about this

Users? / Stakeholders? / Team members?

Done when

Tasks we need to do:

• this
• this
• and this

Next steps

What we need to do next.

Reorder asset preconnects and remove unneeded dns-prefetch

See the issue raised on the NHSX website repository: nhsx/nhsx-website#9

Month (3) to word (March) Nunjucks filter

Description

For the formatting of dates on the check your answers page in a prototype, I came across this this useful Nunjucks filter to change a number, like 1 "12" or 04, to a month in words: https://github.com/nhsuk/permission-to-contact-prototype/blob/master/app/filters.js#L12

I think this would be useful adding to main prototype kit?

About page in the prototype kit docs links to #standards channel on NHS.UK Slack workspace

Bug Report

What is the issue?

The about page in the NHS.UK prototype kit documentation links to the #standards channel in the NHS.UK Slack workspace which has limited access and hasn't been used for a long time.

I would suggest linking to the #prototype-kit channel on the NHS service manual Slack workspace.

What steps are required to reproduce the issue?

1. Visit the about page in the NHS.UK prototype kit documentation
2. Click either of the "get in touch on the NHS.UK #standards Slack channel" links
3. Taken (if you have access) to the #standards channel in the NHS.UK Slack workspace

What was the environment where this issue occurred?

• Device: MacBook Pro (15-inch, 2019)
• Operating System: macOS Big Sur Version: 11.4 (20F71)
• Browser: Google Chrome Version: 91.0.4472.114 (Official Build) (x86_64)

How to guide: Passing data page to page example - Incorrect page links

On the How to pass data page to page example (https://nhsuk-prototype-kit.azurewebsites.net/examples/passing-data/register-gp-step1) both the Yes and No radio button options lead to the same page of https://nhsuk-prototype-kit.azurewebsites.net/examples/passing-data/register-gp-step2

I would expect them to lead to different pages depending on your answer - it also isn't obvious where it is passing data or what the example of passing data is until 5 steps into the process. Maybe cut down the passing data functionality to just 1 form page?