patternfly · nicolethoen · Mar 19, 2024 · Sep 21, 2023 · Sep 28, 2023 · Oct 16, 2023
diff --git a/packages/documentation-framework/scripts/webpack/webpack.base.config.js b/packages/documentation-framework/scripts/webpack/webpack.base.config.js
@@ -47,6 +47,7 @@ module.exports = (_env, argv) => {
             /react-[\w-]+\\src\\.*\\examples/, // fix for Windows
             /react-[\w-]+\/patternfly-docs\/.*\/examples/, //fixes for extensions
             /react-[\w-]+\\patternfly-docs\\.*\\examples/,
+            path.resolve(__dirname, '../../../../node_modules/@patternfly/design-tokens/patternfly-docs/content')
           ].concat(includePaths.map(path => new RegExp(path))),
           exclude: [
             path.resolve(__dirname, '../../node_modules'), // Temporarily compile theme using webpack for development

diff --git a/packages/documentation-framework/templates/mdx.css b/packages/documentation-framework/templates/mdx.css
@@ -50,6 +50,11 @@
   margin-bottom: var(--pf-v6-c-content--MarginBottom);
 }
 
+.ws-image {
+  text-align: center;
+  width: "600px";
+}
+
 /* Table styles */
 /* Undo patternfly reset to respect MD table styles */
 .ws-table td[align="center"],
@@ -68,6 +73,7 @@
   table-layout: fixed;
   width: 100%;
 }
+
 .ws-table td > code,
 .ws-table th > code,
 .ws-table tr > code {

diff --git a/packages/documentation-site/package.json b/packages/documentation-site/package.json
@@ -17,7 +17,7 @@
     "screenshots": "pf-docs-framework screenshots"
   },
   "dependencies": {
-    "@patternfly/documentation-framework": "6.0.0-alpha.10",
+    "@patternfly/documentation-framework": "6.0.0-alpha.12",
     "@patternfly/quickstarts": "5.1.0",
     "@patternfly/react-catalog-view-extension": "5.0.0",
     "@patternfly/react-console": "5.0.0",
@@ -27,6 +27,7 @@
     "@patternfly/react-user-feedback": "5.0.0",
     "@patternfly/react-component-groups": "5.0.0-prerelease.10",
     "@patternfly/react-virtualized-extension": "5.0.0",
+    "@patternfly/design-tokens": "1.0.2",
     "react": "^17.0.0 || ^18.0.0",
     "react-dom": "^17.0.0 || ^18.0.0",
     "showdown": "^2.1.0"

diff --git a/packages/documentation-site/patternfly-docs/content/tokens/about-tokens.md b/packages/documentation-site/patternfly-docs/content/tokens/about-tokens.md
@@ -0,0 +1,56 @@
+---
+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. 
+
+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.
+
+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)
+
+## Why use tokens? 
+
+A token system enables a a shared language for building UIs and helps support better consistency and maintenance across the PatternFly design system.
+
+### Consistency 
+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 created more consistently and efficiently.
+
+### 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
+
+PatternFly token names are composed of a `--pf-t` prefix, a version number, and a series of token segments, separated by double hyphens.
+
+<div class="ws-image" style="text-align: center;">
+    <img src="./img/token-name.png"  alt="PatternFly token naming structure."  width="600px"/>
+</div>
+<br />
+
+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. 
+
+| **Segment** | **Description** |
+| --- | --- |
+| Scope | The token's range, such as *global* or *chart*.
+| 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 token's higher level concepts, such as *status*, *primary*, or *action*, which have different variant options.
+| 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. 
+
+* **Palette tokens** use [PatternFly color palettes](/design-foundations/colors#patternfly-palettes) to create a color foundation for other token layers to reference. 
+
+* **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.
+
+* **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. 
+
+<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>
diff --git a/packages/documentation-site/patternfly-docs/content/tokens/design-with-tokens.md b/packages/documentation-site/patternfly-docs/content/tokens/design-with-tokens.md
@@ -0,0 +1,56 @@
+---
+id: Design with tokens
+section: tokens
+---
+
+## Penta design kit
+
+PatternFly tokens are only available as part of the PatternFly 6 [Penta design kit.]() In order to make use of our token system, you will need to [upgrade to PatternFly 6](/get-started/upgrade).
+
+## What is in the Penta design kit
+
+### Tokens 
+
+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). 
+
+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 (--).
+
+<div style="text-align: center;">
+    <img src="./img/token-example-brand.png"  alt="Table of brand color tokens." width="600px"/>
+</div>
+<br />
+
+### Penta component library 
+
+You will have access to all PatternFly tokens when you install the component library. Penta 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 Penta design kit 
+
+To install the Penta design kit, [find instructions in our design onboarding guide.](/get-started/design#figma-library)
+
+### Using Penta components
+
+As you insert a component into a 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>
+<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.
+
+## Migrate to 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 have any existing Sketch-based designs that you want to migrate into Figma, you will need to manually recreate each UI mockup using the Penta component library.
diff --git a/packages/documentation-site/patternfly-docs/content/tokens/develop-with-tokens.md b/packages/documentation-site/patternfly-docs/content/tokens/develop-with-tokens.md
@@ -0,0 +1,22 @@
+---
+id: Develop with tokens
+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).
+
+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.
+
+### 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) 
+
+## 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).
+
+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. 
+
+Once you've completed your migration, you're ready to continue developing with tokens! 
diff --git a/...es/documentation-site/patternfly-docs/content/tokens/img/component-instance.png b/...es/documentation-site/patternfly-docs/content/tokens/img/component-instance.png
diff --git a/...ages/documentation-site/patternfly-docs/content/tokens/img/component-tokens.png b/...ages/documentation-site/patternfly-docs/content/tokens/img/component-tokens.png
diff --git a/...s/documentation-site/patternfly-docs/content/tokens/img/token-example-brand.png b/...s/documentation-site/patternfly-docs/content/tokens/img/token-example-brand.png
diff --git a/.../documentation-site/patternfly-docs/content/tokens/img/token-layers-example.png b/.../documentation-site/patternfly-docs/content/tokens/img/token-layers-example.png
diff --git a/packages/documentation-site/patternfly-docs/content/tokens/img/token-name.png b/packages/documentation-site/patternfly-docs/content/tokens/img/token-name.png
diff --git a/packages/documentation-site/patternfly-docs/patternfly-docs.config.js b/packages/documentation-site/patternfly-docs/patternfly-docs.config.js
@@ -32,6 +32,7 @@ if (process.env.EXTENSIONS_ONLY === 'true') {
     sideNavItems: [
       { section: 'get-started' },
       { section: 'design-foundations' },
+      { section: 'tokens' },
       { section: 'accessibility' },
       { section: 'UX writing' },
       { section: 'components' },

diff --git a/packages/documentation-site/patternfly-docs/patternfly-docs.source.js b/packages/documentation-site/patternfly-docs/patternfly-docs.source.js
@@ -16,6 +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, 'tokens/**/*.md'), 'tokens');
 
     // Gallery pages
     const galleryBase = path.join(__dirname, '../patternfly-docs/pages');
