Skip to content

Support color contrast-based theme determining #182863

Open

Description

@xxxOVALxxx

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

  1. added
    frameworkflutter/packages/flutter repository. See also f: labels.
    p: material_uimaterial_ui package in flutter/packages
    a: accessibilityAccessibility, e.g. VoiceOver or TalkBack. (aka a11y)
    c: proposalA detailed proposal for a change to Flutter
    in triagePresently being triaged by the triage team
    fyi-androidFor the attention of Android platform team
    fyi-designFor the attention of Design Languages team
    team-accessibilityOwned by Framework Accessibility team (i.e. responsible for accessibility code in flutter/flutter)
    on Feb 25, 2026
  2. mbcorona commented on Feb 25, 2026

    @mbcorona
    Member

    Hi @xxxOVALxxx, thanks for the proposal and for linking the related PR, labeling team-accessibility to evaluate.

  3. removed
    in triagePresently being triaged by the triage team
    on Feb 25, 2026
  4. added
    P2Important issues not at the top of the work list
    triaged-androidTriaged by Android platform team
    on Mar 3, 2026
  5. removed
    fyi-designFor the attention of Design Languages team
    on Mar 4, 2026
  6. added
    packageflutter/packages repository. See also p: labels.
    and removed
    frameworkflutter/packages/flutter repository. See also f: labels.
    on Aug 17, 2026
  7. mmohankrishna-lab commented on Oct 20, 2026

    @mmohankrishna-lab

    ThemeData(contrastLevel: ...) and ColorScheme.fromSeed(contrastLevel: ...) now support numeric contrast levels (-1.0 to 1.0) as well as the ContrastLevel enum (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:

    • Option B (ThemeData.lerp): ColorScheme.lerp performs linear RGB interpolation (Color.lerp) rather than using Material 3 HCT tones. As a result, t = 0.5 fails to match ContrastLevel.medium, can violate WCAG contrast requirements, and is unable to handle negative contrast values.
    • Option C (ColorScheme.withContrast): ColorScheme stores only the finalized Color values (omitting seedColor and dynamicSchemeVariant), and this capability is already covered by ThemeData(colorSchemeSeed: ..., contrastLevel: ...).
    • Option A (MaterialApp theme resolution): Altering the signature of MaterialApp.theme would be a breaking change, meaning any updates must be additive.

    Proposed Next Steps

    1. flutter/flutter: Introduce double contrastLevel (-1.0 to 1.0, defaulting to 0.0) on PlatformDispatcher and MediaQueryData (accessible via MediaQuery.contrastLevelOf(context)).
    2. flutter/packages (material_ui): Update MaterialApp to automatically resolve themes based on MediaQuery.contrastLevelOf(context) by introducing:
    • mediumContrastTheme and mediumContrastDarkTheme properties, and/or
    • A themeBuilder: (Brightness brightness, double contrastLevel) => ThemeData(...) optional callback.

    cc @QuncCccccc @chunhtai @xxxOVALxxx — Which of these MaterialApp APIs does the team prefer?

  8. QuncCccccc commented on Oct 29, 2026

    @QuncCccccc
    Contributor

    2. flutter/packages (material_ui): Update MaterialApp to automatically resolve themes based on MediaQuery.contrastLevelOf(context) by introducing:

    • mediumContrastTheme and mediumContrastDarkTheme properties, and/or
    • A themeBuilder: (Brightness brightness, double contrastLevel) => ThemeData(...) optional callback.

    Could you provide more details about this proposal? How do these APIs help with Android's floating-point contrast levels?

  9. mmohankrishna-lab commented on Oct 29, 2026

    @mmohankrishna-lab

    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

    1. themeBuilder (Supports any continuous double in [-1.0, 1.0])
      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.

    1. mediumContrastTheme / mediumContrastDarkTheme + Default Baseline Resolution (For discrete/non-seed themes)
      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

    1. themeBuilder: Solves continuous floating-point contrast ([-1.0, 1.0]) with a single callback instead of requiring six static ThemeData parameters.
    2. mediumContrastTheme / mediumContrastDarkTheme: Extends the existing highContrastTheme pattern to cover ContrastLevel.medium (0.5) for apps using static ThemeData instances.
    

    Would you prefer going with themeBuilder alone, adding mediumContrastTheme / mediumContrastDarkTheme, or supporting both?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Important issues not at the top of the work lista: accessibilityAccessibility, e.g. VoiceOver or TalkBack. (aka a11y)c: proposalA detailed proposal for a change to Flutterp: material_uimaterial_ui package in flutter/packagespackageflutter/packages repository. See also p: labels.team-accessibilityOwned by Framework Accessibility team (i.e. responsible for accessibility code in flutter/flutter)triaged-accessibilityTriaged by Framework Accessibility team

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions