docs(tokens): Update content for accuracy and with additional details. (

#4100)

* docs(tokens): Updates and expands docs.

* Content updates and package updates.

* Updates to content.

* Continued content changes.

* Adds instructions for choosing tokens.

* Resize images.

* Prepares content for review.

packages/documentation-site/patternfly-docs/content/tokens/about-tokens.md

@@ -3,13 +3,11 @@ id: About tokens
 section: tokens
 --- 
 
-**Design tokens** are variables that store visual design attributes like color, typography, and spacing. Tokens have a name and value that conveys their associated design style, making their purpose clear and recognizable. 
+**Design tokens** are variables that store visual design attributes like color, typography, and spacing. Tokens have a name and value that conveys their associated design style, making their purpose clear and recognizable.
 
-PatternFly's tokens are set up as variables and styles within Figma, and are exported as CSS variables for use in development. Tokens are only available as part of the PatternFly 6 release, so make sure you [upgrade to PatternFly 6](/get-started/upgrade) in order to take advantage of tokens.
+PatternFly's tokens are set up as variables and styles within Figma, and are available as CSS variables for development. Tokens are only available as part of the PatternFly 6 release, so make sure you [upgrade to PatternFly 6](/get-started/upgrade) and/or [install our Figma library](/get-started/design#figma-library) in order to take advantage of tokens. PatternFly 6 components, charts, and extensions are all built with tokens.
 
-To learn more about designing with the PatternFly Figma library, [refer to our onboarding guide.](/get-started/design#figma-library)
-
-You can also [view the complete list of PatternFly's design tokens.](/tokens/all-patternfly-tokens)
+[View all PatternFly design tokens.](/tokens/all-patternfly-tokens)
 
 ## Why use tokens? 
 
@@ -21,16 +19,23 @@ Tokens help maintain consistency across product design processes by ensuring tha
 ### Easier maintenance
 Tokens also enable easier design system maintenance. Whenever a color is changed as part of a redesign or update, all related tokens are automatically updated to reflect this change. This means that developers won't have to make any code changes to ensure that a product is up to date with the latest PatternFly recommendations. Likewise, designers will see that their Figma designs automatically update to reflect any changes made to tokens.
 
-## Token names
+## Token layers
+The PatternFly token system has 3 layers: palette tokens, base tokens, and semantic tokens. 
+
+* **Palette tokens** use [PatternFly color palettes](/design-foundations/colors#patternfly-palettes) to create a color foundation for other token layers to reference. 
 
-PatternFly token names are composed of a `--pf-t` prefix, a version number, and a series of token segments, separated by double hyphens.
+* **Base tokens** expand on the palette layer to apply PatternFly colors to concepts. They also introduce additional concepts, like spacing and borders. Base tokens are grouped conceptually and named numerically, with no duplicate values in a concept group.
 
-<div class="ws-image" style="text-align: center;">
-    <img src="./img/token-name.png"  alt="PatternFly token naming structure."  width="600px"/>
-</div>
-<br />
+* **Semantic tokens** are the top-level tokens that are grouped conceptually and named semantically. They are built with base tokens and are the tokens that you should see and use in most use cases. Semantic naming is intentionally chosen to support the proper and relevant use of a token, which makes design consistency easier for everyone. 
+
+![PatternFly token layer names for the same color value](./img/token-layers-example.png)
+
+## Token names
+PatternFly token names are composed of a `--pf-t` prefix and a series of token segments, separated by double hyphens:
+
+`--pf-t--[scope]--[component]--[property]--[concept]--[variant]--[state]`
 
-Each token segment represents a different type of style information. If a segment isn't relevant for a particular token then it will be skipped in the token's name. 
+Each token segment represents a different type of style information: 
 
 | **Segment** | **Description** |
 | --- | --- |
@@ -41,16 +46,15 @@ Each token segment represents a different type of style information. If a segmen
 | Variant | The variant of a component or concept, such as *link*, *plain*, *warning*, or *success*.
 | State | The state that the component is in, such as *default*, *hover*, or *active*.
 
-## Token layers
-
-The PatternFly token system has 3 layers: palette tokens, base tokens, and semantic tokens. 
+<br />
 
-* **Palette tokens** use [PatternFly color palettes](/design-foundations/colors#patternfly-palettes) to create a color foundation for other token layers to reference. 
+If a segment isn't relevant for a particular token then it will be skipped in the token's name:
 
-* **Base tokens** expand on the palette layer to apply PatternFly colors to concepts. They also introduce additional concepts, like spacing and borders. Base tokens are grouped conceptually and named numerically, with no duplicate values in a concept group.
+| **Segments** | **Example** |
+| --- | --- |
+| [scope]--[component]--[property]--[concept]--[variant]--[state] | `--pf-t--global--background--color--action--plain--clicked` |
+| [scope]--[component]--[property]--[variant]--[state]  | `--pf-t--global--background--color--backdrop--default` |
+| [scope]--[component]--[property]--[variant]  |  `--pf-t--global--border--width--regular`	|
 
-* **Semantic tokens** are the top-level tokens that are grouped conceptually and named semantically. These are built with base tokens and are the tokens that you will see and use the majority of the time. The naming is intentionally chosen to support the proper and relevant use of a token, which makes design consistency easier for everyone. 
+<br />
 
-<div class="ws-image" style="text-align: center;">
-    <img src="./img/token-layers-example.png"  alt="PatternFly token layer names for the same color value." width="600px"/>
-</div>

packages/documentation-site/patternfly-docs/content/tokens/design-with-tokens.md

@@ -3,54 +3,29 @@ id: Design with tokens
 section: tokens
 ---
 
-## PatternFly 6 design kit
+Tokens are only available as part of PatternFly 6. In order to make use of our token system, you will need to install the PatternFly 6 design kit [using our onboarding guide](/get-started/design) and make sure that your product is [upgraded to PatternFly 6](/get-started/upgrade). 
 
-PatternFly tokens are only available as part of [the PatternFly 6 design kit.](https://www.figma.com/@patternfly) In order to make use of our token system, you will need to [upgrade to PatternFly 6](/get-started/upgrade).
+## Using tokens in Figma
 
-## What is in the PatternFly 6 design kit
+Our tokens are set up as [variables](https://help.figma.com/hc/en-us/articles/15339657135383-Guide-to-variables-in-Figma) and [styles](https://help.figma.com/hc/en-us/articles/360039238753-Styles-in-Figma) in Figma, within our [Design Tokens and Styles Library](https://www.figma.com/@PatternFly). They define all of the design elements used in PatternFly, including color, font size, spacing, dimensions, and more.
 
-### Tokens 
+Figma tokens align with the segments in [our token variable structure](/tokens/about-tokens#token-names), but they use a forward slash (/) in place of a double hyphen (--).
 
-Our tokens are set up at a high level as Figma [variables](https://help.figma.com/hc/en-us/articles/15339657135383-Guide-to-variables-in-Figma) and [styles](https://help.figma.com/hc/en-us/articles/360039238753-Styles-in-Figma). 
+![Table of brand color tokens.](./img/token-example-brand.png)  
 
-In Figma, the variable names look similar to [token names](/tokens/all-patternfly-tokens), but will be separated by a forward slash (/) instead of a double hyphen (--).
+PatternFly 6 elements, including components, charts, and extensions, are built with tokens. Therefore, you will typically not need to work with tokens directly. The exception to this is if you are deviating from our built-in customization options. [See these instructions for more detail.](#making-customizations)
 
-<div style="text-align: center;">
-    <img src="./img/token-example-brand.png"  alt="Table of brand color tokens." width="600px"/>
-</div>
-<br />
-
-### Component library 
-
-You will have access to all PatternFly tokens when you install the component library. PatternFly 6 components are built with tokens. From the colors used, to the spacing of elements, to the font size: tokens control it all!
-
-<div style="text-align: center;">
-    <img src="./img/component-tokens.png"  alt="PatternFly alert components built with Figma tokens."  width="700px"/> 
-</div>
-
-## Using the PatternFly 6 design kit 
+Because tokens are set up behind the scenes, they enable you to customize components as you add them to your design. Before you insert a component into a Figma design workspace, you can adjust its properties and variable modes to fit your specific use case. 
 
-To install the design kit, [find instructions in our design onboarding guide.](/get-started/design#figma-library)
+This allows you to quickly swap between different variants and enable/disable component enhancements. For example: 
 
-### Using PatternFly 6 components
-
-As you insert a component into a Figma design workspace, you can adjust properties and variable modes to customize the appearance to your needs. 
-
-<div style="text-align: center;">
-    <img src="./img/component-instance.png"  alt="PatternFly alert components built with Figma tokens."  width="350px"/> 
-</div>
+![PatternFly alert components built with Figma tokens.](./img/component-instance.png)  
 <br />
 
-Once you've inserted a component into your workspace, you can continue to customize different parts of its appearance in [Figma's design sidebar](https://help.figma.com/hc/en-us/articles/360039832014-Design-prototype-and-explore-layer-properties-in-the-right-sidebar). Here, you will be able to see all tokens that can be used within a particular design property. 
-
-### Making customizations 
-
-Occasionally, you may find that you need to customize a design beyond what the PatternFly component natively supports. For example, adding text or adding custom spacing.
-
-Our tokens are intentionally scoped so that they can only be used to modify relevant and related visual attributes. For example, a token may have its color scope limited so that it can only be used as a fill color or a stroke color. This means that, while you can use tokens to customize a design, you will only be able to use certain tokens in certain situations. This helps ensure that you're using tokens that are conceptually related to each design element that you're working on.
+Once you've inserted a component into your workspace, you can continue to customize its appearance in [Figma's design sidebar](https://help.figma.com/hc/en-us/articles/360039832014-Design-prototype-and-explore-layer-properties-in-the-right-sidebar). When choosing colors, styles, and effects, you will see a list of tokens to choose from.
 
-## Migrate to tokens
+### Customizing designs with tokens
 
-Our tokens are only available within Figma. If you've previously designed with PatternFly by using our Sketch design kits, you will need to begin to create all new product designs within Figma.
+If you're working on a custom design, you may need to adjust a component beyond the predefined options. For example, you may need to add text or custom spacing where it isn't already present. When you create custom designs, use tokens appropriately to achieve the style and structure you need. Choose the semantic token that is the best fit for your needs. 
 
-If you have any existing Sketch-based designs that you want to migrate into Figma, you will need to manually recreate each UI mockup using the PatternFly 6 component library.
+Our tokens are intentionally scoped so that they can only be used to modify relevant visual attributes. For example, a token may have its color scope limited so that it can only be used as a fill color or a stroke color. This means that, while you can use tokens to customize a design, you will only be able to use certain tokens in certain situations. This helps ensure that you're using tokens that are conceptually relevant to the design element that you're working on.

packages/documentation-site/patternfly-docs/content/tokens/develop-with-tokens.md

@@ -5,18 +5,59 @@ section: tokens
 
 ## Using tokens in code
 
-PatternFly tokens are exported from Figma and transformed into CSS variables for use in code. You can find token files in [PatternFly's core HTML repo](https://github.com/patternfly/patternfly/tree/v6/src/patternfly/base/tokens) and refer to [our list of all tokens](/tokens/all-patternfly-tokens).
+PatternFly tokens are exported from Figma and transformed into CSS variables for use in code. You can find all token files in [the core HTML repo](https://github.com/patternfly/patternfly/tree/v6/src/patternfly/base/tokens).
 
-When using tokens in code: if there's a semantic token that matches your needs then you should always use that. In the event that there isn't a semantic token, then you can use a base token. You should not use palette tokens, as they are the foundation of our token system and there should always be a better base or semantic token to use.
+Our tokens are named semantically, so that they're meaningful and better communicate their function. When using tokens in code you should always use the semantic token that best matches your needs. For example, choose a color token based on its function, not just its hex value. 
+
+In the event that there isn't a semantic token that fits your use case, then you can use a base token instead, but do so sparingly. Do not use palette tokens. They are the foundation of our token system and there will always be a better base or semantic token to use.
+
+[View all PatternFly design tokens.](/tokens/all-patternfly-tokens)
 
 ### Dark theme support
 
-Our token system is available for both light and dark themes. We have [separate tokens for dark theme](https://github.com/patternfly/patternfly/blob/v6/src/patternfly/base/tokens/_tokens-dark.scss) to ensure proper contrast ratios. For guidance on enabling and supporting dark theme in your product, refer to our [dark theme handbook.](/developer-resources/dark-theme-handbook) 
+Our token system supports both light and dark themes by default. To enable dark theme, you just need to add the class `pf-[version]-theme-dark` (for example, `pf-v6-theme-dark`) to your application's `<html>` tag. Then, when dark theme is enabled, your product will automatically pull in dark theme tokens, in order to adapt visual styles appropriately.
+
+For more information, refer to our [dark theme handbook.](/developer-resources/dark-theme-handbook) 
 
 ## Migrate to tokens
 
-To support tokens, PatternFly's global CSS variable system has been updated and variable names have been updated across all PatternFly components and extensions. To migrate to our token system, all you need to do is [upgrade to PatternFly 6](/get-started/upgrade).
+To support tokens, PatternFly's global CSS variable system has been updated. Variable names have been updated across all PatternFly components and extensions. To migrate to our token system, you must [upgrade to PatternFly 6.](/get-started/upgrade)
+
+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:  
+
+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. **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]`
+
+    For each segment, consider the following:
+        - **Prefix:** `--pf-t-` indicates the CSS variable is a token.
+        - **Scope:** This will be `global` or `chart`.
+        - **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:
+            - 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. **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 
 
-However, 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 [token variable](/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. 
+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):
 
-Once you've completed your migration, you're ready to continue developing with tokens! 
+- **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. 
+    1. You'll end up selecting `var(--pf-t--global--background--color--disabled--default)`. 
+    1. Next you’ll want to set the text color of that element: type `pft`, then `text` for text color, then `ondis` 
+    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)`.