@@ -27,6 +28,12 @@ module.exports = (sourceMD, sourceProps, sourceFunctionDocs) => {
       .replace('package.json', 'pages');
     sourceMD(path.join(themePagesPath, '*.md'), 'pages-overview');
 
+    // Design tokens
+    const designTokensPath = require
+      .resolve('@patternfly/design-tokens/package.json')
+      .replace('package.json', 'patternfly-docs/content');
+    sourceMD(path.join(designTokensPath, '/*.md'), 'tokens');
+
     // Core MD
     const coreDocsPath = require
       .resolve('@patternfly/patternfly/package.json')

diff --git a/yarn.lock b/yarn.lock
@@ -2240,6 +2240,13 @@
     node-addon-api "^3.2.1"
     node-gyp-build "^4.3.0"
 
+"@patternfly/design-tokens@1.0.2":
+  version "1.0.2"
+  resolved "https://registry.yarnpkg.com/@patternfly/design-tokens/-/design-tokens-1.0.2.tgz#7d4114774e4e232614ab786fc32f0a856a269588"
+  integrity sha512-IJCq2VgDkdQMPWF9h9SxtPk0qOEMWEB0etcQGQi5t+eAA0M/0Xf+4o+W5tQmhmTBWCZ8Hunzh6btubys64U71w==
+  dependencies:
+    "@patternfly/react-core" "^6.0.0-alpha.36"
+
 "@patternfly/patternfly-a11y@4.3.1":
   version "4.3.1"
   resolved "https://registry.yarnpkg.com/@patternfly/patternfly-a11y/-/patternfly-a11y-4.3.1.tgz#09f050d3a899a60471519f552d64ecaaeb5fec2f"