[theme] Add HighContrast theme enhancer by silviuaavram · Pull Request #48319 · mui/material-ui

silviuaavram · 2026-04-17T13:23:21Z

I have followed (at least) the PR section of the contributing guide.

Added the changes (excluding the slider borders) to a separate theme object.

To be used like so:

enhanceHighContrast(createTheme(...), {})

Closes #48334
Closes #13174

Preview: https://deploy-preview-48319--material-ui.netlify.app/material-ui/customization/palette/#windows-high-contrast-mode

Improves support for Dark High Contrast by adding a new theme support. The theme support will merge HCL styles on top of an existing theme.

For disabled, use GrayText for border, placeholder and text.
For error, use mark for border and text.
For selected, use Highlight for border, HighlightText for text, and none for forcedColorAdjust.
When both error and disabled are true, disabled wins, since there's no point in showing an error control if we can't do anything about it.
Some docs examples needed style changes since they did not support high contrast.

Colors were chosen based on this doc page.

Use Case	Before	After
Disabled Checkbox
Disabled Radio
Error Radio / FormLabel / FormHelperText
Rating (ButtonBase focus outline / FormControlLabel)
Disabled Inputs — FilledInput, Input, OutlinedInput
Error Inputs — FilledInput, Input, OutlinedInput
Input Placeholder
Disabled Select (NativeSelect icon)
Autocomplete Disabled Options
Autocomplete focused / selected option
Selected MenuItem (also Select and Autocomplete)
ListItemButton hovered / focused / selected + ListItemIcon color
LinearProgress
Disabled Slider
Disabled Switch
Toggle Button Selected
Toggle Button Selected + Hovered
Disabled MenuItem
Tooltip
Disabled Accordion Summary

code-infra-dashboard · 2026-04-17T13:26:14Z

Deploy preview

Bundle size

Bundle	Parsed size	Gzip size
@mui/material	🔺+7.02KB^(+1.38%)	🔺+1.61KB^(+1.10%)
@mui/lab	0B^(0.00%)	0B^(0.00%)
@mui/private-theming	0B^(0.00%)	0B^(0.00%)
@mui/system	0B^(0.00%)	0B^(0.00%)
@mui/utils	0B^(0.00%)	0B^(0.00%)

Details of bundle changes

Check out the code infra dashboard for more information about this PR.

siriwatknp

👍

mnajdova

Please add documentation page for it? It will help with the discoverability.

Copilot

Pull request overview

Adds a new Material UI theme enhancer (enhanceHighContrast) that layers Windows High Contrast / forced-colors component overrides on top of an existing theme, and wires it into the docs demo theming plus documentation.

Changes:

Export enhanceHighContrast from @mui/material/styles (JS + TS entrypoints).
Introduce enhanceHighContrast implementation that injects @media (forced-colors: active) overrides for multiple components with configurable system-color tokens.
Update docs demos to apply the enhancer and add documentation describing usage and token customization.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/mui-material/src/styles/index.js	Re-exports the new `enhanceHighContrast` API from the styles entrypoint.
packages/mui-material/src/styles/index.d.ts	Adds TypeScript exports for `enhanceHighContrast` and `HighContrastTokens`.
packages/mui-material/src/styles/enhanceHighContrast.ts	Implements the theme enhancer and token interface; injects forced-colors overrides for multiple components.
packages-internal/core-docs/src/Demo/DemoThemeProviders.tsx	Applies `enhanceHighContrast` to the docs demo theme setup.
docs/data/material/customization/palette/palette.md	Documents Windows High Contrast Mode usage and available tokens.

Comments suppressed due to low confidence (1)

packages-internal/core-docs/src/Demo/DemoThemeProviders.tsx:56

