Skip to content

Commit

Permalink
docs(tokens) Updates migration instructions. (#4239)
Browse files Browse the repository at this point in the history 
* docs(tokens) Updates migration instructions.

* Add React tokens to upgrade guide.

* Adjusts tokens info and adds extra codemod content.
  • Loading branch information
@edonehoo
edonehoo authored Oct 9, 2024
1 parent 4befad5 commit 51f5a8a
Show file tree
Hide file tree
Showing 2 changed files with 74 additions and 33 deletions.
57 changes: 32 additions & 25 deletions packages/documentation-site/patternfly-docs/content/get-started/upgrade.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,34 +4,30 @@ source: upgrade-guide
title: PatternFly 6 upgrade
section: get-started
---
import { Alert } from '@patternfly/react-core';

If you have not previously upgraded to PatternFly 5, make sure to review its [upgrade guide](https://www.patternfly.org/get-started/upgrade) before attempting to support PatternFly 6, to ensure that your product has addressed any necessary changes from our previous release.
<Alert variant="info" isInline title="Before you upgrade"> Make sure that you have already completed [the PatternFly 5 upgrade](https://www.patternfly.org/get-started/upgrade) before attempting to support PatternFly 6. This will ensure that your product has addressed any necessary changes from our previous release.
</Alert>

PatternFly 6 introduces new support and functionality to PatternFly, including:
PatternFly 6 introduces exciting new features and functionality, including a visual theme refresh that's created with our new [design token system.](/tokens/about-tokens) To learn about the most significant changes in this release, read our [release highlights](/get-started/release-highlights). A detailed list of all changes can be found in our [major release notes](/get-started/upgrade/release-notes).

- A design token system,
- A new PatternFly 6 visual theme,
- And more!

To learn about the most significant changes in this release, read our [release highlights](/get-started/release-highlights). A detailed list of all changes can be found in our [major release notes](/get-started/upgrade/release-notes).

This guide outlines the major steps you should take to upgrade your product's codebase from PatternFly 5 to PatternFly 6.
This guide outlines the requirements for upgrading your codebase to PatternFly 6 and provides additional resources to support your migration efforts.

## Get help

If you need support as you upgrade to PatternFly 6, the PatternFly team is here to help. Reach out to us on [Slack](https://join.slack.com/t/patternfly/shared_invite/zt-1npmqswgk-bF2R1E2rglV8jz5DNTezMQ) or ask a question on our [GitHub discussion board](https://github.com/orgs/patternfly/discussions). We'll always do our best to answer your questions and connect you with the right people quickly.

## Upgrade your product's codebase
If you need support as you upgrade, the PatternFly team is here to help! Reach out to us on [Slack](https://join.slack.com/t/patternfly/shared_invite/zt-1npmqswgk-bF2R1E2rglV8jz5DNTezMQ) or ask a question on our [GitHub discussion board](https://github.com/orgs/patternfly/discussions). We'll always do our best to answer your questions and connect you with the right people quickly.

When you upgrade your product to PatternFly 6, several breaking changes will likely be introduced to your product’s codebase. We offer a suite of codemods to simplify and streamline your upgrade process. Instead of requiring you to manually identify all errors and issues in your codebase, you can run our codemods to quickly identify and fix major issues. Keep in mind that some changes will still require manual intervention, but our codemods can automatically fix a large amount of issues and flag any issues that do require manual work.
## How to upgrade

To utilize our codemods, refer to the following instructions. You can also [view the project on GitHub](https://github.com/patternfly/pf-codemods/) for additional details.
When you upgrade your product to PatternFly 6, several breaking changes will likely be introduced to your product’s codebase.

### Run our codemods
Where we can, we offer a suite of codemods to simplify and streamline your upgrade process. Instead of requiring you to manually identify all errors and issues in your codebase, you can run our codemods to quickly identify and fix major issues. Keep in mind that some changes will still require manual intervention, but our codemods can automatically fix a large amount of issues and flag any issues that do require manual work.

**Note:** Running codemods after making manual changes will lead to even more manual intervention and cleanup. Because of this, we strongly recommend running codemods _before_ making any manual changes to your codebase.

To run our codemods, complete the following steps:
### 1. Run our codemods suite

[Our suite of PatternFly codemods](https://github.com/patternfly/pf-codemods/) will help your upgrade process. To run these codemods, follow these steps:

1. Run the following command, adding in the path to your product's source code:

Expand All @@ -55,20 +51,31 @@ To run our codemods, complete the following steps:

7. Run codemods multiple times to ensure that all issues are flagged and addressed.

## Review and update variable and class names
### 2. Review and update variable and class names

PatternFly 6 supports our new design token system, which changes variable names across PatternFly. These changes mean that **all** existing CSS overrides must be updated (or removed), because they will be targeting outdated styles and will no longer work.

Wherever you have any custom CSS overrides that reference PatternFly class names or CSS variables, you should carefully review them and make updates to ensure that they align with our token variables, which are outlined in our [tokens documentation](/tokens/all-patternfly-tokens). As much as possible, we recommend removing your CSS overrides so that your product upgrade experience will be smoother for future releases.
Wherever you have any custom CSS overrides that reference PatternFly class names or CSS variables, you should carefully review them and make updates to ensure that they align with our token variables, as described in our [tokens documentation](/tokens/all-patternfly-tokens). As much as possible, we recommend removing your CSS overrides so that your product upgrade experience will be smoother for future releases.

If your product uses a custom solution to replicate PatternFly styling (without using PatternFly components), then it will need to be re-skinned. We recognize that this may be a large undertaking, so we encourage you to reach out to the PatternFly team so that we can help support this work.

If your product uses a custom solution to replicate PatternFly styling (without using PatternFly components), then it will need to be reskinned. We recognize that this may be a large undertaking, so we encourage you to reach out to the PatternFly team so that we support this work.
#### Utilize our class-name-updater codemod
[The class-name-updater codemod](https://github.com/patternfly/pf-codemods/tree/main/packages/class-name-updater) automatically identifies class names that need to be updated as a result of changes in PatternFly 6. This helps highlight places in your codebase that may require you to make adjustments.

### Utilize our class-name-updater codemod
We offer a [`class-name-updater` codemod](https://github.com/patternfly/pf-codemods/tree/main/packages/class-name-updater) to help support your updates. This utility automatically identifies class names that need to be updated as a result of class name changes in Patternfly 6, which helps highlight places in your codebase that may require you to adjust class names.
This utility performs a simple ‘find and replace’, so it's possible that it will inadvertently identify code that is formatted similarly to a PatternFly class name, but is not one. You should check to ensure that this doesn't cause any unintentional changes.

When using this codemod, keep the following guidance in mind:
- This codemod targets v5 of PatternFly by default, so you will need to add the `--v6` option if you are upgrading to v6.
When using this codemod, make sure to:
- Add the `--v6` option if you are upgrading to v6. This codemod targets v5 of PatternFly by default.
- Add the `--fix` flag to allow the codemod to fix issues where possible.
- This utility performs a simple ‘find and replace’, so it's possible that it will inadvertently identify code that is formatted similarly to a PatternFly class name, but is not one. You should check to ensure that this doesn't cause any unintentional changes.

For more details, you can refer to [the README file for this codemod](https://github.com/patternfly/pf-codemods/tree/main/packages/class-name-updater).
#### Utilize our tokens-update codemod

[The tokens-update codemod](https://github.com/patternfly/pf-codemods?tab=readme-ov-file#tokens-update) can help you update global CSS variables in your React code. Note that this will *only* fix JavaScript or TypeScript files: not CSS.

This codemod updates global color variables to a temporary hot pink color (`--pf-t--temp--dev--tbd`, or `t_temp_dev_tbd` when using [React tokens](/tokens/develop-with-tokens#react-tokens)) to visibly mark the places where you will have to manually replace tokens. For other global variables (like spacers, font size, or box shadows), this codemod will attempt to provide an auto-fix to match the same value (or the closest one).

This codemod works both for CSS variables and React tokens. For example:
- A CSS variable: `--pf-v5-global--FontSize--lg` becomes `--pf-t--global--font--size--lg`
- A react token: `global_FontSize_lg` becomes `t_global_font_size_lg`


50 changes: 42 additions & 8 deletions packages/documentation-site/patternfly-docs/content/tokens/develop-with-tokens.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,12 +25,11 @@ To support tokens, PatternFly's global CSS variable system has been updated. Var

If you make customizations to PatternFly components in your product, or use CSS overrides, you will need to manually update your CSS variable names to match an appropriate [semantic token](/tokens/all-patternfly-tokens). There is no one-to-one recommendation for any particular CSS variable, so you will need to choose the most appropriate token for your use case.

### Choosing tokens
We tried to name our semantic tokens so that their meaning is clear, but, until you're familiar with our token system, it may not be obvious which token you should choose for your use case. When choosing tokens, consider the following tips and reminders:
As you migrate and [select tokens](#selecting-tokens), refer to these recommendations and reminders:

1. **Fuzzy matching/autocomplete on CSS variables** is immensely helpful in finding the right token name. For VSCode, we like the [CSS variable autocomplete plugin.](https://marketplace.visualstudio.com/items?itemName=vunguyentuan.vscode-css-variables)
1. **Remember that you should only use semantic tokens.** Palette and base tokens provide values for semantic tokens, but generally should never be used otherwise. Palette and base tokens end in a number, but semantic tokens do not&mdash;so never use a token that ends in a number.

1. **Remember that you should only use semantic tokens.** Palette and base tokens provide values for semantic tokens, but generally should never be used otherwise. Palette and base tokens end in a number, but semantic tokens do not&mdash;so never use a token that ends in a number.
1. **Don’t start with the old value and work backwards.** For example, there are many things that are “blue” but it’s important to choose the right token for your purpose. In addition, PatternFly 6 has a completely new look&mdash;so what used to be “blue” might not be anymore!

1. **Understand the naming layers for semantic tokens.** Remember [the structure of our token names:](/tokens/about-tokens#token-names)
`--pf-t--[scope]--[component]--[property]--[concept]--[variant]--[state]`
Expand All @@ -41,17 +40,28 @@ We tried to name our semantic tokens so that their meaning is clear, but, until
- **Component:** What are you applying it to? For example, the background, text, icon, border, box-shadow, motion, or spacer.
- **Property:** What’s the attribute you are applying? For example, color, size, radius, or width.
- **Concept:** Is it associated with a concept, like primary, status, nonstatus, or action?
- **Variant:** What variation do you need? This typically includes:
- **Variant:** Which variation do you need? This typically includes:
- Sizes (xs, sm, md, lg, xl, 2xl)
- Statuses (danger, warning, success, info)
- In the case of some text and icon colors&mdash;`on-`, which refers to accessible colors to use on a particular background.
- **State:** What is the state? For example, default, hover, or clicked.

1. **Use fuzzy matching/autocomplete on CSS variables.** This is immensely helpful in finding the right token name. For VSCode, we like the [CSS variable autocomplete plugin.](https://marketplace.visualstudio.com/items?itemName=vunguyentuan.vscode-css-variables)

1. **If you use semantic tokens, you will get dark theme styling for free.** You may notice tokens with `dark` in their name. Don’t be tempted to use them! These exist within a selector that applies dark theme values to the main set of semantic tokens.

#### Examples
1. **Be sure to spend time testing how things look.**
- Switch to dark theme and make sure things look correct. This will often expose improper tokens.
- If your custom style should match and behave like an existing PatternFly component, compare that component's style to yours (in light and dark themes), to confirm that it matches.
- Try changing a token and see if it changes what you'd expect.

### Selecting tokens

It’s difficult to consistently map the old global variables to the new design tokens because, for the most part, the old global variables did not convey a lot of meaning. In contrast, design tokens carry intentional meaning. We tried to name our semantic tokens so that their meaning is clear, but, until you're familiar with our token system, it may not be obvious which token you should choose for your use case.

When choosing tokens, look at what you need a token for, and use fuzzy matching to help you find the appropriate token options.

Look at what you need a token for, and use fuzzy matching to help you find the appropriate token options. Consider the following scenarios (based on [the VS code plugin](https://marketplace.visualstudio.com/items?itemName=vunguyentuan.vscode-css-variables) we recommend):
The following scenarios provide examples (based on [the VS code plugin](https://marketplace.visualstudio.com/items?itemName=vunguyentuan.vscode-css-variables) we recommend):

- **Scenario 1:** You need to make a disabled state on a custom element.
1. You’ll probably want to set the background color: start typing `pft` to get tokens, then `back` for background, followed by `dis` for disabled.
Expand All @@ -60,4 +70,28 @@ Look at what you need a token for, and use fuzzy matching to help you find the a
1. You'll end up with `var(--pf-t--global--text--color--on-disabled)`.
- **Scenario 2:** You need to adjust spacing.
1. You probably want a spacer: start typing `pft`, then `sp` to get spacers, followed by the spacer size you want (`sm`, `md`, and so on).
1. You'll end up with something like `var(--pf-t--global--spacer--sm)`.
1. You'll end up with something like `var(--pf-t--global--spacer--sm)`.

### React tokens

React tokens are the React version of our CSS variables. They include more than just token variables and will require additional attention to upgrade properly. [You can find the latest tokens here.](https://www.npmjs.com/package/@patternfly/react-tokens)

A React token can be imported from its file directly:

`import t_token_name from '@patternfly/react-tokens/dist/esm/t_token_name'`

or from the whole package:

`import { t_token_name } from '@patternfly/react-tokens'`

React token names are similar to the CSS token names, but use different formatting. Instead of a double-hyphen ( -- ), token segments are separated by an underscore ( _ ). Additionally the `--pf-t` prefix is replaced with `t`. For example, a CSS variable of `--pf-t--global--spacer--sm` becomes `t_global_spacer_sm` as a React token.

Each React token is an object that stores name, value, and var properties:

```
const t_global_spacer_sm = {
"name": "--pf-t--global--spacer--sm",
"value": "0.5rem",
"var": "var(--pf-t--global--spacer--sm)"
}
```

0 comments on commit 51f5a8a

Please sign in to comment.