{Insert why depth consistency impacts merchant [wayfinding, etc]}
- -If you've found that merchants benefit from an additional layer of visual hierarchy not represented in the current depth tokens, we'd love to learn more.
- -Contribute a feature proposal issue or pull request in GitHub to share context and implement a proposed improvement or addition to Polaris. Start a GitHub discussion if community collaboration is needed to find a solution.
-keywords: - - stylelint - - dev tools - - developer tools - - tools - - tooling - - development - - plugin - - rules - - depth - - shadows - - linter - - linting - - css ---- - -## declaration-property-unit-disallowed-list - -Use the [Polaris depth tokens](https://polaris.shopify.com/tokens/depth) before custom shadows. - -```diff -// Do -+ box-shadow: var(--p-shadow-card); - -// Don't -- box-shadow: 0 1px 0 rgba(0, 0, 0, 0.05); -``` - -## function-disallowed-list - -Use [Polaris depth tokens](https://polaris.shopify.com/tokens/depth) instead of custom shadows. - -```diff -// Do -+ box-shadow: var(--p-shadow-base); - -// Don't -- filter: drop-shadow(0 2px 4px rgba(0, 0, 0, 0.1)); -``` - -## global-disallowed-list - -Use the [Polaris depth tokens](https://polaris.shopify.com/tokens/depth) instead of legacy mixins/variables. - -```diff -// Do -+ box-shadow: var(--p-shadow-card); - -// Don't -- box-shadow: var(--p-card-shadow); -``` - -## property-disallowed-list - -Instead of using properties like `text-shadow`, make sure the text has proper contrast with the background so that it is readable without a shadow. - -```diff -// Don't -- text-shadow: 2px 2px #ff0000; -``` diff --git a/polaris.shopify.com/content/tools/stylelint-polaris/index.md b/polaris.shopify.com/content/tools/stylelint-polaris/index.md index 3212e8c74d4..9baf88f4e8b 100644 --- a/polaris.shopify.com/content/tools/stylelint-polaris/index.md +++ b/polaris.shopify.com/content/tools/stylelint-polaris/index.md @@ -196,14 +196,460 @@ yarn run stylelint path/to/component.scss ## Rules -[Conventions](/tools/stylelint-polaris/conventions) | -[Colors](/tools/stylelint-polaris/colors) | -[Motion](/tools/stylelint-polaris/motion) | -[Typography](/tools/stylelint-polaris/typography) | -[Shape](/tools/stylelint-polaris/shape) | -[Spacing](/tools/stylelint-polaris/shape) | -[Depth](/tools/stylelint-polaris/depth) | -[Media queries](/tools/stylelint-polaris/media-queries) | -[Z-index](/tools/stylelint-polaris/z-index) | -[Layout](/tools/stylelint-polaris/layout) | -[Legacy](/tools/stylelint-polaris/conventions) +### Conventions + +#### conventions/custom-property-allowed-list + +Allows definition of custom properties not prefixed with `--p-`, `--pc-`, or `--polaris-version-`. + +```diff +root: { +// Don't +- --p-animation-name-drag-handle-pulse: osui_drag-handle-pulse; +// Do ++ --osui_animation-name-drag-handle-pulse: osui_drag-handle-pulse; +}; +``` + +Flags declaration property values using `--p-*` that are not valid Polaris tokens. + +```diff +// Don't +- font-size: var(--p-fontsize-200); +// Do ++ font-size: var(--p-font-size-200); +``` + +Flags declaration property values using private `--pc-*` tokens. + +The following token value is considered a problem: + +```diff +// Don't +- background: var(--pc-button-color-depressed); +// Do ++ background: var(--p-action-secondary-depressed); +``` + +### Colors + +#### colors/color-named + +```diff +// Don't +- color: black; +- fill: dimgray; +// Do ++ color: var(--p-text); ++ fill: var(--p-icon) +``` + +#### colors/color-no-hex + +```diff +// Don't +- color: #202223; +- fill: #5c5f62; +// Do ++ color: var(--p-text); ++ fill: var(--p-icon) +``` + +#### colors/declaration-property-value-disallowed-list + +```diff +// Don't +- background: black; +- opacity: 0.15; +// Do ++ background: var(--p-hint-from-direct-light); +``` + +#### colors/function-disallowed-list + +```diff +// Don't +- color: rgb(140, 145, 150); +- background: color('hover'); +// Do ++ color: var(--p-text-disabled); ++ background: var(--p-action-secondary-hovered-dark); +``` + +#### colors/at-rule-disallowed-list + +```diff +// Don't +- fill: recolor-icon(--p-text-subdued); +// Do ++ fill: var(--p-icon-subdued); +``` + +#### colors/global-disallowed-list + +Disallows use of legacy custom properties. + +```diff +// Don't +- border: var(--p-override-transparent); +// Do ++ border: transparent; +``` + +Disallows use of legacy mixin map data. + +```diff +- @type map $filter-palette-data: $polaris-color-filters; +``` + +### Motion + +#### motion/function-disallowed-list + +```diff + +``` + +#### motion/declaration-property-unit-disallowed-list + +```diff +// Don't +- transition-duration: 200ms; +// Do ++ transition-duration: var(--p-duration-200); +``` + +#### motion/at-rule-disallowed-list + +```diff + +``` + +#### motion/global-disallowed-list + +```diff + +``` + +### Typography + +#### typography/declaration-property-value-disallowed-list + +```diff + +``` + +#### typography/declaration-property-unit-disallowed-list + +```diff +// Don't +- font-size: 12px; +- line-height: 1.5rem +// Do ++ font-size: var(--p-font-size-75); ++ line-height: var(--p-font-line-height-3); +``` + +#### typography/function-disallowed-list + +```diff + +``` + +#### typography/at-rule-disallowed-list + +```diff + +``` + +#### typography/property-disallowed-list + +```diff + +``` + +### Shape + +#### shape/declaration-property-value-disallowed-list + +```diff + +``` + +#### shape/declaration-property-unit-disallowed-list + +```diff +// Don't +- border-width: 2px; +- border-radius: 0.5rem; +// Do ++ border-width: var(--p-border-width-2); ++ border-radius: var(--p-border-radius-2); +``` + +#### shape/function-disallowed-list + +```diff + +``` + +#### shape/at-rule-disallowed-list + +```diff + +``` + +#### shape/property-disallowed-list + +```diff + +``` + +### Spacing + +#### spacing/declaration-property-value-disallowed-list + +```diff + +``` + +#### spacing/declaration-property-unit-disallowed-list + +```diff +// Don't +- gap: 2px; +- margin: 12px 0; +// Do ++ gap: var(--p-space-05); ++ margin: var(--p-space-3) 0; +``` + +#### spacing/function-disallowed-list + +```diff + +``` + +#### spacing/at-rule-disallowed-list + +```diff + +``` + +#### spacing/property-disallowed-list + +```diff + +``` + +### Depth + +_{Insert why depth consistency impacts merchant [wayfinding, etc]}_ + +Have you found that merchants benefit from {an additional layer of visual hierarchy that's not in the depth tokens? We'd love to learn more. You can jumpstart a contribution to Polaris in GitHub by: + +- Starting a [discussion](https://github.com/Shopify/polaris/discussions/6750) to collaborate with the community to find a solution +- Submitting a [feature proposal issue](https://github.com/Shopify/polaris/issues/new?assignees=&labels=Feature+request&template=FEATURE_REQUEST.md) to share context on your suggestion +- Drafting a [pull request](https://github.com/Shopify/polaris/pulls) with your proposed improvement or addition + +#### depth/declaration-property-unit-disallowed-list + +Use the [Polaris depth tokens](https://polaris.shopify.com/tokens/z-index) instead of custom shadows. + +```diff +// Don't +- box-shadow: 0 1px 0 rgba(0, 0, 0, 0.05); +// Do ++ box-shadow: var(--p-shadow-card); +``` + +#### depth/function-disallowed-list + +Use the [Polaris depth tokens](https://polaris.shopify.com/tokens/z-index) instead of custom shadows. + +```diff +// Don't +- filter: drop-shadow(0 2px 4px rgba(0, 0, 0, 0.1)); +// Do ++ box-shadow: var(--p-shadow-base); +``` + +#### depth/global-disallowed-list + +Use the [Polaris depth tokens](https://polaris.shopify.com/tokens/z-index) instead of legacy mixins/variables. + +```diff +// Don't +- box-shadow: var(--p-card-shadow); +// Do ++ box-shadow: var(--p-shadow-card); +``` + +#### depth/property-disallowed-list + +Instead of using properties like `text-shadow`, make sure the text has proper contrast with the background so that it is readable without a shadow. + +```diff +// Don't +- text-shadow: 2px 2px #ff0000; +``` + +### Media queries + +#### media-queries/function-disallowed-list + +Use the [Polaris breakpoint sass variables](https://polaris.shopify.com/tokens/breakpoints#sass-variables) instead of legacy mixins/variables. + +```diff +// Don't +- @include breakpoint-after(layout-width(page-with-nav)) {} +// Do ++ @media (min-width: var(--p-breakpoints-md)) {} +``` + +#### media-queries/media-queries-allowed-list + +Try to use the [Polaris breakpoint sass variables](https://polaris.shopify.com/tokens/breakpoints#sass-variables) before creating your own custom styles. + +```diff +// Don't +- @include @media #{$my-var} {} +// Do ++ @include @media #{$p-breakpoints-sm-up} {} +``` + +#### media-queries/at-rule-disallowed-list + +Use the [Polaris breakpoint sass variables](https://polaris.shopify.com/tokens/breakpoints#sass-variables) instead of legacy mixins/variables. + +```diff +// Don't +- @include breakpoint-before(layout-width(page-with-nav)) {} +// Do ++ @media (max-width: var(--p-breakpoints-md)) {} +``` + +### Z-Index + +#### z-index/declaration-property-value-allowed-list + +Try to use the [Polaris z-index tokens](https://polaris.shopify.com/tokens/z-index) before creating your own custom styles. + +```diff +// Don't +- z-index: 1; +// Do ++ z-index: var(--p-z-1); +``` + +#### z-index/function-disallowed-list + +Use the [Polaris z-index tokens](https://polaris.shopify.com/tokens/z-index) instead of legacy mixins/variables. + +```diff +// Don't +- z-index: z-index(content); +// Do ++ z-index: var(--p-z-1); +``` + +#### z-index/global-disallowed-list + +Use the [Polaris z-index tokens](https://polaris.shopify.com/tokens/z-index) instead of legacy mixins/variables. + +```diff +// Don't +- z-index(toast, $fixed-element-stacking-order); +// Do ++ z-index: var(--p-z-1); +``` + +### Layout + +#### layout/declaration-property-value-disallowed-list + +There are many ways to use [Polaris components](https://polaris.shopify.com/components) to compose desired layouts. Please explore the layout components before writing custom styles. + +```diff +// Don't +- width: 100%; +// Do ++