@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

Rules of stylelint-config-standard

• at-rule-name-space-after: always
• color-hex-length: short
• comment-empty-line-before: always, except: first-nested, ignore: stylelint-commands
• comment-whitespace-inside: always
• custom-property-empty-line-before: always, except: after-custom-property, first-nested, ignore: after-comment, inside-single-line-block
• declaration-bang-space-after: never
• declaration-bang-space-before: always
• declaration-block-single-line-max-declarations: 1
• declaration-empty-line-before: always, except: after-declaration, first-nested, ignore: after-comment, inside-single-line-block
• function-name-case: lower
• function-whitespace-after: always
• length-zero-no-unit
• media-feature-colon-space-after: always
• media-feature-colon-space-before: never
• media-feature-parentheses-space-inside: never
• media-feature-range-operator-space-after: always
• media-feature-range-operator-space-before: always
• selector-attribute-brackets-space-inside: never
• selector-attribute-operator-space-after: never
• selector-attribute-operator-space-before: never
• selector-pseudo-class-parentheses-space-inside: never
• selector-pseudo-element-colon-notation: double
• selector-type-case: lower
• value-keyword-case: lower
• block-no-empty
• color-no-invalid-hex
• comment-no-empty
• declaration-block-no-duplicate-properties: true, ignore: consecutive-duplicates-with-different-values
• font-family-no-duplicate-names
• font-family-no-missing-generic-family-keyword
• function-calc-no-unspaced-operator
• function-linear-gradient-no-nonstandard-direction
• keyframe-declaration-no-important
• media-feature-name-no-unknown
• no-descending-specificity
• no-duplicate-at-import-rules
• no-duplicate-selectors
• no-empty-source
• no-invalid-double-slash-comments
• property-no-unknown
• selector-pseudo-class-no-unknown
• selector-pseudo-element-no-unknown
• selector-type-no-unknown
• string-no-newline
• unit-no-unknown
• selector-attribute-quotes: always
• at-rule-semicolon-space-before: never

Disabled rules

Rules that are turned off on purpose.

• at-rule-no-unknown
• at-rule-empty-line-before
• at-rule-name-case
• at-rule-semicolon-newline-after
• block-closing-brace-empty-line-before
• block-closing-brace-newline-after
• block-closing-brace-newline-before
• block-closing-brace-space-before
• block-opening-brace-newline-after
• block-opening-brace-space-after
• block-opening-brace-space-before
• color-hex-case
• declaration-block-semicolon-newline-after
• declaration-block-semicolon-space-after
• declaration-block-semicolon-space-before
• declaration-block-trailing-semicolon
• declaration-colon-newline-after
• declaration-colon-space-after
• declaration-colon-space-before
• function-comma-newline-after
• function-comma-space-after
• function-comma-space-before
• function-max-empty-lines
• function-parentheses-newline-inside
• function-parentheses-space-inside
• indentation
• max-empty-lines
• media-feature-name-case
• media-query-list-comma-newline-after
• media-query-list-comma-space-after
• media-query-list-comma-space-before
• no-eol-whitespace
• no-missing-end-of-source-newline
• number-leading-zero
• number-no-trailing-zeros
• property-case
• rule-empty-line-before
• selector-combinator-space-after
• selector-combinator-space-before
• selector-descendant-combinator-no-non-space
• selector-list-comma-newline-after
• selector-list-comma-space-before
• selector-max-empty-lines
• selector-pseudo-class-case
• selector-pseudo-element-case
• unit-case
• value-list-comma-newline-after
• value-list-comma-space-after
• value-list-comma-space-before
• value-list-max-empty-lines
• no-extra-semicolons
• linebreaks
• max-line-length
• function-comma-newline-before
• value-list-comma-newline-before
• declaration-block-semicolon-newline-before
• block-closing-brace-space-after
• block-opening-brace-newline-before
• selector-list-comma-newline-before
• selector-list-comma-space-after
• media-query-list-comma-newline-before
• at-rule-name-newline-after
• no-empty-first-line
• unicode-bom
• string-quotes

Unused rules

Rules that are not configured.

• a11y/line-height-is-vertical-rhythmed
• a11y/media-prefers-color-scheme
• a11y/no-display-none
• a11y/no-outline-none
• a11y/no-spread-text
• a11y/selector-pseudo-class-focus
• comment-word-blacklist
• custom-media-pattern
• custom-property-pattern
• declaration-block-no-redundant-longhand-properties
• declaration-property-unit-blacklist
• declaration-property-unit-whitelist
• declaration-property-value-blacklist
• declaration-property-value-whitelist
• font-family-name-quotes
• font-weight-notation
• function-blacklist
• function-url-no-scheme-relative
• function-url-quotes
• function-url-scheme-blacklist
• function-url-scheme-whitelist
• function-whitelist
• keyframes-name-pattern
• linebreaks
• media-feature-name-blacklist
• media-feature-name-value-whitelist
• media-feature-name-whitelist
• no-empty-first-line
• no-unknown-animations
• number-max-precision
• property-blacklist
• property-whitelist
• scss/partial-no-import
• scss/selector-nest-combinators
• selector-attribute-operator-blacklist
• selector-attribute-operator-whitelist
• selector-class-pattern
• selector-combinator-blacklist
• selector-combinator-whitelist
• selector-max-attribute
• selector-max-class
• selector-max-combinators
• selector-max-compound-selectors
• selector-max-pseudo-class
• selector-max-universal
• selector-nested-pattern
• selector-pseudo-class-blacklist
• selector-pseudo-class-whitelist
• selector-pseudo-element-blacklist
• selector-pseudo-element-whitelist
• time-min-milliseconds
• unit-blacklist
• unit-whitelist
• value-keyword-case
• scss/dollar-variable-pattern
• scss/at-function-pattern
• scss/at-import-partial-extension-blacklist
• scss/at-import-partial-extension-whitelist
• scss/dollar-variable-default
• scss/no-dollar-variables
• scss/selector-no-union-class-name
• scss/function-color-relative
• scss/at-rule-conditional-no-parentheses
• at-rule-blacklist
• at-rule-property-requirelist
• at-rule-whitelist
• color-no-hex
• selector-id-pattern
• order/properties-alphabetical-order
• scss/at-else-closing-brace-newline-after
• scss/at-else-closing-brace-space-after
• scss/at-else-empty-line-before
• scss/at-else-if-parentheses-space-before
• scss/at-extend-no-missing-placeholder
• scss/at-function-parentheses-space-before
• scss/at-if-closing-brace-newline-after
• scss/at-if-closing-brace-space-after
• scss/at-import-no-partial-leading-underscore
• scss/at-mixin-parentheses-space-before
• scss/at-mixin-pattern
• scss/declaration-nested-properties-no-divided-groups
• scss/dollar-variable-colon-newline-after
• scss/dollar-variable-colon-space-after
• scss/dollar-variable-colon-space-before
• scss/dollar-variable-empty-line-before
• scss/double-slash-comment-empty-line-before
• scss/double-slash-comment-inline
• scss/double-slash-comment-whitespace-inside
• scss/operator-no-newline-after
• scss/operator-no-newline-before
• scss/operator-no-unspaced