Run `color` migration in polaris #10528

lgriffee · 2023-09-18T17:51:17Z

Migration

To replace these deprecated color custom properties, you can run the snapshot of the v12-styles-replace-custom-property-color migration. Please reference the recommended token migration workflow section below for additional migration support.

cd polaris-react

npx @shopify/polaris-migrator@0.0.0-snapshot-release-20230919050618 \
  v12-styles-replace-custom-property-color \
  'src/**/*.scss'

Note

If you get an error saying the migration doesn’t exist with a snapshot or you don’t see up to date migration changes, then delete node-modules folder in polaris at the top level. After the migration if you need to run yarn commands remember to yarn at polaris level.

Recommended token migration workflow

When running token migrations we suggest the following workflow:

Handle automated migrations

# Example migration
npx @shopify/polaris-migrator ...
# Stage all migrated files
git add .
# Format staged files only
git diff --staged --name-only | xargs npx prettier --write
# Commit automated migrations
git commit -m "Migrate color custom properties from Polaris v11 to v12"

Handle manual migrations

Search for token RegExps and handle manual migrations (see Post-migration section below)

# Stage all manually migrated files
git add .
# Format staged files only
git diff --staged --name-only | xargs npx prettier --write
# Commit manual migrations
git commit -m "Manually migrate color custom properties from Polaris v11 to v12"

Check for errors after all custom property migrations are finished

# Change to polaris root directory 
cd ..
# Install dependencies
yarn 
# Run stylelint against polaris-react
npx stylelint 'polaris-react/src/**/*.scss'

Post-migration validation

After migrating use the following RegExp to check for any additional instances of color custom properties across all file types:

Important

Since the following values cannot be safely migrated while maintaining existing feature flag functionality we need different custom property regexp for pre-v12 versus during the v12 release.

Deprecated CSS Custom Property	Replacement token
`--p-color-bg-hover`	`--p-color-bg-surface-hover`
`--p-color-bg-active`	`--p-color-bg-surface-active`
`--p-color-bg-disabled`	`--p-color-bg-surface-disabled`
`--p-color-bg-primary`	`--p-color-bg-fill-brand`
`--p-color-bg-primary-hover`	`--p-color-bg-fill-brand-hover`
`--p-color-bg-primary-active`	`--p-color-bg-fill-brand-active`
`--p-color-bg-primary-subdued`	`--p-color-bg-surface-brand`
`--p-color-bg-primary-subdued-hover`	`--p-color-bg-surface-brand-hover`
`--p-color-bg-primary-subdued-active`	`--p-color-bg-surface-brand-active`
`--p-color-bg-primary-subdued-selected`	`--p-color-bg-surface-brand-selected`
`--p-color-bg-magic-subdued`	`--p-color-bg-surface-magic`
`--p-color-text-critical-hover-experimental`	`--p-color-text-critical-hover`
`--p-color-text-warning-experimental`	`--p-color-text-warning`
`--p-color-text-interactive-inverse`	`--p-color-text-link-inverse`
`--p-color-border-strong`	`--p-color-border-tertiary`
`--p-color-border-interactive`	`--p-color-border-emphasis`

[PRE-V12] Check RegExp for hardcoded color custom properties across all file types

