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.
- 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.
- Be consistent with GOV.UK Design System patterns and conventions, most
of the initial rules of this project were defined to maintain consistency.
- 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.
- Support CSS and SCSS equally.
- 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