has been released! Read the upgrade guide

Migrating to v2

The documentation on this page is considered legacy.

We will be updating this content to our new principle-based format in the near future.

This guide will show you how to upgrade your codebase.

CSS Framework

The MOD.UK Design System v2 is a major refactor of the CSS Framework. It introduces a number of under-the-hood tweaks that improve both its performance and accuracy to the Sketch Toolkit.

1SCSS Modules

The MOD.UK Design System v2 has been ported to SASS Modules. This provides the ability to namespace all MOD.UK Design System functions & mixins, scope all variables locally to the file they are declared in, and keep the outputted file size down as @use only includes the imported file once across the entire project.

  • Your application should have a single entry-point for scss. The best way to achieve this is to create an index.scss file in the root of your project and @use every Sass file across your codebase. Then, import the index.scss file (and only this file) once into your main JS entry-point - avoid importing SCSS files into individual js component files. At the top of your index.scss file, @use the Design System CSS framework, as noted below.

  • All instances of @import "@rayalnavy/css-framework" should be replaced with @use "@defencedigital/css-framework" as rn. Whilst the rn namespace is optional, we recommend using this as it will prevent the MOD.UK Design System CSS Framework from clashing with any other SCSS files that may be imported into the project.

  • Alternatively, the CSS Framework can be imported as @use "@defencedigital/css-framework" as *. This will add all functions and mixins to the global scope, meaning you don’t have to namespace your function calls.

  • Every file that requires any mixins or functions from the CSS Framework should individually call @use “@defencedigital/css-framework” as rn. Unlike the @import syntax, @use ensures the imported file is only compiled once, rather than every time it is imported. This prevents duplicate styles and should cut down your outputted CSS’s file size.

  • You must use the sass npm package, rather than node-sass. sass uses Dart under the hood, as apposed to Node. Dart is the primary implementation of the Sass language and currently is the only version to support Modules.

To gain an understanding of the CSS Framework's architecture, use this PDF as a reference.

Functions & Mixins

  • All functions and mixins now use quotes for their arguments - be sure to update these function calls, otherwise your build will fail.

  • If you are using the rn namespace as outlined above, ensure all function & mixin calls are prepended with it (e.g. rn.color(“neutral”, “500”).


The colour palette has been expanded to include an extra colours, under the namespace “supplementary” (sup). v2 also renames several of the colours to improve consistency. Because of this, several functions will need to be updated with their new argument values.

  • primary colour has been renamed action - this better describes the colour’s main usage.

  • alt primary has been renamed to supa.

  • alt success has been renamed to supf.

  • alt warning has been renamed to supb.

  • Additional colours supb, supc, supd, and supe have been added.

All renamed colours should have their function calls updated to the new names.


The MOD.UK Design System supplies pre-determined spacing values to maintain consistency across all our applications and to ensure the designs from the Sketch library correlate with our code output.

In v2, the Spacing scale has been updated as follows:


You will need to update your rn.spacing() functions with the new, updated values.

* Note: As the Spacing Scale is sized in rems, this is the assumed value based on an html font-size of 100% (16px default font-size for Browsers).


  • Makes the base scale position 0.875rem ( 14px at body font-size: 100% ).

  • Balances the scale so that it runs xxs through xxl, rather than xxxs through xl.


You will need to update your mod.font-size() functions & mixins with the new, updated values.


  • Normalises Breakpoint scale so font-size: 100% has a value of 16px at the 1200px - 1400px breakpoint.

  • Removes the xxxl breakpoint and adds in the xs breakpoint. This bumps all scale positions down a breakpoint.


You will need to update your @include breakpoint() mixins with the new, updated values.


  • helper classes have been renamed to utility in v2. This is to better align the MOD.UK Design System with the industry standard of “Utility classes”, which better describe their function, rather than “Helper classes”.

  • Utility class namespace has been updated with .rn_ to be more consistent with the .rn- component namespace.

All instances of the utility classes that use the old .h_ syntax will need to be updated to .rn_. Alternatively, you can set the $utility-ns value back to h_ when you initialise the project. See below for more details.

6Overriding the Toolkit

With the new module system, it is easier than ever to override values provided by the MOD.UK Design System. When @use-ing the CSS Framework, you can assign the provided variables your own values to override any that exist in the Context. The variables that can be overridden are:

1// Fonts
2$font-size: 16px !default;
3$font-family: "lato" !default;
5// Choose Context
6$context: "light" !default;
8// Adjust Context values
9$breakpoints: () !default;
10$colors: () !default;
11$spacing: () !default;
12$shadows: () !default;
13$typography: () !default;
14$zindex: () !default;
16// Utility Namespace
17$utility-ns: "rn_";
19// General Housekeeping
20$content-width: 1280px;
21$animation-timing: 0.3s;

To override any of these variables in the CSS Framework, use the with () syntax:

1@use "@defencedigital/css-framework" as rn with (
2 $utiliy-ns: "h_",
3 $colors: (
4 "neutral": (
5 "500": #FF0000
6 )
7 )

This will merge the values provided inside with () with the default context variables.

React Components

The interfaces for components have been updated.

7Flag Props

All boolean flags have been renamed so that they reflect a question that can be answered. As an example active is now isActive. Examples of other name prefixes are can and has.

8Compound Components

A compound component pattern has been adopted so that components are composed in a more flexible manner. This is an improvement for the developer as it further utilises the JSX interface. The big benefit is that it gives the developer an opportunity to customise components by swapping out sub components for custom implementations.

From React.js - Compound Components:

A compound component is a type of component that manages the internal state of a feature while delegating control of the rendering to the place of implementation opposed to the point of declaration. They provide a way to shield feature specific logic from the rest of the app providing a clean and expressive API for consuming the component. Internally they are built to operate on a set of data that is passed in through children instead of props. Behind the scenes they make use of React’s lower level API such as, and React.cloneElement(). Using these methods, the component is able to express itself in such a way that promotes patterns of composition and extensibility.

Note that a hybrid pattern is being used. In most instances the sub components will be passed using the children prop. If the component has multiple sub components then these are passed in as props. As TypeScript is being used this is a more type safe option, and it also aligns with the preferred approach demonstrated in the React documentation.

9Affected components

The MOD.UK Design System provides guidance and tools for building high–quality Services within the UK Ministry of Defence. This project is open source and its source code is available on GitHub.

All content is available under the Apache 2.0 licence, except where otherwise stated.

© Crown copyright