@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"]
}
}