Skip to content

Commit 8fc0fef

Browse files
sophschneiderchloerice
sophschneider
and
chloerice
authored
[Polaris Lighthouse] Add tooling section to doc website (#8027)
### WHY are these changes introduced? Fixes #7928 Adds tools section to polaris.shopify.com to house documentation for Polaris tooling. Migrated over docs for Stylelint Polaris and Polaris VSCode. |Theme|`/tools`|`/tools/stylelint-polaris`|`/tools/stylelint-polaris/rules`|`/tools/stylelint-polaris/rules/{category}-{rule-name}`| |---|---|---|---|---| |Dark|<img width="1512" alt="Screenshot 2023-01-17 at 11 59 49 AM" src="https://user-images.githubusercontent.com/18447883/212963342-9960e11d-1fdb-442c-898d-4afbee7c224b.png">|<img width="1512" alt="Screenshot 2023-01-17 at 1 17 32 PM" src="https://user-images.githubusercontent.com/18447883/212979357-a0c7c0be-43de-4a9d-9b0c-ee4104da13c2.png">|<img width="1512" alt="Screenshot 2023-01-17 at 11 57 25 AM" src="https://user-images.githubusercontent.com/18447883/212963394-5e485588-84c9-4cb0-95a4-292d09088d14.png">|<img width="1512" alt="Screenshot 2023-01-17 at 11 58 13 AM" src="https://user-images.githubusercontent.com/18447883/212963437-63dad6ad-e315-43a2-835f-7d7b33dcb6b3.png">| |Light|<img width="1512" alt="Screenshot 2023-01-17 at 1 23 00 PM" src="https://user-images.githubusercontent.com/18447883/212980511-b6493cb8-8602-4e25-a5cd-25ba10ec881d.png">|<img width="1512" alt="Screenshot 2023-01-17 at 1 23 07 PM" src="https://user-images.githubusercontent.com/18447883/212980538-6388c516-c45a-4106-b3ed-ba3949b0dc1e.png">|<img width="1512" alt="Screenshot 2023-01-17 at 1 23 12 PM" src="https://user-images.githubusercontent.com/18447883/212980589-f9559f4a-0c4f-4811-a20f-e124de543dcf.png">|<img width="1512" alt="Screenshot 2023-01-17 at 1 23 21 PM" src="https://user-images.githubusercontent.com/18447883/212980633-97c7556d-1d84-4d40-9588-3b142861e594.png">| Co-authored-by: Chloe Rice <chloe.rice@shopify.com>
1 parent c44c96c commit 8fc0fef

File tree

61 files changed

+1361
-211
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

61 files changed

+1361
-211
lines changed

‎.changeset/rich-toes-grin.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'polaris.shopify.com': minor
3+
---
4+
5+
Add tooling section to document tools help build and maintain Polaris in consuming applications.

‎polaris-for-vscode/README.md‎

Lines changed: 2 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,5 @@
11
# Polaris for VS Code
22

3-
Official VS Code extension for building with the Shopify [Polaris Design System](https://polaris.shopify.com/).
3+
Official VS Code extension for building with the Shopify Polaris Design System
44

5-
![Demo of Polaris for VS Code tokens autocomplete](https://github.com/Shopify/polaris/blob/main/polaris-for-vscode/docs/polaris-for-vscode-preview.gif?raw=true)
6-
7-
## Features
8-
9-
### Design Token Autocomplete
10-
11-
Get code autocomplete suggestions for the [Polaris Design Tokens](https://polaris.shopify.com/tokens/colors#navigation)
12-
13-
- 🗄️ Automatically works for CSS and Sass files
14-
- 🔍 Preview design token values in autocomplete description
15-
- 🎨 Color previews for all `color` tokens
16-
- 🥇 Relevant code completions based on the current line of code
17-
18-
## How to use
19-
20-
Once installed and enabled, the Polaris for VS Code extension will automatically run in any CSS and Sass files.
21-
22-
To trigger tokens autocomplete feature:
23-
24-
1. Open a CSS or Sass file from your project
25-
2. Start typing the CSS property you want to set ex. `color: `
26-
3. Type the extension trigger characters `--`. This will bring up the relevant autocomplete tokens associated with the CSS property typed.
5+
[Polaris for VS Code documentation](https://polaris.shopify.com/tools/polaris-for-vscode)

‎polaris.shopify.com/content/tools/index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: Tools
3+
description: Extensions, plugins, and other tools to help you use Polaris to build Admin experiences.
4+
icon: ToolsMajor
5+
order: 11
6+
---

‎polaris.shopify.com/content/tools/polaris-for-vscode.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: Polaris for VS Code
3+
description: Official VS Code extension for building with the Shopify Polaris Design System
4+
icon: HintMajor
5+
---
6+
7+
![Demo of Polaris for VS Code tokens autocomplete](https://github.com/Shopify/polaris/blob/main/polaris-for-vscode/docs/polaris-for-vscode-preview.gif?raw=true)
8+
9+
## Features
10+
11+
### Design Token Autocomplete
12+
13+
Get code autocomplete suggestions for the [Polaris Design Tokens](https://polaris.shopify.com/tokens/colors#navigation)
14+
15+
- 🗄️ Automatically works for CSS and Sass files
16+
- 🔍 Preview design token values in autocomplete description
17+
- 🎨 Color previews for all `color` tokens
18+
- 🥇 Relevant code completions based on the current line of code
19+
20+
## How to use
21+
22+
Install the [Polaris for VS Code extension](https://marketplace.visualstudio.com/items?itemName=Shopify.polaris-for-vscode). Once enabled, the extension will automatically run in any CSS and Sass files.
23+
24+
To trigger the token autocomplete feature:
25+
26+
1. Open a CSS or Sass file from your project
27+
2. Start typing the CSS property you want to set, for example: `color:`
28+
3. Type the extension trigger characters: `--`. This will bring up the relevant autocomplete tokens associated with the CSS property typed.

‎polaris.shopify.com/content/tools/stylelint-polaris/index.md‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
---
2+
title: Stylelint Polaris
3+
description: A configuration of Stylelint rules that promote adoption and track coverage of the Polaris design system in consuming apps.
4+
icon: WandMajor
5+
collapseChildren: true
6+
keywords:
7+
- stylelint
8+
- dev tools
9+
- developer tools
10+
- tools
11+
- tooling
12+
- development
13+
- plugin
14+
- rules
15+
- linter
16+
- linting
17+
- css
18+
---
19+
20+
## Installation
21+
22+
```sh
23+
yarn add -D @shopify/stylelint-polaris stylelint
24+
```
25+
26+
> Note: `stylelint-polaris` requires a peer dependency of `stylelint@>=14.15.0`
27+
28+
[Source code](https://github.com/Shopify/polaris/tree/main/stylelint-polaris)
29+
30+
## Usage
31+
32+
Extend `@shopify/stylelint-polaris` in your [Stylelint config](https://stylelint.io/user-guide/configure/). Example in `package.json`
33+
34+
```json
35+
{
36+
"stylelint": {
37+
"extends": ["@shopify/stylelint-polaris"]
38+
}
39+
}
40+
```
41+
42+
> IMPORTANT: `@shopify/stylelint-polaris` must be added to the end of the `extends` array
43+
44+
### Run the linter
45+
46+
```sh
47+
npx stylelint '**/*.{css,scss}'
48+
```
49+
50+
### Run the linter and autofix failures
51+
52+
```sh
53+
npx stylelint --fix '**/*.{css,scss}'
54+
```
55+
56+
### Ignoring existing failures
57+
58+
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](https://github.com/Shopify/polaris/tree/main/polaris-migrator#v10) migration inserts [ignore comments](https://stylelint.io/user-guide/ignore-code/) so that enabling `stylelint-polaris` can be unblocked.
59+
60+
The migration will insert comments as follows:
61+
62+
```diff
63+
+ // stylelint-disable-next-line -- generated by polaris-migrator DO NOT COPY
64+
padding: 1rem;
65+
```
66+
67+
Run the following command substituting `<path>` with a glob pattern of files to run against:
68+
69+
```sh
70+
npx @shopify/polaris-migrator styles-insert-stylelint-disable <path>
71+
```
72+
73+
## Rules
74+
75+
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.
76+
77+
- [Colors](/tools/stylelint-polaris/rules#colors)
78+
- [Conventions](/tools/stylelint-polaris/rules#conventions)
79+
- [Depth](/tools/stylelint-polaris/rules#depth)
80+
- [Layout](/tools/stylelint-polaris/rules#layout)
81+
- [Legacy](/tools/stylelint-polaris/rules#legacy)
82+
- [Media queries](/tools/stylelint-polaris/rules#media-queries)
83+
- [Motion](/tools/stylelint-polaris/rules#motion)
84+
- [Shape](/tools/stylelint-polaris/rules#shape)
85+
- [Spacing](/tools/stylelint-polaris/rules#spacing)
86+
- [Typography](/tools/stylelint-polaris/rules#typography)
87+
- [Z-index](/tools/stylelint-polaris/rules#z-index)
88+
89+
## Development
90+
91+
### Add new rules
92+
93+
1. Navigate to the root [`stylelint-polaris` config](https://github.com/Shopify/polaris/blob/main/stylelint-polaris/index.js)
94+
1. Locate the `stylelint-polaris/coverage` options
95+
1. Identify the appropriate category for the new rule
96+
1. Insert the rule using standard Stylelint [rule configurations](https://stylelint.io/user-guide/configure#rules)
97+
1. Add documentation for the rule with examples of code that will be reported as a problem and code that will fix the problem
98+
1. The title should be the category + the stylelint rule name, for example `### colors/color-named`
99+
100+
```js
101+
module.exports = {
102+
rules: {
103+
'polaris/coverage': {
104+
colors: {...}, // Standard Stylelint rules config
105+
layout: {...}, // Standard Stylelint rules config
106+
motion: {
107+
'new-rule': 'new-rule-options',
108+
},
109+
},
110+
},
111+
};
112+
```
113+
114+
### Build custom rules
115+
116+
1. Refer to the [Writing plugins](https://stylelint.io/developer-guide/plugins) guide of the Stylelint documentation
117+
1. Create your rule in the [plugins](plugins) directory
118+
1. Validate your plugin with [tests](https://github.com/stylelint/jest-preset-stylelint#usage) (reference sibling plugins for examples)
119+
1. Refer to the [Add new rules](#add-new-rules) section to add your custom rule to the `stylelint-polaris` config
120+
121+
### Add custom messages
122+
123+
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.
124+
125+
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:
126+
127+
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.
128+
129+
```js
130+
module.exports = {
131+
rules: {
132+
'polaris/coverage': {
133+
colors: [
134+
{
135+
'color-named': 'never'
136+
'color-no-hex': true,
137+
},
138+
{message: 'Please use a Polaris color token: https://polaris.shopify.com/tokens/colors'},
139+
],
140+
},
141+
},
142+
}
143+
```
144+
145+
Example failure message:
146+
147+
```diff
148+
- Unexpected named color "red" (color-named)
149+
+ Unexpected named color "red" (color-named) Please use a Polaris color token
150+
```
151+
152+
Set a custom message on the `message` property in the [Stylelint rule config's secondary options](https://stylelint.io/user-guide/configure/#message) if supported. This message is appended to the default rule message instead of the generic category message when provided.
153+
154+
```js
155+
module.exports = {
156+
rules: {
157+
'polaris/coverage': {
158+
layout: [
159+
{
160+
'property-disallowed-list': [
161+
['position'],
162+
{message: 'Please use the Polaris "Sticky" component'},
163+
],
164+
},
165+
{message: 'Please use a Polaris layout component'},
166+
],
167+
},
168+
},
169+
};
170+
```
171+
172+
Example failure message:
173+
174+
```diff
175+
- Unexpected value "sticky" for property "position" (declaration-property-value-disallowed-list) Please use a Polaris layout component
176+
+ Unexpected value "sticky" for property "position" (declaration-property-value-disallowed-list) Please use the Polaris "Sticky" component
177+
```
178+
179+
### Tophat `stylelint-polaris` updates in `polaris-react`
180+
181+
> Open your terminal to the root of the `polaris` monorepo:
182+
183+
1. Install and symlink dependencies
184+
185+
```sh
186+
yarn install
187+
```
188+
189+
2. Build `@shopify/polaris` dependencies, but not `@shopify/polaris` itself
190+
191+
```sh
192+
yarn build -- --filter=@shopify/polaris^...
193+
```
194+
195+
> Note: Remove the `^` character if you do want to build `@shopify/polaris`
196+
197+
3. Run `stylelint` in `polaris-react`
198+
199+
All files
200+
201+
```sh
202+
yarn turbo run lint:styles --filter=@shopify/polaris
203+
```
204+
205+
Specific file
206+
207+
```sh
208+
yarn run stylelint path/to/component.scss
209+
210+
// yarn run stylelint polaris-react/src/components/TopBar/TopBar.scss
211+
```

‎polaris.shopify.com/content/tools/stylelint-polaris/rules/colors-at-rule-disallowed-list.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
title: colors/at-rule-disallowed-list
3+
description: Disallows use of legacy color mixins
4+
keywords:
5+
- stylelint
6+
- colors
7+
- colors rules
8+
---
9+
10+
```diff
11+
// Do
12+
+ fill: var(--p-icon-subdued);
13+
// Don't
14+
- fill: recolor-icon(--p-text-subdued);
15+
```

‎polaris.shopify.com/content/tools/stylelint-polaris/rules/colors-color-named.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: colors/color-named
3+
description: Disallows named colors
4+
keywords:
5+
- stylelint
6+
- colors
7+
- colors rules
8+
---
9+
10+
```diff
11+
// Do
12+
+ color: var(--p-text);
13+
+ fill: var(--p-icon)
14+
// Don't
15+
- color: black;
16+
- fill: dimgray;
17+
```

‎polaris.shopify.com/content/tools/stylelint-polaris/rules/colors-color-no-hex.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: colors/color-no-hex
3+
description: Disallows hex colors
4+
keywords:
5+
- stylelint
6+
- colors
7+
- colors rules
8+
---
9+
10+
```diff
11+
// Do
12+
+ color: var(--p-text);
13+
+ fill: var(--p-icon)
14+
// Don't
15+
- color: #202223;
16+
- fill: #5c5f62;
17+
```

‎polaris.shopify.com/content/tools/stylelint-polaris/rules/colors-declaration-property-value-disallowed-list.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
title: colors/declaration-property-value-disallowed-list
3+
description: Disallows custom decimal opacity values
4+
keywords:
5+
- stylelint
6+
- colors
7+
- colors rules
8+
---
9+
10+
```diff
11+
// Do
12+
+ background: var(--p-hint-from-direct-light);
13+
// Don't
14+
- background: black;
15+
- opacity: 0.15;
16+
```

‎polaris.shopify.com/content/tools/stylelint-polaris/rules/colors-function-disallowed-list.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: colors/function-disallowed-list
3+
description: Disallows allows use of built in and legacy color functions
4+
keywords:
5+
- stylelint
6+
- colors
7+
- colors rules
8+
---
9+
10+
```diff
11+
// Do
12+
+ color: var(--p-text-disabled);
13+
+ background: var(--p-action-secondary-hovered-dark);
14+
// Don't
15+
- color: rgb(140, 145, 150);
16+
- background: color('hover');
17+
```

0 commit comments

Comments
 (0)