diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/dark-theme-handbook.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/dark-theme-handbook.md new file mode 100644 index 0000000000..84f272dfff --- /dev/null +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/dark-theme-handbook.md @@ -0,0 +1,55 @@ +--- +id: Theming +section: design-foundations +source: dark-theme-handbook +--- + +# Dark theme developer handbook + +## Enabling dark theme + +Dark theme is available with PatternFly by default. To enable dark theme, add the class `pf-[version]-theme-dark` (for example, `pf-v6-theme-dark`) to your application's `` tag. This class can be added dynamically to toggle dark theme on and off in your application. + +Dark theme can also be applied based on the browser’s `prefers-color-scheme` media query. When using this method, we recommend using JavaScript to detect the media query and apply the `pf-[version]-theme-dark` class. This allows you to manipulate a single class in order to toggle dark theme based on user preference. [Adam Argyle wrote a great article](https://web.dev/building-a-theme-switch-component/#javascript) on using JavaScript to manage dark theme preference, using the `prefers-color-scheme` media query alongside a manual button that toggles dark theme. + +[Our token resources](https://github.com/patternfly/patternfly/tree/v6/src/patternfly/base/tokens) include styles for both light and dark themes. When dark theme is enabled, your product will automatically pull dark theme tokens in order to adapt visual styles appropriately. + +The only features which will require additional work in order to support dark theme are charts and images. + +### Charts + +To use charts with dark themes, refer to our guidance for [developing with charts](/charts/about-charts#develop-with-charts). + +### Images + +To create images that adapt to light and dark themes, there are a few approaches you can take: + +- Use inline SVG's with fill colors set to [PatternFly color tokens](/tokens/all-patternfly-tokens), which inherently adapt to light and dark themes. +- Create images with colors that work well with both light and dark themes. These colors should meet [WCAG AA contrast requirements](https://webaim.org/resources/contrastchecker/). +- Utilize background color, border color, border-radius, and padding/spacing to create a container that can hold dynamic/user-supplied images. +- Write CSS and dynamically swap between 2 image variations: + + ``` + + + + + ``` + +## Best practices + +The most important step to ensure your application supports dark theme is to follow our [general theming best practices](/design-foundations/theming#best-practices). Adhering to these guidelines, especially by using design tokens instead of hard-coded values, will resolve most adoption challenges. + +Additionally, keep these key points in mind: + +- **Plan for static images:** If you can't use SVGs that are compatible with both light and dark backgrounds, you will need to create two versions of you image and swap them based on the active theme. +- **Test custom components in both themes:** When building custom components, always check your work in both light and dark themes. This helps you catch issues early, like hard-coded colors or styles that don't adapt as expected. \ No newline at end of file diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/high-contrast-handbook.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/high-contrast-handbook.md new file mode 100644 index 0000000000..8a102a9e94 --- /dev/null +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/high-contrast-handbook.md @@ -0,0 +1,68 @@ +--- +id: Theming +section: design-foundations +source: high-contrast-handbook +--- + +# High contrast mode developer handbook + +## High contrast mode vs. forced colors mode + +Our high contrast mode increases the contrast of PatternFly components, often introducing additional borders to distinguish between elements, states, and interactions that otherwise rely on subtle background colors. High contrast mode is enabled by applying styles that are meant to target the [`prefers-contrast: more`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-contrast) media query, which is the mode triggered on MacOS via **System Settings** > **Accessibility** > **Display** > **Increase contrast**. + +This is different from [`forced-colors: active`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/forced-colors), which is a more aggressive contrast mode where the browser enforces a limited, user-chosen color palette on a webpage, often by replacing author-defined colors with CSS system colors and removing styles like background colors and box shadows. Common triggers for forced colors mode are enabling Windows High Contrast Mode and Firefox High Contrast Mode. As outlined in [“Automatic high contrast”](#automatic-high-contrast), we recommend applying high contrast mode when `forced-colors: active` is `true`. + +## Enabling high contrast mode + +High contrast mode is designed to work with both our standard light and dark themes, and it's available with PatternFly by default. To enable high contrast mode, add the class `.pf-v6-theme-high-contrast` to your application’s `` tag. This class can be added dynamically to toggle high contrast mode on and off in your application. + +[Adam Argyle's "Building a theme switch" article](https://web.dev/articles/building/a-theme-switch-component) outlines principles that should be applied to a high contrast mode theme switcher. + +### Automatic high contrast + +To apply high contrast mode automatically, based off of a user’s OS and browser contrast preferences, you can use `window.matchMedia()` to detect the browser’s `prefers-contrast` and `forced-colors` media queries. Because our high contrast mode often introduces additional borders, we recommend detecting `forced-colors` and applying high contrast styles when the value is `active`. + +Even when high contrast mode is enabled automatically, it’s important to also add a manual toggle that allows users to toggle the theme on and off. A user's manual toggle of high contrast should always override the OS and browser preference. + +### Dynamic high contrast + +To allow your users to apply high contrast mode dynamically, independent of their OS and browser preferences, you can place an interactive toggle in a prominent location of your application. It is best practice store a user’s most recent toggle selection by storing their preference in `localStorage`, and using it enable or disable high contrast mode automatically when they return. + +## High contrast design tokens + +The following tokens have been introduced specifically for use in high contrast mode. + +| **Token** | **Default theme value** | **High contrast mode value** | +| :---: | :---: | :---: | +| `--pf-t--global--border--color--high-contrast` | `transparent` | `--pf-t--global--border--color--default`

