GDS Stylelint Config

This provides a Stylelint configuration for linting SCSS and CSS files as per the conventions of the Government Digital Service (GDS).

It builds upon stylelint-config-standard with conventions GDS have adopted over the years.

Project goals

This project was developed with a number of goals in mind, these should be considered whenever proposals are made to add to or amend the rules.

1. Lean on community standards over defining our own rules as much as possible - it's not a good use of our time to debate preferences so let's follow common community guidelines unless we have a compelling reason not to do so.
2. Be consistent with GOV.UK Design System patterns and conventions, most of the initial rules of this project were defined to maintain consistency.
3. Reflect modern CSS practices over providing compatibility for legacy projects, if it is unfeasible for legacy projects to adopt all these rules they are encouraged to disable problematic rules in their project configuration.
4. Support CSS and SCSS equally.
5. Be sufficiently agreeable that these rules can be used, or aspired to, across all GDS programmes.

Usage

These rules are expected to be mostly used for SCSS projects (as these are more common at GDS) however the CSS rules can be used alone.

To add this to your project, install Stylelint and this module:

npm install --save-dev stylelint stylelint-config-gds

You then need to configure Stylelint.

To lint SCSS you can add the following property to your package.json:

"stylelint": {
  "extends": "stylelint-config-gds/scss"
}

To lint CSS add the following:

"stylelint": {
  "extends": "stylelint-config-gds/css"
}

You should then be able to run a lint with node_modules/.bin/stylelint '**/*.(s)?css'.

Development

Make changes to rules that affect both CSS and SCSS in ./css-rules.js, for rules that only apply to SCSS add them to ./scss-rules.js.

You can lint the JS and run tests with npm test

Releasing

GitHub Actions is used to release new versions of this module when a PR is merged into the main branch and there is a new version number.

To create a new release you should amend package.json to have the new version number (based on semvar) and run npm install to update package-lock.json. You should then update the CHANGELOG.md. Finally, open a PR - once this is merged the change will be released.

Licence

MIT License