stylelint-config-telegraph
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.
Install
$ npm install @telegraph-engineering/stylelint-config-telegraph --save-dev
Usage
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.
{
"extends": "@telegraph-engineering/stylelint-config-telegraph"
}Rules
The different options for rules can be found in the original stylelint repo
Styleguide
Indentation
Indent your CSS properties with tabs. The default tab size should be set as 4.
Nesting
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.
Prefixes
Do not prefix any of your CSS as we let autoprefixer do all of the hard work for us.
Selectors
Multiple shared selectors should go on seperate lines and you should not have more than 3 levels deep for selectors.
Universal
Avoid all universal selectors (*). Components and styles will be shared on pages and these selectors will cause unforseen problems.
Type
Avoid the use of top level type selectors. Components and styles will be shared on pages and these selectors will cause unforseen problems.
ID
Never use ID selectors. The high specificty can cause unexpected issues between styles.
Class
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.
Compound
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.
Important
The use of !important should only be considered for helper classes or if it is a requirement to override third party, inline, styles.
Comments
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.
@extend
We don't promote the use of the @extend operator. It can generate unexpected results in compiled CSS.