Repository navigation
Description
Use case
Currently, Flutter handles accessibility contrast as a boolean value (MediaQuery.highContrast, MaterialApp.highContrastTheme). This aligns with iOS's binary "Increase Contrast" toggle, where high contrast is either on or off.
But Android supports floating-point contrast levels ranging from -1.0 to 1.0 (where 0.0 is standard, 0.5 is medium, 1.0 is high, and negative values represent lower contrast)
Proposal
First, we need to implement contrast retrieval on all available platforms. Currently, contrast retrieval is implemented using the boolean value via MediaQuery.highContrast and only on iOS (it will be available on Android after this PR is merged).
Second, since highContrastTheme only expects a static ThemeData object, we need a new approach. Here are the options I came up with:
A. Merge into a single theme resolver
theme: (double contrast) => ThemeData(...)
B. Keep the existing theme and highContrastTheme as static ThemeData objects, but use contrast to automatically interpolate between them
if (contrast > 0.0 && highContrastTheme != null) {
return ThemeData.lerp(theme, highContrastTheme, contrast);
}
C. Instead of swapping entire themes, adjust the ColorScheme dynamically based on the contrast
MaterialApp(
theme: ThemeData(
colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue).withContrast(contrast),
),
)
Activity
mbcorona commentedon Feb 25, 2026
Hi @xxxOVALxxx, thanks for the proposal and for linking the related PR, labeling team-accessibility to evaluate.
mmohankrishna-lab commentedon Oct 20, 2026
ThemeData(contrastLevel: ...)andColorScheme.fromSeed(contrastLevel: ...)now support numeric contrast levels (-1.0to1.0) as well as theContrastLevelenum (standard = 0.0,medium = 0.5,high = 1.0), following [flutter/packages#11801](flutter/packages#11801) and [flutter/packages#12743](flutter/packages#12743).Reviewing the proposal's alternatives:
ThemeData.lerp):ColorScheme.lerpperforms linear RGB interpolation (Color.lerp) rather than using Material 3 HCT tones. As a result,t = 0.5fails to matchContrastLevel.medium, can violate WCAG contrast requirements, and is unable to handle negative contrast values.ColorScheme.withContrast):ColorSchemestores only the finalizedColorvalues (omittingseedColoranddynamicSchemeVariant), and this capability is already covered byThemeData(colorSchemeSeed: ..., contrastLevel: ...).MaterialApptheme resolution): Altering the signature ofMaterialApp.themewould be a breaking change, meaning any updates must be additive.Proposed Next Steps
flutter/flutter: Introducedouble contrastLevel(-1.0to1.0, defaulting to0.0) onPlatformDispatcherandMediaQueryData(accessible viaMediaQuery.contrastLevelOf(context)).flutter/packages(material_ui): UpdateMaterialAppto automatically resolve themes based onMediaQuery.contrastLevelOf(context)by introducing:mediumContrastThemeandmediumContrastDarkThemeproperties, and/orthemeBuilder: (Brightness brightness, double contrastLevel) => ThemeData(...)optional callback.cc @QuncCccccc @chunhtai @xxxOVALxxx — Which of these
MaterialAppAPIs does the team prefer?QuncCccccc commentedon Oct 29, 2026
Could you provide more details about this proposal? How do these APIs help with Android's floating-point contrast levels?
mmohankrishna-lab commentedon Oct 29, 2026
Thanks @QuncCccccc! Here are more details on how each option handles Android's floating-point contrast (UiModeManager.getContrast(), which returns a double in [-1.0, 1.0]):
Problem in MaterialApp Today
Currently, MaterialApp only accepts pre-built ThemeData objects (theme, darkTheme, highContrastTheme, highContrastDarkTheme), and _MaterialAppState._themeBuilder only checks the boolean MediaQuery.highContrastOf(context). Because those ThemeData objects are instantiated by the caller before MaterialApp builds, they cannot automatically receive the ambient double contrastLevel from MediaQuery.
How the Two Proposed APIs Work With Floating-Point Contrast
When colorSchemeSeed is used, ThemeData and ColorScheme.fromSeed already support any double in [-1.0, 1.0]. Adding an optional themeBuilder callback on MaterialApp lets _MaterialAppState._themeBuilder pass the resolved Brightness (taking themeMode and MediaQuery.platformBrightnessOf(context) into account) and the exact double contrastLevel from MediaQuery.contrastLevelOf(context) into ThemeData:
Dart
typedef MaterialThemeBuilder = ThemeData Function(
BuildContext context,
Brightness brightness,
double contrastLevel,
);
Usage:
Dart
MaterialApp(
themeMode: ThemeMode.system,
themeBuilder: (BuildContext context, Brightness brightness, double contrastLevel) {
// Receives the exact float in [-1.0, 1.0] from Android (e.g., -0.5, 0.0, 0.5, 1.0)
return ThemeData(
colorSchemeSeed: Colors.blue,
brightness: brightness,
contrastLevel: contrastLevel,
);
},
home: const MyHomePage(),
)
Inside _MaterialAppState._themeBuilder(BuildContext context):
Dart
final double contrastLevel = MediaQuery.contrastLevelOf(context);
if (widget.themeBuilder != null) {
final Brightness effectiveBrightness =
useDarkTheme ? Brightness.dark : Brightness.light;
theme = widget.themeBuilder!(context, effectiveBrightness, contrastLevel);
}
Because _materialBuilder wraps the result in AnimatedTheme, any change to the platform contrast level smoothly animates to the newly generated ThemeData.
When colorSchemeSeed is not provided, ThemeData() only supports the three token-backed Material 3 baseline levels (ContrastLevel.standard = 0.0, ContrastLevel.medium = 0.5, ContrastLevel.high = 1.0), and some apps define separate static ThemeData objects per contrast tier rather than using a seed color.
On Android 14+, the system "Color contrast" setting maps the float in [-1.0, 1.0] to three tiers (0.0 Default, 0.5 Medium, 1.0 High, bucketed in Android's ContrastUtils at thresholds 1/3 and 2/3):
contrastLevel >= 2/3 (or highContrast == true): Use highContrastDarkTheme / highContrastTheme (falling back to ThemeData(contrastLevel: ContrastLevel.high) when no custom theme is provided).
contrastLevel >= 1/3: Use mediumContrastDarkTheme / mediumContrastTheme (falling back to ThemeData(contrastLevel: ContrastLevel.medium) when no custom theme is provided).
Otherwise: Use darkTheme / theme (falling back to ThemeData(contrastLevel: ContrastLevel.standard)).
Usage:
Dart
MaterialApp(
theme: ThemeData(contrastLevel: ContrastLevel.standard),
mediumContrastTheme: ThemeData(contrastLevel: ContrastLevel.medium),
highContrastTheme: ThemeData(contrastLevel: ContrastLevel.high),
darkTheme: ThemeData(brightness: Brightness.dark, contrastLevel: ContrastLevel.standard),
mediumContrastDarkTheme: ThemeData(brightness: Brightness.dark, contrastLevel: ContrastLevel.medium),
highContrastDarkTheme: ThemeData(brightness: Brightness.dark, contrastLevel: ContrastLevel.high),
home: const MyHomePage(),
)
Summary
Would you prefer going with themeBuilder alone, adding mediumContrastTheme / mediumContrastDarkTheme, or supporting both?