The enhancer is applied before runtimeTheme is deep-merged. This means any demo-provided runtimeTheme overrides can overwrite/remove the forced-colors component overrides, which is the opposite of the stated goal of layering high-contrast styles on top of an existing theme. Consider deep-merging runtimeTheme first and then running enhanceHighContrast(...) last so HCM overrides reliably win.

    const resultTheme = enhanceHighContrast(
      createTheme(
        {
          cssVariables: {
            colorSchemeSelector: 'data-mui-color-scheme',
          },
          colorSchemes: {
            light: true,
            dark: true,
          },
          direction: direction as 'ltr' | 'rtl',
        },
        dense ? highDensity : {},
      ),
    );
    if (upperMode) {
      Object.assign(resultTheme, resultTheme.colorSchemes[upperMode]);
    }
    if (runtimeTheme && Object.prototype.toString.call(runtimeTheme) === '[object Object]') {
      try {
        return deepmerge(resultTheme, runtimeTheme);
      } catch {

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

mj12albert

Implementation looks good ~ commented on a few docs-related things, additionally enhanceHighContrast could be documented here as well: https://master--material-ui.netlify.app/material-ui/customization/theming/#api

mnajdova · 2026-05-15T11:51:03Z

+import { Theme } from './createTheme';
+
+export interface HighContrastTokens {
+  /** Color for disabled elements. Default: `'GrayText'` */


Suggested change

/** Color for disabled elements. Default: `'GrayText'` */

/**

* Color for disabled elements.

* @default 'GrayText'

*/

We use the JSDOM default tag for default values. Please update everywhere.

mnajdova · 2026-05-15T11:53:17Z

+ * Follows the same signature as `responsiveFontSizes`: accepts a fully-created
+ * theme, merges in HCM component overrides using arrays so that Emotion emits
+ * each entry as a separate CSS rule and the browser cascade (rather than JS


Suggested change

* Follows the same signature as `responsiveFontSizes`: accepts a fully-created

* theme, merges in HCM component overrides using arrays so that Emotion emits

* each entry as a separate CSS rule and the browser cascade (rather than JS

* Accepts a fully-created theme, merges in HCM component overrides using arrays so that Emotion emits

* each entry as a separate CSS rule and the browser cascade (rather than JS

No need to reference other utils here. We'll need to remember to update this comment if that other util changes in the future.

mnajdova · 2026-05-15T11:59:31Z

+
+The following tokens are available:
+
+| Token                | Default            | Description                                     |


Can we use the theme here and show the values for each color? We are already doing it for the regular palette. This table will need to be extracted in a Demo tough, so you can get access to the theme.

mnajdova · 2026-05-21T12:12:09Z

+import Typography from '@mui/material/Typography';
+import { styled } from '@mui/material/styles';
+
+const tokens = [


Ideally we should have extracted this out of API generated code. @dav-is it may be interesting to have a JSON generated for the theme (or parts of it) that we need to document. We could extract this object out of the theme object, but we would miss the description & the default values.

mnajdova

🚢 it

silviuaavram requested review from ZeeshanTamboli, mj12albert, mnajdova and siriwatknp April 17, 2026 13:23

silviuaavram added accessibility a11y customization: theme Higher level theming customizability. type: enhancement It’s an improvement, but we can’t make up our mind whether it's a bug fix or a new feature. labels Apr 17, 2026

silviuaavram self-assigned this Apr 17, 2026

silviuaavram mentioned this pull request Apr 17, 2026

[accessibility] Improve High Contrast Mode styles for some components #48271

Closed

1 task

silviuaavram force-pushed the feat/high-contrast-theme branch from 7f8ca62 to 27ef658 Compare April 21, 2026 12:40

siriwatknp reviewed Apr 22, 2026

View reviewed changes

Comment thread packages/mui-material/src/styles/createHighContrastTheme.ts Outdated

silviuaavram mentioned this pull request Apr 22, 2026

[docs-infra] Fix tab index on base ui tab #48345

Merged

1 task

silviuaavram force-pushed the feat/high-contrast-theme branch from cf4a588 to 4e8f75d Compare May 5, 2026 05:17

siriwatknp reviewed May 5, 2026

View reviewed changes

Comment thread packages/mui-material/src/styles/enhanceHighContrast.ts

siriwatknp reviewed May 5, 2026

View reviewed changes

Comment thread packages/mui-material/src/styles/enhanceHighContrast.ts

siriwatknp approved these changes May 6, 2026

View reviewed changes

mnajdova requested changes May 6, 2026

View reviewed changes

silviuaavram force-pushed the feat/high-contrast-theme branch from b3d5287 to 8f1ea64 Compare May 8, 2026 08:17

silviuaavram marked this pull request as ready for review May 11, 2026 05:28

Copilot AI review requested due to automatic review settings May 11, 2026 05:28

Copilot started reviewing on behalf of silviuaavram May 11, 2026 05:28 View session

Copilot AI reviewed May 11, 2026

View reviewed changes

Comment thread docs/data/material/customization/palette/palette.md Outdated

Comment thread packages/mui-material/src/styles/enhanceHighContrast.ts Outdated

Comment thread packages/mui-material/src/styles/enhanceHighContrast.ts

silviuaavram force-pushed the feat/high-contrast-theme branch from 23fcc50 to a67759e Compare May 11, 2026 12:11

oliviertassinari reviewed May 11, 2026

View reviewed changes

Comment thread docs/data/material/customization/palette/palette.md Outdated

mj12albert reviewed May 13, 2026

View reviewed changes

Comment thread docs/data/material/customization/palette/palette.md Outdated

Comment thread docs/data/material/customization/palette/palette.md Outdated

silviuaavram added 4 commits May 14, 2026 14:38

[theme] HighContrast theme

f1ffd3f

return the theme as an object

9284025

prettier

cbfc59d

fix lint

cff5816

silviuaavram added 18 commits May 14, 2026 14:38

select items focus and hover

ddf8f3e

button base components outline

f5583b9

add input base opacity

f11ee8e

prettier

6e7829a

list item button selected and focused

a1cddfc

list item icon color

620ffba

linear progress visibility

ff2ff46

new API

99fa49c

prettier

7761e4f

use activeText for menu item color

23b3f4f

palette section

adceb26

prettier

c9811d9

rename file

82ca746

more improvements including light hcm

ffcdf8c

code review

5d0344d

tests

b989b19

prettier

e5738b8

fix capitalization

05ce878

mnajdova reviewed May 15, 2026

View reviewed changes

code review

44cdadd

silviuaavram force-pushed the feat/high-contrast-theme branch from 200607f to 44cdadd Compare May 15, 2026 15:18

mnajdova reviewed May 21, 2026

View reviewed changes

silviuaavram added 4 commits May 22, 2026 10:06

add to the theming documentation

ab9b903

add to agents

78d6079

add todo for tokens

bdea243

prettier

6b3f1da

mnajdova changed the title ~~[theme] HighContrast theme~~ [theme] Add HighContrast theme enhancer May 22, 2026

mnajdova approved these changes May 22, 2026

View reviewed changes

silviuaavram merged commit d69827f into mui:master May 22, 2026
22 checks passed

silviuaavram deleted the feat/high-contrast-theme branch May 22, 2026 12:20


		The following tokens are available:

		\| Token \| Default \| Description \|

Uh oh!

Conversation

silviuaavram commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

code-infra-dashboard Bot commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploy preview

Bundle size

Uh oh!

Uh oh!

Uh oh!

Uh oh!

siriwatknp left a comment

Choose a reason for hiding this comment

Uh oh!

mnajdova left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mj12albert left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mnajdova May 15, 2026

Choose a reason for hiding this comment

Uh oh!

mnajdova May 15, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mnajdova May 15, 2026

Choose a reason for hiding this comment

Uh oh!

mnajdova May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mnajdova left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

silviuaavram commented Apr 17, 2026 •

edited

Loading

code-infra-dashboard Bot commented Apr 17, 2026 •

edited

Loading

mnajdova May 21, 2026 •

edited

Loading