Cookies on ons.gov.uk

Cookies are small files stored on your device when you visit a website. We use some essential cookies to make this website work.

We would like to set additional cookies to remember your settings and understand how you use the site. This helps us to improve our services.

View cookies

You have accepted all additional cookies. You have rejected all additional cookies. You can change your cookie preferences at any time.

Skip to main content

Installing the design system Using the CSS, JS and assets

Overview

CSS

How to import Sass files from the npm package

If your project has its own bundling tool, you can import Sass rules from your @ons/design-system npm package.

How to import Sass rules

First, import normalize.css. using:

npm i normalize.css

You can then get all of the Sass rules by adding the following to your main Sass file:

@import 'node_modules/@ons/design-system/scss/main';

How to import specific Sass rules

For performance reasons, you may only want specific parts of the design system Sass files.

As a minimum, you should import the following Sass files:

@import 'node_modules/@ons/design-system/scss/vars/index';
@import 'node_modules/@ons/design-system/scss/helpers/index';
@import 'node_modules/@ons/design-system/scss/utilities/index';
@import 'node_modules/@ons/design-system/scss/base/index';
@import 'node_modules/@ons/design-system/scss/objects/index';

Importing these files ensures components and patterns have access to any required global classes and utilities.

Import Sass rules for a single component

To import the styles for a single component, for example, the button component, you need to add this after the base Sass files:

@import 'node_modules/@ons/design-system/components/button/button';

Some components are built using other components. For example, the accordion component uses the details component.

You need to import the Sass files for each component used.

How to use compiled CSS from the npm package

You can either import or copy the main.css file to include the compiled style sheet of all components and styles. This file can be found under node_modules/@ons/design-system/css/main.css.

Creating themes

To display the colour palette, the ONS design system uses CSS Custom Properties (opens in a new tab) .

This allows services to create a custom theme, without overriding properties in their existing stylesheets.

Open Github to find our custom properties for colours [LINK].

This example shows the custom properties that are overridden to create the Census theme.

:root {
  --ons-color-black: #222;
  --ons-color-white: #fff;
  --ons-color-branded: #902082;
  --ons-color-branded-tint: rgba(144, 32, 130, 0.1); // 10% of brand colour
  --ons-color-branded-secondary: #df0667;
  --ons-color-branded-tertiary: #3c388e;
  --ons-color-branded-supporting: #00a3a6;
  --ons-color-branded-supporting-tint: rgba(#00a3a6, 0.2);

  // Assignment
  --ons-color-tag-bg: var(--ons-color-branded-supporting-tint);
  --ons-color-text-link-hover: var(--ons-color-black);
}

Accessibility

Before creating your theme, check that it meets the accessibility requirements for colour contrast.

You can check if a colour combination meets WCAG 2.1 AA requirements by using WebAim’s colour contrast checker (opens in a new tab) .

Referencing your CSS file

To create a theme, you need a CSS file with a :root CSS pseudo-class [LINK] which overrides colours. This file needs to be referenced after our main.css file in the <head> of your application.

You can add your stylesheet reference inside the head block if you are using the base page template.

JavaScript

To import the JavaScript (JS) for components, you can either:

  • add the JS file to your HTML
  • import JS using a bundler

Add the JS file to your HTML

To add a JS file, you can:

  • use the main.js from the design system npm package.
  • copy the file from node_modules/@ons/design-system/scripts into a/scripts folder in your project
  • set up routing on your service to point to the /scripts located in node_modules/@ons/design-system

Then import the JS file before the closing body tag of your HTML page or page template.

<body>
...
  <script src='<YOUR-APP>/<YOUR-JS-FILE>.js'></script>
</body>

You can also reference the published JS file from the content delivery network (CDN).

Import JS using a bundler

If your service uses a bundler like Webpack (opens in a new tab)  you can select and initialise all component JS using import or require().

Import the node_modules/design-system/js/main.js to import the JS for all components.

Import JS for a specific component

You can import the JS for a specific component. For example, node_modules/design-system/components/button/button.dom.js imports the JS for the button component.

Each component that uses JS will have a <COMPONENT>.dom.js file available to import. This file will handle the initialising of a component.

CDN

All the global styles and individual component code is compiled and made available via a content delivery network (CDN).

Each release deployed to the CDN is always available. This allows services to plan upgrades to new versions. The pipeline to push files to this CDN is managed by the eQ team.

Releases

Each release of the design system is tagged with a version. For example: release | 62.0.1 which forms part of the URL of the compiled files for a specific release.

The following files are deployed to the CDN which can be referenced in a service or project:

  • main.css - responsive CSS file of all components
  • main.js - bundled JS modules

If you are using the design system base page template (recommended) you will not need to reference any assets from the CDN. The release version is automatically applied in the base template to any references.

If you do need to reference the files in your service, use the following URL structures:

  • https://cdn.ons.gov.uk/sdc/design-system/[VERSION]/css/main.css
  • https://cdn.ons.gov.uk/sdc/design-system/[VERSION]/scripts/main.js

The [VERSION] should be replaced with the required release version. For example: release | 62.0.1

Some local development environments require you to override the global ONS_assets_base_URL variable to use the chunked JS files.

To do this, add the following script before the reference to the main.js file:

<script>var ONS_assets_base_URL='https://cdn.ons.gov.uk/sdc/design-system/[VERSION]/';</script>

Assets

All assets are available through the CDN. If you choose to use the main CSS file via the CDN, all required fonts and images will be served from there.

Fonts

If you import all or parts of the CSS from the npm package you will need to import fonts into your service.

You can copy the font files from node_modules/@ons/design-system/fonts into a /fonts folder in your project. Alternatively, set up routing on your service to point to the /fonts folder that is served from node_modules/@ons/design-system/fonts.

Images

The main images used across the design system have been implemented as inline SVGs, so you may not need any of the images within the npm package or CDN.

We do supply placeholder images for some components. If you require these, you can make them available by:

  • referencing directly from the CDN
  • following the same process as for including fonts and using a folder named img

Favicons

There are favicons (or shortcut icons) for Safari, Chrome and Edge/Internet Explorer for desktop and mobile.

Place the following references into the head of all pages within your service to make use of the available favicons. The [VERSION] should be replaced with the required release version.

<meta name="msapplication-config" content="https://cdn.ons.gov.uk/sdc/design-system/[VERSION]/favicons/browserconfig.json">
<link rel="icon" type="image/x-icon" href="/favicons/favicon.ico">
<link rel="icon" type="image/png" href="https://cdn.ons.gov.uk/sdc/design-system/[VERSION]/favicons/favicon-32x32.png" sizes="32x32">
<link rel="icon" type="image/png" href="https://cdn.ons.gov.uk/sdc/design-system/[VERSION]/favicons/favicon-16x16.png" sizes="16x16">
<link rel="mask-icon" color="#5bbad5" href="https://cdn.ons.gov.uk/sdc/design-system/[VERSION]/favicons/safari-pinned-tab.svg">
<link rel="apple-touch-icon" type="image/png" href="https://cdn.ons.gov.uk/sdc/design-system/[VERSION]/favicons/apple-touch-icon.png" sizes="180x180">
<link rel="manifest" href="https://cdn.ons.gov.uk/sdc/design-system/[VERSION]/favicons/manifest.json">

If using the npm package, you can also copy the favicons from node_modules/@ons/design-system/favicons and reference them from your project folder.

Help improve this page

Let us know how we could improve this page, or share your user research findings. Discuss this page on GitHub (opens in a new tab)