CSS and Sass

The Design System follows the BEM ('Block, Element, Modifier') method for writing CSS. BEM is a naming convention that helps when writing modular and reusable components.

A CSS file containing all the Design System's styles is in the Design System’s npm package at /dist/css/design-system.css.

The Design System uses modular Sass with modules provided as SCSS files. We recommend that you work with the SCSS files if you are modifying or extending the Design System. If you work with the SCSS, you will be able to use the Design system's Sass variables, functions and mixins.

Creating your own main SCSS file

The simplest starting point for a main SCSS file might look something like this, where all the design system modules are used:

@use '/path/to/design-system/src/design-system';

You may wish to include the base module in your file. This contains styling for typography and HTML elements that you may include within other components.

You can choose which components you want to use. You do not need to use them all if you do not want to. For example:

@use "/path/to/design-system/src/base";
@use "/path/to/design-system/src/components/accordion";
@use "/path/to/design-system/src/components/breadcrumbs";
@use "/path/to/design-system/src/components/page-header";

Customising Design System components

The Design System is extensible. You can:

• create your own new components
• add to Design System components
• override Design System styles

You might find it useful to use the same variables, functions and Sass mixins that the Design System uses. This will help your component to look consistent with the Design System’s components.

Example: extending the notification banner component

Gov.scot has a use case for a black notification banner. The team has created a new modifier class for the Design System’s notification banner in a new SCSS file.

@use "/path/to/design-system/src/base/settings";

.ds_notification--black {
    background-color: settings.$ds_colour__black;
}

A black notification banner uses both the ds_notification and ds_notification—black CSS classes.

<div class="ds_notification  ds_notification--black">
    ...
</div>

The main SCSS file includes the black notification banner like this:

@use "/path/to/design-system/src/base";
@use "/path/to/design-system/src/components";
@use "/path/to/overrides/override.notification-banner";

Example: overriding the notification banner component

An organisation needs to apply their brand colour #E6007A to replace the default notification banner background. This can be achieved by passing the replacement colour to either the notification banner module or the components module which collates them all.

@use "/path/to/design-system/src/base";
@use "/path/to/design-system/src/components" with (
    $notification-banner__background-colour: #E6007A
)

This example refers to the hex colour value directly for simplicity, but to make it easier to maintain this would be replaced with Sass variable references.