Polaris v9

[alex-page]

Overview

• Done criteria for v9 is removing sass functions and replacing with tokens. These are breaking changes that set us up for our goal of 100% token coverage.
• Some sass functions have long tentacles and removal is tied with other work. Document those that won't be removed in v9 and instead get pushed out to v9.x or v10.
• Removal of some sass mixins that are breaking changes and small enough in scope to be an easy win.

Timeline

• Release Goal Date: Feb 8
• Release v9 to npm #5180

Prepare for RC

• Ensure there are no unnecessary @import '../../styles/common'; in components #5019
• Confirm legacy tokens are converted to rem
• Update v9 with main #5002
• Resolve Chromatic diffs against main #5003

Blockers

• Release Polaris v8 #4896 getting the fontsize/spacing value calculation simplified

Task Breakdown

Communication strategy

• Create a release communication strategy for v9 #4935
• Create a blog post about v9 #5174

Documentation page on polaris.shopify.com

• polaris.shopify.com includes a table of tokens with copy/pastable values #4936
• https://github.com/Shopify/polaris-styleguide/issues/4904

Migration guide

• Create migration guidance for CSS custom properties #5004
• Create migration guidance for Sass functions and mixins #5005
• Create migration guidance for Sass global variables #5006
• Document breaking changes from Simplify ThemeProvider #4706
• Create migration guidance for ThemeProvider #5007
• Create migration guidance for polaris-tokens package #4883
• Create Mega public scss API file #5111
• Create migration guidance for component breaking changes #5131

Cleanup

• Create a table of contents for the migration guide #5126
• Consolidate CSS Custom Properties into one table in the migration guide #5127
• Clarify table header language in migration guide #5128
• Consolidate megafile sections in the migration guide #5129
• Put filter() function table inside of a details dropdown in the migration guide #5130
• Turn any code blocks into tables if possible in migration guide #5140

/web

• Upgrade Web and Deps to Polaris v9 #5152

Deprecate public api

• Remove public scss api #4980

SCSS functions

Replace SCSS functions related to tokens with css custom properties. If a scss function can be replaced with a css custom property it should. Document any scss functions that cannot be removed right now in Follow Up Tasks below.

foundation/_accessibility.scss

• Replace @mixin high-contrast-outline with outline/border tokens #4913
• Replace @mixin high-contrast-border with border tokens #4914

foundation/_borders.scss

• Replace @function border with border tokens #4915

foundation/_colors.scss

• Replace @function ms-high-contrast-color with values #4916

foundation/_typography.scss

• Replace @function font-family with new token(s) #4918
• Consolidate font-size and line-height token files into typography #4919

foundation/_utilities.scss

• Investigate usage to see if we consolidate/remove @function available-names #4920
• Investigate usage to see if we consolidate/remove @function map-extend #4921
• Remove em() function #4937 Remove @function em

shared/_icons.scss

• Replace icon-size() with tokens #4923

shared/_interaction-state.scss

• Replace @mixin state() with value #4988

shared/_layout.scss

• Investigate usage to see if we consolidate/remove shared/_layout.scss #4926

shared/_links.scss

• Remove and replace @mixin unstyled-link() with hard coded #4927

shared/_lists.scss

• Remove and replace @mixin unstyled-list with hard coded #4928

shared/_printing.scss

• Replace @mixin when-printing with value #4985
• Replace @mixin when-not-printing with value #4986

shared/_private-breakpoints.scss

• Remove shared/_private-breakpoints.scss #4930

shared/_skeleton.scss

• Replace @mixin skeleton-page-secondary-actions-layout with value #4983
• Replace @mixin skeleton-page-header-layout with value #4984

shared/_printing.scss

• Investigate usage to see if we consolidate/remove shared/_printing.scss #4929

[BPScott]

@function em - keep until layout project

The web folks have a ticket to investigate using dart-sass as node-sass has been deprecated for a while. Using dart-sass with polaris-react's public API spits out lots of deprecation warnings. I pushed for the removal of the rem/em/px functions as the vast majority of those deprecation warnings are due to the usage of those functions. I've been telling folks "lets wait till polaris v9 as that'll remove most of the deprecation warnings and thus make the investigation easier".

Would it be possible to reconsider this stance, and either get em() removed in v9, or adjust it so it doesn't spit out a warning every time it is used (which is lots of times because it is used in the breakpoint() function which is used by the various breakpoint mixins which are used extensively in web)?

[aveline]

@BPScott removing em() isn't so straightforward and would really increase the scope of v9. But yes we can look at adjusting it so it doesn't spit out a warning every time it's used. Is it a matter of refactoring the existing em() function to use math.div()?

[BPScott]

Is it a matter of refactoring the existing em() function to use math.div()?

Per #4725 math.div is a problem because it is present in dart-sass but not in node-sass.

[aveline]

@BPScott what approach would you suggest for quieting the em() down until we are able to remove it?

[BPScott]

It's not really fixable in place unfortunately. We'd need to reduce usage of em(). Fortunately it seems that em() is only used for values you pass into breakpoint(). So if we refactor breakpoint() to avoid relying on em()'s general-purpose behaviour then we get closer

I had an idea for how that could be done in #4861 (comment)

Perhaps we could do something like claiming that breakpoint() now only accepts values/ adjustments in pixels (make it throw errors on other units) and that it shall internally convert that value into an em value by multiplying 0.0625 - the same as dividing it by 16, except you don't need to use the division sign that would trigger the deprecation warning (as 1em always equals 16px when used within a media query at the default zoom level).

[BPScott]

#4937 removes the em function

[BPScott]

As we'll be removing lots of the content within styles/_common.scss, it is likely that many component scss files no longer reference the mixins/functions that remain within that file. Once the trimming of the API is done, it might be worthwhile to go audit cases where component files do @import '../../styles/common';, and if no mixins/functions from that file are used then the import can be removed.