Stylelint Polaris
A configuration of Stylelint rules that promote adoption of the Polaris design system in consuming apps.
Installation
Exampleyarn add -D @shopify/stylelint-polaris stylelint
Note:
stylelint-polaris
requires a peer dependency ofstylelint@>=14.15.0
Usage
Extend @shopify/stylelint-polaris
in your Stylelint config. Example in package.json
Example{ "stylelint": { "extends": ["@shopify/stylelint-polaris"] } }
IMPORTANT:
@shopify/stylelint-polaris
must be added to the end of theextends
array
Run the linter
Examplenpx stylelint '**/*.{css,scss}'
Run the linter and autofix failures
Examplenpx 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:
Example+ // 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:
Examplenpx @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 |
*@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
Examplemodule.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.
Examplemodule.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:
Example- 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.
Examplemodule.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:
Example- 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
Exampleyarn install
- Build
@shopify/polaris
dependencies, but not@shopify/polaris
itself
Exampleyarn build -- --filter=@shopify/polaris^...
Note: Remove the
^
character if you do want to build@shopify/polaris
- Run
stylelint
inpolaris-react
All files
Exampleyarn turbo run lint:styles --filter=@shopify/polaris
Specific file
Exampleyarn run stylelint path/to/component.scss // yarn run stylelint polaris-react/src/components/TopBar/TopBar.scss