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
Support CSS and SCSS equally.
Be sufficiently agreeable that these rules can be used, or aspired to,
across all GDS programmes.
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:
You should then be able to run a lint with
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
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.