[Loading Indicator] Update documentation to align with Material 3 spec.

Restructures the LoadingIndicator component documentation to improve clarity, add more context, and align with Material 3.

- Adds a Table of Contents for better navigation.
- Links to the official M3 spec for overview and guidelines.
- Adds new sections for Anatomy and M3 Expressive with corresponding images.
- Improves the component definition and clarifies usage.

PiperOrigin-RevId: 787630502

Author: Material Design Team

docs/components/LoadingIndicator.md

@@ -9,16 +9,75 @@ path: /catalog/loading-indicators/
 
 # Loading Indicators
 
-Loading indicators express an unspecified wait time of a process.
+[Loading indicators](https://m3.material.io/components/loading-indicator/overview)
+show the progress for a short wait time. It has two configurations.
 
-![Animation of loading indicator](assets/loadingindicator/loading_indicator.gif)
+![Loading indicator configurations](assets/loadingindicator/loadingindicator-configurations.gif)
 
-**Contents**
+1.  Default (contained)
+2.  Uncontained
 
-*   [Using loading indicators](#using-progress-indicators)
-*   [Anatomy and key properties](#anatomy-and-key-properties)
+**Note:** Images use various dynamic color schemes.
 
-## Using loading indicators
+## Design & API documentation
+
+*   [Material 3 (M3) spec](https://m3.material.io/components/loading-indicator/overview)
+
+## Anatomy
+
+![Loading indicator anatomy](assets/loadingindicator/anatomy.png)
+
+1.  Active indicator
+2.  Container (optional)
+
+More details on anatomy items in the
+[component guidelines](https://m3.material.io/components/loading-indicator/guidelines#a6bb9df2-568a-41d4-a4e9-08ac8f844a7d).
+
+## M3 Expressive
+
+### M3 Expressive update
+
+The loading indicator is a new component added to the library in the M3
+Expressive update.
+
+The loading indicator is designed to show progress that loads in under five
+seconds. It should replace most uses of the indeterminate circular progress
+indicator.
+[More on M3 Expressive](https://m3.material.io/blog/building-with-m3-expressive)
+
+**Loading indicators:**
+
+*   Can be contained or uncontained
+*   Use shape and motion to capture attention
+*   Can scale in size
+
+## Key properties
+
+#### Attributes
+
+Element              | Attribute             | Related method(s)                             | Default value
+-------------------- | --------------------- | --------------------------------------------- | -------------
+**Indicator color**  | `app:indicatorColor`  | `setIndicatorColor`</br>`getIndicatorColor`   | `colorPrimary`
+**Container color**  | `app:containerColor`  | `setContainerColor`</br>`getContainerColor`   | `transparent`
+**Indicator size**   | `app:indicatorSize`   | `setIndicatorSize`</br>`getIndicatorSize`     | 38dp
+**Container width**  | `app:containerWidth`  | `setContainerWidth`</br>`getContainerWidth`   | 48dp
+**Container height** | `app:containerHeight` | `setContainerHeight`</br>`getContainerHeight` | 48dp
+
+#### Styles
+
+Element             | Style
+------------------- | ---------------------------------------------
+**Default style**   | `Widget.Material3.LoadingIndicator`
+**Contained style** | `Widget.Material3.LoadingIndicator.Contained`
+
+Default theme attribute: `?attr/loadingIndicatorStyle`
+
+See the full list of
+[styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/loadingindicator/res/values/styles.xml)
+and
+[attributes](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/loadingindicator/res/values/attrs.xml).
+
+## Code implementation
 
 Before you can use Material loading indicators, you need to add a dependency to
 the Material Components for Android library. For more information, go to the
@@ -34,7 +93,17 @@ indeterminate circular progress indicators.
 **Note:** Use progress indicators, if the processes can transition from
 indeterminate to determinate.
 
-### Usage
+### Adding loading indicators
+
+Loading indicators capture attention through motion. It morphs the shape in a
+sequence with potential color change, if multiple colors are specified for the
+indicator. A fully rounded container is optionally drawn behind the morphing
+shape.
+
+Source code:
+
+*   `LoadingIndicator`
+    *   [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/loadingindicator/LoadingIndicator.java)
 
 A loading indicator can be added to a layout:
 
@@ -59,8 +128,8 @@ A loading indicator can be added to a layout:
 
 ### Making loading indicators accessible
 
-Loading indicators have support very limited user interactions. Please consider
-setting the content descriptor for use with screen readers.
+Loading indicators have limited support for user interactions. Please
+consider setting the content descriptor for use with screen readers.
 
 That can be done in XML via the `android:contentDescription` attribute or
 programmatically like so:
@@ -71,48 +140,3 @@ loadingIndicator.contentDescription = contentDescription
 
 For contained loading indicators, please ensure the indicator color and the
 container color have enough contrast (3:1).
-
-## Loading indicators
-
-Loading indicators capture attention through motion. It morphs the shape in a
-sequence with potential color change, if multiple colors are specified for the
-indicator. A fully rounded container is optionally drawn behind the morphing
-shape.
-
-Source code:
-
-*   `LoadingIndicator`
-    *   [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/loadingindicator/LoadingIndicator.java)
-
-### Anatomy and key properties
-
-A loading indicator consists of an optional container and an indicator.
-
-![Loading indicator anatomy](assets/loadingindicator/anatomy.png)
-
-1.  Active indicator
-2.  Container
-
-#### Attributes
-
-Element              | Attribute             | Related method(s)                             | Default value
--------------------- | --------------------- | --------------------------------------------- | -------------
-**Indicator color**  | `app:indicatorColor`  | `setIndicatorColor`</br>`getIndicatorColor`   | `colorPrimary`
-**Container color**  | `app:containerColor`  | `setContainerColor`</br>`getContainerColor`   | `transparent`
-**Indicator size**   | `app:indicatorSize`   | `setIndicatorSize`</br>`getIndicatorSize`     | 38dp
-**Container width**  | `app:containerWidth`  | `setContainerWidth`</br>`getContainerWidth`   | 48dp
-**Container height** | `app:containerHeight` | `setContainerHeight`</br>`getContainerHeight` | 48dp
-
-#### Styles
-
-Element             | Style
-------------------- | ---------------------------------------------
-**Default style**   | `Widget.Material3.LoadingIndicator`
-**Contained style** | `Widget.Material3.LoadingIndicator.Contained`
-
-Default theme attribute: `?attr/loadingIndicatorStyle`
-
-See the full list of
-[styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/loadingindicator/res/values/styles.xml)
-and
-[attributes](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/loadingindicator/res/values/attrs.xml).