(?:--p-color-avatar-background-experimental|--p-color-avatar-color-experimental|--p-color-avatar-style-five-background-experimental|--p-color-avatar-style-five-color-experimental|--p-color-avatar-style-four-background-experimental|--p-color-avatar-style-four-color-experimental|--p-color-avatar-style-one-background-experimental|--p-color-avatar-style-one-color-experimental|--p-color-avatar-style-three-background-experimental|--p-color-avatar-style-three-color-experimental|--p-color-avatar-style-two-background-experimental|--p-color-avatar-style-two-color-experimental|--p-color-bg|--p-color-bg-app-selected|--p-color-bg-backdrop-experimental|--p-color-bg-caution|--p-color-bg-caution-strong|--p-color-bg-caution-subdued|--p-color-bg-caution-subdued-active|--p-color-bg-caution-subdued-hover|--p-color-bg-critical|--p-color-bg-critical-strong|--p-color-bg-critical-strong-active|--p-color-bg-critical-strong-hover|--p-color-bg-critical-subdued|--p-color-bg-critical-subdued-active|--p-color-bg-critical-subdued-hover|--p-color-bg-info|--p-color-bg-info-strong|--p-color-bg-info-subdued|--p-color-bg-info-subdued-active|--p-color-bg-info-subdued-hover|--p-color-bg-input|--p-color-bg-input-active-experimental|--p-color-bg-input-hover-experimental|--p-color-bg-inset|--p-color-bg-inset-strong|--p-color-bg-inverse-active|--p-color-bg-inverse-hover|--p-color-bg-magic|--p-color-bg-magic-active|--p-color-bg-magic-hover|--p-color-bg-magic-strong|--p-color-bg-magic-subdued-hover|--p-color-bg-secondary-experimental|--p-color-bg-strong|--p-color-bg-strong-active|--p-color-bg-strong-hover|--p-color-bg-subdued|--p-color-bg-subdued-active|--p-color-bg-subdued-hover|--p-color-bg-success|--p-color-bg-success-strong|--p-color-bg-success-strong-active-experimental|--p-color-bg-success-strong-hover-experimental|--p-color-bg-success-subdued|--p-color-bg-success-subdued-active|--p-color-bg-success-subdued-hover|--p-color-bg-transparent-active-experimental|--p-color-bg-transparent-disabled-experimental|--p-color-bg-transparent-experimental|--p-color-bg-transparent-hover-experimental|--p-color-bg-transparent-primary-disabled-experimental|--p-color-bg-transparent-subdued-experimental|--p-color-bg-warning|--p-color-bg-warning-strong-experimental|--p-color-bg-warning-subdued-experimental|--p-color-border-critical-strong-experimental|--p-color-border-input|--p-color-border-input-active-experimental|--p-color-border-input-hover|--p-color-border-interactive-active|--p-color-border-interactive-focus|--p-color-border-interactive-hover|--p-color-border-magic-strong|--p-color-border-primary|--p-color-border-subdued|--p-color-icon-interactive|--p-color-icon-interactive-active|--p-color-icon-interactive-hover|--p-color-icon-primary|--p-color-icon-subdued|--p-color-text-info-strong|--p-color-text-interactive|--p-color-text-interactive-active|--p-color-text-interactive-hover|--p-color-text-inverse-subdued|--p-color-text-primary|--p-color-text-primary-hover|--p-color-text-subdued)(?![\w-])

[V12] Check RegExp for hardcoded color custom properties across all file types

