Installing the design system Using the CSS, JS and assets
How to import Sass files from the npm package
You can get all the Sass rules by adding the following to your main Sass file:
How to import specific Sass rules
You may not need any or many of the CSS for components. 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.
To import the styles for a single component, for example, the button component, you need to add this after the base Sass files:
Some components use 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
- add the JS file to your HTML
- import JS using a bundler
Add the JS file to your HTML
You can use the
main.js from the design system npm package. You can copy the file from
node_modules/@ons/design-system/scripts into a
/scripts folder in your project. You could also set up routing on your service to point to the
/scripts located in
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
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.
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.
Each release of the design system is tagged with a version, for example,
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 (the
[VERSION] should be replaced with the required release version, for example
). Do not include the
v, just include the number:
Note that 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:
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.
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. You could also set up routing on your service to point to the
/fonts folder that is served from
All of 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 or following the same process as for including fonts and using a folder named
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">
Alternatively, you can copy the favicons from
node_modules/@ons/design-system/favicons (if using the npm package) and referencing 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)