contributing

31 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Contributions should address known issues or gaps and add value at scale

Contributions to Polaris should address a known issue or gap in the system, and they should add value at scale. Unique solutions may be best for a specific user, but they do not necessarily need to be in Polaris—custom solutions can still be built using Polaris tokens and best practices.

Minor contribution types: bug fixes, documentation, icons, and style changes

Minor contributions include bug fixes, documentation updates, icon additions or updates, and component style changes. These are often worthwhile because they are simple to implement and improve system quality and trust.

Major contribution types: patterns, new or redesigned components, and API changes

Major contributions include patterns, new or redesigned components, and API changes. Major contributions typically require more evaluation and greater involvement from the Polaris team. They usually introduce breaking changes to the system.

All contributions except Figma UI kits are made through GitHub

With the exception of Figma UI kits, all contributions to Polaris are made through GitHub. Figma UI kit contributions are made through a different process.

Icon and patch contributions can usually be started directly through GitHub pull request

Icon or patch contributions can usually be started directly through a GitHub pull request. If unsure, contributors can check with the Polaris team.

Major contributions should start with a proposal

Major contributions to Polaris should start with a proposal. Contributors should use the contribution proposal template in GitHub Discussions to start a contribution proposal and include any relevant explorations and documentation.

Questions to consider before proposing a major contribution

Before proposing a contribution, consider: Have I used the existing Polaris patterns, components, and tokens to their limit? Does my solution bring significant value to the admin and to other teams? Have I verified its effectiveness? What impact could my solution have on existing implementations? Do I have the resources (people, time, tools, etc.) to follow through?

How to get help with contributing to Polaris

For questions about how, what, or when to contribute, use GitHub Discussions to propose solutions, discuss new ideas, or ask questions. If working at Shopify, the #polaris Slack channel is also available for support.

Figma UI Kit updated for v12

The Polaris components, styles, and icons libraries in Figma have been updated to reflect the new design language, updated tokens, and component API changes. The kits have been updated to use Figma variables for color, space, and size, with color variables accessible via fill, stroke, and text color menus, and space variables accessible via auto layout's gap and padding.

Polaris for VS Code extension official tool

The Polaris for VS Code extension is an official VS Code extension for building with the Shopify Polaris design system. It can be installed from the marketplace at https://marketplace.visualstudio.com/items?itemName=Shopify.polaris-for-vscode.

Ways to contribute to Polaris

Merchants' needs that are not met by Polaris can be contributed back through three methods: starting a discussion on GitHub to collaborate with the community, submitting a feature proposal issue to share context on the suggestion, or drafting a pull request with the proposed improvement or addition.

How to ignore stylelint-polaris failures for intentional divergence

If styles are intentionally designed to diverge from Polaris and contribution back to the design system is not viable, failing rules can be ignored using the stylelint ignore syntax. A disable description must be provided to explain why custom styles are being used instead of Polaris. The syntax is: // stylelint-disable-next-line -- why custom styles are being used instead of Polaris

border-declaration-property-unit-disallowed-list stylelint rule

The border/declaration-property-unit-disallowed-list stylelint rule disallows hard-coded px, em, and rem units in border property values. Instead, use CSS custom properties like var(--p-border-width-050) and var(--p-border-radius-200).

Stylelint rule: color/color-no-hex disallows hex colors

The stylelint-polaris color/color-no-hex rule disallows the use of hex color values in code. Instead, developers must use CSS custom properties (variables) like var(--p-color-text) or var(--p-color-icon) to reference design tokens.

color/function-disallowed-list stylelint rule

The color/function-disallowed-list rule disallows use of built-in and legacy color functions. Developers should use CSS custom properties (variables) instead. The correct approach is to use var(--p-color-*) format for color values, such as var(--p-color-text-disabled) or var(--p-color-bg-fill-inverse-hover). Do not use rgb() functions or legacy color() functions like color('hover').

Stylelint Polaris contains over 40 rules

Stylelint Polaris is configured with over 40 rules to help developers avoid errors and follow stylistic and non-stylistic conventions while building for the Shopify admin.

Stylelint Polaris rules are grouped into categories

The rules configured in Stylelint Polaris are organized into categories that help measure the Polaris design system's coverage in the Shopify admin code base.

legacy/function-disallowed-list stylelint rule

The legacy/function-disallowed-list stylelint rule disallows use of legacy Sass functions. The function @include available-names is disallowed and should not be used.

layout/property-disallowed-list stylelint rule

The layout/property-disallowed-list stylelint rule disallows direct declarations of layout properties in CSS. Instead of writing display: grid directly, use the InlineGrid component.

media-queries/at-rule-disallowed-list stylelint rule

The media-queries/at-rule-disallowed-list rule disallows use of legacy breakpoint Sass mixins. Use standard CSS media queries with design tokens instead. Do use @media (max-width: var(--p-breakpoints-md)) {}. Do not use @include breakpoint-before(layout-width(page-with-nav)) {}.

media-queries-allowed-list incorrect syntax example

@include @media #{$my-var} {} is incorrect because it uses a custom variable instead of a Polaris breakpoint.

media-queries-allowed-list rule overview

The media-queries/media-queries-allowed-list stylelint rule allows declaration of print and screen @media queries, allows @media queries for forced-colors and ms-high-contrast features, and allows @media queries using Polaris breakpoints.

Use Polaris breakpoints in media queries

When writing @media queries, use Polaris breakpoints such as $p-breakpoints-sm-up. Do not use custom variables like $my-var for media queries.

media-queries-allowed-list correct syntax example

@include @media #{$p-breakpoints-sm-up} {} is the correct way to write a media query using a Polaris breakpoint.

shadow/function-disallowed-list stylelint rule

The shadow/function-disallowed-list stylelint rule disallows the use of built-in and legacy shadow functions in Polaris projects.

Shadow stylelint rule: shadow/property-disallowed-list

The stylelint rule shadow/property-disallowed-list disallows the text-shadow CSS property. This rule enforces that text readability must be achieved through proper contrast with the background rather than relying on shadows.

space/declaration-property-unit-disallowed-list stylelint rule

The space/declaration-property-unit-disallowed-list stylelint rule disallows use of hard-coded px, em, and rem values on gap, margin, and padding properties. Instead, design token variables like var(--p-space-050) should be used. Valid examples: gap: var(--p-space-050); and margin: var(--p-space-300) 0;. Invalid examples that violate the rule: gap: 2px; and margin: 12px 0;

z-index/global-disallowed-list stylelint rule

The z-index/global-disallowed-list stylelint rule disallows use of legacy z-index Sass APIs. Specifically, it prevents the use of @type map $elevation-data: $global-elements;

Polaris v12 upgrade package versions required

When upgrading to Polaris v12, the following package versions must be installed: @shopify/polaris version 12, @shopify/polaris-tokens version 8, @shopify/stylelint-polaris version 15, and @shopify/polaris-icons at least version 7.9.0.

Polaris v12 migration workflow overview

The recommended workflow for Polaris v11 to v12 migration is: 1) Run automated migrations using the @shopify/polaris-migrator CLI tool, 2) Manually migrate any issues marked with polaris-migrator: comments, 3) Search for and update any remaining migrations using provided RegExp searches. After each step, git stash changes, run prettier formatting, and commit changes.

CSS class removal: .Polaris-Summer-Editions-2023

The <html> element no longer receives the .Polaris-Summer-Editions-2023 class in v12. This class can be safely removed from CSS selectors.

Give your agent this brain