docs(tokens) Updates migration instructions.

[edonehoo]

Closes #4218, adds to existing tokens docs

[patternfly-build]

Preview: https://patternfly-org-pr-4239-site.surge.sh

[edonehoo]

@srambach RE #4218, were you thinking of a different direction than this pr goes? Much of the info from the linked doc in the issue was already on the site, but do you think it would make more sense in a different page or with more detail? Added some more details and specifics, though!

I saw the codemods notes in the original doc, but they seemed like observations more than things we want to communicate on org

[srambach]

I think this came out of a recent conversation specifically about React tokens (which are the React version of our CSS variables). This includes more than just token variables. This is great info, and I like the improvements you've made to the "develop with tokens" page. But I think this was intended to add some information to the upgrade guide about finding and fixing React tokens specifically. @nicolethoen @wise-king-sullyman maybe you two have more specific information?

[adamviktora]

Following on what Sarah has written about React tokens - we just discussed that on a working session, and it would be great to add some notes like this:

• React token names are based on the CSS variable names, but instead of -- symbol, _ is used plus the starting --pf- is removed. So for example --pf-t--global--spacer--sm becomes a t_global_spacer_sm react token.
• React token can be imported from its file directly: import t_global_spacer_sm from '@patternfly/react-tokens/dist/esm/t_global_spacer_sm' or from the whole package: import { t_global_spacer_sm } from '@patternfly/react-tokens'
• React token is an object having 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)"
}

[kmcfaul]

@adamviktora Is this a blocker or could it be done in a follow up?

[adamviktora]

@kmcfaul It can be a follow up for sure

[srambach]

@kmcfaul I think @adamviktora 's suggestions are the core of this issue so I think it's worth doing before merging this rather than making another issue.

[edonehoo]

@adamviktora ty for this context!
@srambach I integrated Adam's comment, but I can't tell if it's enough extra context on its own to help guide people that will actually use this info. WDYT?

If we do want to go further in these docs, or if I'm misunderstanding any of these details, it would probably be good to arrange time for a call to help me understand this more deeply (also cc @nicolethoen) !

[adamviktora]

I really like the updates, I think it explains React tokens pretty well. Two comments bellow:

[adamviktora]

I'd mention also (probably in this block) that we have a codemod for updating global CSS variables, which are part of their React code (it will not fix .css files, but only javascript or typescript ones).

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), so consumers can build their code and visually see on the website, at which places they will have to manually replace this token with a new one.

For other global variables (spacers, font size, box shadow), it will try to provide an autofix to match the same value (or the closest one).

This codemod works both for CSS variables and React tokens.
e.g. a CSS variable: --pf-v5-global--FontSize--lg becomes --pf-t--global--font--size--lg
and a react token: global_FontSize_lg becomes t_global_font_size_lg

[edonehoo]

thanks for all of this info!! Is that this codemod? https://github.com/patternfly/pf-codemods?tab=readme-ov-file#tokens-update. I linked to that one in my last commit, but can adjust if needed. Is https://github.com/patternfly/pf-codemods/tree/main/packages/class-name-updater limited to css?

[adamviktora]

Yes, that's the codemod. The class-name-updater is not limited to just css. Thanks for doing all the updates!

[adamviktora]

LGTM 🎉

[kmcfaul]

🎉

[srambach]

I think this looks good, thank you! 🩷