Currently, `Switch.factory` delegates to `CupertinoSwitch` when platform
is iOS or macOS. This PR is to:
* have the factory configure the Material `Switch` for the expected look
and feel.
* introduce `Adaptation` class to customize themes for the adaptive
components.

Provide a helpful error message when `ColorScheme.brightness` doesn't match `ThemeData.brightness` (#137611)

fixes [Unexpected behaviour with ColorScheme.fromSeed and Brightness.dark](https://github.com/flutter/flutter/issues/127523)

This comment on _localizedThemeDataCacheSize was a bit garbled from getting split up, and the doc on _localizedThemeDataCache was missing from having been moved elsewhere.

It looks like the dislocation happened in 8b86d238 (#116088), which was otherwise making unrelated changes, including a couple of lines near these.  Likely it was due to an error in resolving merge or rebase conflicts at some point while revising that PR.

This fixes/notates a few deprecations from an audit for the next tech debt cycle.

- ThemeData errorColor and backgroundColor are notated as deprecated in multiple places, but one usage had a different version tag. Updated to match the rest.
- ThemeData.copyWith useMaterial3 was deprecated because it did not do what developers expected - it did not automatically reassign all of the color values and such. (confirmed with @HansMuller) I added a note so that when we later remove it we don't introduce a bug.
- the describeEnum deprecation was tagged wrong, it was a very long PR so by the time it merged the version it was finally tagged with was much later. (https://github.com/flutter/flutter/pull/125016)

## Description

This removes all of the comments that are of the form "so-and-so (must not be null|can ?not be null|must be non-null)" from the cases where those values are defines as non-nullable values.

This PR removes them from the material library.

This was done by hand, since it really didn't lend itself to scripting, so it needs to be more than just spot-checked, I think. I was careful to leave any comment that referred to parameters that were nullable, but I may have missed some.

In addition to being no longer relevant after null safety has been made the default, these comments were largely fragile, in that it was easy for them to get out of date, and not be accurate anymore anyhow.

This did create a number of constructor comments which basically say "Creates a [Foo].", but I don't really know how to avoid that in a large scale change, since there's not much you can really say in a lot of cases.  I think we might consider some leniency for constructors to the "Comment must be meaningful" style guidance (which we de facto have already, since there are a bunch of these).

## Related PRs
- https://github.com/flutter/flutter/pull/134984
- https://github.com/flutter/flutter/pull/134992
- https://github.com/flutter/flutter/pull/134993
- https://github.com/flutter/flutter/pull/134994

## Tests
 - Documentation only change.

Catch up document. As Material 3 actually use a purple theme.

https://github.com/flutter/flutter/blob/d8cbaf62615497fdb1e51167d0eb306a2d7b7bcf/packages/flutter/lib/src/material/theme_data.dart#L2777-L2856

Fixes https://github.com/flutter/flutter/issues/130761

fixes [[Material3] AppBar does not respect `foregroundColor` or `iconTheme` for leading and actions in some cases](https://github.com/flutter/flutter/issues/130485)

### Description

- Fix `Colors.white` not applied in dark mode
- Add regression tests
- make `iconStyle` private for consistency

### Before
![Screenshot 2023-07-14 at 18 40 58](https://github.com/flutter/flutter/assets/48603081/a6caffd6-d9a1-407a-aea7-c30047bfe7c7)

### After
![Screenshot 2023-07-14 at 18 41 04](https://github.com/flutter/flutter/assets/48603081/f864da7a-2ff8-46a4-8927-591e50050502)

Changes the default for `ThemeData.useMaterial3` to true.

See https://github.com/flutter/flutter/issues/127064

## Description

This improves defaults generation with logging, stats, and token validation. 

This PR includes these changes:
* introduce `TokenLogger`, with a verbose mode
  * prints versions and tokens usage to the console
  * outputs `generated/used_tokens.csv`, a list of all used tokens, for use by Google
* find token files in `data` automatically
* hide tokens `Map`
  * tokens can be obtained using existing resolvers (e.g. `color`, `shape`), or directly through `getToken`.
  * tokens can be checked for existence with `tokenAvailable`
* remove version from template, since the tokens are aggregated and multiple versions are possible (as is the case currently), it does not make sense to attribute a single version
* improve documentation

## Related Issues
 - Fixes https://github.com/flutter/flutter/issues/122602

## Tests
 - Added tests for `TokenLogger`
 - Regenerated tokens, no-op except version removal

## Future work
A future PR should replace or remove the following invalid tokens usages

<img width="578" alt="image" src="https://github.com/flutter/flutter/assets/6655696/b6f9e5a7-523f-4f72-94f9-1b0bf4cc9f00">

## Description

Removes references to `ThemeData.primaryColorBrightness`, deprecated in https://github.com/flutter/flutter/pull/93396 and subject to remove now because of our [deprecation policy](https://github.com/flutter/flutter/wiki/Tree-hygiene#deprecations).

## Related PRs
 - https://github.com/flutter/flutter/pull/93396

## Tests
 - Removed unneeded tests, removed references.

This PR is to remove deprecated `primaryVariant` and `secondaryVariant` from framework. These two apis are made obsolete in #93427

Part of https://github.com/flutter/flutter/issues/127042

This is to update the components section for `useMaterial3` api doc.

The deprecation period has elapsed. The method was made obsolete in https://github.com/flutter/flutter/pull/87281.

Fixes a [grocer's apostrophe](https://www.grammar-monster.com/lessons/apostrophe_error_with_plurals.htm). 

Apostrophes are not used to indicate plurals, and this incorrect usage in the documentation tripped me up, so I figured I could submit a quick correction :)

Initialize `ThemeData.visualDensity` using `ThemeData.platform` instead of `defaultTargetPlatform` (#124357)

Initialize `ThemeData.visualDensity` using `ThemeData.platform` instead of `defaultTargetPlatform`

Remove 1745 decorative breaks

Update Material tokens to 0.162

* Add ActionButtonIconsData for overriding action icons

* Fix formatting issues

* Add missing exports in material library and add copyWith method in ActionButtonIconsData

* Move all action buttons, and icons to action_buttons.dart

* Rename actionButtonIcons to actionIconTheme

* Refactor buttons in action_buttons.dart to extend a private class for common implementation

* Refactor icons in action_buttons

* Fix docs in action_buttons_theme

* Fix #107646 always use 'Icons.arrow_back' as a back_button icon in web

* Update documentation for action buttons and add style parameter to every action button

* Fix analyzer warnings

* Add missing style argument in IconButton of _ActionButton

* Add tests for action buttons, action icon theme, drawer buttons, and back buttons

* Add example (+test) for action icon button's action icon theme in examples/api

* Fix analysis errors

* Add missing license header in action_icon_theme.0.dart

* Fix deprecation notice in theme_data.dart

* Update theme data tests for actionIconTheme

* Remove iconSize parameter from ActionButtons and update docs

* Fix failing tests

* Update button color during backbutton tests to red

* Fix analytics issues

* Fix format

Co-authored-by: Qun Cheng <quncheng@google.com>

* lerp documentation

* Remove Note, Note That from repo

* Improve BorderSide documentation.

* apply review comments

* Update to v0.158 of the token database.

* Update checkbox template

* Fix DatePickerTheme test

---------
Co-authored-by: Qun Cheng <quncheng@google.com>

Co-authored-by: Renzo Olivares <roliv@google.com>

* Add missing variants and *new* indicators to useMaterial3 docs

* add missing *new*

* Remove superfluous words from comments.

* Revert `win32_window.h`

Which seems to come from `gallery`

* Add Decoding Flutter videos to API docs

* Review comments

* Update widget of the week videos too

* dart fix --apply

* manual fixes

* Remove ThemeData.buttonColor references

* Fix test

* Remove more buttonColors

* Macro the definition of color scheme

* remove doc reference

* Updated to tokens v0.150.

* Updated with a reverted list_tile.dart.

* Introduce flag to maximally apply CupertinoTheme

* add missing docs

* add tests

* fix docs

* fix test

* Add M2 defaults and template skeleton

* add MaterialStateColor functionality to ActionTextColor (issue #110402)

* Add M2 defaults and template skeleton

* updated material 3 tokens

* Updated snackbar demo

* add theme tests

* add gen defaults

* formatting

* more whitespace fixes

* add widget type

* update docs

* code review changes

* Add line overflow functionality

* whitespace fixes

* update M3 animation

* whitespace fixes

* add insetPadding param

* Modifed icon parameter to showCloseIcon

* white space fixes

* test fixes

* rename iconColor to closeIconColor

* debug test fix

* de-britishification

* g3fix

* g3fix

* debug test fix