| 1 | # Vision
|
| 2 |
|
| 3 | A mighty, modern linter and fixer for CSS and CSS-like languages.
|
| 4 |
|
| 5 | One that is:
|
| 6 |
|
| 7 | - Complete - with coverage of all standard CSS syntax.
|
| 8 | - Extensible - with multiple points of extension.
|
| 9 | - Configurable - with no defaults and plenty of options to tailor the linter.
|
| 10 | - Robust - with comprehensive test coverage and a wide range of fixtures.
|
| 11 | - Consistent - with conventions for behaviour, naming and documentation.
|
| 12 | - Performant - with tools to test and improve performance.
|
| 13 |
|
| 14 | ## Complete
|
| 15 |
|
| 16 | Provide built-in rules for the following three areas:
|
| 17 |
|
| 18 | - [Possible errors](docs/user-guide/rules.md#possible-errors).
|
| 19 | - [Limit language features](docs/user-guide/rules.md#limit-language-features).
|
| 20 | - [Stylistic issues](docs/user-guide/rules.md#stylistic-issues).
|
| 21 |
|
| 22 | ### Possible errors
|
| 23 |
|
| 24 | Provide rules to catch two types of possible errors:
|
| 25 |
|
| 26 | - Invalid code e.g. invalid hex colors and unknown language features.
|
| 27 | - Code that is valid but likely has unintended consequences e.g. duplicates and overrides.
|
| 28 |
|
| 29 | Invalid code is best handled by emerging dedicated tools e.g. [csstree](https://github.com/csstree/csstree) - a language parser with syntax validation. As a stop-gap, while these tools mature, provide invalid code rules for the simplest of cases.
|
| 30 |
|
| 31 | (In the future, these tools can be wrapped as plugins to make use of features such as `/* stylelint-* */` command comments, severity levels, and options validator.)
|
| 32 |
|
| 33 | ### Limit language features
|
| 34 |
|
| 35 | Provide rules to limit what language features can be used, including:
|
| 36 |
|
| 37 | - Enforcing a maximum specificity by limiting the specificity itself or the occurrence of different selector types e.g. class, ID, attribute etc.
|
| 38 | - Enforcing best practices _at the configuration level_ e.g. disallowing the `all` keyword for transitions as it is not performant.
|
| 39 | - Enforcing the use of a subset of features to improve consistency across a code base e.g. limiting what units are allowed (`px` or `rem` etc.)
|
| 40 | - Enforcing specific patterns for selectors and names (e.g. those of custom properties).
|
| 41 |
|
| 42 | ### Stylistic issues
|
| 43 |
|
| 44 | Provide rules to enforce a diverse range of stylistic conventions, including:
|
| 45 |
|
| 46 | - Whitespace
|
| 47 | - Case
|
| 48 | - Quotes
|
| 49 |
|
| 50 | There are two approaches to enforcing stylistic conventions:
|
| 51 |
|
| 52 | - A machine algorithmically pretty prints the code (usually based on a maximum line length).
|
| 53 | - A human initially formats the code, and a machine fixes-up/warns-about any mistakes.
|
| 54 |
|
| 55 | The former is handled by pretty printers, like [prettier](https://github.com/prettier/prettier), whereas the latter is catered for by the built-in stylistic rules.
|
| 56 |
|
| 57 | Additionally, the built-in stylistic rules and plugins are configurable to support this diverse range of stylistic conventions. This is in contrast to pretty printers, which tend to be opinionated. The ordering of properties within declaration blocks is an example of a divisive topic, where there is no one or two dominant conventions. The [`stylelint-order`](https://www.npmjs.com/package/stylelint-order) plugin adheres to stylelint's philosophies, and can be used to lint and fix a diverse range of ordering conventions.
|
| 58 |
|
| 59 | Another example is the use of single-line rules for sets of _related_ rules e.g.
|
| 60 |
|
| 61 | ```css
|
| 62 | /* Single-line related classes */
|
| 63 | .class-1 { top: 0; bottom: 0; }
|
| 64 | .class-2 { top: 5px; right: 0; }
|
| 65 | .class-3 { top: 8px; left: 0; }
|
| 66 | ```
|
| 67 |
|
| 68 | The built-in stylistic rules can be configured to allow both multi-line and single-line rules. The choice of when to use each belongs to the user, who can determine which rules are related.
|
| 69 |
|
| 70 | ## Extensible
|
| 71 |
|
| 72 | Provide multiple points of extensions, including:
|
| 73 |
|
| 74 | - [Plugins](docs/developer-guide/plugins.md) - build community rules to support methodologies, toolsets, non-standard CSS features, or very specific use cases.
|
| 75 | - [Processors](docs/user-guide/processors.md) - lint the CSS within non-stylesheet files.
|
| 76 | - [Extendable configs](docs/user-guide/configuration.md#extends) - extend and share configurations.
|
| 77 | - [Formatters](docs/developer-guide/formatters.md) - format stylelint result objects.
|
| 78 | - [Custom syntax](docs/user-guide/node-api.md#customsyntax) - use any PostCSS-compatible syntax module.
|
| 79 |
|
| 80 | ## Robust
|
| 81 |
|
| 82 | Provide a robust tool with a [comprehensive test suite](docs/developer-guide/rules.md#write-tests), including:
|
| 83 |
|
| 84 | - High coverage, currently over 95%.
|
| 85 | - A wide range of fixtures for rules, currently over 10000.
|
| 86 |
|
| 87 | ## Consistent
|
| 88 |
|
| 89 | Provide consistency throughout, including:
|
| 90 |
|
| 91 | - Consistent [names](docs/developer-guide/rules.md#naming-a-rule), [options](docs/developer-guide/rules.md#determining-options), [violation messages](docs/developer-guide/rules.md#determine-violation-messages), [documentation](docs/developer-guide/rules.md#write-the-readme) and [treatment](docs/developer-guide/rules.md#write-the-rule) of non-standard syntax within/of rules.
|
| 92 | - Consistent [requirements for inclusion](docs/developer-guide/rules.md#criteria-for-inclusion).
|
| 93 |
|
| 94 | ## Performant
|
| 95 |
|
| 96 | Provide a fast tool, and the means to test and improve performance, including:
|
| 97 |
|
| 98 | - [Benchmarking](docs/developer-guide/rules.md#improving-the-performance-of-a-rule) of an individual rule's performance.
|