Light mode value: #4D4D4D
Dark mode value: #C7C7C7 | +| `--pf-t--global--border--width--high-contrast--regular` | 0px | `--pf-t--global--border--width--regular`

Value: 1px | +| `--pf-t--global--border--width--high-contrast--strong` | 0px | `--pf-t--global--border--width--strong`

Value: 2px | +| `--pf-t--global--border--width--high-contrast--extra-strong`| 0px | `--pf-t--global--border--width--extra-strong`

Value: 3px| + +**Note:** The `--pf-t--global--border--color--high-contrast` token can be used strategically to support styles in `forced-colors` mode, as transparent borders will become visible when this mode is active. + +### Plain action tokens + +We also added the following tokens for plain actions (actions with a transparent background). These are now used in PatternFly anywhere where an action has a transparent background, such as plain buttons or navigation items. + +| **Token** | **Default theme value** | **High contrast mode value** | +| :---: | :---: | :---: | +| `--pf-t--global--border--width--action--plain--default` | 0px| 0px| +| `--pf-t--global--border--width--action--plain--hover` | 0px | `--pf-t--global--border--width--100`

Value: 1px | +| `--pf-t--global--border--width--action--plain--clicked` | 0px | `--pf-t--global--border--width--200`

Value: 2px | + +## Best practices + +In addition to the [general theming best practices](/design-foundations/theming#best-practices), ensure that you adhere to the following guidelines when working in high contrast mode. + +### Color and contrast + +- **Meet text contrast ratios:** All normal text must meet a minimum contrast ratio of 7:1 against its background. While WCAG allows a 4.5:1 ratio for large text (18px or larger), it is best to aim for a 7:1 ratio for all text sizes to ensure maximum readability. +- **Meet non-text contrast ratios:** All other UI elements, like icons and borders must meet a minimum contrast ratio of 4.5:1 against their background. + +### Boundaries + +- **Add borders for clarity:** If an element's background color doesn't have a 4.5:1 contrast ratio, add a visible border. For example, add borders to elements with a secondary background color that are placed on top of a primary background. +- **Replace shadows with borders:** To properly separate elements from the background, add a border to any elements that rely on a shadow in default themes. +- **Thicken borders on interaction:** Use border width to provide clear feedback for interactive states. An element's border should become progressively thicker on hover, focus, and click. + - Example: An element with no default border should have a 1px border on hover and a 2px border when clicked. \ No newline at end of file diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/img/components-dark.svg b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/img/components-dark.svg new file mode 100644 index 0000000000..9a34db1186 --- /dev/null +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/img/components-dark.svg @@ -0,0 +1,212 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/img/components-light.svg b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/img/components-light.svg new file mode 100644 index 0000000000..298db20125 --- /dev/null +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/img/components-light.svg @@ -0,0 +1,212 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/theming.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/theming.md new file mode 100644 index 0000000000..7d29c785a1 --- /dev/null +++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/styles/theming/theming.md @@ -0,0 +1,84 @@ +--- +id: Theming +section: design-foundations +source: about +--- + +import '../../components/components.css' +import { Alert, AlertActionLink} from '@patternfly/react-core'; +import ExternalLinkAltIcon from '@patternfly/react-icons/dist/esm/icons/external-link-alt-icon'; + +A **theme** applies a specific visual style to all UI components in order to create a unique, cohesive, and purposeful look. The use of theming can provide more flexibility for user preferences, as well as different options for accessibility needs. + +Theming is supported in PatternFly through [our design token system](/tokens/about-tokens), which was intentionally structured so that sets of tokens can be adjusted together to create alternate UI styles. By reassigning token values, the fonts, spacing, shadows, and borders in a UI can be changed together to create a theme. This system has enabled us to create multiple PatternFly themes, while also supporting the ability for you to create custom themes. + +## PatternFly themes + +The following themes are currently supported across PatternFly components and are designed to meet specific [WCAG accessibility standards](https://www.w3.org/WAI/standards-guidelines/wcag/). You can explore our different themes on our website by toggling your display preferences in our site's masthead dropdown. + +### Light mode + +Generally, light mode is the default appearance of PatternFly. In this mode, dark text is presented on light backgrounds to meet a [text contrast ratio of at least 4.5:1](https://www.w3.org/WAI/WCAG22/quickref/?versions=2.1#contrast-minimum), while colors for other UI elements meet a [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 find it easier to read text on light screens, while others might simply prefer the appearance. + +
+![A collage of multiple light-themed PatternFly components, like a calendar, alert, and menu. The components have white backgrounds and black text.](./img/components-light.svg) +
+ +### 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. + +For development guidance, refer to the [dark theme handbook](/design-foundations/theming/dark-theme-handbook). + +
+![A collage of multiple dark-themed PatternFly components, like a calendar, alert, and menu. The components have dark gray backgrounds and white text.](./img/components-dark.svg) +
+ +### High contrast mode + + +Learn more + +} +> +

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.

