docs(theming patterns): add best practices

packages/documentation-site/patternfly-docs/content/foundations-and-styles/styles/theming/theming.md

@@ -119,6 +119,49 @@ The following table outlines the availability and compatibility of PatternFly fe
 | Branded icons | Optional (Manual) | Default
 | High contrast support | Yes | Yes |
 
+## Theme controls
+
+Because theme, color scheme, and contrast mode affect both personalization and accessibility, products should give users an easy, discoverable way to adjust them. We recommend exposing these controls from the masthead, using one of the following patterns.
+
+### User preferences page or modal
+
+The masthead's [Settings button or User menu toggle](/components/masthead#elements) opens a menu with a dedicated **User preferences** item. This will trigger either a page or modal, where theme, color scheme, and contrast mode controls appear along with other application-level preferences, such as language or notification settings.
+
+<!-- TODO: replace placeholder screenshot with final PatternFly-style illustration -->
+<div class="ws-docs-content-img">
+![Placeholder screenshot of a preferences page with a Theme dropdown and a Contrast mode dropdown, shown alongside other unrelated application settings like search and project defaults.](./img/theme-switcher-preferences.png)
+</div>
+
+Use this pattern when:
+- Theming controls are one of several User preferences that could be exposed in a single, dedicated location.
+- Your product already has an established settings or preferences experience that you want to extend, rather than introduce a new masthead item.
+- You want to pair each control with additional context, like descriptive helper text, without crowding the masthead.
+
+### Masthead theme switcher
+
+A persistent icon toggle, commonly represented by a sun or moon icon, sits directly in the masthead. Selecting it opens a menu with expanded controls for theme, color scheme, and contrast mode, letting users adjust their preferences without leaving their current page.
+
+<!-- TODO: replace placeholder screenshot with final PatternFly-style illustration -->
+<div class="ws-docs-content-img">
+![Placeholder screenshot of a masthead icon toggle opening a menu with toggle groups for Theme, Color scheme, and Contrast mode.](./img/theme-switcher-masthead-menu.png)
+</div>
+
+Use this pattern when:
+- You want theme controls to be reachable from anywhere in the product, in a single click.
+- Color scheme is the control most users will reach for, with theme and contrast mode as secondary, expanded options.
+- Your product doesn't already have a dedicated settings page or modal, and you don't want to introduce one solely for theming.
+
+### Best practices for Theme controls
+
+Regardless of which pattern you use, keep the following guidelines in mind:
+
+- **Default to the system setting:** Provide a "System" option for color scheme and contrast mode, and select it by default, so your product respects the user's OS- or browser-level preferences until they choose to override them.
+- **Persist user selections:** Store each user's choice, for example in `localStorage` or their account settings, so their preferences are remembered across sessions.
+- **Apply changes immediately:** Update the UI as soon as a user makes a selection, without requiring a separate save or submit action.
+- **Group controls by tier:** Present Theme, Color scheme, and Contrast mode as distinct, clearly labeled groups so users understand how each layer affects their experience.
+- **Match the control to the option count:** Use a toggle group for a small, fixed set of options (like Light, Dark, and System) and a dropdown or select list if you expect to support more options in the future.
+- **Keep accessibility controls easy to find:** Don't bury Contrast mode behind extra steps or unrelated settings. Users who need High contrast, or who need to turn off Glass, should be able to do so quickly.
+
 ## Best practices
 
 To ensure your application is robust, maintainable, and adaptable across different themes, we recommend following these best practices.