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 compiled CSS file containing all the Design System's styles is in the Design System’s npm package at /dist/styles/main.css.

The Design System’s components are also 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

A starting point for a main SCSS file using the Design System might look something like this:

@import "/path/to/base/all-base";
@import "/path/to/forms/all-forms";
@import "/path/to/components/all-components";

You always need to include the base styles in your file. They contain the typography and colour rules used by the components. The base styles also provide helpful mixins and functions.

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

@import "/path/to/base/all-base";
@import "/path/to/forms/all-forms";
@import "/path/to/components/accordion/accordion";
@import "/path/to/components/breadcrumbs/breadcrumbs";
@import "/path/to/components/page-header/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.

.ds_notification--black {
    background-color: $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:

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