(?:--p-color-avatar-background-experimental|--p-color-avatar-color-experimental|--p-color-avatar-style-five-background-experimental|--p-color-avatar-style-five-color-experimental|--p-color-avatar-style-four-background-experimental|--p-color-avatar-style-four-color-experimental|--p-color-avatar-style-one-background-experimental|--p-color-avatar-style-one-color-experimental|--p-color-avatar-style-three-background-experimental|--p-color-avatar-style-three-color-experimental|--p-color-avatar-style-two-background-experimental|--p-color-avatar-style-two-color-experimental|--p-color-bg|--p-color-bg-active|--p-color-bg-app-selected|--p-color-bg-backdrop-experimental|--p-color-bg-caution|--p-color-bg-caution-strong|--p-color-bg-caution-subdued|--p-color-bg-caution-subdued-active|--p-color-bg-caution-subdued-hover|--p-color-bg-critical|--p-color-bg-critical-strong|--p-color-bg-critical-strong-active|--p-color-bg-critical-strong-hover|--p-color-bg-critical-subdued|--p-color-bg-critical-subdued-active|--p-color-bg-critical-subdued-hover|--p-color-bg-disabled|--p-color-bg-hover|--p-color-bg-info|--p-color-bg-info-strong|--p-color-bg-info-subdued|--p-color-bg-info-subdued-active|--p-color-bg-info-subdued-hover|--p-color-bg-input|--p-color-bg-input-active-experimental|--p-color-bg-input-hover-experimental|--p-color-bg-inset|--p-color-bg-inset-strong|--p-color-bg-inverse-active|--p-color-bg-inverse-hover|--p-color-bg-magic|--p-color-bg-magic-active|--p-color-bg-magic-hover|--p-color-bg-magic-strong|--p-color-bg-magic-subdued|--p-color-bg-magic-subdued-hover|--p-color-bg-primary|--p-color-bg-primary-active|--p-color-bg-primary-hover|--p-color-bg-primary-subdued|--p-color-bg-primary-subdued-active|--p-color-bg-primary-subdued-hover|--p-color-bg-primary-subdued-selected|--p-color-bg-secondary-experimental|--p-color-bg-strong|--p-color-bg-strong-active|--p-color-bg-strong-hover|--p-color-bg-subdued|--p-color-bg-subdued-active|--p-color-bg-subdued-hover|--p-color-bg-success|--p-color-bg-success-strong|--p-color-bg-success-strong-active-experimental|--p-color-bg-success-strong-hover-experimental|--p-color-bg-success-subdued|--p-color-bg-success-subdued-active|--p-color-bg-success-subdued-hover|--p-color-bg-transparent-active-experimental|--p-color-bg-transparent-disabled-experimental|--p-color-bg-transparent-experimental|--p-color-bg-transparent-hover-experimental|--p-color-bg-transparent-primary-disabled-experimental|--p-color-bg-transparent-subdued-experimental|--p-color-bg-warning|--p-color-bg-warning-strong-experimental|--p-color-bg-warning-subdued-experimental|--p-color-border-critical-strong-experimental|--p-color-border-input|--p-color-border-input-active-experimental|--p-color-border-input-hover|--p-color-border-interactive|--p-color-border-interactive-active|--p-color-border-interactive-focus|--p-color-border-interactive-hover|--p-color-border-magic-strong|--p-color-border-primary|--p-color-border-strong|--p-color-border-subdued|--p-color-icon-interactive|--p-color-icon-interactive-active|--p-color-icon-interactive-hover|--p-color-icon-primary|--p-color-icon-subdued|--p-color-text-critical-hover-experimental|--p-color-text-info-strong|--p-color-text-interactive|--p-color-text-interactive-active|--p-color-text-interactive-hover|--p-color-text-interactive-inverse|--p-color-text-inverse-subdued|--p-color-text-primary|--p-color-text-primary-hover|--p-color-text-subdued|--p-color-text-warning-experimental)(?![\w-])

Check RegExp for outdated <Box background="..." /> props

<Box[^>\w](?:[^>]|\n)*?background

Check RegExp for outdated <Card background="..." /> props

<Card[^>\w](?:[^>]|\n)*?background

Check RegExp for outdated <Box borderColor="..." /> props

<Box[^>\w](?:[^>]|\n)*?borderColor

Check RegExp for outdated <Box outlineColor="..." /> props

<Box[^>\w](?:[^>]|\n)*?outlineColor

Check RegExp for outdated <Divider borderColor="..." /> props

<Divider[^>\w](?:[^>]|\n)*?borderColor

Check RegExp for outdated <Banner textColor="..." /> props

<Banner[^>\w](?:[^>]|\n)*?textColor

Check RegExp for outdated <Box color="..." /> props

<Box[^>\w](?:[^>]|\n)*?color

Replacement maps

