DOCSEARCHbyAlgolia
Submit Docs

GOV.UK Design System

repository·main·Indexed 20 days ago

https://github.com/alphagov/govuk-design-system

The website for the GOV.UK Design System, used to showcase and document the design system. It is a static site generated using Metalsmith and hosted on Netlify, consuming the govuk-frontend package via NPM.

Tokens
70.2K
Snippets
102
Records
394
Agent score
70%

What's inside govuk-design-system

  1. Use the Service navigation component

    main

    The Service navigation component helps users identify which service they are using and provides links to navigate between different parts of that service. It works in conjunction with the GOV.UK header component to provide a consistent experience across GOV.UK.

    If you are using the standard GOV.UK page template, the Service navigation is included by default. To customize it, refer to the page template guidance for changing template content.

  2. Use the Task list component

    main

    The Task list component displays all tasks a user needs to complete, allowing them to identify finished tasks and those remaining. It is designed for long, complex services where users might not complete everything in one sitting and need to choose their own order of completion.

    When to use:

    • When users cannot or do not want to complete all tasks in one sitting.
    • When users need to choose the order in which they complete tasks.

    When NOT to use:

    • If the service can be simplified to reduce the number of tasks.
    • If the service must be completed in a specific, fixed order (in this case, use a 'save progress' pattern instead).
    • To show users their answers (use the Summary list component for that).

  3. Understand the GOV.UK Design System deployment model

    main

    The Design System is a static site generated using Metalsmith. It is hosted on Netlify. The deployment process is triggered by Netlify running npm run build and deploying the resulting build directory.

    Note that deployments occur in parallel with GitHub Actions tests, but Netlify will only proceed with the deployment if the build command executes successfully.

  4. View current and upcoming component priorities

    main

    The Design System team prioritizes work based on essential criteria (e.g., accessibility, security, and scale) and community input.

    Working on now

    These components are currently in development. You can join discussions to help build them:

    • Interruption panel: Part of an Interruption page to show critical information.
    • Feedback link: Allows users to leave consistent page feedback. Discuss Feedback link.
    • Language switcher: Allows users to switch page languages. Discuss Language selector.

    Next priorities

    Input on these themes is particularly welcome via designs, code, or research findings:

  5. Navigate between pages of items using list-type layout

    main

    Use a list-type layout when users need to navigate through pages of similar items, such as search results or case lists.

    Best practices for item lists:

    • Page Titles: Include the page number in the HTML <title> (e.g., 'Search results (page 1 of 4)') so screen reader users know they have navigated to a new page.
    • Responsive Display:
      • Small screens: Show the current page, previous/next pages, and first/last pages.
      • Large screens: Show the current page, at least one page before and after, and first/last pages.
    • Ellipses: Use ellipses (…) to represent skipped page ranges.
    • Filtering/Sorting: If you provide filtering or sorting, ensure the filter applies to the entire dataset (not just the current page) and redirect the user back to the first page of the new results.

  6. Configure Notification banner variants and accessibility

    main

    The Notification banner supports different visual styles and accessibility roles depending on the message type:

    1. Neutral (Blue) Banner

    Used for service-wide problems or information happening elsewhere in the service.

    • Role: role="region"
    • Accessibility: Use aria-labelledby="govuk-notification-banner-title" on the container and id="govuk-notification-banner-title" on the title element.

    2. Success (Green) Banner

    Used to confirm an outcome of a previous action (e.g., "Email sent").

    • Role: role="alert" (to shift focus to the banner on page load).
    • Accessibility Requirements:
      • Do not rely on color alone; use a heading like <h3>Success</h3> to meet WCAG 2.2 success criterion 1.4.1.
      • Use consistent headings for green banners across the service to meet WCAG 2.2 success criterion 3.2.4.
    • Lifecycle: Remove the green banner when the user navigates to a new page.

  7. Handling text within images

    main

    Generally, avoid images containing text. Text inside images is difficult for screen readers, copy-paste, highlighting, resizing, and recolouring.

    Images that happen to have text

    It is acceptable to use an image that contains text if the text is not the focus (e.g., a photo of a library with book covers in the background). In these cases, write alt text that explains the visual meaning and context.

    Essential text in images

    Text is considered 'essential' only if removing it causes the image to lose its intended meaning and context, and the information cannot be provided via written content. Examples include:

    • A portion of a historical document showing handwriting style.
    • A store's sign on a shopfront.
    • Logotypes (text within a logo).
    • A distinctive signature.

    Action for essential text: If using an image with essential text, you must provide alt text to convey the meaning and context.

  8. Conditionally reveal related questions

    main

    You can reveal a related question only when a specific radio option is selected. This is useful for grouping related questions on one page (e.g., revealing a phone number input when 'Contact me by phone' is selected).

    Guidelines

    • Keep it simple: If the revealed question is complex or has multiple parts, show it on a separate page instead.
    • Avoid inline: Do not use conditional reveals with inline radios (e.g., 'yes' and 'no' placed side-by-side).
    • Question only: Only show or hide other questions, not non-question elements.

    Accessibility Note

    There is a known issue where users of assistive technologies may not be immediately notified when a question is revealed (WCAG 2.2 4.1.2). However, testing shows that simple revealed questions do not cause significant difficulty for screen reader users.

  10. Understand changes to the GOV.UK Frontend type scale

    main

    Starting from GOV.UK Frontend version 6.0.0, the typography scale has been updated to improve accessibility. If you are upgrading, be aware of the following specific changes to scale points:

    PointChange
    14Deprecated and removed in version 6.0.0 and later
    16Now 16px across all screen sizes
    19Now 19px across all screen sizes
    24On small screens: font size is 21px (was 18px) and line height is 25px (was 20px)
    27On small screens: font size is 21px (was 18px) and line height is 25px (was 20px)
    36On small screens: font size is 27px (was 24px) and line height is 30px (was 25px)

  11. Handle bookmarked confirmation pages

    main

    Users often bookmark confirmation pages to use them as receipts. To support this behavior:

    1. Allow returns: Whenever possible, allow users to return to the confirmation page via a bookmarked link.
    2. Provide helpful alternatives: If users cannot return to the page, ensure the service responds helpfully when they attempt to use a bookmarked link. Provide links to:
      • Tracking an existing application.
      • Starting a new application.
      • Contact information or guidance for troubleshooting problems with their application.