[material_ui] Document Material 3 fallback for Divider.color and VerticalDivider.color by gbolahan507 · Pull Request #12967 · flutter/packages

gbolahan507 · 2026-09-22T00:46:14Z

Port of flutter/flutter#193136 — the original PR could not land on flutter/flutter due to the Material/Cupertino code freeze on packages/flutter/lib/src/material (see flutter/flutter#188444). Re-opening the doc fix here in material_ui.

The Divider.color and VerticalDivider.color docstrings currently state that when both the local color and DividerThemeData.color are null, ThemeData.dividerColor is used. In Material 3 (the default since Flutter 3.16) the effective fallback is actually ColorScheme.outlineVariant, as Divider.createBorderSide already documents. This PR aligns the public field docstrings with the actual runtime behavior.

Fixes: flutter/flutter#190534

Notes for reviewers:

The Divider.color docstring is a {@template material_ui.Divider.color} reused via {@macro} elsewhere, so the fix propagates.
VerticalDivider.color carries a duplicate (non-macro) docstring, which has been updated to match.
A prior attempt on flutter/flutter (#190535) was approved by @elliette before being auto-closed for inactivity on a whitespace nit; this port takes that direction into the correct repo per the decoupling policy.

Pre-launch Checklist

…icalDivider.color The Divider.color and VerticalDivider.color docstrings previously stated that when the color and DividerThemeData.color are both null, ThemeData.dividerColor is used. In Material 3 (the default) the effective fallback is actually ColorScheme.outlineVariant. Align the public field docs with the actual behavior. Port of flutter/flutter#193136 (closed due to code freeze on packages/flutter/lib/src/material). Fixes: flutter/flutter#190534

flutter-dashboard · 2026-09-22T00:46:18Z

It looks like this pull request may not have tests. Please make sure to add tests or get an explicit test exemption before merging.

If you are not sure if you need tests, consider this rule of thumb: the purpose of a test is to make sure someone doesn't accidentally revert the fix. Ask yourself, is there anything in your PR that you feel it is important we not accidentally revert back to how it was before your fix?

Reviewers: Read the Tree Hygiene page and make sure this patch meets those guidelines before LGTMing. If you believe this PR qualifies for a test exemption, contact "@test-exemption-reviewer" in the #hackers channel in Discord (don't just cc them here, they won't see it!). The test exemption team is a small volunteer group, so all reviewers should feel empowered to ask for tests, without delegating that responsibility entirely to the test exemption group.

gemini-code-assist

Code Review

This pull request updates the documentation for Divider.color and VerticalDivider.color to describe the Material 3 fallback behavior, and adds a corresponding changelog entry. Feedback suggests using a macro template for VerticalDivider.color to reduce docstring duplication.

gemini-code-assist · 2026-09-22T00:47:19Z

  /// The color to use when painting the line.
  ///
  /// If this is null, then the [DividerThemeData.color] is used. If that is
-  /// also null, then [ThemeData.dividerColor] is used.
+  /// also null, then if [ThemeData.useMaterial3] is true it defaults to
+  /// [ColorScheme.outlineVariant], otherwise [ThemeData.dividerColor] is used.


Instead of duplicating the docstring for VerticalDivider.color, you can use the {@macro material_ui.Divider.color} template defined on Divider.color. This reduces duplication and ensures that any future updates to the fallback documentation automatically propagate to both widgets.

/// {@macro material_ui.Divider.color}

I think this is valid and worth addressing

Hey @elliette — just flagging that ecf95ec applies the {@macro} suggestion. Ready for another look whenever you have a moment, thanks!

elliette

Thanks for porting this over! The Gemini suggestion seems valid, otherwise looks good!

gbolahan507 · 2026-10-01T23:56:00Z

Thanks for the review! Applied the macro suggestion in ecf95ec — VerticalDivider.color now reuses {@macro material_ui.Divider.color} so the two docstrings stay in sync going forward.

QuncCccccc

Thanks a lot for the correction! Overall looks good!

QuncCccccc · 2026-10-09T01:06:44Z

@@ -0,0 +1,3 @@
+changelog: |
+  - Correct the `Divider.color` and `VerticalDivider.color` docstrings to describe the Material 3 fallback behavior (`ColorScheme.outlineVariant` when `ThemeData.useMaterial3` is true, otherwise `ThemeData.dividerColor`).


Just to follow converntion:

Suggested change

- Correct the `Divider.color` and `VerticalDivider.color` docstrings to describe the Material 3 fallback behavior (`ColorScheme.outlineVariant` when `ThemeData.useMaterial3` is true, otherwise `ThemeData.dividerColor`).

- Corrects the `Divider.color` and `VerticalDivider.color` documentation to describe the Material 3 fallback (`ColorScheme.outlineVariant`).

QuncCccccc · 2026-10-09T01:15:03Z

+  /// also null, then if [ThemeData.useMaterial3] is true it defaults to
+  /// [ColorScheme.outlineVariant], otherwise [ThemeData.dividerColor] is used.


useMaterial3 is true by default, so I think we don't need to explicitly mention "if useMaterial3 is true".

Suggested change

/// also null, then if [ThemeData.useMaterial3] is true it defaults to

/// [ColorScheme.outlineVariant], otherwise [ThemeData.dividerColor] is used.

/// also null, then this defaults to [ColorScheme.outlineVariant], or to

/// [ThemeData.dividerColor] if [ThemeData.useMaterial3] is false.

gbolahan507 · 2026-10-09T06:05:10Z

Thanks @QuncCccccc — both applied. Flipped the Divider.color docstring so M3 reads as the default and M2 as the exception, and reworded the changelog bullet to match the house phrasing. Ready for another look when you have a moment.

QuncCccccc

LGTM. Thank you!

auto-submit · 2026-10-09T23:55:48Z

autosubmit label was removed for flutter/packages/12967, because This PR has not met approval requirements for merging. The PR author is not a member of flutter-hackers and needs 1 more review(s) in order to merge this PR.

Merge guidelines: A PR needs at least one approved review if the author is already part of flutter-hackers or two member reviews if the author is not a member of flutter-hackers before re-applying the autosubmit label. Reviewers: If you left a comment approving, please use the "approve" review action instead.

gbolahan507 · 2026-10-15T04:54:57Z

Thanks for the earlier review @elliette — @QuncCccccc approved after some small tweaks, but autosubmit says it needs one more review before merge. Would you mind taking another look when you get a chance?

QuncCccccc · 2026-10-15T16:31:26Z

Hello! @elliette is currently out of office and will get back to this PR once she come back. Thanks a lot for your patience:).

