stylelint-config-torchbox

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

Usage

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 or stylelint.config.mjs in the root of your project:

/** @type {import('stylelint').Config} */
export default {
  // See https://github.com/torchbox/stylelint-config-torchbox for rules.
  extends: 'stylelint-config-torchbox',
};

Tips

Linting setup for ongoing projects

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,
};

/** @type {import('stylelint').Config} */
export default {
  // See https://github.com/torchbox/stylelint-config-torchbox for rules.
  extends: 'stylelint-config-torchbox',
  rules: {
    ...legacyRules,
  },
};

Agent skills

This is new - please share feedback about agent skills if you use this on projects!

This project ships an upgrading-stylelint agent skill for AI coding agents. It is meant for auditing or carrying out a Stylelint upgrade, including checking the upgrade path, reviewing migration guides, updating dependencies or config, running QA, and reporting follow-up work.

Install the project skills with Vercel Lab’s Agent Skills:

npx skills add torchbox/stylelint-config-torchbox

Example prompt:

Use the upgrading-stylelint skill to upgrade this project from Stylelint 16 to 17, including updating to the compatible stylelint-config-torchbox version. Update dependencies and config as needed, update as much of the styles as you can if safe.

Common CLI flags

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

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

• Use --report-needless-disables to ensure you do not use more stylelint-disable comments than needed.
• Use --report-unscoped-disables to prevent fully disabling linting.
• Target specific folders so Stylelint doesn’t attempt to lint other file types, say JS or HTML files.

.stylelintignore

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

Prettier

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

Tailwind

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

prek for pre-commit hooks

We recommend prek, an implementation of the pre-commit framework to manage hooks. Our sample setup uses a standard .pre-commit-config.yaml, so the same configuration also works with pre-commit if needed:

default_language_version:
  node: system
repos:
  - repo: https://github.com/thibaudcolas/pre-commit-stylelint
    rev: v17.4.0
    hooks:
      - id: stylelint
        files: \.(scss|vue)$
        additional_dependencies:
          - stylelint@17.4.0
          - stylelint-config-torchbox@5.0.0

Vue

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 --report-unscoped-disables './src/sass' './src/vue_components'.
• With stylelint-webpack-plugin, use extensions: ['scss', 'vue'],.
• With prek or pre-commit, use files: \.(scss|vue)$.

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

What’s included

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

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

Rules

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

Custom rules

• 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
• scss/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, config, theme, custom-variant, plugin, source, variant, utility, reference
• 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

Inherited rules

• at-rule-no-deprecated
• block-no-empty
• block-no-redundant-nested-style-rules
• color-function-alias-notation: without-alpha
• color-hex-length: short
• color-no-invalid-hex
• comment-empty-line-before: always, except: first-nested, ignore: stylelint-commands
• comment-whitespace-inside: always
• container-name-pattern: ^(--)?(a-za-z0-9*)(-a-z0-9+)*$,
• 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
• declaration-property-value-keyword-no-deprecated
• 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
• layer-name-pattern: ^(a-za-z0-9*)(.-a-z0-9+)*$,
• length-zero-no-unit: true, ignore: custom-properties, ignorePreludeOfAtRules: function, mixin
• lightness-notation: percentage
• media-feature-name-no-unknown
• media-type-no-deprecated
• named-grid-areas-no-invalid
• nesting-selector-no-missing-scoping-root: true, ignoreAtRules: mixin
• no-duplicate-at-import-rules
• no-empty-source
• no-invalid-double-slash-comments
• no-invalid-position-at-import-rule: true, ignoreAtRules: use, forward
• no-invalid-position-declaration
• no-irregular-whitespace
• number-max-precision: 4
• property-no-deprecated
• 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-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-single-line
• 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/load-no-partial-leading-underscore
• scss/load-partial-extension: never
• 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
• syntax-string-no-invalid
• unit-no-unknown
• value-keyword-case: lower

Contributing

See the contribution guidelines for guidance and setup instructions.