Makes some content updates.

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

@@ -1,6 +1,6 @@
 ---
 id: Designing with tokens
-section: design-tokens
+section: tokens
 ---
 
 As a designer, you can access and use our token libraries in Figma.

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

@@ -1,6 +1,6 @@
 ---
 id: Developing with tokens
-section: design-tokens
+section: tokens
 ---
 
 ## Installing tokens

packages/documentation-site/patternfly-docs/content/tokens/migrate-to-tokens.md

@@ -0,0 +1,47 @@
+---
+id: Migrate to tokens
+section: tokens
+---
+
+## How to migrate to tokens 
+
+The PatternFly token system is an addition to PatternFly as part of our V6 release. If you've previously used PatternFly through our Sketch design kits and our global CSS variables, you will need to complete a few steps to migrate to our token system. 
+
+If you're new to PatternFly, you can get set up on the token system by following our [Design]() and/or [Develop]() onboarding guides.
+
+[we could maybe include a visual showing the difference between v5 and Penta designs]
+
+### For designers 
+
+**Our tokens are only available within Figma.** To take advantage of the PatternFly token system, you must migrate all existing designs over from Sketch.
+
+To migrate to Figma, follow these steps:
+
+1. Import files from Sketch 
+
+        1. From the sketch.cloud file browser, select the ellipse button on the relevant file and choose "Download"
+
+        2. In Figma, go to the relevant project and select the "Import" button. Select the .sketch file that you downloaded in step 1.
+
+1. If this is your first time using Figma, be sure to familiarize yourself with its [training tutorials]().
+
+1. Once you've completed your migration, you can begin to [design with tokens.]()
+
+[Add more specific instructions - what is the process for non-UXD designers re Figma?]
+
+### For developers
+
+Previously, user interface design solutions were implemented by using our [global CSS variables](/developer-resources/css-variables). Our token system replaces these CSS variables, so you will need to migrate the style variables throughout your codebase to align with our tokens instead. 
+
+To migrate to token variables, follow these steps: 
+
+1. Download the PatternFly token packages 
+1. Update your color and style variables to use [PatternFly tokens](/tokens/patternfly-tokens). For example: 
+
+        | CSS variable | Token |
+        | --- | --- |
+        | | |
+        | | |
+    - If there's a table outlining the specific 1:1 changes, we'll link to that here. Or if there's any kind of automated tool to update variable names, we will include that as a step. 
+
+1. Once you've completed your migration, you can begin to [develop with tokens](/tokens/develop-with-tokens).

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

@@ -0,0 +1,8 @@
+---
+id: PatternFly tokens
+section: tokens
+---
+
+## All tokens
+
+(This is where we will add a generate list of all tokens.)

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

