The Telegraph Engineering stylelint config.
We have based our config on
stylelint-config-standard and made various custom changes to adhere to our internal standards.
$ npm install @telegraph-engineering/stylelint-config-telegraph --save-dev
Within your stylelint config object You can extend this configuration. This will serve as a base for your config, then you can make overrides in your own config object.
The different options for rules can be found in the original stylelint repo
Indent your CSS properties with tabs. The default tab size should be set as 4.
Heavy nesting should be avoided at all times, particularly with Sass. Every element should have its own class and be written on a new line.
Nesting is only permitted for pseudo selectors and must have a new, empty, line above them.
Readability vs Compression
CSS should be written in a readable manor and compression left for the build process and tooling.
Do not prefix any of your CSS as we let autoprefixer do all of the hard work for us.
Multiple shared selectors should go on seperate lines and you should not have more than 3 levels deep for selectors.
Avoid all universal selectors (
*). Components and styles will be shared on pages and these selectors will cause unforseen problems.
Avoid the use of top level type selectors. Components and styles will be shared on pages and these selectors will cause unforseen problems.
Never use ID selectors. The high specificty can cause unexpected issues between styles.
Class names should be in the Block Element Modifier (BEM) style. BEM allows for clean, reusable code, that makes a clear connection between the HTML 'component' and its styles.
Never go more than two levels deep with compound selectors. If the BEM syntax is followed carefully then this should mitigate the need for these type of selectors.
The use of
!important should only be considered for helper classes or if it is a requirement to override third party, inline, styles.
Comment as much as you can to be as clear as you can. Where applicable, for a component, comment out a piece of markup to help define the context of the CSS. Comments should have a new, empty, line above them and be above the CSS selector.
We don't promote the use of the
@extend operator. It can generate unexpected results in compiled CSS.