Deprecated CSS Custom Property	Replacement token
`--p-color-bg`	`--p-color-bg-surface`
~~`--p-color-bg-hover`~~	~~`--p-color-bg-surface-hover`~~
~~`--p-color-bg-active`~~	~~`--p-color-bg-surface-active`~~
~~`--p-color-bg-disabled`~~	~~`--p-color-bg-surface-disabled`~~
`--p-color-bg-subdued`	`--p-color-bg-surface-secondary`
`--p-color-bg-subdued-hover`	`--p-color-bg-surface-secondary-hover`
`--p-color-bg-subdued-active`	`--p-color-bg-surface-secondary-active`
`--p-color-bg-secondary-experimental`	`--p-color-bg-surface-tertiary`
`--p-color-bg-strong`	`--p-color-bg-fill-tertiary`
`--p-color-bg-strong-hover`	`--p-color-bg-fill-tertiary-hover`
`--p-color-bg-strong-active`	`--p-color-bg-fill-tertiary-active`
`--p-color-bg-input`	`--p-color-input-bg-surface`
`--p-color-bg-input-hover-experimental`	`--p-color-input-bg-surface-hover`
`--p-color-bg-input-active-experimental`	`--p-color-input-bg-surface-active`
~~`--p-color-bg-primary`~~	~~`--p-color-bg-fill-brand`~~
~~`--p-color-bg-primary-hover`~~	~~`--p-color-bg-fill-brand-hover`~~
~~`--p-color-bg-primary-active`~~	~~`--p-color-bg-fill-brand-active`~~
~~`--p-color-bg-primary-subdued`~~	~~`--p-color-bg-surface-brand`~~
~~`--p-color-bg-primary-subdued-hover`~~	~~`--p-color-bg-surface-brand-hover`~~
~~`--p-color-bg-primary-subdued-active`~~	~~`--p-color-bg-surface-brand-active`~~
~~`--p-color-bg-primary-subdued-selected`~~	~~`--p-color-bg-surface-brand-selected`~~
`--p-color-bg-app-selected`	`--p-color-bg-surface-selected`
`--p-color-bg-success-strong`	`--p-color-bg-fill-success`
`--p-color-bg-success-strong-hover-experimental`	`--p-color-bg-fill-success-hover`
`--p-color-bg-success-strong-active-experimental`	`--p-color-bg-fill-success-active`
`--p-color-bg-success`	`--p-color-bg-fill-success-secondary`
`--p-color-bg-success-subdued`	`--p-color-bg-surface-success`
`--p-color-bg-success-subdued-hover`	`--p-color-bg-surface-success-hover`
`--p-color-bg-success-subdued-active`	`--p-color-bg-surface-success-active`
`--p-color-bg-critical-strong`	`--p-color-bg-fill-critical`
`--p-color-bg-critical-strong-hover`	`--p-color-bg-fill-critical-hover`
`--p-color-bg-critical-strong-active`	`--p-color-bg-fill-critical-active`
`--p-color-bg-critical`	`--p-color-bg-fill-critical-secondary`
`--p-color-bg-critical-subdued`	`--p-color-bg-surface-critical`
`--p-color-bg-critical-subdued-hover`	`--p-color-bg-surface-critical-hover`
`--p-color-bg-critical-subdued-active`	`--p-color-bg-surface-critical-active`
`--p-color-bg-caution-strong`	`--p-color-bg-fill-caution`
`--p-color-bg-caution`	`--p-color-bg-fill-caution-secondary`
`--p-color-bg-caution-subdued`	`--p-color-bg-surface-caution`
`--p-color-bg-caution-subdued-hover`	`--p-color-bg-surface-caution-hover`
`--p-color-bg-caution-subdued-active`	`--p-color-bg-surface-caution-active`
`--p-color-bg-info-strong`	`--p-color-bg-fill-info`
`--p-color-bg-info`	`--p-color-bg-fill-info-secondary`
`--p-color-bg-info-subdued`	`--p-color-bg-surface-info`
`--p-color-bg-info-subdued-hover`	`--p-color-bg-surface-info-hover`
`--p-color-bg-info-subdued-active`	`--p-color-bg-surface-info-active`
`--p-color-bg-warning-strong-experimental`	`--p-color-bg-fill-warning`
`--p-color-bg-warning`	`--p-color-bg-fill-warning-secondary`
`--p-color-bg-warning-subdued-experimental`	`--p-color-bg-surface-warning`
`--p-color-bg-magic-strong`	`--p-color-bg-fill-magic`
`--p-color-bg-magic`	`--p-color-bg-fill-magic-secondary`
`--p-color-bg-magic-hover`	`--p-color-bg-fill-magic-secondary-hover`
`--p-color-bg-magic-active`	`--p-color-bg-fill-magic-secondary-active`
~~`--p-color-bg-magic-subdued`~~	~~`--p-color-bg-surface-magic`~~
`--p-color-bg-magic-subdued-hover`	`--p-color-bg-surface-magic-hover`
`--p-color-bg-inset`	`--p-color-bg-fill-secondary`
`--p-color-bg-inset-strong`	`--p-color-bg-fill-inverse`
`--p-color-bg-inverse-hover`	`--p-color-bg-fill-inverse-hover`
`--p-color-bg-inverse-active`	`--p-color-bg-fill-inverse-active`
`--p-color-bg-transparent-experimental`	`--p-color-bg-surface-transparent`
`--p-color-bg-transparent-hover-experimental`	`--p-color-bg-fill-transparent-hover`
`--p-color-bg-transparent-active-experimental`	`--p-color-bg-fill-transparent-active`
`--p-color-bg-transparent-disabled-experimental`	`--p-color-bg-fill-disabled`
`--p-color-bg-transparent-subdued-experimental`	`--p-color-bg-fill-transparent-secondary`
`--p-color-bg-transparent-primary-disabled-experimental`	`--p-color-bg-fill-brand-disabled`
`--p-color-bg-backdrop-experimental`	`--p-color-backdrop-bg`
`--p-color-avatar-background-experimental`	`--p-color-avatar-bg-fill`
`--p-color-avatar-style-one-background-experimental`	`--p-color-avatar-one-bg-fill`
`--p-color-avatar-style-two-background-experimental`	`--p-color-avatar-two-bg-fill`
`--p-color-avatar-style-three-background-experimental`	`--p-color-avatar-three-bg-fill`
`--p-color-avatar-style-four-background-experimental`	`--p-color-avatar-four-bg-fill`
`--p-color-avatar-style-five-background-experimental`	`--p-color-avatar-five-bg-fill`
`--p-color-text-subdued`	`--p-color-text-secondary`
`--p-color-text-interactive`	`--p-color-text-emphasis`
`--p-color-text-interactive-hover`	`--p-color-text-emphasis-hover`
`--p-color-text-interactive-active`	`--p-color-text-emphasis-active`
`--p-color-text-primary`	`--p-color-text-brand`
`--p-color-text-primary-hover`	`--p-color-text-brand-hover`
~~`--p-color-text-critical-hover-experimental`~~	~~`--p-color-text-critical-hover`~~
`--p-color-text-info-strong`	`--p-color-text-info-on-bg-fill`
~~`--p-color-text-warning-experimental`~~	~~`--p-color-text-warning`~~
`--p-color-text-inverse-subdued`	`--p-color-text-inverse-secondary`
~~`--p-color-text-interactive-inverse`~~	~~`--p-color-text-link-inverse`~~
`--p-color-avatar-color-experimental`	`--p-color-avatar-text-on-bg-fill`
`--p-color-avatar-style-one-color-experimental`	`--p-color-avatar-one-text-on-bg-fill`
`--p-color-avatar-style-two-color-experimental`	`--p-color-avatar-two-text-on-bg-fill`
`--p-color-avatar-style-three-color-experimental`	`--p-color-avatar-three-text-on-bg-fill`
`--p-color-avatar-style-four-color-experimental`	`--p-color-avatar-four-text-on-bg-fill`
`--p-color-avatar-style-five-color-experimental`	`--p-color-avatar-five-text-on-bg-fill`
`--p-color-icon-subdued`	`--p-color-icon-secondary`
`--p-color-icon-interactive`	`--p-color-icon-emphasis`
`--p-color-icon-interactive-hover`	`--p-color-icon-emphasis-hover`
`--p-color-icon-interactive-active`	`--p-color-icon-emphasis-active`
`--p-color-icon-primary`	`--p-color-icon-brand`
`--p-color-border-subdued`	`--p-color-border-secondary`
~~`--p-color-border-strong`~~	~~`--p-color-border-tertiary`~~
`--p-color-border-input`	`--p-color-input-border`
`--p-color-border-input-hover`	`--p-color-input-border-hover`
`--p-color-border-input-active-experimental`	`--p-color-input-border-active`
~~`--p-color-border-interactive`~~	~~`--p-color-border-emphasis`~~
`--p-color-border-interactive-hover`	`--p-color-border-emphasis-hover`
`--p-color-border-interactive-active`	`--p-color-border-emphasis-active`
`--p-color-border-interactive-focus`	`--p-color-border-focus`
`--p-color-border-primary`	`--p-color-border-brand`
`--p-color-border-critical-strong-experimental`	`--p-color-border-critical-secondary`
`--p-color-border-magic-strong`	`--p-color-border-magic-secondary`

