Skip to main content

The GDS Way and its content is intended for internal use by the GDS community.

CSS coding style

Contents

Linting

Your project should conform to GDS CSS/Sass linting rules, these are published as a stylelint configuration: stylint-config-gds.

Whitespace

Use soft tabs with a 2 space indent. This follows the conventions we use in our other projects.

Spacing

You should use the GOV.UK Design System spacing scale.

Use with deprecated libraries

If your project is not using the GOV.UK Design System, you should use pixel values in multiples of 5px.

Use rem units strategically

As a general rule, per Josh W. Comeau’s The Surprising Truth About Pixels and Accessibility:

When picking between pixels and rems, here’s the question you should be asking yourself: Should this value scale up as the user increases their browser’s default font size?

Use rem units for font-size wherever possible.

You should generally avoid using rem for padding or border-width if these are likely to cause layout or readability issues when the font-size increases.

Vendor prefixing

When using CSS features which require vendor prefixes use autoprefixer.

You should configure autoprefixer to target our supported browsers.

Sass nesting

Sass nesting should be avoided where possible.

Over use of nesting can make searching for selectors difficult and can hide complicated CSS that should be simplified.

Exceptions to this include pseudo selectors and JavaScript enabled classes.

.accordion {
  // styles when the accordion is not enhanced here
}
.js-enabled {
  .accordion {
    // styles when the accordion is enhanced here

    &:focus {
      // ...
    }
  }
}
This page was last reviewed on 3 April 2023. It needs to be reviewed again on 3 April 2024 by the page owner #frontend .
This page was set to be reviewed before 3 April 2024 by the page owner #frontend. This might mean the content is out of date.