[Docs] Updated Floating Toolbar doc to make it more user friendly

PiperOrigin-RevId: 787618839

Author: Material Design Team

docs/components/FloatingToolbar.md

@@ -1,43 +1,99 @@
 <!--docs:
-title: "Floating Toolbar"
+title: "Floating toolbar"
 layout: detail
 section: components
 excerpt: "Floating toolbars show actions related to the current page"
 iconId: floating_toolbar
 path: /catalog/floating-toolbar/
 -->
 
-# Floating Toolbar
+# Floating toolbar
 
-Floating Toolbar provides a way to show actions related to the current page.
-Floating Toolbar is an undocked variant of Toolbars.
+Floating toolbar provides a way to show actions related to the current page.
+Floating toolbars can be vertical or horizontal.
 
-See [Top App Bars](TopAppBar.md) and [Bottom App Bars](BottomAppBar.md) for docked Toolbar variants.
+Vertical floating toolbar                                                                        | Horizontal floating toolbar
+:----------------------------------------------------------------------------------------------: | :-------------------------:
+<img src="assets/floatingtoolbar/ftbvertical.png" alt="Vertical floating toolbar" height="500"/> | <img src="assets/floatingtoolbar/ftbhorizontal.png" alt="Horizontal floating toolbar" width="590"/>
 
