CSS and Sass

A precompiled CSS file containing the styles used by the Design System is included in the Design System’s npm package at /dist/styles/main.css.

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

The Design System’s components are also provided as SCSS files. If you are modifying or extending the Design System to meet your needs, our recommendation is to work with the SCSS files. If you work with the SCSS, you will be able to use all of the variables, functions and mixins that the Design System itself uses.

Creating your own main SCSS file

If you choose to build your own SCSS file using the Design System, a typical starting point for your main SCSS file might look something like this.

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

You’ll always need to include the base styles in your file. They contain the typography and colour rules used by the components, and a number of 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 was made to be extensible. You can create your own new components or override and add to the components already provided in the Design System.

If you are creating your own components or overriding existing components to meet your service's needs, you might find it useful to use some of the same variables, functions and 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. This has been achieved by creating a new modifier class for the Design System’s notification banner in a new SCSS file.

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

This is then applied to a notification banner by using a class attribute that includes both the default ‘ds_notification’ class and the new ‘ds_notification—black' class.

The SCSS file for this notification banner override is included in the gov.scot main.scss file, similar to 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";