+ + +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. + +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. + +For development guidance, refer to the [high contrast handbook](/design-foundations/theming/high-contrast-handbook). + +## Custom themes + +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](/tokens/all-patternfly-tokens) and provide new values to use within your application. + +### When to customize a theme + +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. + +## Using themes in Figma + +Our Figma libraries fully support theming. Designers can create a single layout and then use various Figma "Appearance" settings to swap a wireframe to light, dark, or high contrast mode. This makes it easy to visually test and validate designs across all supported themes. + +## 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 diff --git a/packages/documentation-site/patternfly-docs/content/developer-resources/dark-theme-handbook.md b/packages/documentation-site/patternfly-docs/content/developer-resources/dark-theme-handbook.md deleted file mode 100644 index 0badffb58e..0000000000 --- a/packages/documentation-site/patternfly-docs/content/developer-resources/dark-theme-handbook.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -id: Dark theme handbook -title: PatternFly dark theme handbook -section: developer-resources ---- - -## Enabling dark theme - -Dark theme styles ship with PatternFly CSS by default. To enable dark theme, add the class `pf-[version]-theme-dark` (for example, `pf-v6-theme-dark`) to your application's `` tag. This class can be added dynamically to toggle dark theme on and off in your application. - -Dark theme can also be applied based on the browser’s `prefers-color-scheme` media query. When using this method, we recommend using JavaScript to detect the media query and apply the `pf-[version]-theme-dark` class. This allows you to manipulate a single class in order to toggle dark theme based on user preference. [Adam Argyle wrote a great article](https://web.dev/building-a-theme-switch-component/#javascript) on using JavaScript to manage dark theme preference, using the `prefers-color-scheme` media query alongside a manual button that toggles dark theme. - -[Our token resources](https://github.com/patternfly/patternfly/tree/v6/src/patternfly/base/tokens) include styles for both light and dark themes. When dark theme is enabled, your product will automatically pull dark theme tokens in order to adapt visual styles appropriately. - -The only features which will require additional work in order to support dark theme are charts and images. - -### Charts - -To use charts with dark themes, refer to our guidance for [developing with charts](/charts/about-charts#develop-with-charts). - -### Images - -To create images that adapt to light and dark themes, there are a few approaches you can take: - -- Use inline SVG's with fill colors set to [PatternFly color tokens](/tokens/all-patternfly-tokens), which inherently adapt to light and dark themes. -- Create images with colors that work well with both light and dark themes. These colors should meet [WCAG AA contrast requirements](https://webaim.org/resources/contrastchecker/). -- Utilize background color, border color, border-radius, and padding/spacing to create a container that can hold dynamic/user-supplied images. -- Write CSS and dynamically swap between 2 image variations: - - ``` - - - - - ``` - -## Best practices - -To make it easier to support light and dark theming in your application, we recommend following these best practices during design and development: - -* **Use PatternFly components without customizations.** Most problems with dark theming are due to the use of custom styles, overrides to PatternFly styles, and non-PatternFly components. To ensure consistent styling and behavior when switching themes, try to use PatternFly components as they are. - -* **Use tokens and component variables to define any overrides.** - * For example, to override a primary button’s background color, declare `.pf-[version]-c-button { --pf-[version]-c-button--m-primary--BackgroundColor: [color token]; }` instead of `.pf-[version]-c-button.pf-m-primary { background-color: [color token]; }`. - -* **Use tokens in custom styles.** - * For example, use `background-color: var(--pf-t--[version]--global--background--color--primary--default)` for a primary background instead of `background-color: #fff` or `background-color: white`. Values like `#fff` and `white` will not change between light and dark theme, but tokens will. - -* **Always use the most relevant semantic token for your use case.** If there isn't a semantic token for your scenario, then you can use a base token. Never use a palette token directly in your code. - * For example, `--pf-t--[version]--global--text--color--link--default`, `--pf-t--[version]--color--blue--20`, and `#b9dafc` are all the same in PatternFly's default light theme. When you create something custom, where the color should match the application’s link text color, any of these values will work. However, in a different theme, these token values may not always be the same color. - -* **Use SVG files or icon fonts for icons, and use tokens for icon colors.** To easily manipulate icon colors between light and dark theme, SVG files and icon fonts can be changed via CSS by using the `fill` and `color` properties. When using semantic tokens, like `--pf-t--[version]--global--color--status--info--default`, colors will automatically adjust between light and dark theme. If images must be used, we advise you to use colors that work well in both light and dark themes and/or hide and show the appropriate images based on the presence of the dark theme body class. \ No newline at end of file diff --git a/packages/documentation-site/patternfly-docs/content/get-started/release-highlights.md b/packages/documentation-site/patternfly-docs/content/get-started/release-highlights.md index 74be13a2ca..31b9a003c7 100644 --- a/packages/documentation-site/patternfly-docs/content/get-started/release-highlights.md +++ b/packages/documentation-site/patternfly-docs/content/get-started/release-highlights.md @@ -743,6 +743,6 @@ All of our components have a new look to match. As you use the alpha website, ta In order to support PatternFly 6, and any future visual theming capabilities, we have implemented a design token system for PatternFly. For more details and instructions on how to use tokens, you can refer to our new [design token documentation](/tokens/about-tokens). -Our tokens cover both dark and light themes, and make it easier to support both in your product. We also updated our [dark theme handbook](/developer-resources/dark-theme-handbook) to align with our tokens. +Our tokens cover both dark and light themes, and make it easier to support both in your product. We also updated our [dark theme handbook](/design-foundations/theming/dark-theme-handbook) to align with our tokens. **Note:*- The PatternFly 5 design library is not built with tokens. To take advantage of our token system, you must [upgrade your product to PatternFly 6](/get-started/upgrade). 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 index 4ac133506a..0c537dc286 100644 --- a/packages/documentation-site/patternfly-docs/content/tokens/develop-with-tokens.md +++ b/packages/documentation-site/patternfly-docs/content/tokens/develop-with-tokens.md @@ -17,7 +17,7 @@ In the event that there isn't a semantic token that fits your use case, then you 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 `` 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) +For more information, refer to our [dark theme handbook.](/design-foundations/theming/dark-theme-handbook) ## Migrate to tokens diff --git a/packages/site/src/content/get-started/release-highlights.mdx b/packages/site/src/content/get-started/release-highlights.mdx index cef730fe87..8952b70181 100644 --- a/packages/site/src/content/get-started/release-highlights.mdx +++ b/packages/site/src/content/get-started/release-highlights.mdx @@ -437,6 +437,6 @@ All of our components have a new look to match. As you use the alpha website, ta In order to support PatternFly 6, and any future visual theming capabilities, we have implemented a design token system for PatternFly. For more details and instructions on how to use tokens, you can refer to our new [design token documentation](/tokens/about-tokens). -Our tokens cover both dark and light themes, and make it easier to support both in your product. We also updated our [dark theme handbook](/developer-resources/dark-theme-handbook) to align with our tokens. +Our tokens cover both dark and light themes, and make it easier to support both in your product. We also updated our [dark theme handbook](/design-foundations/theming/dark-theme-handbook) to align with our tokens. **Note:*- The PatternFly 5 design library is not built with tokens. To take advantage of our token system, you must [upgrade your product to PatternFly 6](/get-started/upgrade).