Important

The following values will not be migrated until v12 since they cannot be safely migrated while maintaining existing feature flag functionality.

Deprecated CSS Custom Property	Replacement token
`--p-color-bg-hover`	`--p-color-bg-surface-hover`
`--p-color-bg-active`	`--p-color-bg-surface-active`
`--p-color-bg-disabled`	`--p-color-bg-surface-disabled`
`--p-color-bg-primary`	`--p-color-bg-fill-brand`
`--p-color-bg-primary-hover`	`--p-color-bg-fill-brand-hover`
`--p-color-bg-primary-active`	`--p-color-bg-fill-brand-active`
`--p-color-bg-primary-subdued`	`--p-color-bg-surface-brand`
`--p-color-bg-primary-subdued-hover`	`--p-color-bg-surface-brand-hover`
`--p-color-bg-primary-subdued-active`	`--p-color-bg-surface-brand-active`
`--p-color-bg-primary-subdued-selected`	`--p-color-bg-surface-brand-selected`
`--p-color-bg-magic-subdued`	`--p-color-bg-surface-magic`
`--p-color-text-critical-hover-experimental`	`--p-color-text-critical-hover`
`--p-color-text-warning-experimental`	`--p-color-text-warning`
`--p-color-text-interactive-inverse`	`--p-color-text-link-inverse`
`--p-color-border-strong`	`--p-color-border-tertiary`
`--p-color-border-interactive`	`--p-color-border-emphasis`