-Floating toolbars can be vertical or horizontal.
+**Note:** Images use various dynamic color schemes.
+
+## Design & API documentation
+
+*   [Material 3 (M3) spec](https://m3.material.io/components/toolbars/overview)
+*   API reference in progress
+
+## Anatomy
+
+<img src="assets/floatingtoolbar/ftbanatomy.png" alt="Floating toolbar anatomy diagram" width="600"/>
+
+1.  Container
+2.  Elements
+
+More details on anatomy items in the
+[component guidelines](https://m3.material.io/components/toolbars/guidelines#d6b7bcb1-295d-41e6-a051-37f12e1c96ab).
+
+## M3 Expressive update
+
+Before you can use `Material3Expressive` component styles, follow the
+[`Material3Expressive themes` setup instructions](https://github.com/material-components/material-components-android/tree/master/docs/getting-started.md#material3expressive-themes).
+
+<img src="assets/floatingtoolbar/floatingtoolbar_expressive.png" alt="The floating toolbar expressive.png" width="700"/>
+Floating toolbar show controls relevant to the current page
+
+The **floating toolbar** was created for more versatility, greater amounts of
+actions, and more variety in where it's placed.
+[More on M3 Expressive](https://m3.material.io/blog/building-with-m3-expressive)
+
+**Types and naming:**
+
+*   Added **floating toolbar** with the following attributes:
+
+    *   Layout: Horizontal or vertical
+    *   Color: Standard or vibrant
+    *   Flexibility: Can hold many elements and components. Can be paired with
+        FAB.
+
+## Key properties
 
-Vertical Floating Toolbar                                               | Horizontal Floating Toolbar
--------------------------------------------------------------------------- | ------------------------
-![Vertical floating toolbar](assets/floatingtoolbar/ftbvertical.png) | ![Horizontal floating toolbar](assets/floatingtoolbar/ftbhorizontal.png)
+### Container attributes
 
-**Contents**
+Element                 | Attribute                            | Related methods | Default value
+----------------------- | ------------------------------------ | --------------- | -------------
+**Color**               | `app:backgroundTint`                 | N/A             | standard is `?attr/colorSurfaceContainer`, vibrant is `?attr/colorPrimaryContainer`
+**Shape**               | `app:shapeAppearance`                | N/A             | `50% rounded`
+**Left inset margin**   | `app:marginLeftSystemWindowInsets`   | N/A             | `true`
+**Top inset margin**    | `app:marginTopSystemWindowInsets`    | N/A             | `true`
+**Right inset margin**  | `app:marginRightSystemWindowInsets`  | N/A             | `true`
+**Bottom inset margin** | `app:marginBottomSystemWindowInsets` | N/A             | `true`
 
-*   [Design and API Documentation](#design-and-api-documentation)
-*   [Using Floating Toolbar](#using-floating-toolbar)
-*   [Theming](#theming-a-floating-toolbar)
+### Styles
 
-## Design and API Documentation
+Element            | Style                                      | Theme attribute
+------------------ | ------------------------------------------ | ---------------
+**Standard style** | `Widget.Material3.FloatingToolbar`         | `?attr/floatingToolbarStyle`
+**Vibrant style**  | `Widget.Material3.FloatingToolbar.Vibrant` | `?attr/floatingToolbarVibrantStyle`
 
-*   Google Material3 Spec in progress
-*   API Reference in progress
+Floating toolbar also recommends a special style for specific components for
+when they are inside of a floating toolbar. Currently, the floating toolbar
+styles also include a theme overlay for `?attr/materialButtonStyle`,
+`?attr/materialIconButtonStyle`, and `?attr/borderlessButtonStyle` to style
+buttons inside of a floating toolbar.
+
+For the full list, see
+[styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/floatingtoolbar/res/values/styles.xml)
+and
+[floating toolbar attributes](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/floatingtoolbar/res/values/attrs.xml)
 
-## Using Floating Toolbar
+## Code implementation
 
-Before you can use the Floating Toolbar, you need to add a dependency to
-the Material Components for Android library. For more information, go to the
+Before you can use the floating toolbar, you need to add a dependency to the
+Material components for Android library. For more information, go to the
 [Getting started](https://github.com/material-components/material-components-android/tree/master/docs/getting-started.md)
 page.
 
+### Adding floating toolbar
+
 Here's what a typical layout would look like:
 
 ```xml
@@ -71,7 +127,7 @@ Here's what a typical layout would look like:
     android:layout_margin="16dp">
 
     <!-- floating toolbar sample content -->
-    <com.google.android.material.overflow.OverflowLinearLayout
+   <com.google.android.material.overflow.OverflowLinearLayout
       android:id="@+id/floating_toolbar_child"
       android:layout_width="wrap_content"
       android:layout_height="wrap_content"
@@ -150,25 +206,32 @@ attribute:
 </com.google.android.material.floatingtoolbar.FloatingToolbarLayout>
 ```
 
-This behavior will be disabled when Talkback is enabled for a11y reasons. See [how to make floating toolbars accessible](#making-floating-toolbar-accessible).
+This behavior will be disabled when TalkBack is enabled for a11y reasons. See
+[how to make floating toolbars accessible](#making-floating-toolbar-accessible).
 
-Note that the default M3 style is the horizontal standard color styling. Vibrant color or vertical styles should be explicitly set on the `FloatingToolbarLayout`. M3 stylings for specific components may also be defined, such as for icon buttons. These are recommended to be set explicitly on the corresponding components inside `FloatingToolbarLayout`. See the full list of [styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/floatingtoolbar/res/values/styles.xml).
+Note that the default M3 style is the horizontal standard color styling. Vibrant
+color or vertical styles should be explicitly set on the
+`FloatingToolbarLayout`. M3 stylings for specific components may also be
+defined, such as for icon buttons. These are recommended to be set explicitly on
+the corresponding components inside `FloatingToolbarLayout`. See the full list
+of
+[styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/floatingtoolbar/res/values/styles.xml).
 
 API and source code:
 
 *   `FloatingToolBar`
     *   [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/floatingtoolbar/FloatingToolbarLayout.java)
 
-### Making Floating Toolbar accessible
+### Making floating toolbar accessible
 
-You should set a `contentDescription` on all the actions in the Floating Toolbar
+You should set a `contentDescription` on all the actions in the floating toolbar
 so that screen readers like TalkBack can properly announce what each action
 represents.
 
-You can also control the ordering of the Talkback focus through the
+You can also control the ordering of the TalkBack focus through the
 `accessibilityTraversalBefore` and `accessibilityTraversalAfter` flags.
 
-For example, if you want the Floating Toolbar to gain Talkback focus first, you
+For example, if you want the floating toolbar to gain TalkBack focus first, you
 can set these accessibility flags like below:
 
 ```xml
@@ -198,17 +261,17 @@ android:id="@+id/floating_toolbar"
   </com.google.android.material.floatingtoolbar.FloatingToolbarLayout>
 ```
 
-#### Talkback
+#### TalkBack
 
 Floating toolbars can optionally use the `CoordinatorLayout.Behavior`
 `HideViewOnScrollBehavior` to hide the floating toolbar on scroll. This behavior
-is disabled when Talkback is enabled disabled due to screen readers not being
+is disabled when TalkBack is enabled disabled due to screen readers not being
 able to see it if the floating toolbar is hidden when scrolled.
 
-If using a Floating toolbar in a layout that obscures any content when
-hide on scroll is disabled, make sure to add the appropriate padding to the
-content. For example, if the floating toolbar is on the bottom and it is
-obscuring the content, bottom padding should be added to the content.
+If using a floating toolbar in a layout that obscures any content when hide on
+scroll is disabled, make sure to add the appropriate padding to the content. For
+example, if the floating toolbar is on the bottom and it is obscuring the
+content, bottom padding should be added to the content.
 
 See below for an example:
 
@@ -227,58 +290,24 @@ if (am != null && am.isTouchExplorationEnabled) {
 }
 ```
 
-### Anatomy and key properties
-
-The following is an anatomy diagram for the floating toolbar:
-
-![Floating toolbar anatomy diagram](assets/floatingtoolbar/ftbanatomy.png)
-
-1.  Container
-2.  Content
-
-#### Container attributes
+## Customizing floating toolbar
 
-**Element**             | **Attribute**                        | **Related methods** | **Default value**
------------------------ | ------------------------------------ | ------------------- | -----------------
-**Color**               | `app:backgroundTint`                 | N/A                 | standard is `?attr/colorSurfaceContainer`, vibrant is `?attr/colorPrimaryContainer`
-**Shape**               | `app:shapeAppearance`                | N/A                 | `50% rounded`
-**Left inset margin**   | `app:marginLeftSystemWindowInsets`   | N/A                 | `true`
-**Top inset margin**    | `app:marginTopSystemWindowInsets`    | N/A                 | `true`
-**Right inset margin**  | `app:marginRightSystemWindowInsets`  | N/A                 | `true`
-**Bottom inset margin** | `app:marginBottomSystemWindowInsets` | N/A                 | `true`
+### Theming floating toolbar
 
-#### Styles
+Floating toolbars support the customization of color and typography.
 
-**Element**        | **Style**
------------------- | ------------------------------------------
-**Standard style** | `Widget.Material3.FloatingToolbar`
-**Vibrant style**  | `Widget.Material3.FloatingToolbar.Vibrant`
-
-Standard style theme attribute: `?attr/floatingToolbarStyle`
-Vibrant style theme attribute: `?attr/floatingToolbarVibrantStyle`
-
-Floating Toolbar also recommends a special style for specific components for
-when they are inside of a floating toolbar. Currently, the Floating Toolbar
-styles also include a theme overlay for `?attr/materialButtonStyle`,
-`?attr/materialIconButtonStyle`, and `?attr/borderlessButtonStyle` to
-style buttons inside of a Floating Toolbar.
-
-See the full list of
-[styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/floatingtoolbar/res/values/styles.xml) and
-[floating toolbar attributes](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/floatingtoolbar/res/values/attrs.xml)
-
-## Theming a Floating Toolbar
+API and source code:
 
-Floating Toolbar supports [Material Theming](https://m3.material.io/foundations/customization),
-which can customize color and typography.
+*   `FloatingToolBarLayout`
+    *   [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/floatingtoolbar/FloatingToolbarLayout.java)
 
-### Floating Toolbar theming example
+#### Floating toolbar theming example
 
-The following example shows a Floating Toolbar with Material Theming.
+The following example shows a floating toolbar with Material theming.
 
-![Floating Toolbar theming example](assets/floatingtoolbar/ftbtheming.png)
+<img src="assets/floatingtoolbar/ftbtheming.png" alt="Floating toolbar theming example" width="600"/>
 
-#### Implementing floating toolbar theming
+##### Implementing floating toolbar theming
 
 Use theme attributes and a style in `res/values/styles.xml` which apply to all
 floating toolbars and affect other components:
@@ -336,7 +365,8 @@ all floating toolbars but do not affect other components:
 </style>
 ```
 
-Or use the style in the layout, which affects only this specific floating toolbar:
+Or use the style in the layout, which affects only this specific floating
+toolbar:
 
 ```xml
 <com.google.android.material.floatingtoolbar.FloatingToolbarLayout