Migrating to Standards Toolkit v2
This guide will show you how to upgrade your codebase to work with v2
The Standards Toolkit 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.
The Standards Toolkit v2 has been ported to SASS Modules. This provides the ability to namespace all Standards Toolkit 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.scssfile in the root of your project and
@useevery Sass file across your codebase. Then, import the
index.scssfile (and only this file) once into your main JS entry-point - avoid importing SCSS files into individual
jscomponent files. At the top of your
@usethe Standards CSS framework, as noted below.
- All instances of
@import "@royalnavy/css-framework"should be replaced with
@use "@royalnavy/css-framework" as rn. Whilst the
rnnamespace is optional, we recommend using this as it will prevent the Standards Toolkit 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 "@royalnavy/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 “@royalnavy/css-framework” as rn. Unlike the
@useensures 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
sassnpm package, rather than
sassuses 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
rnnamespace as outlined above, ensure all function & mixin calls are prepended with it (e.g.
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.
primarycolour has been renamed
action- this better describes the colour’s main usage.
alt primaryhas been renamed to
alt successhas been renamed to
alt warninghas been renamed to
- Additional colours
supehave been added.
All renamed colours should have their function calls updated to the new names.
The Standards Toolkit 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.
v2, the Spacing scale has been updated as follows:
|Current Scale||Updated Scale||Computed Value*|
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 for Browsers).
- Makes the
- Balances the scale so that it runs
xxl, rather than
|Current Scale||Updated Scale||Computed Value (rems)|
You will need to update your
rn.font-size() functions & mixins with the new, updated values.
- Normalises Breakpoint scale so
font-size: 100%has a value of
1200px - 1400pxbreakpoint.
- Removes the
xxxlbreakpoint and adds in the
xsbreakpoint. This bumps all scale positions down a breakpoint.
|Current Scale||Updated Scale||Breakpoint Size (px)|
You will need to update your
@include breakpoint() mixins with the new, updated values.
helperclasses have been renamed to
utilityin v2. This is to better align the Standards Toolkit 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
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.
Overriding the Toolkit
With the new module system, it is easier than ever to override values provided by the Standards Toolkit. 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:
// Fonts $font-size: 16px !default; $font-family: "lato" !default; // Choose Context $context: "light" !default; // Adjust Context values $breakpoints: () !default; $colors: () !default; $spacing: () !default; $shadows: () !default; $typography: () !default; $zindex: () !default; // Utility Namespace $utility-ns: "rn_"; // General Housekeeping $content-width: 1280px; $animation-timing: 0.3s;
To override any of these variables in the CSS Framework, use the
with () syntax:
@use "@royalnavy/css-framework" as rn with ( $utiliy-ns: "h_", $colors: ( "neutral": ( "500": #FF0000 ) ) );
This will merge the values provided inside
with () with the default context variables.
The interfaces for components have been updated.
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
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.
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 React.children.map(), 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.