Code Style

NSW Design System uses SASS as its css preprocessor, along with PostCSS and stylelint to compile a modern, consistent CSS file.

Naming convention

To keep specificity low, classes are using prefixed BEM naming convention is being utilised across the project for example:

The prefix is .nsw- then the regular BEM convention follows.

It is recommended to utilise consistent element names such as:

  • __item

  • __link

  • __title

  • __content

This will help to keep things consistent across components and easier to debug.

Mixins

Below is a list of the regularly used mixins built into the Design system

Breakpoint

Accepts a predefined size based off a $breakpoints in _settings.scss

Usage: @include breakpoint(size) { ... }

@include breakpoint('md') {  
  display: block; 
} 

Spacing

Accepts either padding or margin properties names and a predefined size based off a $spacing-sizes in _settings.scss

Usage: @include nsw-spacing(type, size) { ... }

Shorthand

@include nsw-spacing(margin-top, md); 

Longhand

@include nsw-spacing(margin, sm md lg xl);

Font stack

Accepts a predefined font-weight based off a value in $font-weight map in _settings.scss

Usage: @include font-stack(weight: 'regular');

@include font-stack; // regular font 
@include font-stack('heading'); // heading font

Accepts a predefined font-size based off a value in $font-size map in _settings.scss

This mixin handles the mobile and desktop size fonts in the one mixin

Usage: @include font-size(size) { ... }

@include font-size('sm');

Usage:
@include hover;
@include focus(offset: true, color: $focus-color);
@include active;

&:hover { 
  @include nsw-hover; 
} 

&:focus { 
  @include nsw-focus($offset: false, $white); 
} 

&:active { 
  @include nsw-active; 
}

Other mixins include:

  • pseudo-clickable-block

  • break-out/break-out-reset

  • background-svg

  • border-radius

  • z-index

  • border

PostCSS

PostCSS is used to enhance the CSS files by using plugins, the plugins used are:

  • Autoprefixer, with CSS Grid prefixing turned on

  • Normalize, imported inline

  • CSSNano, minify compiled css

PostCSS uses the browserlist.rc file to workout what prefixes are supported and what rules to import for normalise to make sure our compiled css is as modern as possible.

The browsers we support are shown on the browserl.ist website.

Autoprefixer grid support

Ensure that the way you define your CSS Grids comply with Autoprefixers required configs for it to be able to generate IE-Friendly prefixes using grid-template / grid-template-areas to define your grid will enable you to use the grid-gap property without having to hack the css.

For more information see: https://css-tricks.com/css-grid-in-ie-css-grid-and-the-new-autoprefixer/#article-header-id-2

Stylelint

Stylelint has been set up to give a consistent format to the source scss files to make it easier for others to debug and use.

In general the rules we have set are:

  • hexadecimal values are long (6 character) and lowercase

  • no !important rules

  • double colon for pseudo selectors

  • @rules should appear before any other properties

  • maximum nesting depth of 4

  • color properties should use a variable

  • variable pattern is hyphenated-lowercase

Last updated