@thibaudcolas/stylelint-config-cookbook NPM

@thibaudcolas/stylelint-config-cookbook

Shareable stylelint config for CSS and SCSS, with a strict baseline

Usage

Install stylelint and the config:

npm install --save-dev stylelint @thibaudcolas/stylelint-config-cookbook

Then configure stylelint to use this config. As a stylelint.config.js in the root of your project:

module.exports = {
  // https://github.com/thibaudcolas/stylelint-config-cookbook
  extends: "@thibaudcolas/stylelint-config-cookbook",
};

Tips

Use Stylelint’s --report-needless-disables flag to ensure you do not use more stylelint-disable comments than needed.

Related tools

To get the most out of this config, it is assumed that projects have the following tools set up:

Prettier for automated formatting of stylesheets.
Browserslist for the definition of target browsers (along with autoprefixer and @babel/preset-env).

Conventions

The overarching principle behind this config is to make it simpler to maintain stylesheets in large-scale projects. This means:

Support for large-scale CSS architectures like ITCSS.
Mandatory reusable values (via variables and functions) for properties that impact the overall consistency of the UI, e.g. colors and attributes of fonts.
A low maximum specificity, to prevent abuse of the CSS cascade (or altogether discourage usage of styles overrides beyond single components).
Blanket ban of CSS/SCSS features that make it harder to maintain stylesheets – id selectors (never), element selectors (max 1), nested properties, etc).

Rules

Cookbook config