@@ -0,0 +1,108 @@
+---
+id: About tokens
+section: tokens
+--- 
+
+## What are design 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 visual design, making their purpose clear and recognizable. By using a system of tokens, we can enable a shared language for building user interfaces.
+
+## Why use tokens? 
+
+Tokens help maintain consistency across product design processes by ensuring that the same colors and styles are always used for the same use cases. By removing the decision making that would otherwise go into choosing the right color, heading level, spacing, and so on, designs can be create more consistently and efficienctly.
+
+[Add visual here with an example of a couple of tokens being used for an element]
+
+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 changes to code to ensure that their product is up to date with the latest recommendations. Likewise, designers will see that their designs automatically update to reflect any changes.
+
+## PatternFly design tokens
+
+PatternFly's tokens aren't available within Sketch, so you'll need to use Figma when designing with tokens. If necessary, you can follow our [Figma migration guide]() to get set up.
+
+[Find a list of all PatternFly tokens here.](tokens/patternfly-tokens.md)
+
+### Token naming
+
+Tokens are read from left to right, with a forward slash ( / ) separating different segments of the token name:
+
+`scope / component / property / concept / variant / state` 
+
+[replace this ^ with more of a visual]
+
+Each segment represents different style information:
+
+| Token segment | Description |
+| --- | --- |
+| **Scope** | The range of the token. For example, `global` signifies that a token applies across the entire system.
+| **Component** | The component that the token relates to, such as `icon`, `background`, or `text`.
+| **Property** | The style property of a component, such as `color`, `size`, `width`, or `radius`.
+| **Concept** | The higher level concepts, such as `status`, `primary`, or `action`. These tokens will have different variant options.
+| **Variant** | The variant type of the token's component, such as `link`, `plain`, `warning`, or `success`.
+| **State** | The state that the component is in, such as `default`, `hover`, or `active`.
+
+If a name segment isn't relevant for a particular token then it will be skipped, as shown in the following table. 
+
+| Scope | Component | Property | Concept | Variant | State | 
+| --- | --- | --- | --- | --- | --- |
+| global | icon | color |  action |  danger  | hover |
+bal | background | color | highlight | 100 |
+| global | spacer | width |  |  |  |
+
+
+**Note:** all PatternFly tokens also begin with `pft` and a version number. For example:
+
+`pft-v5` / `global` / `spacer` / `width` [replace with image]
+
+### Token system layers
+
+The PatternFly token system has 3 layers: **palette tokens**, **base tokens**, and **semantic tokens**. 
+
+[insert visual - should make one within Figma]
+
+#### Palette tokens
+
+Palette tokens refer to all of the colors in the [PatternFly color palettes](/design-foundations/colors#patternfly-palettes) and create the foundation of colors that the other token layers reference. 
+
+If you've used PatternFly previously, these values resemble some of the CSS color variables that you may be familiar with. 
+
+[Add visual example]
+
+#### Base tokens
+
+Base tokens expands on the palette layer to apply PatternFly colors to concepts. They also introduce additional concepts, like spacing and borders.
+
+These values are grouped conceptually and named numerically. There are no duplicate values within a concept group.
+
+[Add visual example]
+
+#### Semantic tokens
+
+You should almost always use semantic tokens. These are the top-level tokens that are grouped conceptually and named semantically. 
+
+Most of the time, semantic tokens reference base tokens, but they can also reference other semantic tokens, such as [such as when, if worth stating].
+
+[Add visual example]
+
+### Examples of token use 
+
+#### Color 
+
+[Add visual examples]
+
+#### Spacing 
+
+[Add visual examples]
+
+#### Status
+
+[Add visual examples]
+
+#### Theming
+
+Light and dark themes are built into all PatternFly tokens and they will toggle when users select a theme preference.
+
+[Add visual examples]
+
+#### Variant
+
+[Add visual examples]

packages/documentation-site/patternfly-docs/patternfly-docs.config.js

@@ -32,7 +32,7 @@ if (process.env.EXTENSIONS_ONLY === 'true') {
     sideNavItems: [
       { section: 'get-started' },
       { section: 'design-foundations' },
-      { section: 'design-tokens' },
+      { section: 'tokens' },
       { section: 'accessibility' },
       { section: 'UX writing' },
       { section: 'components' },

packages/documentation-site/patternfly-docs/patternfly-docs.source.js

@@ -16,7 +16,7 @@ module.exports = (sourceMD, sourceProps, sourceFunctionDocs) => {
     sourceMD(path.join(contentBase, 'accessibility/**/*.md'), 'accessibility');
     sourceMD(path.join(contentBase, 'design-guidelines/**/*.md'), 'design-guidelines');
     sourceMD(path.join(contentBase, 'training/**/*.md'), 'training');
-    sourceMD(path.join(contentBase, 'design-tokens/**/*.md'), 'design-tokens');
+    sourceMD(path.join(contentBase, 'tokens/**/*.md'), 'tokens');
 
     // Gallery pages
     const galleryBase = path.join(__dirname, '../patternfly-docs/pages');