[Docs] Updated docs with Expressive code/info.

PiperOrigin-RevId: 798982415

Author: Material Design Team

docs/components/Chip.md

@@ -14,7 +14,7 @@ represent an input, attribute, or action. Chips help people enter information,
 make selections, filter content, or trigger actions. There are four variants of
 chips.
 
-![Examples of the four different chip types](assets/chips/chip_types.png)
+![Examples of the four different chip types](assets/chips/chip-types.png)
 
 1.  Assist chip
 2.  Filter chip
@@ -34,7 +34,7 @@ chips.
 
 <summary><h4>Assist</h4></summary>
 
-![Anatomy of assist chip](assets/chips/assist_anatomy.png)
+![Anatomy of assist chip](assets/chips/assist-anatomy.png)
 
 1.  Container
 2.  Label text
@@ -45,7 +45,7 @@ chips.
 
 <summary><h4>Filter</h4></summary>
 
-![Anatomy of a filter chip](assets/chips/filter_anatomy.png)
+![Anatomy of a filter chip](assets/chips/filter-anatomy.png)
 
 1.  Container
 2.  Label text
@@ -57,7 +57,7 @@ chips.
 
 <summary><h4>Input</h4></summary>
 
-![Anatomy of a input chip](assets/chips/input_anatomy.png)
+![Anatomy of a input chip](assets/chips/input-anatomy.png)
 
 1.  Container
 2.  Label text
@@ -69,7 +69,7 @@ chips.
 
 <summary><h4>Suggestion</h4></summary>
 
-![Anatomy of a suggestion chip](assets/chips/suggestion_anatomy.png)
+![Anatomy of a suggestion chip](assets/chips/suggestion-anatomy.png)
 
 1.  Container
 2.  Label text
@@ -184,12 +184,12 @@ Assist chips represent smart or automated actions that can span multiple apps,
 such as opening a calendar event from the home screen. Assist chips function as
 though the user asked an assistant to complete the action.
 
