@salesforce-ux/sds-stylelint-config

About

The Salesforce Design System shareable config for stylelint.

Use it "as is" or as a foundation for your own config.

Installation

Pre-requisite

Install stylelint from npm:

npm install --save-dev stylelint

Use npm to install the SDS stylelint configuration:

npm install --save-dev @salesforce-ux/sds-stylelint-config

Usage

Create .stylelintrc.json configuration file in the root of your project:

{
  "extends": "@salesforce-ux/sds-stylelint-config"
}

Run stylelint, for example, all the CSS files in your project:

npx stylelint "**/*.css"

Plugins

sds-stylelint-plugin/styling-hooks-pattern

The linting rules will check for valid CSS custom property definition, as per SDS naming syntax

Usage

The plugin for sds-stylelint-plugin/styling-hooks-pattern is enabled by default. We validate namespace, scope, context, variant, element, category, property, attribute, state, and pseudoState. You can find the valid terms here.

module.exports = {
  extends: ['@salesforce-ux/sds-stylelint-config']
};

Options

If you need to add new terms to category, property, attribute, state, or pseudoState groups to be validated, you can add to the existing valid key.

module.exports = {
  extends: ['@salesforce-ux/sds-stylelint-config'],
  rules: {
    'sds-stylelint-plugin/styling-hooks-pattern': [true, { valid: { category: ['bacon'], state: ['eat'] } }],
  },
};

category

The category of the property that the hook affects.

array: ["array", "of", "categories"]

property

The semantic UI property being affected.

array: ["array", "of", "categories"]

attribute

The semantic characteristic of a property.

array: ["array", "of", "categories"]

state

The state of a property within context of interaction design.

array: ["array", "of", "categories"]

pseudoState

The pseudo class that matches a user interaction.

array: ["array", "of", "categories"]

sds-stylelint-plugin/namespace-pattern

Custom plugin for SDS to lint custom property declaration for namespace and scope syntax.

Usage

In your stylelint config, add the plugin sds-stylelint-plugin/namespace-pattern to your rules array. Lint rules check for the namespace provided, it can either be a string or an array of namespaces; additionally the plugin checks for a scope of -g-, -s-, or -c-. See SDS Styling Hooks for more information.

module.exports = {
  extends: ['@salesforce-ux/sds-stylelint-config'],
  rules: {
    'sds-stylelint-plugin/namespace-pattern': [true, { namespace: 'sds', property: true, value: true }],
  },
};

Options

namespace

Lints for the namespace(s) defined in your subsystem.

array|string: ["array", "of", "namespaces"]|"namespace"

property

Lints property declarations.

boolean: true|false

value

Lints value declarations within a var() function. Additionally this will lint all fallbacks declaraed.

boolean: true|false

sds-stylelint-plugin/component-pattern

Custom plugin for SDS to lint that the custom property declaration is authored in the correct component folder.

Usage

In your stylelint config, add the plugin sds-stylelint-plugin/component-pattern to your rules array. Lint rules check a custom property is owned by the component it is being authored within.

module.exports = {
  extends: ['@salesforce-ux/sds-stylelint-config'],
  rules: {
    'sds-stylelint-plugin/component-pattern': true,
  },
};

Ignoring rules

If you need to disable any of these rules for development purposes, please follow the guidance provided by stylelint. https://stylelint.io/user-guide/ignore-code.

Extending rules for your sub-system

Simply add a rules key to your config, then add your overrides and additions there.

For example, to change the indentation to tabs, turn off the number-leading-zero rule, change the property-no-unknown rule to use its ignoreAtRules option and add the unit-whitelist rule:

See all stylelint rules here

{
  "extends": "@salesforce-ux/sds-stylelint-config",
  "rules": {
    "indentation": "tab",
    "number-leading-zero": null,
    "property-no-unknown": [ true, {
      "ignoreProperties": [
        "composes"
      ]
    }],
    "unit-whitelist": ["em", "rem", "s"]
  }
}