color-named: never
declaration-block-no-shorthand-property-overrides
shorthand-property-no-redundant-values
declaration-no-important
selector-max-id: 0
selector-max-type: 1
selector-no-qualifying-type
max-nesting-depth: 3
selector-max-specificity: 0,3,0
value-no-vendor-prefix
function-calc-no-invalid
property-no-vendor-prefix
selector-no-vendor-prefix
media-feature-name-no-vendor-prefix
at-rule-no-vendor-prefix
scss/at-rule-no-unknown
scss/declaration-nested-properties: never
scss/selector-no-redundant-nesting-selector
scss/percent-placeholder-pattern: ^do-not-use-placeholders$
scss/at-function-named-arguments: always
scss/at-mixin-named-arguments: always
scss/dollar-variable-no-missing-interpolation
scss/at-mixin-argumentless-call-parentheses: always
scss/media-feature-value-dollar-variable: always
scss/no-duplicate-dollar-variables
scss/no-duplicate-mixins
scss/map-keys-quotes: always
scss/function-unquote-no-unquoted-strings-inside
scss/function-quote-no-quoted-strings-inside
scss/dimension-no-non-numeric-values
scss/comment-no-loud
scss/at-import-partial-extension: never
scss/at-if-no-null
scss/at-each-key-value-single-line
plugin/declaration-block-no-ignored-properties
scale-unlimited/declaration-strict-value: /color/, z-index, font-size, font-family, ignoreKeywords: currentColor, inherit, transparent, initial
plugin/no-unsupported-browser-features: true, ignore: user-select-none, css3-cursors, viewport-units, outline, css-appearance
a11y/content-property-no-static-value
a11y/font-size-is-readable
a11y/media-prefers-reduced-motion
a11y/no-obsolete-attribute
a11y/no-obsolete-element
a11y/no-text-align-justify
order/order: dollar-variables, custom-properties, type: at-rule, hasBlock: false, declarations, rules, type: at-rule, hasBlock: true
order/properties-order: groupName: All, properties: all, groupName: Position, properties: position, top, right, bottom, left, z-index, groupName: Display mode, properties: box-sizing, display, groupName: Flexbox, properties: flex, flex-basis, flex-direction, flex-flow, flex-grow, flex-shrink, flex-wrap, groupName: Grid, properties: grid, grid-area, grid-template, grid-template-areas, grid-template-rows, grid-template-columns, grid-row, grid-row-start, grid-row-end, grid-column, grid-column-start, grid-column-end, grid-auto-rows, grid-auto-columns, grid-auto-flow, grid-gap, grid-row-gap, grid-column-gap, groupName: Align, properties: align-content, align-items, align-self, groupName: Justify, properties: justify-content, justify-items, justify-self, groupName: Order, properties: order, groupName: Box model, properties: float, width, min-width, max-width, height, min-height, max-height, padding, padding-top, padding-right, padding-bottom, padding-left, margin, margin-top, margin-right, margin-bottom, margin-left, overflow, overflow-x, overflow-y, -webkit-overflow-scrolling, -ms-overflow-x, -ms-overflow-y, -ms-overflow-style, clip, clear, groupName: Typography, properties: font, font-family, font-size, font-style, font-weight, font-variant, font-size-adjust, font-stretch, font-effect, font-emphasize, font-emphasize-position, font-emphasize-style, -webkit-font-smoothing, -moz-osx-font-smoothing, font-smooth, hyphens, line-height, color, text-align, text-align-last, text-emphasis, text-emphasis-color, text-emphasis-style, text-emphasis-position, text-decoration, text-indent, text-justify, text-outline, -ms-text-overflow, text-overflow, text-overflow-ellipsis, text-overflow-mode, text-shadow, text-transform, text-wrap, -webkit-text-size-adjust, -ms-text-size-adjust, letter-spacing, word-break, word-spacing, word-wrap, overflow-wrap, tab-size, white-space, vertical-align, list-style, list-style-position, list-style-type, list-style-image, groupName: Accessibility & Interactions, properties: pointer-events, -ms-touch-action, touch-action, cursor, visibility, zoom, table-layout, empty-cells, caption-side, border-spacing, border-collapse, content, quotes, counter-reset, counter-increment, resize, user-select, nav-index, nav-up, nav-right, nav-down, nav-left, groupName: Background & Borders, properties: background, background-color, background-image, -ms-filter: \\'progid: DXImageTransform.Microsoft.gradient, filter: progid: DXImageTransform.Microsoft.gradient, filter: progid: DXImageTransform.Microsoft.AlphaImageLoader, filter, background-repeat, background-attachment, background-position, background-position-x, background-position-y, background-clip, background-origin, background-size, background-blend-mode, isolation, border, border-color, border-style, border-width, border-top, border-top-color, border-top-style, border-top-width, border-right, border-right-color, border-right-style, border-right-width, border-bottom, border-bottom-color, border-bottom-style, border-bottom-width, border-left, border-left-color, border-left-style, border-left-width, border-radius, border-top-left-radius, border-top-right-radius, border-bottom-right-radius, border-bottom-left-radius, border-image, border-image-source, border-image-slice, border-image-width, border-image-outset, border-image-repeat, outline, outline-width, outline-style, outline-color, outline-offset, box-shadow, mix-blend-mode, filter: progid: DXImageTransform.Microsoft.Alpha(Opacity, -ms-filter: \\'progid: DXImageTransform.Microsoft.Alpha, opacity, -ms-interpolation-mode, groupName: SVG Presentation Attributes, properties: alignment-baseline, baseline-shift, dominant-baseline, text-anchor, word-spacing, writing-mode, fill, fill-opacity, fill-rule, stroke, stroke-dasharray, stroke-dashoffset, stroke-linecap, stroke-linejoin, stroke-miterlimit, stroke-opacity, stroke-width, color-interpolation, color-interpolation-filters, color-profile, color-rendering, flood-color, flood-opacity, image-rendering, lighting-color, marker-start, marker-mid, marker-end, mask, shape-rendering, stop-color, stop-opacity, groupName: Transitions & Animation, properties: transition, transition-delay, transition-timing-function, transition-duration, transition-property, transform, transform-origin, animation, animation-name, animation-duration, animation-play-state, animation-timing-function, animation-delay, animation-iteration-count, animation-direction