The text was updated successfully, but these errors were encountered:

### WHY are these changes introduced? Part of #10528 ### WHAT is this pull request doing? Migrated CSS custom properties for `color` token groups. > See #10528 for detailed instructions on the migration process and replacement maps. Polaris migrator snapshot ran on this PR: ```sh cd polaris-react npx @shopify/polaris-migrator@0.0.0-snapshot-release-20230920224230 \ v12-styles-replace-custom-property-color \ 'src/**/*' ```

lgriffee mentioned this issue Sep 18, 2023

[Epic] Write migrations to run across Polaris, Web, 1P, and 3P apps #10301

Closed

lgriffee assigned aaronccasanova Sep 18, 2023

lgriffee added the #gsd:36565 label Sep 18, 2023

aaronccasanova mentioned this issue Sep 19, 2023

Migrate color custom properties from Polaris v11 to v12 #10576

Merged

lgriffee closed this as completed Sep 29, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Run `color` migration in polaris #10528

Run `color` migration in polaris #10528

lgriffee commented Sep 18, 2023 •

edited by aaronccasanova

Loading

Run color migration in polaris #10528

Run color migration in polaris #10528

Comments

lgriffee commented Sep 18, 2023 • edited by aaronccasanova Loading

Migration

Recommended token migration workflow

Post-migration validation

Replacement maps

Run `color` migration in polaris #10528

Run `color` migration in polaris #10528

lgriffee commented Sep 18, 2023 •

edited by aaronccasanova

Loading