Stylelint Polaris
Installation
yarn add -D @shopify/stylelint-polaris stylelint
Note: stylelint-polaris requires a peer dependency of stylelint@>=14.15.0
Usage
Extend @shopify/stylelint-polaris in your Stylelint config. Example in package.json
{
"stylelint": {
"extends": ["@shopify/stylelint-polaris"]
}
}
IMPORTANT: @shopify/stylelint-polaris must be added to the end of the extends array
Run the linter
npx stylelint '**/*.{css,scss}'
Run the linter and autofix failures
npx stylelint --fix '**/*.{css,scss}'
Ignoring existing failures
Enabling the linter could result in a large amount of warnings and errors in existing codebases. It is important to fix as many failures upfront as possible, but that shouldn't block the linter from being added. The styles-insert-stylelint-disable migration inserts ignore comments so that enabling stylelint-polaris can be unblocked.
The migration will insert comments as follows:
+ // stylelint-disable-next-line -- generated by polaris-migrator DO NOT COPY
padding: 1rem;
Run the following command substituting <path> with a glob pattern of files to run against:
npx @shopify/polaris-migrator styles-insert-stylelint-disable <path>
Rules
There are over 40 rules configured in Stylelint Polaris to help you avoid errors and follow stylistic and non-stylistic conventions while building for the Shopify admin. These rules help us measure the Polaris design system's coverage in the Shopify admin code base using the following categories:
Version Matchups
@shopify/stylelint-polaris | @shopify/polaris |
---|---|
1.0.0 | 9.13.0 |
2.0.0 | 9.16.0 |
3.0.0 | 9.19.0 |
4.0.0 | 9.20.0 |
5.0.0 | 10.14.0 |
6.0.0 | 10.28.1 |
7.0.0 | 10.31.0 |
8.0.0 | 10.32.0 |
9.0.0 | 10.36.0 |
10.0.0 | 10.44.0 |
11.0.0 | 10.48.0 |
12.0.0 | 10.49.0 |
13.0.0 | 11.0.0 |
14.0.0 | 11.12.0 |
15.0.0 | 12.0.0 |
*@shopify/stylelint-polaris v5.0.0 was the first stable release
Development
Add new rules
- Navigate to the root stylelint-polaris config
- Locate the stylelint-polaris/coverage options
- Identify the appropriate category for the new rule
- Insert the rule using standard Stylelint rule configurations
- Add documentation for the rule with examples of code that will be reported as a problem and code that will fix the problem
- The title should be the category + the stylelint rule name, for example ### colors/color-named
module.exports = {
rules: {
'polaris/coverage': {
color: {...}, // Standard Stylelint rules config
layout: {...}, // Standard Stylelint rules config
motion: {
'new-rule': 'new-rule-options',
},
},
},
};
Build custom rules
- Refer to the Writing plugins guide of the Stylelint documentation
- Create your rule in the plugins directory
- Validate your plugin with tests (reference sibling plugins for examples)
- Refer to the Add new rules section to add your custom rule to the stylelint-polaris config
Add custom messages
Custom messages are surfaced in the command line, CI, and supported editors along side the default stylelint rule messages. They are added to the root level config and aim to provide more insight on how to resolve rule violations.
In a majority of cases, the default rule messages are clear and concise. However, they don't always guide developers to a desired outcome. Thus, there are two mechanisms we suggest for improving and providing custom rule messages:
Set a generic custom message on the message property of the secondary options of a given stylelint-polaris/coverage category. This message is appended to the default rule message and we expect will cover most cases.
module.exports = {
rules: {
'polaris/coverage': {
color: [
{
'color-named': 'never'
'color-no-hex': true,
},
{message: 'Please use a Polaris color token: https://polaris.shopify.com/tokens/color'},
],
},
},
}
Example failure message:
- Unexpected named color "red" (color-named)
+ Unexpected named color "red" (color-named) Please use a Polaris color token
Set a custom message on the message property in the Stylelint rule config's secondary options if supported. This message is appended to the default rule message instead of the generic category message when provided.
module.exports = {
rules: {
'polaris/coverage': {
layout: [
{
'property-disallowed-list': [
['position'],
{message: 'Please use the Polaris "Sticky" component'},
],
},
{message: 'Please use a Polaris layout component'},
],
},
},
};
Example failure message:
- Unexpected value "sticky" for property "position" (declaration-property-value-disallowed-list) Please use a Polaris layout component
+ Unexpected value "sticky" for property "position" (declaration-property-value-disallowed-list) Please use the Polaris "Sticky" component
Test stylelint-polaris updates in polaris-react
Open your terminal to the root of the polaris monorepo:
- Install and symlink dependencies
pnpm install
- Build @shopify/polaris dependencies, but not @shopify/polaris itself
pnpm build -- --filter=@shopify/polaris^...
Note: Remove the ^ character if you do want to build @shopify/polaris
- Run stylelint in polaris-react
All files
pnpm turbo run lint:styles --filter=@shopify/polaris
Specific file
pnpm run stylelint path/to/component.scss
// pnpm run stylelint polaris-react/src/components/TopBar/TopBar.scss