Installing the Design System Using the CSS, JS and assets

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 all Sass rules

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

<pre class="ons-patternlib-example__pre  language-markup" tabindex="0"><code class="ons-patternlib-example__code ons-  language-markup">@import 'node_modules/@ons/design-system/scss/main';</code></pre>

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:

<pre class="ons-patternlib-example__pre  language-markup" tabindex="0"><code class="ons-patternlib-example__code ons-  language-markup">@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:

<pre class="ons-patternlib-example__pre  language-markup" tabindex="0"><code class="ons-patternlib-example__code ons-  language-markup">@import 'node_modules/@ons/design-system/components/button/button';</code></pre>

Some components use other components, for example, the accordion component uses the collapsible component. You need to import the Sass files for each component used.

How to use compiled CSS from the npm package>

#p>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.

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

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 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 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>

#p>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 CDN. Each release deployed to the CDN is always available. This allows services to plan upgrades to new versions.

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:

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

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:

<pre class="ons-patternlib-example__pre  language-markup" tabindex="0"><code class="ons-patternlib-example__code ons-  language-markup"><span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>script</span><span class="token punctuation">&gt;</span></span><span class="token script"><span class="token language-javascript"><span class="token keyword">var</span> ONS_assets_base_URL<span class="token operator">=</span><span class="token string">'https://cdn.ons.gov.uk/sdc/design-system/[VERSION]/'</span><span class="token punctuation">;</span></span></span><span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>script</span><span class="token punctuation">&gt;</span></span></code></pre>

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. You could also set up routing on your service to point to the /fonts folder that is served from node_modules/@ons/design-system/fonts.

Images>

#p>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 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.

<pre class="ons-patternlib-example__pre  language-markup" tabindex="0"><code class="ons-patternlib-example__code ons-  language-markup"><span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>meta</span> <span class="token attr-name">name</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>msapplication-config<span class="token punctuation">"</span></span> <span class="token attr-name">content</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>https://cdn.ons.gov.uk/sdc/design-system/[VERSION]/favicons/browserconfig.json<span class="token punctuation">"</span></span><span class="token punctuation">&gt;</span></span>

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.