-#### Assist chip example
+#### Default
 
 The following example shows an activated assist chip.
 
 !["A selected action chip with its corresponding action, a visible popup textbox
-stating the chip has been activated."](assets/chips/chips_selected_assist.png)
+stating the chip has been activated."](assets/chips/chips-selected-assist.png)
 
 In the layout:
 
@@ -203,14 +203,31 @@ In the layout:
 
 <com.google.android.material.chip.Chip
   android:id="@+id/chip_1"
-  style="@style/Widget.Material3.Chip.Assist"
   android:layout_width="wrap_content"
   android:layout_height="wrap_content"
   android:text="@string/chip_text_1"
   app:chipIcon="@drawable/circle_1"
   app:ensureMinTouchTargetSize="true"/>
 ```
 
+#### Elevated
+
+!["Assist elevated chip in light theme"](assets/chips/chip-assist-elevated-light-theme.png)
+
+!["Assist elevated chip in dark theme"](assets/chips/chip-assist-elevated-dark-theme.png)
+
+Assist chips also come in an `Elevated` style variant, to be used when placed
+against a background that needs protection, such as an image.
+
+```xml
+<com.google.android.material.chip.Chip
+    style="@style/Widget.Material3.Chip.Assist.Elevated"
+    android:layout_width="wrap_content"
+    android:layout_height="wrap_content"
+    android:text="@string/chip_text"
+    app:chipIcon="@drawable/ic_action_24"/>
+```
+
 </details>
 
 <details>
@@ -222,12 +239,12 @@ Filter chips use tags or descriptive words to filter content.
 Filter chips clearly delineate and display options in a compact area. They are a
 good alternative to toggle buttons or checkboxes.
 
-#### Filter chip example
+#### Default
 
 The following example shows filter chips.
 
 !["6 white "Filter" chips spread across 2 lines: "Filters" 1 and 3 selected and
-are light purple and include checkmarks."](assets/chips/chips_filter.png)
+are light purple and include checkmarks."](assets/chips/chips-filter.png)
 
 In the layout:
 
@@ -271,6 +288,23 @@ In the layout:
 </com.google.android.material.chip.ChipGroup>
 ```
 
+#### Elevated
+
+!["Filter elevated chip in light theme"](assets/chips/chip-filter-elevated-light-theme.png)
+
+!["Filter elevated chip in dark theme"](assets/chips/chip-filter-elevated-dark-theme.png)
+
+Filter chips also come in an `Elevated` style variant, to be used when placed
+against a background that needs protection, such as an image.
+
+```xml
+<com.google.android.material.chip.Chip
+    style="@style/Widget.Material3.Chip.Filter.Elevated"
+    android:layout_width="wrap_content"
+    android:layout_height="wrap_content"
+    android:text="@string/chip_text" />
+```
+
 </details>
 
 <details>
@@ -285,7 +319,7 @@ that input by converting text into chips.
 
 The following example shows input chips.
 
-!["Input chips with texts Input 1 to 6."](assets/chips/chips_input.png)
+!["Input chips with texts Input 1 to 6."](assets/chips/chips-input.png)
 
 In the layout:
 
@@ -294,19 +328,19 @@ In the layout:
     ...>
   <com.google.android.material.chip.Chip
       android:id="@+id/chip_1"
-      style="@style/Widget.Material3.Chip.Input"
+      style="?attr/chipStandaloneStyle"
       android:layout_width="wrap_content"
       android:layout_height="wrap_content"
       android:text="@string/text_input_1"/>
 
   <com.google.android.material.chip.Chip
       ...
-      style="@style/Widget.Material3.Chip.Input"
+      style="?attr/chipStandaloneStyle"
       android:text="@string/text_input_2"/>
 
   <com.google.android.material.chip.Chip
       ...
-      style="@style/Widget.Material3.Chip.Input"
+      style="?attr/chipStandaloneStyle"
       android:text="@string/text_input_3"/>
 
 </com.google.android.material.chip.ChipGroup>
@@ -321,14 +355,14 @@ In the layout:
 Suggestion chips help narrow a user’s intent by presenting dynamically generated
 suggestions, such as offering possible responses or providing search filters.
 
-#### Suggestion chip example
-
-The following example shows suggestion chips.
+The following example shows suggestion chips in default and elevated styles.
 
 !["3 suggestion chips, where suggestion 1 is unselected with a solid border and
 white background, suggestion 2 is selected with no border and a light purple
 background, and suggestion 3 is an unselected elevated suggestion with no border
-and a light grey background."](assets/chips/chips_suggestion.png)
+and a light grey background."](assets/chips/chips-suggestion.png)
+
+#### Default
 
 In the layout:
 
@@ -344,14 +378,26 @@ In the layout:
     ...
     style="@style/Widget.Material3.Chip.Suggestion"
     android:text="@string/chip_text_2"/>
-  <com.google.android.material.chip.Chip
-    ...
-    style="@style/Widget.Material3.Chip.Suggestion.Elevated"
-    android:text="@string/chip_text_3"/>
 
 </com.google.android.material.chip.ChipGroup>
 ```
 
+#### Elevated
+
+Suggestion chips also come in an `Elevated` style variant. These chips
+should be used when placed against a background that needs protection, such
+as an image.
+
+```xml
+<com.google.android.material.chip.Chip
+    style="@style/Widget.Material3.Chip.Suggestion.Elevated"
+    android:layout_width="wrap_content"
+    android:layout_height="wrap_content"
+    android:text="@string/chip_text_3" />
+```
+
+**Note:** Suggestion chips are usually placed within a `ChipGroup`.
+
 </details>
 
 ## Code implementation
@@ -448,7 +494,7 @@ opposed to a `ViewGroup` such as `RecyclerView`. A `ChipGroup` contains a set of
 A `ChipGroup` rearranges chips across multiple rows by default.
 
 !["6 white "Filter" chips spread across 2 lines: "Filters" 1 and 3 selected and
-are light purple and include checkmarks."](assets/chips/chips_filter.png)
+are light purple and include checkmarks."](assets/chips/chips-filter.png)
 
 ```xml
 <com.google.android.material.chip.ChipGroup
@@ -466,7 +512,7 @@ A `ChipGroup` can also constrain its chips to a single row using the
 `ChipGroup` with a `HorizontalScrollView`.
 
 !["Single line of white chips: chips 1, 2, and 3 are fully visible, chip 4 is
-partly visible"](assets/chips/chips_singleline.png)
+partly visible"](assets/chips/chips-singleline.png)
 
 ```xml
 <HorizontalScrollView
@@ -497,7 +543,7 @@ for lower amounts.
 The following image shows a group of chips with
 `app:chipSpacingHorizontal="42dp"`.
 
-!["6 white chips in 2 rows with 42dp horizontal spacing"](assets/chips/chips_spacing.png)
+!["6 white chips in 2 rows with 42dp horizontal spacing"](assets/chips/chips-spacing.png)
 
 </details>
 
@@ -563,7 +609,7 @@ For example, consider an editable e-mail address field that converts addresses
 to chips as they are typed and validated. We can combine `ChipDrawable` with
 spans to add a chip to an `EditText`:
 
-!["Standalone chip inside a text field"](assets/chips/chips_standalone.png)
+!["Standalone chip inside a text field"](assets/chips/chips-standalone.png)
 
 ```kt
 chip.setBounds(0, 0, chip.intrinsicWidth, chip.intrinsicHeight)
@@ -594,7 +640,7 @@ API and source code:
 
 The following example shows chips with Material theming.
 
-!["3 chips with brown text and icons, white fill, and pink outlines"](assets/chips/chips_theming.png)
+!["3 chips with brown text and icons, white fill, and pink outlines"](assets/chips/chips-theming.png)
 
 ##### Implementing chip theming
 

docs/components/NavigationRail.md

@@ -13,7 +13,7 @@ path: /catalog/navigation-rail/
 lets people switch between UI views on mid-sized devices. There are two types of
 navigation rail.
 
-<img src="assets/navigationrail/navigation_rail_hero.png" alt="The navigation rail container is 80 dp wide by default." height="400"/>
+<img src="assets/navigationrail/navigation-rail-hero.png" alt="The navigation rail container is 80 dp wide by default." height="400"/>
 
 1.  Collapsed navigation rail
 2.  Expanded navigation rail
@@ -27,7 +27,7 @@ navigation rail.
 
 ## Anatomy
 
-<img src="assets/navigationrail/navigation_rail_anatomy.png" alt="Navigation rail anatomy diagram">
+<img src="assets/navigationrail/navigation-rail-anatomy.png" alt="Navigation rail anatomy diagram">
 Collapsed and expanded navigation rail elements:
 
 1.  Container
@@ -43,12 +43,14 @@ Collapsed and expanded navigation rail elements:
 More details on anatomy items in the
 [component guidelines](https://m3.material.io/components/navigation-rail/guidelines#b51e4558-351f-4368-af8d-bbf1f63f68b4).
 
-## M3 Expressive update
+## M3 Expressive
+
+### 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/navigationrail/navigation_rail_expressive.png" alt="collapsed and expanded navigation rails" width="500">
+<img src="assets/navigationrail/navigation-rail-expressive.png" alt="collapsed and expanded navigation rails" width="500">
 The collapsed and expanded navigation rails match visually and can transition
 into each other
 
@@ -79,6 +81,28 @@ The expanded nav rail is meant to replace the navigation drawer.
 *   Active label on vertical items changed from **on surface variant** to
     **secondary**
 
+### M3 Expressive styles
+
+Measurement changes from M3:
+
+*   Width: from 80dp to 96dp
+*   Color: new expressive colors!
+*   Item minimum height: from 60dp to 64dp
+*   Item spacing: from 0dp to 4dp
+*   Elevation: from 0dp to 3dp
+*   Top item padding: from 4dp to 6dp
+*   Bottom item padding: from 12dp to 4dp
+*   Top margin of navigation rail content: from 8dp to 44dp
+*   Padding between optional header view and navigation rail items: from 8dp to
+    40dp
+*   Label text is no longer bolded when selected
+
+The default style for navigation rail is:
+
+```xml
+<item name="navigationRailStyle">@style/Widget.Material3Expressive.NavigationRailView</item>
+```
+
 ## Key properties
 
 ### Container attributes
@@ -319,7 +343,7 @@ navigationRail.setOnNavigationItemReselectedListener { item ->
 
 Which results in:
 
-![The navigation rail container is 72 dp wide by default.](assets/navigationrail/navigation_rail_demo.png)
+![The navigation rail container is 72 dp wide by default.](assets/navigationrail/navigation-rail-demo.png)
 
 By default, navigation rail adds top and bottom padding according to top and
 bottom window insets—helping the header layout and menu items dodge system
@@ -336,7 +360,7 @@ bottom insets independently by using `app:paddingTopSystemWindowInsets` and
 
 The following example shows a navigation rail with four icons.
 
-<img src="assets/navigationrail/navigation_rail_example.png" alt="Example navigation rail with four icons" height="500"/>
+<img src="assets/navigationrail/navigation-rail-example.png" alt="Example navigation rail with four icons" height="500"/>
 
 *   Alarms
 *   Schedule
@@ -425,7 +449,7 @@ off' as it could result in a strange animation due to the `Transition`.
 
 Collapsed navigation rail <div style="width:420px"></div>                                              | Expanded navigation rail <div style="width:420px"></div>
 :----------------------------------------------------------------------------------------------------: | :------------------------------------------------------:
-<img src="assets/navigationrail/collapsed_nav_rail.png" alt="Collapsed navigation rail" height="560"/> | <img src="assets/navigationrail/expanded_nav_rail.png" alt="Expanded navigation rail" height="560"/>
+<img src="assets/navigationrail/collapsed-nav-rail.png" alt="Collapsed navigation rail" height="560"/> | <img src="assets/navigationrail/expanded-nav-rail.png" alt="Expanded navigation rail" height="560"/>
 
 </details>
 
@@ -436,7 +460,7 @@ Rail icons can include badges on the upper right corner of the icon. Badges
 convey dynamic information about the associated destination, such as counts or
 status.
 
-![Navigation rail with badges](assets/navigationrail/navigation_rail_badges.png)
+![Navigation rail with badges](assets/navigationrail/navigation-rail-badges.png)
 
 Initialize and show a `BadgeDrawable` associated with `menuItemId`. Subsequent
 calls to this method will reuse the existing `BadgeDrawable`:
@@ -476,7 +500,7 @@ The rail provides a convenient container for anchoring a header view, such as a
 `FloatingActionButton` or a logo, to the top of the rail, using the
 `app:headerLayout` attribute.
 
-<img src="assets/navigationrail/navigation_rail_fab.png" alt="Navigation rail with a FAB in the header" height="550"/>
+<img src="assets/navigationrail/navigation-rail-fab.png" alt="Navigation rail with a FAB in the header" height="550"/>
 
 ```xml
 <com.google.android.material.navigationrail.NavigationRailView
@@ -520,7 +544,7 @@ API and source code:
 
 The following example shows a navigation rail with Material theming.
 
-![Navigation rail theming example](assets/navigationrail/navigation_rail_theming.png)
+![Navigation rail theming example](assets/navigationrail/navigation-rail-theming.png)
 
 ##### Implementing navigation rail theming