Skip to content

Add migration guidance for replacing v14 text custom properties #11832

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Apr 5, 2024
Merged

Add migration guidance for replacing v14 text custom properties #11832

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
49172ad
Add migration guidance for replacing v14 text custom properties
lgriffee Apr 3, 2024
53d9e96
Update polaris.shopify.com/content/version-guides/migrating-from-v12-…
lgriffee Apr 5, 2024
452fc9e
Update polaris.shopify.com/content/version-guides/migrating-from-v12-…
lgriffee Apr 5, 2024
e52119a
Merge branch 'v14.0.0' of https://github.com/Shopify/polaris into tex…
lgriffee Apr 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 104 additions & 13 deletions polaris.shopify.com/content/version-guides/migrating-from-v13-to-v14.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -204,25 +204,116 @@ To replace deprecated `font` custom properties, you can run the [v14-styles-repl
code={{
title:
'Check RegExp for hardcoded font custom properties across all file types',
code: String.raw`(?:--p-font-size-800|--p-font-size-900|--p-font-size-1000|--p-font-letter-spacing-densest|--p-font-line-height-1200|--p-text-heading-3xl-font-family|--p-text-heading-3xl-font-size|--p-text-heading-3xl-font-weight|--p-text-heading-3xl-font-letter-spacing|--p-text-heading-3xl-font-line-height(?![\w-])`,
code: String.raw`(?:--p-font-size-800|--p-font-size-900|--p-font-size-1000|--p-font-letter-spacing-densest|--p-font-line-height-1200)(?![\w-])`,
}}
/>
</CollapsibleDetails>

<CollapsibleDetails summary="➡️ Token replacement mappings">

| Deprecated Token | Replacement Value |
| ------------------------------------------ | ------------------------------------------ |
| `--p-font-size-800` | `--p-font-size-750` |
| `--p-font-size-900` | `--p-font-size-750` |
| `--p-font-size-1000` | `--p-font-size-750` |
| `--p-font-letter-spacing-densest` | `--p-font-letter-spacing-denser` |
| `--p-font-line-height-1200` | `--p-font-line-height-1000` |
| `--p-text-heading-3xl-font-family` | `--p-text-heading-2xl-font-family` |
| `--p-text-heading-3xl-font-size` | `--p-text-heading-2xl-font-size` |
| `--p-text-heading-3xl-font-weight` | `--p-text-heading-2xl-font-weight` |
| `--p-text-heading-3xl-font-letter-spacing` | `--p-text-heading-2xl-font-letter-spacing` |
| `--p-text-heading-3xl-font-line-height` | `--p-text-heading-2xl-font-line-height` |
| Deprecated Token | Replacement Value |
| --------------------------------- | -------------------------------- |
| `--p-font-size-800` | `--p-font-size-750` |
| `--p-font-size-900` | `--p-font-size-750` |
| `--p-font-size-1000` | `--p-font-size-750` |
| `--p-font-letter-spacing-densest` | `--p-font-letter-spacing-denser` |
| `--p-font-line-height-1200` | `--p-font-line-height-1000` |

</CollapsibleDetails>

### Text

To replace deprecated `text` custom properties, you can run the [v14-styles-replace-custom-property-text](/tools/polaris-migrator#v14-styles-replace-custom-property-text) migration then validate with RegExp. Please reference the [recommended migration workflow](#migration-workflow) section below for additional migration support.

<CollapsibleDetails summary="💡 Migration example">

```diff
- font-size: var(--p-text-heading-xl-font-size);
+ font-size: var(--p-font-size-600);
```

</CollapsibleDetails>

<Code
code={{
title: 'polaris-migrator codemod',
className: 'language-bash',
code: String.raw`npx @shopify/polaris-migrator v14-styles-replace-custom-property-text "**/*.{css,scss}"`,

}}
/>

<CollapsibleDetails summary="✅ Post-migration RegExp validation">
After migrating, use the following RegExp to check for any additional
instances of `text` custom properties across all file types:
<Code
code={{
title:
'Check RegExp for hardcoded text custom properties across all file types',
code: String.raw`(?:--p-text-heading-3xl-font-family|--p-text-heading-3xl-font-size|--p-text-heading-3xl-font-weight| --p-text-heading-3xl-font-letter-spacing|--p-text-heading-3xl-font-line-height|--p-text-heading-2xl-font-family|--p-text-heading-2xl-font-size|--p-text-heading-2xl-font-weight| --p-text-heading-2xl-font-letter-spacing|--p-text-heading-2xl-font-line-height| --p-text-heading-xl-font-family|--p-text-heading-xl-font-size|--p-text-heading-xl-font-weight| --p-text-heading-xl-font-letter-spacing|--p-text-heading-xl-font-line-height|--p-text-heading-lg-font-family|--p-text-heading-lg-font-size|--p-text-heading-lg-font-weight|--p-text-heading-lg-font-letter-spacing|--p-text-heading-lg-font-line-height|--p-text-heading-md-font-family|--p-text-heading-md-font-size|--p-text-heading-md-font-weight|--p-text-heading-md-font-letter-spacing|--p-text-heading-md-font-line-height|--p-text-heading-sm-font-family|--p-text-heading-sm-font-size|--p-text-heading-sm-font-weight|--p-text-heading-sm-font-letter-spacing|--p-text-heading-sm-font-line-height|--p-text-heading-xs-font-family|--p-text-heading-xs-font-size|--p-text-heading-xs-font-weight|--p-text-heading-xs-font-letter-spacing|--p-text-heading-xs-font-line-height|--p-text-body-lg-font-family|--p-text-body-lg-font-size|--p-text-body-lg-font-weight|--p-text-body-lg-font-letter-spacing|--p-text-body-lg-font-line-height|--p-text-body-md-font-family|--p-text-body-md-font-size|--p-text-body-md-font-weight|--p-text-body-md-font-letter-spacing|--p-text-body-md-font-line-height|--p-text-body-sm-font-family|--p-text-body-sm-font-size|--p-text-body-sm-font-weight|--p-text-body-sm-font-letter-spacing|--p-text-body-sm-font-line-height|--p-text-body-xs-font-family|--p-text-body-xs-font-size|--p-text-body-xs-font-weight|--p-text-body-xs-font-letter-spacing|--p-text-body-xs-font-line-height)(?![\w-])`,
}}
/>
</CollapsibleDetails>

<CollapsibleDetails summary="➡️ Token replacement mappings">

| Deprecated Token | Replacement Value |
| ------------------------------------------ | -------------------------------- |
| `--p-text-heading-3xl-font-family` | `--p-font-family-sans` |
| `--p-text-heading-3xl-font-size` | `--p-font-size-750` |
| `--p-text-heading-3xl-font-weight` | `--p-font-weight-bold` |
| `--p-text-heading-3xl-font-letter-spacing` | `--p-font-letter-spacing-denser` |
| `--p-text-heading-3xl-font-line-height` | `--p-font-line-height-1000` |
| `--p-text-heading-2xl-font-family` | `--p-font-family-sans` |
| `--p-text-heading-2xl-font-size` | `--p-font-size-750` |
| `--p-text-heading-2xl-font-weight` | `--p-font-weight-bold` |
| `--p-text-heading-2xl-font-letter-spacing` | `--p-font-letter-spacing-denser` |
| `--p-text-heading-2xl-font-line-height` | `--p-font-line-height-1000` |
| `--p-text-heading-xl-font-family` | `--p-font-family-sans` |
| `--p-text-heading-xl-font-size` | `--p-font-size-600` |
| `--p-text-heading-xl-font-weight` | `--p-font-weight-bold` |
| `--p-text-heading-xl-font-letter-spacing` | `--p-font-letter-spacing-dense` |
| `--p-text-heading-xl-font-line-height` | `--p-font-line-height-800` |
| `--p-text-heading-lg-font-family` | `--p-font-family-sans` |
| `--p-text-heading-lg-font-size` | `--p-font-size-500` |
| `--p-text-heading-lg-font-weight` | `--p-font-weight-semibold` |
| `--p-text-heading-lg-font-letter-spacing` | `--p-font-letter-spacing-dense` |
| `--p-text-heading-lg-font-line-height` | `--p-font-line-height-600` |
| `--p-text-heading-md-font-family` | `--p-font-family-sans` |
| `--p-text-heading-md-font-size` | `--p-font-size-350` |
| `--p-text-heading-md-font-weight` | `--p-font-weight-semibold` |
| `--p-text-heading-md-font-letter-spacing` | `--p-font-letter-spacing-normal` |
| `--p-text-heading-md-font-line-height` | `--p-font-line-height-500` |
| `--p-text-heading-sm-font-family` | `--p-font-family-sans` |
| `--p-text-heading-sm-font-size` | `--p-font-size-325` |
| `--p-text-heading-sm-font-weight` | `--p-font-weight-semibold` |
| `--p-text-heading-sm-font-letter-spacing` | `--p-font-letter-spacing-normal` |
| `--p-text-heading-sm-font-line-height` | `--p-font-line-height-500` |
| `--p-text-heading-xs-font-family` | `--p-font-family-sans` |
| `--p-text-heading-xs-font-size` | `--p-font-size-300` |
| `--p-text-heading-xs-font-weight` | `--p-font-weight-semibold` |
| `--p-text-heading-xs-font-letter-spacing` | `--p-font-letter-spacing-normal` |
| `--p-text-heading-xs-font-line-height` | `--p-font-line-height-400` |
| `--p-text-body-lg-font-family` | `--p-font-family-sans` |
| `--p-text-body-lg-font-size` | `--p-font-size-350` |
| `--p-text-body-lg-font-weight` | `--p-font-weight-regular` |
| `--p-text-body-lg-font-letter-spacing` | `--p-font-letter-spacing-normal` |
| `--p-text-body-lg-font-line-height` | `--p-font-line-height-500` |
| `--p-text-body-md-font-family` | `--p-font-family-sans` |
| `--p-text-body-md-font-size` | `--p-font-size-325` |
| `--p-text-body-md-font-weight` | `--p-font-weight-regular` |
| `--p-text-body-md-font-letter-spacing` | `--p-font-letter-spacing-normal` |
| `--p-text-body-md-font-line-height` | `--p-font-line-height-500` |
| `--p-text-body-sm-font-family` | `--p-font-family-sans` |
| `--p-text-body-sm-font-size` | `--p-font-size-300` |
| `--p-text-body-sm-font-weight` | `--p-font-weight-regular` |
| `--p-text-body-sm-font-letter-spacing` | `--p-font-letter-spacing-normal` |
| `--p-text-body-sm-font-line-height` | `--p-font-line-height-400` |
| `--p-text-body-xs-font-family` | `--p-font-family-sans` |
| `--p-text-body-xs-font-size` | `--p-font-size-275` |
| `--p-text-body-xs-font-weight` | `--p-font-weight-regular` |
| `--p-text-body-xs-font-letter-spacing` | `--p-font-letter-spacing-normal` |
| `--p-text-body-xs-font-line-height` | `--p-font-line-height-300` |

</CollapsibleDetails>

Expand Down