Shareable stylelint config for CSS and SCSS, following Torchbox’s code style.

Install stylelint, and the config:

npm install --save-dev stylelint stylelint-config-torchbox

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

module.exports = {
  // See https://github.com/torchbox/stylelint-config-torchbox for rules.
  extends: 'stylelint-config-torchbox',
};

Review our CHANGELOG for guidance on how to upgrade a project’s linting to a specific version.

More generally, when retrofitting stricter linting onto an existing project, consider a gradual approach to linting strictness, so you can start using linting without having to change significant portions of the project’s code. Here is an example, disabling commonly hard-to-retrofit rules:

// Rules which we ideally would want to enforce but are reporting too many issues currently.
const legacyRules = {
  'max-nesting-depth': null,
  'selector-max-specificity': null,
};

module.exports = {
  // See https://github.com/torchbox/stylelint-config-torchbox for rules.
  extends: 'stylelint-config-torchbox',
  rules: {
    ...legacyRules,
  },
};

We recommend the following run script to add to your package.json:

"lint:css": "stylelint --report-needless-disables 'src/sass' 'src/vue'"

• Use --report-needless-disables flag to ensure you do not use more stylelint-disable comments than needed.
• Target specific folders so Stylelint doesn’t attempt to lint e.g. JS or HTML files.

Stylelint supports ignore patterns in a .stylelintignore file, however we tend not to use this since we lint all files within a given folder.

This config is Prettier-compatible, there isn’t anything extra needed.

This config should work with Tailwind with no adjustments needed. Please submit an issue if that’s not the case.

Here is a sample setup with our recommended configuration for the pre-commit pre-commit hook framework:

default_language_version:
  node: system
repos:
  - repo: https://github.com/thibaudcolas/pre-commit-stylelint
    rev: v15.10.3
    hooks:
      - id: stylelint
        files: \.(scss|vue)$
        additional_dependencies:
          - [email protected]
          - [email protected]

Stylelint supports Vue, and our configuration is usable in .vue single-file components with no changes. Do make sure linting is configured to check .vue files:

• Wherever stylelint is manually invoked, make sure to point it both at stylesheets, and Vue components: stylelint --report-needless-disables './src/sass' './src/vue_components'.
• With stylelint-webpack-plugin, use extensions: ['scss', 'vue'],.
• With pre-commit, use files: \.(scss|vue)$.

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 and autoprefixer.

See config.js for the config definition. This package includes configuration from:

• stylelint-config-standard-scss
• stylelint-order
• stylelint-declaration-strict-value

For the full list of enabled, disabled, and unused rules, view src/rules.md.

• color-named: never
• declaration-block-no-shorthand-property-overrides
• declaration-no-important
• selector-max-id: 0
• selector-max-type: 2, ignore: child, compounded, next-sibling
• selector-class-pattern: , resolveNestedSelectors: true
• max-nesting-depth: 4
• selector-max-specificity: 0,4,0
• value-no-vendor-prefix
• property-no-vendor-prefix
• selector-no-vendor-prefix
• media-feature-name-no-vendor-prefix
• at-rule-no-vendor-prefix
• declaration-property-value-disallowed-list: text-align: justify
• scss/at-rule-no-unknown: true, ignoreAtRules: tailwind, apply, variants, responsive, screen, layer
• scss/declaration-nested-properties: never
• scss/selector-no-redundant-nesting-selector
• scss/percent-placeholder-pattern: ^do-not-use-placeholders$
• scss/dollar-variable-no-missing-interpolation
• scss/at-mixin-argumentless-call-parentheses: always
• scss/at-mixin-pattern: ``
• order/order: dollar-variables, custom-properties, type: at-rule, hasBlock: false, declarations
• scale-unlimited/declaration-strict-value: color, fill, stroke, /-color/, ignoreKeywords: currentColor, inherit, transparent, initial, none, unset, Canvas, CanvasText, LinkText, VisitedText, ActiveText, ButtonFace, ButtonText, ButtonBorder, Field, FieldText, Highlight, HighlightText, SelectedItem, SelectedItemText, Mark, MarkText, GrayText, AccentColor, AccentColorText

• block-no-empty
• color-hex-length: short
• color-no-invalid-hex
• 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
• custom-property-no-missing-var-function
• declaration-block-no-duplicate-custom-properties
• declaration-block-no-duplicate-properties: true, ignore: consecutive-duplicates-with-different-syntaxes
• declaration-block-single-line-max-declarations: 1
• font-family-name-quotes: always-where-recommended
• font-family-no-duplicate-names
• font-family-no-missing-generic-family-keyword
• function-calc-no-unspaced-operator
• function-linear-gradient-no-nonstandard-direction
• function-name-case: lower
• function-url-quotes: always
• hue-degree-notation: angle
• import-notation: string
• keyframe-block-no-duplicate-selectors
• keyframe-declaration-no-important
• keyframe-selector-notation: percentage-unless-within-keyword-only-block
• length-zero-no-unit: true, ignore: custom-properties
• media-feature-name-no-unknown
• named-grid-areas-no-invalid
• no-duplicate-at-import-rules
• no-duplicate-selectors
• no-empty-source
• no-invalid-double-slash-comments
• no-invalid-position-at-import-rule: true, ignoreAtRules: use, forward
• no-irregular-whitespace
• number-max-precision: 4
• property-no-unknown
• rule-empty-line-before: always-multi-line, except: first-nested, ignore: after-comment
• scss/at-else-closing-brace-newline-after: always-last-in-chain
• scss/at-else-closing-brace-space-after: always-intermediate
• scss/at-else-empty-line-before: never
• scss/at-else-if-parentheses-space-before: always
• scss/at-function-parentheses-space-before: never
• scss/at-if-closing-brace-newline-after: always-last-in-chain
• scss/at-if-closing-brace-space-after: always-intermediate
• scss/at-if-no-null
• scss/at-import-no-partial-leading-underscore
• scss/at-import-partial-extension: never
• scss/at-mixin-parentheses-space-before: never
• scss/at-rule-conditional-no-parentheses
• scss/comment-no-empty
• scss/declaration-nested-properties-no-divided-groups
• scss/dollar-variable-colon-space-after: always
• scss/dollar-variable-colon-space-before: never
• scss/double-slash-comment-whitespace-inside: always
• scss/function-quote-no-quoted-strings-inside
• scss/function-unquote-no-unquoted-strings-inside
• scss/no-duplicate-mixins
• scss/operator-no-newline-after
• scss/operator-no-newline-before
• scss/operator-no-unspaced
• selector-anb-no-unmatchable
• selector-attribute-quotes: always
• selector-pseudo-class-no-unknown
• selector-pseudo-element-colon-notation: double
• selector-pseudo-element-no-unknown
• selector-type-case: lower
• selector-type-no-unknown: true, ignore: custom-elements
• string-no-newline
• unit-no-unknown
• value-keyword-case: lower

See the contribution guidelines for guidance and setup instructions.