Stylelint

Summary

Stylelint is a mighty, modern linter that helps you avoid errors and enforce conventions in your styles.

Details

Using Zasaf as our in-house approach to write modular CSS with easily maintainable and scalable stylesheets, we have a very opinionated picture of what our CSS should look like. Therefore, we decided to use a Zweitag-wide configuration and deviate from the standard rules. The configuration provided in this repository helps on the one hand to write better CSS and on the other hand to fulfil parts of the goals and guidelines of Zasaf.

The stylelint documentation is very good and explains each rule (and a lot more) in detail.

Our Zweitag config

The commonly usable config file is located here in this repository.

It is based on some simple principles:

1. Exceptions should be justified and documented (in a comment). You don't want to ask yourself in a month if it wouldn't be better to remove the exception and so on.
2. Exceptions should be as small as possible, meaning that if for example you have to turn off a rule because it makes sense for files in stylesheets/globals for example, just disable it for this directory, not globally!

Using the Zweitag config

Projects which are generated from our rails template repository should automatically use this config. The Zweitag stylelint configuration is available as a package in the npm package-registry. If you want to use it in an existing project (please do), add the package as node module:

yarn add --dev @zweitag/stylelint-config
or
npm install --save-dev @zweitag/stylelint-config

Additionally you need a .stylelintrc.json where you extend our global configuration:

{
  "extends": "@zweitag/stylelint-config"
}

Adapting the configuration to your project and handling edge cases

Situations will arise where you have to deactivate stylelint rules for certain cases. This can be done with the help of the comment ignore syntax, but ensure to disable only the specific rules:

// stylelint-disable-next-line [rules] -- comment

or

// stylelint-disable-line [rules] -- comment

or

// stylelint-disable [rules] -- comment
.block {
  width: 100px;
}
// stylelint-enable [rules]

There is a more detailed documentation on the stylelint docs available.

In some cases, some rules must also be overridden or deactivated project-wide. To do this, you can simply override a rule in your .stylelintrc.json. If it makes sense to adapt the rule for all projects, you are welcome to create a pull request for the central configuration in this repository.

If you just want to ignore some specific files, you can create a .stylelintignore including the github glob-pattern for the files to be ignored.

How do I migrate an existing project?

As you are migrating an existing project, there is a --fix option, auto-correcting simple errors and code smells. In case you don't want to migrate the whole project at once, you can use the comment ignore syntax or the .stylelintignore to handle larger code smells when there is time and budget.

Adjusting the central config

If you feel that a rule that is currently enabled/disabled should be changed in the shared config

• it doesn't make sense in our circumstances (like enforcing documentation which we usually don't)
• or it does make absolutely no sense whatsoever
• ...

please feel free to discuss the rule

• in the office
• during hack teams
• on slack
• in a github issue or a github pull request
• ...

and eventually create a pull request that does the following:

• enables/disables the rule(s) or adds exceptions regarding files in the config file
• adds a comment directly beside or beneath the exception explaining why it exists
• probably links some more resources or reasons for the decision (e.g. a slack conversation) on the pull request (not in the config)

Last but not least, feel free to also discuss and adjust this readme.