UI Tool Guidance

Guidance for using the GOV.UK Design System UI tools and updating the site.

This guidance is for administrators and developers working with the GOV.UK Design System components and patterns.

Getting Started

The GOV.UK Design System provides a comprehensive set of components and patterns for building government services.

Key Principles

  • Start with user needs
  • Make services accessible
  • Design for consistency
  • Use plain English
  • Test with users

Using Components

Components are reusable parts of the user interface that have been designed and tested to work across different services.

Adding a new component
  1. Check the GOV.UK Design System components library
  2. Copy the HTML and CSS from the component page
  3. Add the component to your template
  4. Test the component with users
Customizing components

You can customize components by:

  • Using variant classes (e.g., govuk-button--secondary)
  • Adding custom CSS classes
  • Overriding default styles with your own CSS
Warning Always test customizations for accessibility and usability

Updating the Site

Follow these steps to update the site safely:

  1. Make changes in a development environment
  2. Test changes thoroughly
  3. Check accessibility with automated tools
  4. Test with users if possible
  5. Deploy to production

File Structure

The site uses the following structure: 

/gov_website/
├── server.js              # Main server file
├── package.json           # Dependencies
├── views/                 # Templates
│   ├── layouts/           # Base templates
│   ├── admin/             # Admin pages
│   └── *.html             # Page templates
├── public/                # Static assets
│   ├── stylesheets/       # CSS files
│   ├── javascripts/       # JS files
│   └── images/            # Images
└── node_modules/          # Dependencies

Common Tasks

Add a new page
Create a new HTML template in the views folder and add a route in server.js
Update styles
Edit CSS files in public/stylesheets or override GOV.UK Frontend styles
Add JavaScript
Add JS files to public/javascripts and include them in your templates
Update forms
Modify the HTML in the template and update the POST route handler

Testing and Accessibility

All updates should be tested for:

  • Accessibility (WCAG 2.1 AA compliance)
  • Cross-browser compatibility
  • Mobile responsiveness
  • Form validation
  • Error handling

Testing Tools

Back to dashboard

Related resources