All design patterns and components in the GOV.UK Design System should follow the below content pattern. If you’re working on a pattern or component page for the Design System, you should use this as a template.
(Don’t edit, copy and paste the content into a new doc)
[Overview]
If the component/pattern is experimental, include this line:
This [component/pattern] is currently experimental because [more research](link to research section below) is needed to validate it.
Then, use this overview section to:
- explain, in one line, how the component/pattern helps users
- show a live example - if this is not possible because the component/pattern is bigger than one screen (eg Confirm an email address), you can use an appropriate illustration or screenshot and/or link to a prototyped example.
Describe when to use this component/pattern. When is it appropriate to use and what need does it help you meet?
If necessary, include an additional H2 titled ‘When not to use this pattern’. Use this section to highlight any exceptions or known scenarios where the pattern does not work. If you include this section, explain what to use instead (with a relevant link if we’re suggesting an alternative pattern or component).
Use this section to explain how the pattern works.
This should include:
- (if the component/pattern is too complex to have been fully described in the overview) a full description of how the pattern works (for users)
- rules/instructions on how to implement it
- steps to follow
It can also include:
- coded examples
- things to avoid
- why it works
If this section is quite long, break it into smaller sections with H3s.
[Research summary - no H3]
Use this section to summarise the research that supports this component or pattern. If the component or pattern is experimental, summarise the research it’s based on.
Describe:
the research context, for example, whether it was tested in isolation, or as part of a prototype or a live service types of users tested with, for example, users with disabilities, users with low digital literacy
If possible, finish this section with a link to more detailed research notes. It must be documented somewhere that’s open and publicly-accessible, ideally a blog post.
Use this section to describe any known issues with the component or pattern, or any gaps in the research.
Use this section to provide up to 5 examples of services using the component or pattern. If there are more than 5 services using it, you should choose the top 5 most popular, using this list https://www.gov.uk/api/search.json?filter_content_store_document_type=transaction
For very common components, like text inputs, use this content:
This [component/pattern] is commonly used across GOV.UK. You can see examples of it being used in the following services.
List of services in following format:
Service name
For other components and patterns, use this content:
This [component/pattern] has been used in a number of services, including the following.
List of services in following format:
Service name
If applicable, include this section and use it describe outstanding research or work to be done or questions to answer.