@@ -54,42 +57,54 @@ Generally, light mode is the default appearance of PatternFly. In this mode, dar
### Dark mode
-In dark mode, light text is presented on dark backgrounds backgrounds, and our color palette adapts to maintain a [text contrast ratio of at least 4.5:1](https://www.w3.org/WAI/WCAG22/quickref/?versions=2.1#contrast-minimum) and [non-text contrast ratio of at least 3:1](https://www.w3.org/WAI/WCAG22/quickref/?versions=2.1#non-text-contrast). Some users might prefer dark mode for aesthetics, while others find it to be easier on the eyes and less straining for those with light sensitivities.
+Dark mode adapts color palettes for light-sensitive users or low-light environments. It presents light text on dark backgrounds backgrounds while maintaining the same accessibility ratios as light mode. Some users might prefer dark mode for aesthetics, while others find it to be easier on the eyes and less straining for those with light sensitivities.
-For development guidance, refer to the [dark theme handbook](/foundations-and-styles/theming/dark-theme-handbook).
+For implementation guidance, refer to the [dark theme handbook](/foundations-and-styles/theming/dark-theme-handbook).
-### High contrast mode
+## Contrast modes
-
- High contrast mode is still under development and will continue to evolve and be enabled for charts and extensions. This beta allows you to preview our progress.
-
+Contrast modes adjust the surface treatment of UI elements across both color schemes. They are mutually exclusive and can't be applied simultaneously.
-High contrast mode adjusts our default colors to meet an [enhanced contrast ratio of at least 7:1](https://www.w3.org/WAI/WCAG21/Understanding/contrast-enhanced.html), making it more suitable for users who require higher contrast between UI elements. By using wider border strokes and adjusted fill colors, high contrast mode creates more visual distinction and clarity between interactive elements.
+### High contrast
-In high contrast mode, distinct borders are also added to components to ensure that their boundaries are clearly defined without requiring users to rely on subtle background colors as a visual cue.
+High contrast mode is focused on improving accessibility for users who require more clarity and higher contrast between UI elements. Turned on by user preference, high contrast mode adjusts border strokes and colors to meet an [enhanced contrast ratio of at least 7:1](https://www.w3.org/WAI/WCAG21/Understanding/contrast-enhanced.html).
-For development guidance, refer to the [high contrast handbook](/foundations-and-styles/theming/high-contrast-handbook).
+**Note:** Activating high contrast mode will override and disable glass mode to ensure all boundaries and text meet strict accessibility requirements.
+
+For implementation guidance, refer to the [high contrast handbook](/foundations-and-styles/theming/high-contrast-handbook).
-## Custom themes
+### Glass
-To branch off of our themes and create your own, you can identify the design tokens you'd like to adjust on our [all tokens page](/foundations-and-styles/design-tokens/all-design-tokens) and provide new values to use within your application.
+Glass mode introduces transparency and depth to the UI, creating a layered visual effect. It is enabled in the Unified theme by default, but can also be manually enabled in the Default theme.
-### When to customize a theme
+When glass is enabled, the following changes will apply:
+- **Transparency:** Container backgrounds will become more transparent, allowing the content below to subtly show through.
+- **Background image:** A pre-approved background image will fill the page body. Product teams must work with the Brand team ensure these images maintain accessibility compliance behind UI elements.
+- **Layout changes:** Layout variations, including the banded masthead and floating side navigation.
-There are a couple of instances when you might want to adjust an existing PatternFly theme:
-- One-off adjustments, like changing a single button color, spacer, or font size, when intentional deviation is needed across your product.
-- Application-wide adjustments, like changing all button colors and font sizes to adjust the overall brand identity of your product.
+For implementation guidance, refer to the glass handbook.
+
+## Feature compatibility
+
+The following table outlines the availability and compatibility of PatternFly features across themes.
+
+| Feature | Default theme | Unified theme |
+| --- | --- | --- |
+| Accent color | Blue | Red |
+| Interactive element colors | Blue | Blue |
+| Border radius shape | Square | Pill |
+| Default contrast mode | Standard | Glass |
+| Background image | Optional (Manual) | Required (with glass mode) |
+| Branded icons | Optional (Manual) | Default
+| High contrast support | Yes | Yes |
## Using themes in Figma
@@ -97,6 +112,10 @@ Our Figma libraries fully support theming. Designers can create a single design
The standard light PatternFly theme will be applied to components by default. If you want your mockups to use our dark or high contrast themes, you will need to adjust the following settings in Figma.
+### Unified theme
+
+To swap between the Default and Unified themes, adjust the themevariable mode. The Unified mode will automatically apply the red accents, pill shapes, and glass treatment.
+
### Dark mode
To swap your components to our standard dark mode, change the Semantic Color Tokens variable mode to be "Dark":
From 1f44f70f26b8e35d6123791676ccaa837a7db61b Mon Sep 17 00:00:00 2001
From: Erin Donehoo <105813956+edonehoo@users.noreply.github.com>
Date: Fri, 27 Mar 2026 13:42:38 -0400
Subject: [PATCH 03/29] docs(theming): Update theming docs.
---
.../styles/theming/theming.md | 49 +++++++++----------
1 file changed, 24 insertions(+), 25 deletions(-)
diff --git a/packages/documentation-site/patternfly-docs/content/foundations-and-styles/styles/theming/theming.md b/packages/documentation-site/patternfly-docs/content/foundations-and-styles/styles/theming/theming.md
index 5ae7f27d7d..41484bef02 100644
--- a/packages/documentation-site/patternfly-docs/content/foundations-and-styles/styles/theming/theming.md
+++ b/packages/documentation-site/patternfly-docs/content/foundations-and-styles/styles/theming/theming.md
@@ -106,17 +106,35 @@ The following table outlines the availability and compatibility of PatternFly fe
| Branded icons | Optional (Manual) | Default
| High contrast support | Yes | Yes |
-## Using themes in Figma
+
+## Best practices
+
+To ensure your application is robust, maintainable, and adaptable across different themes, we recommend following these best practices.
+
+- **Use default PatternFly components:** Whenever possible, use PatternFly components as they are. This ensures you stay up-to-date with our intended design, functionality, and accessibility standards. It also makes upgrades more seamless, decreases development time, and guarantees consistency across applications.
+- **Use design tokens and variables for customizations:** If you must customize a component, use the appropriate method:
+ - **Design tokens:** For global changes
+ - **Component variables:** For component-specific changes
+ - Example: To override a primary button’s background color, declare `.pf-v6-c-button { --pf-v6-c-button--m-primary--BackgroundColor: [color token]; }` instead of `.pf-v6-c-button.pf-m-primary { background-color: [color token]; }`.
+- **Always use tokens to create custom styles:** When creating custom components or styles, never use hard-coded values like hex codes or color names (`#fff` or `white`). Instead, use the appropriate design token, such as `var(--pf-t--global--background--color--primary--default)`. Tokens automatically adapt to different themes, while hard-coded values do not.
+- **Prioritize semantic tokens:** Always use the most relevant semantic token for your use case to ensure the element's purpose is clear and that it receives the correct styling in any theme. If no semantic token exists, you can fall back to a base token.
+- **Never use a palette token**: Do not use palette tokens (like `--pf-t--color--blue--20`) directly in your code, as the value is not guaranteed to be consistent across themes.
+- **Use scalable icons:** For icons, use vector images (SVG) or icon fonts instead of raster or bitmap images (PNG, JPEG, GIF, BMP, and so on). This allows you to control their color with CSS `fill` and `color` properties. By assigning a design token to these properties, your icons will automatically change color to match the active theme.
+ - If you must use static images, you might need to hide and show different image files based presence of a theme-specific class (like `pf-v6-theme-dark`).
+
+## Theming in Figma
Our Figma libraries fully support theming. Designers can create a single design and then swap between our themes using the "Apply Variable Mode" toggles in the "Appearance" section of the component properties panel. This makes it easy to visually test and validate designs across all supported themes.
The standard light PatternFly theme will be applied to components by default. If you want your mockups to use our dark or high contrast themes, you will need to adjust the following settings in Figma.
-### Unified theme
+**Note:** Our charts use a unique token collection, so you will need to adjust chart variable modes separately from components in order to swap themes. To change the variable mode for charts, follow the same steps outlined for component theme adjustments.
-To swap between the Default and Unified themes, adjust the themevariable mode. The Unified mode will automatically apply the red accents, pill shapes, and glass treatment.
+### Swapping themes
-### Dark mode
+To swap between the Default and Unified themes, adjust the theme variable mode. The Unified mode will automatically apply the red accents, pill shapes, and glass treatment.
+
+### Swapping color schemes
To swap your components to our standard dark mode, change the Semantic Color Tokens variable mode to be "Dark":
@@ -124,29 +142,10 @@ To swap your components to our standard dark mode, change the Semantic Color Tok
-
-
-### Chart themes
-
-Our charts use a unique token collection, so you will need to adjust chart variable modes separately from components in order to swap themes. To change the variable mode for charts, follow the same steps previously outlined for component theme adjustments.
-
-## Best practices
-
-To ensure your application is robust, maintainable, and adaptable across different themes, we recommend following these best practices.
-
-- **Use default PatternFly components:** Whenever possible, use PatternFly components as they are. This ensures you stay up-to-date with our intended design, functionality, and accessibility standards. It also makes upgrades more seamless, decreases development time, and guarantees consistency across applications.
-- **Use design tokens and variables for customizations:** If you must customize a component, use the appropriate method:
- - **Design tokens:** For global changes
- - **Component variables:** For component-specific changes
- - Example: To override a primary button’s background color, declare `.pf-v6-c-button { --pf-v6-c-button--m-primary--BackgroundColor: [color token]; }` instead of `.pf-v6-c-button.pf-m-primary { background-color: [color token]; }`.
-- **Always use tokens to create custom styles:** When creating custom components or styles, never use hard-coded values like hex codes or color names (`#fff` or `white`). Instead, use the appropriate design token, such as `var(--pf-t--global--background--color--primary--default)`. Tokens automatically adapt to different themes, while hard-coded values do not.
-- **Prioritize semantic tokens:** Always use the most relevant semantic token for your use case to ensure the element's purpose is clear and that it receives the correct styling in any theme. If no semantic token exists, you can fall back to a base token.
-- **Never use a palette token**: Do not use palette tokens (like `--pf-t--color--blue--20`) directly in your code, as the value is not guaranteed to be consistent across themes.
-- **Use scalable icons:** For icons, use vector images (SVG) or icon fonts instead of raster or bitmap images (PNG, JPEG, GIF, BMP, and so on). This allows you to control their color with CSS `fill` and `color` properties. By assigning a design token to these properties, your icons will automatically change color to match the active theme.
- - If you must use static images, you might need to hide and show different image files based presence of a theme-specific class (like `pf-v6-theme-dark`).
\ No newline at end of file
+
\ No newline at end of file
From deb9a60ebb094d0af0585bce49c942eaecb48ae4 Mon Sep 17 00:00:00 2001
From: Erin Donehoo <105813956+edonehoo@users.noreply.github.com>
Date: Tue, 31 Mar 2026 10:11:35 -0400
Subject: [PATCH 04/29] Adds glass mode handbook outline draft.
---
.../styles/colors/colors.md | 2 +
.../styles/theming/glass-mode-handbook.md | 41 +++++++++++++++++++
.../styles/theming/theming.md | 20 ++++-----
3 files changed, 53 insertions(+), 10 deletions(-)
create mode 100644 packages/documentation-site/patternfly-docs/content/foundations-and-styles/styles/theming/glass-mode-handbook.md
diff --git a/packages/documentation-site/patternfly-docs/content/foundations-and-styles/styles/colors/colors.md b/packages/documentation-site/patternfly-docs/content/foundations-and-styles/styles/colors/colors.md
index 6a77d020d9..bc46c99614 100644
--- a/packages/documentation-site/patternfly-docs/content/foundations-and-styles/styles/colors/colors.md
+++ b/packages/documentation-site/patternfly-docs/content/foundations-and-styles/styles/colors/colors.md
@@ -190,6 +190,8 @@ Status and state colors are indicators that communicate data and actions to user
To check the contrast between background and text colors, use a