docs(theming): Adds details around new theme and glass mode.#4983
Conversation
|
|
||
| ### Swapping contrast modes | ||
|
|
||
| To swap your components to our high contrast mode, change the Semantic Dimension Tokens variable mode to be "High Contrast" and choose either "Light - High Contrast" or "Dark - High Contrast" for the Semantic Color Tokens variable mode: |
There was a problem hiding this comment.
will want to update this to include glass
There was a problem hiding this comment.
also to include the default vs felt theme toggle!
glass has some weirdness where users will have to switch the the "glass" or "plain" style variant of certain components in addition to setting the appearance toggles in order to get the glass mode to appear properly in figma.
|
Just a couple of comments here on the glass mode handbook. Parts of this Opacity section seem to be at odds with the Glass design tokens table below it. Opacity Felt light typically utilizes a 40% opacity to maintain AAA contrast for standard text. Given that a variety of opacity percentages are shown in the table, this seems confusing to cite specific ones for each mode. Also, instead of "reliability" did you intend "readability"? If a product team chooses to override these token values, they are responsible for conducting their own accessibility evaluation to ensure WCAG compliance. I would not use "token values" in the above sentence, since you only referred to base opacity levels and not the tokens themselves. I'm not well-versed in the actual values and tokens tha we've eventually decided on, so someone else will have to review those details. Everything else looked good! |
nicolethoen
left a comment
nicolethoen
left a comment
There was a problem hiding this comment.
This is excellent. Covers all I would expect. I'll defer to others for verifying accuracy of the nuances of tokens and settings.
|
@lboehling @mcoker Could you help verify the accuracy of what I've added in this pr? any suggestions or clarifications are much appreciated! |
Corrected a typo in the Project Felt theme description.
|
note: I'll this could merge first & I could update after, or we could wait. Either way |
|
|
||
| There are a few technical constraints to abide by when using glass in your product. | ||
|
|
||
| - **No glass-on-glass layering:** Never layer glass-enabled containers. Doing so can cause significant performance and accessibility problems. For example, child objects inside a blurred parent container can become illegibly blurred themselves. To mitigate this, we have intentionally adjusted the opacity of our background color design tokens to simulate depth without introducing extra blur. |
There was a problem hiding this comment.
might be worth noting that we have introduced opaque styles for any items that are floating directly on top of glass elements (i.e. sticky sections, menus, popovers, overlay drawers, etc.)
|
|
||
| | Token | Value (in Project Felt theme) | Usage | | ||
| | --- | --- | --- | | ||
| | `--pf-t--global--background--color--glass--primary--default` | Light mode value: #FFFFFF (60% opacity) <br /> Dark mode value: #292929 at 50% opacity | Base fill for glass containers. | |
| | Token | Value (in Project Felt theme) | Usage | | ||
| | --- | --- | --- | | ||
| | `--pf-t--global--background--color--glass--primary--default` | Light mode value: #FFFFFF (60% opacity) <br /> Dark mode value: #292929 at 50% opacity | Base fill for glass containers. | | ||
| | `--pf-t--global--background--filter--glass--default` | Light mode value: #C7C7C7 (25% opacity) <br /> Dark mode value: #C7C7C7 (15% opacity) | Overlay tint used to enhance blur visibility. | |
There was a problem hiding this comment.
we dropped this to a lower 16% blur in both themes. also this is not an overlay tint, its the actual blur value!
| | --- | --- | --- | | ||
| | `--pf-t--global--background--color--glass--primary--default` | Light mode value: #FFFFFF (60% opacity) <br /> Dark mode value: #292929 at 50% opacity | Base fill for glass containers. | | ||
| | `--pf-t--global--background--filter--glass--default` | Light mode value: #C7C7C7 (25% opacity) <br /> Dark mode value: #C7C7C7 (15% opacity) | Overlay tint used to enhance blur visibility. | | ||
| | `--pf-t--global--border--color--glass--default` | Light mode value: #FFFFFF (60% opacity) <br /> Dark mode value: #292929 (50% opacity) | Boundary highlight for glass surfaces. | |
There was a problem hiding this comment.
this references our border--color--alt token in glass mode (which maps to primary bkg color)
lboehling
left a comment
lboehling
left a comment
There was a problem hiding this comment.
thanks erin! left a few comments in line!
other questions/notes --
-
I've added some details around adjusting the additional themes and modes in the PF6 Component Library. This could be a helpful reference for the figma section of the theming overview page.
-
in the glass handbook -- do we want to mention the addition of "plain" variants across several components so that they receive a transparent bkg when placed on a glass element? most of these are turned on my default in glass mode i believe.
…s-and-styles/styles/theming/theming.md Co-authored-by: Michael Coker <35148959+mcoker@users.noreply.github.com>
| High contrast can be enabled manually by users or triggered automatically by OS- and browser-level accessibility settings such as forced colors mode. System-level preferences take precedence over PatternFly theme settings, so users who have already configured high contrast in their OS or browser will get a consistent experience without conflict. | ||
|
|
||
| ## Using themes in Figma | ||
| **Note:** Activating high contrast mode will override and disable glass mode—whether triggered manually or via the OS-level `prefers-reduced-transparency` media query. |
There was a problem hiding this comment.
This may be known/implied here, and it's kind of a nit picky detail, but I'll just mention that this doesn't happen automatically from patternfly. If someone using patternfly applies the glass theme class and the high contrast class, they'll get a mix of styles. It would be up to the user to make sure that glass and high contrast theme are not applied at the same time.
| - **Layout variations:** A banded masthead (with a solid fill and shadowed border to anchor it above the page) and a floating side navigation (with a solid fill and shadow to visually separate it from glass content) are automatically used in place of their standard counterparts. | ||
|
|
||
| ### High contrast mode | ||
| Products using glass mode must provide users a clear way to switch to default contrast or high contrast. When high contrast is enabled—manually or via the OS-level `prefers-reduced-transparency` media query—glass effects are automatically disabled. |
There was a problem hiding this comment.
Same comment here as https://github.com/patternfly/patternfly-org/pull/4983/changes#r3276026525. Just want to make sure it's clear that this isn't provided by patternfly - it's up to users to make sure they respect users' preferences. Also along with prefers-reduced-transparency, there is a prefers-contrast media query that should be respected.
| - **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 | ||
| - 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`). |
There was a problem hiding this comment.
dot for consistency since it's used in the other classes in this doc.
| - 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`). | |
| - 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`). |
| When glass is enabled, the following changes will apply: | ||
| - **Transparency, blur, and shadows:** Surface-level container backgrounds become semi-transparent and apply blur and shadow adjustments, letting content below subtly show through to create a sense of depth and content hierarchy. | ||
| - **Background image:** A brand-approved background image fills the page body, providing the visual layer that glass containers sit above. Product teams must use approved images and ensure text is never placed outside of a container and directly on top of a background image. | ||
| - **Component-level glass:** Glass automatically applies to the login page, masthead, navigation, and page. It can be manually extended to cards, drawers, and panels. |
There was a problem hiding this comment.
Just to match the list on https://pf-org--pr-4983-site.surge.sh/foundations-and-styles/theming/glass-mode-handbook/. Not sure if it should be plural or not
| - **Component-level glass:** Glass automatically applies to the login page, masthead, navigation, and page. It can be manually extended to cards, drawers, and panels. | |
| - **Component-level glass:** Glass automatically applies to the login page, masthead, navigation, and page. It can be manually extended to cards, drawers, hero, and panels. |
mcoker
left a comment
mcoker
left a comment
There was a problem hiding this comment.
NICE!!! Massive updates, and great job as always 👏
9 participants
Makes progress on #4952 and #4951
updated https://pf-org--pr-4983-site.surge.sh/foundations-and-styles/theming
and added https://pf-org--pr-4983-site.surge.sh/foundations-and-styles/theming/glass-mode-handbook
Both of which will need Dev/Design input and validation. Will probably want some images to support the /theming docs (assume these can't be created until the tokens and kit updates are available):