elliette

Thanks for your patience! Looks good

flutter/packages@93baed9...108dad0 2026-10-22 [email protected] [material_ui] Migrate M3 IconButton template to use new gen_defaults (flutter/packages#12922) 2026-10-22 [email protected] [material_ui] Migrate M3 NavigationBar template to use new gen_defaults (flutter/packages#13067) 2026-10-22 [email protected] [material_ui] Remove obsolete `SurfaceTint` defaults template (flutter/packages#13276) 2026-10-22 [email protected] [material_ui] Migrate M3 Radio template to use new gen_defaults (flutter/packages#13210) 2026-10-22 [email protected] [material_ui] Migrate M3 NavigationDrawer template to use new gen_defaults (flutter/packages#13068) 2026-10-22 [email protected] [image_picker_ios] PR 3/5 Split SPM packaging and migrate the plugin class to Swift (flutter/packages#13235) 2026-10-22 [email protected] [ci] Increase check-discovery timeout in release workflows (flutter/packages#13392) 2026-10-22 [email protected] [material_ui] Migrate M3 `Switch` template to use new gen_defaults (flutter/packages#13274) 2026-10-22 [email protected] [material_ui] Migrate M3 PopupMenu template to use new gen_defaults (flutter/packages#13209) 2026-10-22 [email protected] [material_ui] Add day and weekday builders to CalendarDatePicker and showDatePicker (flutter/packages#12587) 2026-10-22 [email protected] [material_ui] Migrate M3 `SearchView` template to use new gen_defaults (flutter/packages#13272) 2026-10-22 [email protected] [material_ui] Migrate M3 `TextField` template to use new gen_defaults (flutter/packages#13275) 2026-10-22 [email protected] [material_ui] Migrate M3 RangeSlider template to use new gen_defaults (flutter/packages#13215) 2026-10-22 [email protected] [go_router] Keep web autocomplete focused in shell routes (flutter/packages#13348) 2026-10-22 [email protected] [shared_preferences_android] Fix web compilation of apps that import the package (flutter/packages#13380) 2026-10-22 [email protected] [material_ui] Migrate M3 NavigationRail template to use new gen_defaults (flutter/packages#13069) 2026-10-22 [email protected] [material_ui] Migrate M3 SearchBar template to use new gen_defaults (flutter/packages#13216) 2026-10-22 [email protected] [material_ui] Fix for time picker error in locales that do not use Latin digits (flutter/packages#13035) 2026-10-22 [email protected] [material_ui] Fix MenuAnchor scrollbar safe-area padding (flutter/packages#12470) 2026-10-22 [email protected] [material_ui] Document Material 3 fallback for Divider.color and VerticalDivider.color (flutter/packages#12967) 2026-10-22 [email protected] [material_ui] Migrate M3 tabs template to use new gen_defaults (flutter/packages#13139) 2026-10-22 [email protected] [material_ui] Migrate M3 progress indicator defaults to new gen_defaults (flutter/packages#13026) 2026-10-22 [email protected] [google_sign_in] Convert the iOS example app and UI tests to Swift (flutter/packages#13271) If this roll has caused a breakage, revert this CL and set the roller to dry run mode using the controls here: https://autoroll.skia.org/r/flutter-packages-flutter-autoroll Please CC [email protected] on the revert to ensure that a human is aware of the problem. To file a bug in Flutter: https://github.com/flutter/flutter/issues/new/choose To report a problem with the AutoRoller itself, please file a bug: https://issues.skia.org/issues/new?component=1389291&template=1850622 Documentation for the AutoRoller is here: https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md

gbolahan507 mentioned this pull request Sep 22, 2026

Document Material 3 fallback for Divider.color and VerticalDivider.color flutter/flutter#193136

Closed

10 tasks done

github-actions Bot added p: material_ui triage-design Should be looked at in design triage labels Sep 22, 2026

gemini-code-assist Bot reviewed Sep 22, 2026

View reviewed changes

gbolahan507 added 4 commits September 22, 2026 15:55

Merge branch 'main' into port-divider-color-m3-fallback

18edae9

Merge branch 'main' into port-divider-color-m3-fallback

79d8037

Merge branch 'main' into port-divider-color-m3-fallback

c085438

Merge branch 'main' into port-divider-color-m3-fallback

aa9b755

elliette self-requested a review September 29, 2026 22:09

elliette reviewed Oct 1, 2026

View reviewed changes

elliette added the CICD Run CI/CD label Oct 1, 2026

Use {@macro} for VerticalDivider.color to deduplicate the docstring

ecf95ec

flutter-dashboard Bot removed the CICD Run CI/CD label Oct 1, 2026

QuncCccccc self-requested a review October 6, 2026 21:26

QuncCccccc reviewed Oct 9, 2026

View reviewed changes

QuncCccccc added the CICD Run CI/CD label Oct 9, 2026

Apply suggestion: use conventional changelog phrasing

e3f8522

flutter-dashboard Bot removed the CICD Run CI/CD label Oct 9, 2026

Apply suggestion: lead with M3 default in Divider.color docstring

6e75acf

QuncCccccc added the CICD Run CI/CD label Oct 9, 2026

QuncCccccc approved these changes Oct 9, 2026

View reviewed changes

QuncCccccc added the autosubmit Merge PR when tree becomes green via auto submit App label Oct 9, 2026

auto-submit Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Oct 9, 2026

QuncCccccc requested a review from elliette October 9, 2026 23:58

elliette approved these changes Oct 22, 2026

View reviewed changes

elliette added the autosubmit Merge PR when tree becomes green via auto submit App label Oct 22, 2026

auto-submit Bot merged commit 6c3361d into flutter:main Oct 22, 2026
14 checks passed

engine-flutter-autoroll mentioned this pull request Oct 23, 2026

Roll Packages from 93baed9106f6 to 108dad0d562e (23 revisions) flutter/flutter#195161

Merged

		@@ -0,0 +1,3 @@
		changelog: \|
		- Correct the `Divider.color` and `VerticalDivider.color` docstrings to describe the Material 3 fallback behavior (`ColorScheme.outlineVariant` when `ThemeData.useMaterial3` is true, otherwise `ThemeData.dividerColor`).

	- Correct the `Divider.color` and `VerticalDivider.color` docstrings to describe the Material 3 fallback behavior (`ColorScheme.outlineVariant` when `ThemeData.useMaterial3` is true, otherwise `ThemeData.dividerColor`).
	- Corrects the `Divider.color` and `VerticalDivider.color` documentation to describe the Material 3 fallback (`ColorScheme.outlineVariant`).

		/// also null, then if [ThemeData.useMaterial3] is true it defaults to
		/// [ColorScheme.outlineVariant], otherwise [ThemeData.dividerColor] is used.

Conversation

gbolahan507 commented Sep 22, 2026

Pre-launch Checklist

Uh oh!

flutter-dashboard Bot commented Sep 22, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Sep 22, 2026

Choose a reason for hiding this comment

Uh oh!

elliette Oct 1, 2026

Choose a reason for hiding this comment

Uh oh!

gbolahan507 Oct 3, 2026

Choose a reason for hiding this comment

Uh oh!

elliette left a comment

Choose a reason for hiding this comment

Uh oh!

gbolahan507 commented Oct 1, 2026

Uh oh!

QuncCccccc left a comment

Choose a reason for hiding this comment

Uh oh!

QuncCccccc Oct 9, 2026

Choose a reason for hiding this comment

Uh oh!

QuncCccccc Oct 9, 2026

Choose a reason for hiding this comment

Uh oh!

gbolahan507 commented Oct 9, 2026

Uh oh!

QuncCccccc left a comment

Choose a reason for hiding this comment

Uh oh!

auto-submit Bot commented Oct 9, 2026

Uh oh!

gbolahan507 commented Oct 15, 2026

Uh oh!

QuncCccccc commented Oct 15, 2026

Uh oh!

elliette left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants