livewire-material/docs/reference/m3/components-navigation-selection-inputs.md

# Material Design 3 — Components Group B Reference
Navigation, selection, text inputs and search. Ground truth extracted from m3.material.io (Sept 2026 snapshot), cross-referenced against androidx Compose Material3 token files (`androidx-main`) and material-components-android docs where the site only shows numbers in images.

Conventions:
- "(site)" = stated in m3.material.io page text/tables.
- "(androidx: <File>.kt)" = read from the Compose M3 token source because the number was only in an image on the site.
- Elevation levels resolved via androidx `ElevationTokens.kt`: Level0=0dp, Level1=1dp, Level2=3dp, Level3=6dp, Level4=8dp, Level5=12dp.
- Shape keys resolved via androidx `ShapeTokens.kt`: CornerNone=0dp (square), CornerExtraSmall=4dp all corners, CornerExtraSmallTop=4dp top corners only, CornerSmall=8dp, CornerMedium=12dp, CornerLarge=16dp, CornerLargeTop=16dp top only, CornerLargeEnd=0/16/16/0 (top-start/top-end/bottom-end/bottom-start), CornerLargeStart=16/0/0/16, CornerExtraLarge=28dp, CornerExtraLargeTop=28dp top only, CornerExtraLargeIncreased=32dp, CornerExtraExtraLarge=48dp, CornerFull=fully rounded (stadium/circle).

---

## Top App Bar (App Bars)

### Status
- M3 baseline: **Small**, **Center-aligned** (merged into Small in Expressive via centered-text configuration), **Medium**, **Large** app bars. (site: app-bars/specs)
- M3 Expressive (May 2025): component renamed from "top app bar" to **App bar**. New **Search app bar** variant added. **Medium flexible** and **Large flexible** added; these replace the M3 baseline **Medium** and **Large** app bars, which are "no longer recommended" but still supported (androidx keeps `AppBarMediumTokens`/`AppBarLargeTokens`). **Small** app bar gained a subtitle, center-aligned text option, and more flexible leading/trailing elements. (site: app-bars/overview, app-bars/specs)
- Variant availability table (site, app-bars/specs, verbatim):

| Variant | M3 | M3 Expressive |
| --- | --- | --- |
| Search app bar | -- | Available |
| Small | Available | Available |
| Center-aligned | Available | Merged into **small**. Use centered-text configuration. |
| Medium (baseline) | Available | Not recommended. Use **medium flexible** |
| Medium flexible | -- | Available |
| Large (baseline) | Available | Not recommended. Use **large flexible** |
| Large flexible | -- | Available |

- Platform availability (site, app-bars/overview): Flutter Available; Jetpack Compose Available; Jetpack Compose Expressive Available (`AppBarRow`); Android Views (MDC-Android) Available and Expressive Available; Web Unavailable (both baseline and Expressive).

### Anatomy
Generic app bar (site, app-bars/specs, 5 elements): 1. Container, 2. Leading button, 3. Trailing elements, 4. Headline, 5. Subtitle.
Search app bar (site, app-bars/specs, 5 elements): 1. Container, 2. Leading icon button, 3. Hinted search text, 4. Trailing icon or avatar, 5. Search container.
Customizable additions: image/logo, subtitle, one filled icon button.

### Variants and configurations
Text alignment table (site, app-bars/specs, verbatim):

| Category | Configuration | M3 | M3 Expressive |
| --- | --- | --- | --- |
| Text alignment | Leading edge (default) | Available | Available |
| Centered | -- | Available |

Four variants overall: Search app bar, Small, Medium flexible, Large flexible; plus two "baseline" (not recommended) variants: Medium, Large.

### Specs
Numbers are all in images on the site; sourced from androidx (`AppBarTokens.kt`, `AppBarSmallTokens.kt`, `AppBarMediumTokens.kt`, `AppBarLargeTokens.kt`, `AppBarMediumFlexibleTokens.kt`, `AppBarLargeFlexibleTokens.kt`).

Common (all app bars, androidx `AppBarTokens.kt`):
- Avatar size: 32dp
- Icon size: 24dp
- Icon button spacing: 0dp
- Leading space: 4dp / Trailing space: 4dp
- Container shape: CornerNone (square)
- Container color: Surface; container elevation: Level0 = 0dp
- On-scroll container color: Surface container (Surface Container role); on-scroll elevation: Level2 = 3dp
- Title color: On surface; Subtitle color: On surface variant; Leading icon color: On surface; Trailing icon color: On surface variant

Container heights (androidx):
| Variant | Container height | Title typography (site) | Subtitle typography (site) |
| --- | --- | --- | --- |
| Small | 64dp | Title large | Label medium |
| Medium (baseline) | 112dp | Headline small | — |
| Large (baseline) | 152dp | Headline medium | — |
| Medium flexible | 112dp (short) / 136dp ("large" collapsed-to-tall state) | Headline medium | Label large |
| Large flexible | 120dp (short) / 152dp (tall) | Display small | Title medium |

Search app bar (site, app-bars/specs measurements table is image-only; numbers instead sourced from androidx `SearchBarTokens.kt`, shared with the Search component — see Search section): container height 56dp, shape CornerFull, avatar 30dp, color Surface Container High, elevation Level3 = 6dp.
Margins: unfocused search container margin 24dp; focused margin 12dp (site, search/specs, text — see Search).

Color roles by state (site, app-bars/specs):
- Leading-edge app bar (flat): Surface (container), On surface (title), On surface variant (subtitle, trailing icon), On surface (leading icon). On scroll: Surface container.
- Search app bar: Surface, On surface variant ×3, Surface container ×2, Surface container highest.

### Behaviour and guidelines
- Use to describe the current page and provide 1–2 essential actions; primary action should alter or exit the whole page (Send/Save/Edit). Avoid an overflow menu in the app bar — put extra actions in a toolbar instead. (site, overview/guidelines)
- Container always spans 100% of window width at its default height; never make it shorter. (site, guidelines)
- Leading button is either a menu icon (opens modal expanded navigation rail) or a back arrow. (site, guidelines)
- Headline: brief; may wrap to 2 lines in Medium flexible/Large flexible only (never wrap in Small); never truncate.
- Trailing: up to 2 icon buttons after headline, most-used closest to leading edge; if changed to filled/tonal, use only one.
- Search app bar: leading element can be a logo (do not use it to open an expanded nav rail); up to 2 trailing icons on mobile, up to 4 on large screens; avoid >2 trailing icons + avatar. Search container fills 100% of available space up to 312dp, then only grows to 50% of remaining space beyond that (site, guidelines — exact numeric threshold from site text).
- Color: default color same as background; fills with contrasting color (Surface container) on scroll for separation (no drop shadow in M3, unlike M2's elevation shadow). App bar can also go fully transparent on scroll, with icon buttons gaining their own container fill.
- Medium flexible / Large flexible app bars can compress into Small on scroll and stay small until scrolled back to top; never transform into a Search app bar.
- RTL: layout mirrors automatically (leading/trailing swap sides).
- Placement/window size: not itself window-size-gated on the site, but works with adaptive resizing — trailing actions collapse into an overflow menu at smaller breakpoints and reappear at larger ones.
- Do/Don't: use straight corners (not curved — curved implies expandability); use default height (don't shrink it); use ≤1 filled/tonal button (not multiple); use filled icons for clear actions (outlined allowed for unselected toggle buttons).

### Accessibility
- Roles: title has role "Title"; icon buttons have role "Button". Screen readers read the UI text followed by role.
- Initial focus lands on the leading button (first interactive element).
- Keyboard: Tab moves focus to next interactive element; Space/Enter activates the focused element.
- Color: search container role Surface Container (or Surface Bright on darker backgrounds); search label On Surface Variant; must maintain ≥3:1 contrast between search text and its container.
- Touch ripple appears on tap; hover state cue on cursor.

### Source URLs
https://m3.material.io/components/app-bars/overview
https://m3.material.io/components/app-bars/guidelines
https://m3.material.io/components/app-bars/specs
https://m3.material.io/components/app-bars/accessibility
https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/AppBarTokens.kt (+ AppBarSmallTokens.kt, AppBarMediumTokens.kt, AppBarLargeTokens.kt, AppBarMediumFlexibleTokens.kt, AppBarLargeFlexibleTokens.kt)

---

## Bottom App Bar

### Status
**Deprecated in M3 Expressive.** The M3 site no longer has a standalone "bottom app bar" page; content now lives under the **Toolbars** component page. Per the Toolbars overview (May 2025 M3 Expressive update): "The bottom app bar is no longer recommended and should be replaced with the docked toolbar, which functions similarly, but is shorter and has more flexibility." (site: toolbars/overview). The bottom app bar "is still available, but not recommended" (site: toolbars/guidelines). Toolbars specs table (site, verbatim):

| Variant | M3 | M3 Expressive |
| --- | --- | --- |
| Docked toolbar | -- | Available |
| Floating toolbar | -- | Available |
| Bottom app bar | Available | Not recommended. Use **docked toolbar**. |

androidx Compose still ships legacy `BottomAppBarTokens.kt` for anyone implementing the deprecated baseline component.

### Anatomy
Baseline bottom app bar (site, toolbars/specs): 1. Container (only element called out — a FAB and icon buttons are placed inside it but aren't separately enumerated on the current spec page).

### Variants and configurations
Only one baseline configuration remains (bottom app bar with/without FAB, icon buttons with or without FAB) — see "Common layouts" in the Toolbars specs page.

### Specs
From androidx `BottomAppBarTokens.kt` (numbers not in site text, only in an image):
- Container height: 80dp
- Container color: Surface container
- Container elevation: Level2 = 3dp
- Container shape: CornerNone (square)

Site text confirms (toolbars/overview, "Differences from M2"): M2 bottom app bar had 8dp elevation and did not contain the FAB; M3's bottom app bar has new colors, taller container, no elevation/shadow, and the FAB sits inside the app bar container.

### Behaviour and guidelines
- Only ever docked to the bottom of the window; never shown at the same time as a navigation bar (both compete for the bottom edge). (site: toolbars/guidelines, applies to its replacement, the docked toolbar, and by extension the deprecated bottom app bar)
- Historically paired with a FAB embedded in the bar (per M3 baseline anatomy, "Icon buttons and FAB" / "Icon buttons and no FAB" common layouts, site: toolbars/specs).
- New implementations should use the **Docked toolbar** instead (see Toolbars section below) — Google explicitly directs migration there.

### Accessibility
No dedicated accessibility page remains for the bottom app bar; treat per the Toolbars accessibility guidance (toolbar role on web, generic container on mobile; all inner actions follow their own component's accessibility rules).

### Source URLs
https://m3.material.io/components/toolbars/overview (bottom app bar deprecation notice)
https://m3.material.io/components/toolbars/guidelines
https://m3.material.io/components/toolbars/specs (baseline bottom app bar section)
https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/BottomAppBarTokens.kt
https://raw.githubusercontent.com/material-components/material-components-android/master/docs/components/TopAppBar.md (MDC-Android combines top/bottom app bar docs)

---

## Navigation Bar

### Status
- M3 baseline "Navigation bar" (formerly "Bottom navigation" in M2) — **no longer recommended** in M3 Expressive.
- M3 Expressive (May 2025): new **Flexible navigation bar** replaces the baseline bar — shorter, and supports horizontal navigation items in medium windows. Active label color changed from On-surface-variant to **Secondary**. (site: navigation-bar/overview)
- Variant table (site, navigation-bar/specs, verbatim):

| Variant | M3 | M3 Expressive |
| --- | --- | --- |
| Flexible navigation bar | -- | Available |
| Navigation bar | Available | Not recommended. Use **flexible navigation bar**. |

- Differences from M2: new color mappings + dynamic color; no drop shadow (elevation removed); taller container; active destination can show a pill-shaped contrasting indicator; renamed from "Bottom navigation" to "Navigation bar."

### Anatomy
Flexible nav bar (site, navigation-bar/specs, 7 elements): 1. Container, 2. Icon, 3. Label text, 4. Active indicator, 5. Small badge (optional), 6. Large badge (optional), 7. Large badge label.
(Guidelines page lists a slightly different 6-item cut: Container, Icon, Label text, Active indicator, Large badge, Small badge.)

### Variants and configurations
Item layout table (site, navigation-bar/specs, verbatim):

| Category | Configuration | M3 | M3 Expressive |
| --- | --- | --- | --- |
| Navigation item layout | Vertical (default) | Available | Available |
| Horizontal | -- | Available |

Vertical items: label below icon+indicator — used in compact windows. Horizontal items: icon and label side-by-side inside the indicator — used in medium windows.

### Specs
Numbers from androidx (`NavigationBarTokens.kt`, `NavigationBarHorizontalItemTokens.kt`, `NavigationBarVerticalItemTokens.kt`) since the site's measurement diagrams are images.

Container (common):
- Container height: 64dp (short) / Tall container height: 80dp
- Container color: Surface container; elevation: Level2 = 3dp
- Container shape: CornerNone
- Item-between space: 0dp
- Active indicator shape: CornerFull; icon-label space inside indicator: 4dp
- Label text font: Label medium

Vertical item: active indicator height 32dp, width 56dp; container-between space 6dp; icon size 24dp.
Horizontal item: active indicator height 40dp; leading/trailing space 16dp; icon size 24dp.

Colors (site, navigation-bar/specs — M3 Expressive flexible bar):
- Surface container (container)
- On-secondary container (active icon)
- Secondary (active label — changed from On-surface-variant in M3 baseline)
- Secondary container (active indicator)
- On-surface variant (inactive icon)
- On-surface variant (inactive label)

Baseline (M3, non-Expressive) colors differ slightly: Surface, On secondary container, On surface (active label, not Secondary), Secondary container, On surface variant ×2.

States (site): Enabled; Hovered (8% state layer); Focused (10% state layer); Pressed (10% state layer).

### Behaviour and guidelines
- Use in **compact** (<600dp) and **medium** (600–839dp) window widths only; never on expanded/large/extra-large — use a navigation rail there instead. (site: overview, guidelines)
- 3–5 destinations of equal importance; destinations must stay fixed/consistent across screens — never fewer than 3 (use tabs) or more than 5 (use tabs, or hide behind a modal expanded navigation rail menu).
- Always positioned at the bottom of the window, spanning 100% of width; destinations have fixed positions — never scrollable.
- Labels are mandatory on every item (1–2 words); never remove labels.
- Active indicator only ever appears on one item at a time.
- FAB, when present, floats above the nav bar, right-aligned — must never overlap/cover it.
- Can be temporarily covered by dialogs, bottom sheets, drawers, or the keyboard, but never permanently obstructed.
- Scrolling: hides on scroll-down, reappears on scroll-up — but never hide it while a screen reader is active.
- Selection: navigates using a "top level" transition pattern; icon fills and the active indicator expands from the icon's center; re-selecting the already-active destination scrolls to top. No swipe-to-navigate between destinations (swipes are reserved for carousels/list actions).
- Preserve vs. reset state on re-selection is a per-product choice: preserve scroll/tab/search state, or reset it — pick one strategy per product.
- Icons: filled for active, outlined for inactive; if no filled variant exists, bump icon weight to semibold instead.

### Accessibility
- Initial focus lands on the first navigation item.
- Keyboard: Tab moves between items; Space/Enter selects the focused item.
- Text scaling: bar must grow vertically to fit larger labels (retaining default padding); labels must stay fully visible up to 2x text scale (may truncate beyond that).
- Active/inactive icon contrast must be ≥3:1 against the container.
- Accessibility label defaults to the destination name; add descriptive context when the visible label is ambiguous (e.g., "Library" → "Music library"). Note: on Android Views (MDC-Android) a more descriptive label isn't settable and role isn't announced.

### Source URLs
https://m3.material.io/components/navigation-bar/overview
https://m3.material.io/components/navigation-bar/guidelines
https://m3.material.io/components/navigation-bar/specs
https://m3.material.io/components/navigation-bar/accessibility
https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/NavigationBarTokens.kt (+ NavigationBarHorizontalItemTokens.kt, NavigationBarVerticalItemTokens.kt)

---

## Navigation Rail

### Status
- M3 Expressive (May 2025) introduced **Collapsed** and **Expanded** navigation rails, replacing the M3 baseline "Navigation rail." The Expanded rail is also positioned as the direct replacement for the **Navigation drawer** ("In the expressive update, use an expanded navigation rail."). (site: navigation-rail/overview)
- Variant table (site, navigation-rail/specs, verbatim):

| Variant | M3 | M3 Expressive |
| --- | --- | --- |
| Collapsed navigation rail | -- | Available |
| Expanded navigation rail | -- | Available |
| Navigation rail (baseline) | Available | Not recommended. Use **collapsed navigation rail**. |

- Configuration table (site, navigation-rail/specs, verbatim):

| Category | Configuration | M3 | M3 Expressive |
| --- | --- | --- | --- |
| Expanded layout | Standard (default) | Available as navigation drawer | Available |
| Modal | Available as navigation drawer | Available |
| Expanded behavior | Hide when collapsed | -- | Available |

- Differences from M2: predictive-back interaction; new color mappings/dynamic color; active destination shown with a pill-shaped contrasting indicator.

### Anatomy
Collapsed + Expanded rail (site, navigation-rail/specs, 9 elements): 1. Container, 2. Menu (optional), 3. FAB or Extended FAB (optional), 4. Icon, 5. Active indicator, 6. Label text, 7. Large badge (optional), 8. Large badge label (optional), 9. Small badge (optional).
Baseline rail (site, navigation-rail/specs, 8 elements): Container, Menu icon (optional), Icon, Active indicator, Label text, Large badge label (optional), Large badge (optional), Badge (optional).

### Variants and configurations
Two variants, **Collapsed** and **Expanded**, that transition into each other via a menu button:
- **Collapsed**: runs along the leading edge, 3–7 nav items, must never be hidden. Usable medium→extra-large breakpoints.
- **Expanded**: **Standard** (beside body content, best for large windows) or **Modal** (overlaps body content, opened via menu icon — for dense layouts or many nav items). Can optionally hide entirely in immersive UIs, reappearing on menu-icon tap (collapsed rail may not hide).

### Specs
Site measurement diagrams are images; numbers sourced from androidx (`NavigationRailCollapsedTokens.kt`, `NavigationRailExpandedTokens.kt`, `NavigationRailBaselineItemTokens.kt`, `NavigationRailHorizontalItemTokens.kt`, `NavigationRailVerticalItemTokens.kt`).

Collapsed rail: container width 96dp (narrow variant 80dp); top space (before first item) 44dp; item vertical space 4dp.
Expanded rail: container width minimum 220dp, maximum 360dp; top space 44dp.
Baseline rail item: container height 64dp; active-indicator leading/trailing space 16dp; icon-label space 8dp; header space minimum 40dp; icon size 24dp; container vertical space 6dp.
Horizontal item layout (used in expanded rail): active indicator height 56dp; full-width leading/trailing space 16dp; icon-label space 8dp; leading space 16dp.
Vertical item layout (used in collapsed rail): active indicator height 32dp, width 56dp; icon-label space 4dp; leading/trailing space 16dp.

Colors (site, navigation-rail/specs, M3 Expressive collapsed/expanded rail):
1. Surface container (optional container fill)
2. On secondary container (active icon)
3. Secondary container (active indicator)
4. Secondary (active label, vertical layout) / On secondary container (active label, horizontal layout)
5–6. On surface variant (inactive icon, inactive label)
7. Error / 8. On error / 9. Error (badge roles)

Baseline rail colors: On secondary container, Secondary container, On surface (active label — not Secondary), On surface variant ×2, Error/On error/Error.

States (site): Enabled, Hovered, Focused, Pressed (for both active and inactive destinations).

### Behaviour and guidelines
- Window size guidance: **Compact** → don't use a standard rail, use a navigation bar. **Medium** → use a rail, especially to keep persistent vertical nav. **Expanded → extra-large** → use a rail (never a bar); choose Standard vs. Modal based on space and destination count.
- 3–7 destinations; container fill can be turned off (transparent) as long as items keep ≥3:1 contrast.
- Always vertical — never horizontal (use a nav bar for horizontal nav instead).
- Alignment: top or center; on tablets prefer center alignment for reach. Menu icon and FAB are always top-aligned.
- FAB, when nested in the rail, uses resting elevation Level 0 (site explicitly states this contrasts with a standalone FAB's normal elevation).
- Active indicator: only for the current page; in the expanded rail it hugs the label text by default (can be overridden to fill the full container width, resembling the old navigation drawer style); target area always spans the full rail width regardless of indicator visual size.
- Badges: small badge upper-right of icon in collapsed rail; moves next to the label text in expanded rail.
- Optional vertical divider separates rail from content, placed on the content-adjacent edge.
- Resizing: rail transitions to a navigation bar on small screens, never shown simultaneously with a nav bar. Rail transitions from collapsed↔expanded should animate the FAB into/out of an Extended FAB.
- Scrolling: nav destinations stay fixed vertically; if the layout scrolls horizontally, the rail may scroll off or stay fixed — use a divider or Level 1 elevation to separate it from scrolling content underneath.
- Selection uses the "top level" transition pattern; icon fills, indicator expands from the icon's center.
- Predictive back (Android): applies only to the **modal expanded** rail — swipe reveals the previous screen in preview and the rail slides off the edge.

### Accessibility
- Initial focus lands on the first interactive item (FAB, menu, or first nav item, in that order); Tab moves from FAB/menu into nav items, then Tab/Arrows move between items.
- Keyboard: Tab/Arrows navigate; Space/Enter selects.
- Text scaling: items grow vertically to fit larger labels; labels stay fully visible up to 2x scale.
- Active/inactive icon contrast must be sufficient against the container; filled icon (or semibold weight if no filled variant) marks the active destination.
- Accessibility label = adjacent text label by default; make it more descriptive when the visible text is ambiguous. Same MDC-Android caveat as nav bar (no descriptive label support, role not announced).

### Source URLs
https://m3.material.io/components/navigation-rail/overview
https://m3.material.io/components/navigation-rail/guidelines
https://m3.material.io/components/navigation-rail/specs
https://m3.material.io/components/navigation-rail/accessibility
https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/NavigationRailCollapsedTokens.kt (+ NavigationRailExpandedTokens.kt, NavigationRailBaselineItemTokens.kt, NavigationRailHorizontalItemTokens.kt, NavigationRailVerticalItemTokens.kt, NavigationRailColorTokens.kt)

---

## Navigation Drawer

### Status
**Deprecated in M3 Expressive.** "The navigation drawer is no longer recommended. Use the expanded navigation rail instead." (site: navigation-drawer/overview, M3 Expressive update, May 2025). The page still exists on the site (unlike bottom app bar) with full M3-baseline guidance and specs, since it remains implemented in Flutter, Jetpack Compose, and MDC-Android — but Google's direction is migration to the Expanded Navigation Rail (Standard or Modal configuration).
Two M3-baseline variants: **Standard** and **Modal**.
Differences from M2: new color mappings/dynamic color; distinguishes Standard vs. Modal as separate variants; rounded corners at the drawer's ending edge (vs. M2's square corners); updated color/shape for the selected state.

### Anatomy
(site, navigation-drawer/specs, 7 elements — guidelines page numbers it as 8 including Scrim): 1. Container, 2. Headline, 3. Label text, 4. Active indicator, 5. Badge label text, 6. Scrim (modal only), 7. Icon. Guidelines page additionally separates: Sheet, Divider, Section label (optional).

### Variants and configurations
- **Standard**: permanently visible or dismissible via a menu icon; sits beside content (no scrim); recommended for **expanded/large/extra-large** breakpoints (≥840dp).
- **Modal**: uses a scrim to block interaction with the rest of the screen; doesn't affect the layout grid; used at **compact/medium** breakpoints (also usable at any breakpoint); dismissed by selecting an item, tapping the scrim, or swiping toward the anchoring edge.
- Structurally it's a list (see Lists component) inside a side sheet, optionally organized with headers, subheads and dividers.

### Specs
Full numeric table is present directly in site text (navigation-drawer/specs) — no androidx fallback needed:

Standard navigation drawer:

| Attribute | Value |
| --- | --- |
| Container height | 100% |
| Container width | 360dp |
| Container shape | 0,16,16,0dp corner radii |
| Icon size | 24dp |
| Active indicator height | 56dp |
| Active indicator shape | 28dp (fully rounded / stadium in practice — androidx uses CornerFull) |
| Active indicator width | 336dp |
| Horizontal label alignment | Start-aligned |
| Left padding | 28dp |
| Right padding | 28dp |
| Active indicator padding | 12dp |
| Padding between elements | 0dp |

Modal navigation drawer: identical table (Container height 100%, width 360dp, icon 24dp, indicator height 56dp / width 336dp, left/right padding 28dp, indicator padding 12dp, padding between elements 0dp) — no separate "container shape" row given for modal on the site, but androidx `NavigationDrawerTokens.kt` gives `ContainerShape = CornerLargeEnd` (0/16/16/0dp) for both, `BottomContainerShape = CornerLargeTop` (16/16/0/0dp) for a bottom-sheet-style presentation.

Elevation/color, from androidx `NavigationDrawerTokens.kt` (not stated as dp/level on the site page directly):
- Standard: container color Surface, elevation Level0 = 0dp
- Modal: container color Surface container low, elevation Level1 = 1dp
- Active icon/label: On secondary container; active indicator: Secondary container; inactive icon/label: On surface variant; headline: On surface variant (Title small typography).

Colors (site, navigation-drawer/specs, 9 roles): Surface container low, On surface variant, On secondary container ×2, Secondary container, On secondary container, On surface variant ×2, Scrim.
States (site): Enabled, Hovered, Focused, Pressed.

### Behaviour and guidelines
- Recommended for apps with **5+ top-level destinations** or **2+ levels of nav hierarchy**; also usable to replace a nav rail/bar on large screens.
- **Never combine** a navigation drawer with another primary nav component (e.g., a navigation bar) on the same screen — pick one based on breakpoint.
- Breakpoint mapping (site): compact → navigation bar; medium/expanded → navigation rail; expanded/large/extra-large → standard navigation drawer. On web, below 320 CSS px, swap the drawer for a navigation bar for accessibility.
- Standard drawer can be **dismissible** (visible menu icon toggles it — good when prioritizing content) or **permanently visible** (can't be closed by the user — good for quick switching).
- Modal drawer always opens from an external action (e.g., a menu icon in a navigation rail), never from within itself.
- Opens from the leading (start) edge of the screen — left in LTR, right in RTL.
- Full-width dividers separate **groups** of destinations; never use dividers between individual destinations.
- Every destination in a group needs the same treatment — icons for all or none, never a mix.
- Section labels (short subheads) can group related destinations.
- Content can scroll vertically within the drawer, independent of body content.
- Uses an enter/exit transition pattern to appear/disappear (same family as other M3 transition patterns).

### Accessibility
- Initial focus lands on the first navigation item.
- Modal drawer can be dismissed by selecting the scrim.
- Filled icon + active indicator marks the selected destination; keep the same icon style consistently across selected/unselected states otherwise the visual cue is lost.
- Keyboard: Tab → focus first destination; Space/Enter → select the focused destination (focus then moves into any newly-opened section); Arrow → navigate between destinations within the drawer.
- Accessibility label = destination name by default; make more descriptive when ambiguous (e.g., "Recents" → "Recent images"). Role stated on site is "tab" (per the screenshots' annotated role), though this may reflect the specific reference implementation shown.

### Source URLs
https://m3.material.io/components/navigation-drawer/overview
https://m3.material.io/components/navigation-drawer/guidelines
https://m3.material.io/components/navigation-drawer/specs
https://m3.material.io/components/navigation-drawer/accessibility
https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/NavigationDrawerTokens.kt

---

## Tabs

### Status
No "M3 Expressive update" section appears on the tabs pages — Google has not flagged an Expressive-specific redesign for Tabs the way it has for app bars/nav bar/nav rail/toolbars/search/sliders (absence noted; not asserting it is unchanged, only that the site does not call out an update).
Two variants: **Primary tabs** and **Secondary tabs**. Both available and current — no deprecations on this page.
Differences from M2: new color mappings/dynamic color; icons and labels are now vertically centered within the container (previously not).

### Anatomy
Primary tabs (site, tabs/specs, 6 elements): 1. Container, 2. Badge (optional), 3. Icon (optional), 4. Label, 5. Divider, 6. Active indicator.
Secondary tabs (site, tabs/specs, 5 elements): 1. Container, 2. Badge (optional), 3. Label, 4. Divider, 5. Active indicator (no icon slot).

### Variants and configurations
- **Primary tabs**: main content destinations, placed at the top of the content pane (often under an app bar).
- **Secondary tabs**: further separate related content within a content area; always placed below primary tabs; simpler indicator style but functionally identical.
- **Fixed** vs **scrollable** tabs: fixed shows all tabs at once with equal-width sections sized to the widest label (avoid >4 fixed tabs — 5+ feels cramped); scrollable allows longer labels and more tabs, offsets the first tab 52dp from the leading edge (site, guidelines, exact number).

### Specs
Full numeric table present directly in site text (tabs/specs):

| Attribute | Value |
| --- | --- |
| Container height (label text only) | 48dp |
| Container height (icon and label text) | 64dp |
| Icon size | 24dp |
| Divider height | 1dp |
| Primary active indicator height | 3dp |
| Secondary active indicator height | 2dp |
| Active indicator shape | 3, 3, 0, 0 (top corners rounded 3dp) |
| Active indicator minimum length | 24dp |
| Padding between inline icon and text | 8dp |
| Padding between inline text and badge | 4dp |
| Overlap of badge on stacked icon | 6dp |

Primary tab active indicators are additionally inset 2dp on each side (site, tabs/specs text).
Cross-checked against androidx `PrimaryNavigationTabTokens.kt` / `SecondaryNavigationTabTokens.kt`: both list `ContainerHeight` 48dp, `IconAndLabelTextContainerHeight` 64dp (primary only), `IconSize` 24dp, `ActiveIndicatorHeight` 3dp (primary) with `RoundedCornerShape(3dp)`, `DividerHeight` 1dp (secondary).

Colors (site, tabs/specs):
- Primary tabs (7 roles): Surface (container), Primary (icon), Primary (active label), On surface variant ×2 (inactive icon/label), Outline variant (divider), Primary (active indicator).
- Secondary tabs (5 roles): Surface, On surface (active label — not Primary), On surface variant (inactive label), Outline variant (divider), Primary (active indicator).

States (site, both variants): Enabled, Hover, Focused, Pressed — for both active and inactive destinations (8 total state combinations shown).

### Behaviour and guidelines
- Use to group **related** content at the same hierarchy level — never sequential content that must be read in order (use typographic hierarchy for that instead).
- Container always spans full width, divided into equal sections; bottom-edge divider separates it from content below.
- Icon usage: all tabs in a set must be consistent (either all have icons+labels, or none do) — never a partial mix.
- Labels: single row by default; may wrap to a max second line if needed with truncation, or use scrollable tabs to give longer titles more room.
- Badges: up to 4 characters including a "+"; update or remove once the user has seen the relevant content.
- Active indicator: underline + color change on text/icon distinguishes the active tab.
- Behavior/navigation: tap a tab directly, or (for fixed tabs) swipe left/right in the content area — use caution with other swipeable content in the same region (e.g., maps, list items) since gestures can conflict.
- Scrolling content: tabs can stay fixed at the top or scroll off-screen and reappear on scroll-up; never scroll them behind an app bar — if attached to a component, they must move as one unit with it.

### Accessibility
- Initial focus: arrow/tab lands on the first interactive tab; the active indicator marks it.
- Keyboard: Arrow moves focus to the next navigation destination; Space/Enter activates the focused destination; Arrow also navigates within an attached menu.
- Never use Space/Enter to navigate between tabs — only Arrow/Tab; Space/Enter is reserved for completing actions.
- Don't apply density to tabs by default — keep interactive targets at minimum 48x48 CSS pixels; give users an explicit denser-layout opt-in instead.
- Scrollable tab sets must not loop infinitely — this can trap screen-reader users navigating linearly.
- Labeling: when visible text/icon is ambiguous, use a more descriptive accessibility label (e.g., a "video camera" icon → "Video format media content").

### Source URLs
https://m3.material.io/components/tabs/overview
https://m3.material.io/components/tabs/guidelines
https://m3.material.io/components/tabs/specs
https://m3.material.io/components/tabs/accessibility
https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/PrimaryNavigationTabTokens.kt (+ SecondaryNavigationTabTokens.kt)

---

## Toolbars

### Status
M3 Expressive-only component (no separate M3-baseline toolbar existed before; the equivalent baseline was the bottom app bar, now folded in here as "not recommended"). Two variants: **Docked toolbar** and **Floating toolbar**.
Variant table (site, toolbars/specs, verbatim):

| Variant | M3 | M3 Expressive |
| --- | --- | --- |
| Docked toolbar | -- | Available |
| Floating toolbar | -- | Available |
| Bottom app bar | Available | Not recommended. Use **docked toolbar**. |

Note from site: "Implementation differs per platform. On Jetpack Compose, the floating toolbar is a separate component from the docked toolbar and bottom app bar."

### Anatomy
(site, toolbars/specs, 2 elements): 1. Container, 2. Placed components (slots — buttons, icon buttons, images, text fields, or custom components).

### Variants and configurations
Configuration table (site, toolbars/specs, verbatim):

| Category | Configuration | M3 | M3 Expressive |
| --- | --- | --- | --- |
| Color | Standard (default) | Available as bottom app bar | Available |
| Vibrant | -- | Available |
| Floating toolbar layout | Horizontal (default) | -- | Available |
| Vertical | -- | Available |
| Other elements | With FAB | Available as bottom app bar | Available* |

*Jetpack Compose fully supports floating toolbar + FAB via `HorizontalFloatingToolbar`; other platforms need each element added separately.

- **Docked toolbar**: spans full window width; best for global actions consistent across pages; only ever placed at the bottom; can't coexist with a navigation bar or bottom app bar (same slot).
- **Floating toolbar**: floats above body content; best for contextual, page-specific actions; horizontal or vertical layout; can pair with a FAB.
- **Standard** color: low-emphasis, keeps attention on body content. **Vibrant** color: high-emphasis, draws attention to the controls (also signals a temporary mode like edit mode).

### Specs
Numbers combine site text tables with androidx fallback (`DockedToolbarTokens.kt`, `FloatingToolbarTokens.kt`) for anything only shown in images.

Site text (toolbars/specs, "Measurements"): "By default all toolbars are 64dp high, center-aligned, have equal padding between items, and have a minimum outside padding of 16dp." Default padding between items: 32dp; minimum: 4dp (per androidx). Guidelines page adds: floating toolbar horizontal margin minimum 16dp from window edge; vertical floating toolbar margin minimum 24dp.

androidx `DockedToolbarTokens.kt`: container height 64dp, leading/trailing space 16dp, min spacing between items 4dp, max spacing 32dp, shape CornerNone, color Surface container.
androidx `FloatingToolbarTokens.kt`: container height 64dp, leading/trailing space 8dp, between-item space 4dp, external padding (margin from window edge) 16dp, shape CornerFull, standard color Surface container, vibrant color Primary container; vibrant selected button uses Surface container (icon/text On surface), vibrant unselected button uses On primary container.

Colors (site, toolbars/specs):
- Standard: Surface container (container); Filled button Primary/On primary; Toggle tonal button Secondary container/On secondary container; Standard button Primary.
- Vibrant: Primary container (container); Filled button Primary/On primary; Toggle tonal button Surface container/On surface; Standard button On primary container.

Bottom app bar (baseline, still documented under Toolbars) — see Bottom App Bar section above for full numbers (80dp height, Surface container color, Level2/3dp elevation, CornerNone).

### Behaviour and guidelines
- Docked toolbar and navigation bar occupy the same screen position — **never show both simultaneously**; show the nav bar on primary pages, toolbars on secondary pages with contextual actions.
- Floating toolbars can double as local/secondary navigation tabs between related pages, but must not create redundant/confusing navigation combos with any bar already on screen.
- Container: docked toolbar never gets rounded corners (implies false expandability) — square only; floating toolbar is fully rounded (CornerFull) by default.
- Slot layout: minimum 16dp leading/trailing padding is mandatory; 32dp between-item padding is the default (adjustable). All controls need a minimum 48x48dp target.
- Avoid overloading a toolbar with too many controls — the floating toolbar's container must stay fully visible on screen; overflow into a menu instead of letting the container clip the window edge.
- Only one action should be visually emphasized at a time (filled/tonal icon button, custom color roles, wide icon button, or a paired FAB) — never emphasize more than one control simultaneously (e.g., a button AND a FAB together).
- Never use square icon buttons inside a floating toolbar (visual conflict with its fully-rounded shape) — square buttons are fine in a docked toolbar.
- Floating toolbar elevation is on by default; can be removed if the background already gives visual separation.
- Vertical floating toolbars: not recommended in compact windows (can overwhelm simple/complex layouts alike); when paired with a navigation rail, place the toolbar on the opposite screen edge and use the rail's centered configuration.
- Resizing: docked toolbar always spans 100% width; medium+ breakpoints allow centering all elements or centering one key action while pinning others to the edges. On web/large screens it can gain rounded corners and use dividers to organize many actions, or shrink height / use extra-small buttons only if vertical space is constrained.
- RTL: mirror icons/text direction; if action order matters, reverse the action order too (e.g., "Next" stays on the trailing edge in both directions).
- Scrolling: docked toolbars can stay fixed or animate off-screen; floating toolbars can stay fixed, animate off-screen, or (Jetpack Compose) collapse into a single high-emphasis action/FAB on scroll — never combine collapsing and scroll-transitioning at the same time.

### Accessibility
- The toolbar container itself has **no interactions by default** — all interactive semantics live on the elements placed inside it.
- Web: container should carry the **toolbar** role; mobile: a generic container is fine. Every inner control must still follow its own component's accessibility rules.
- Initial focus lands on the first interactive element; Tab (or Arrows) moves between all others.
- Keyboard: Tab or Arrows → navigate between interactive elements; Space/Enter → activate the focused element.
- Must keep toolbar controls reachable even when content is scrolled/collapsed (explicit use case on the accessibility page).

### Source URLs
https://m3.material.io/components/toolbars/overview
https://m3.material.io/components/toolbars/guidelines
https://m3.material.io/components/toolbars/specs
https://m3.material.io/components/toolbars/accessibility
https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/DockedToolbarTokens.kt
https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/FloatingToolbarTokens.kt

---

## Search

### Status
M3 Expressive (Feb 2025): search bar and search view are now collectively named **Search**. New configurations: **Contained** style (recommended, persistent filled container) vs. **Divided** (baseline, not recommended — "doesn't have the latest visual style, motion, or flexibility"). Gaps can separate result groups. Motion: the search bar grows wider when focused.
Differences from M2 to M3 baseline: new color mappings/dynamic color; lower elevation, no shadow by default; renamed from "open search bar"; two official sub-variants (search bar, search view).
Variant table (site, search/specs, verbatim):

| Variant | M3 | M3 Expressive |
| --- | --- | --- |
| Search | Available | Available |

Style configuration table (site, search/specs, verbatim):

| Category | Configuration | M3 | M3 Expressive |
| --- | --- | --- | --- |
| Style | Contained | -- | Available |
|  | Divided | Available | Not recommended. Use contained. |
| Layout | Docked, full-screen | Available | Available |

Platform availability (site, search/overview): Android Views (MDC-Android) Available, Expressive Unavailable; Flutter Available; Jetpack Compose Available and Expressive Available (`SearchBar`); Web Unavailable.

### Anatomy
(site, search/specs, 6 elements): 1. Search bar container, 2. Leading icon, 3. Supporting text, 4. Trailing icon and avatar (optional), 5. Input text, 6. Container for search suggestions or results.

### Variants and configurations
- **Style**: Contained (filled persistent container, Expressive default) vs. Divided (baseline, divider between search bar and results, not recommended).
- **Layout**: Docked (opens a results list below the bar with a scrim over the rest of the content — best for medium/expanded windows) vs. Full-screen (expands to fill the screen — default for compact windows).

### Specs
Full numeric table present directly in site text (search/specs):

Search bar (unfocused):
| Element | Attribute | Value |
| --- | --- | --- |
| Container | Width | Min: 360dp, max: 720dp |
| | Height | 56dp |
| | Label alignment | Start-aligned |
| | Leading padding | Unfocused: 24dp, focused: 12dp |
| | Trailing padding | Unfocused: 24dp, focused: 12dp |
| | Leading icon/label padding (from tap target) | 4dp |
| | Label/trailing icon padding (from tap target) | 4dp |
| Avatar | Size | 30dp |

Focused search, contained style:
| Element | Attribute | Value |
| --- | --- | --- |
| Full-screen container | Width | Full width |
| | Height | Full height |
| Docked container | Width | Min: 360dp, max: 720dp |
| | Height | Min: 240dp, max: 2/3 of screen height |
| Search bar container | Height | 56dp |
| | Leading/trailing padding | 16dp |
| | Icon/label padding (from tap target) | 4dp |

Cross-checked against androidx: `SearchBarTokens.kt` (container height 56dp, shape CornerFull, avatar size 30dp, color Surface container high, elevation Level3=6dp) and `SearchViewTokens.kt` (docked header height 56dp, full-screen header height 72dp, docked shape CornerExtraLarge=28dp corners, full-screen shape CornerNone, color Surface container high, elevation Level3=6dp).

Colors:
- Full-screen layout (site, 6 roles): Surface container low, On surface variant ×2, Surface container high, On surface variant, On surface.
- Docked layout (site, 6 roles): Surface container high, On surface variant ×2, Surface container high, On surface variant, On surface.

States (site): search bar — Enabled, Hovered, Focused, Pressed (ripple); search results — Enabled, Hovered, Focused, Pressed (ripple).

### Behaviour and guidelines
- Three entry-point styles: **search bar** (search a specific view, e.g. "Search your messages"), **search app bar** (global/primary search, opens the Search view when selected), **search icon button** (search as a secondary action).
- Focused search shows suggestions before typing and/or results while typing/after a query; each element keeps its own interaction state independent of the overall focused state.
- Container color defaults to **Surface container high** to contrast against a white or tonal-surface background; on darker backgrounds use **Surface bright** instead; always keep ≥3:1 contrast between the search text and container. Never use Surface container high on a Surface container background (contrast too low, blends in) — keep container roles at least one step apart.
- Leading icon: navigational icon button (menu/arrow) or a non-functional search icon. Trailing: up to 1–2 icon buttons/icon-button-plus-avatar combos (voice search, location/profile, overflow, decorative search icon, or a "clear" icon once text is entered) — never more than 2 icons + an avatar.
- Adaptive: docked layout for medium/expanded windows; full-screen for compact (default). Search bar should stay in its pane and scale in width; internal elements anchor left/right as the container scales.
- Behavior: back icon releases focus, dismisses suggestions/results, restores the original state. Scroll: can scroll away with content and reappear on scroll-up, or stay fixed. Executing a search: type + Enter, or select a suggestion/result without querying. Input text stays visible (but unfocused) after results are shown. Android predictive back: search detaches from the screen edge to signal it's about to minimize, revealing the previous screen in preview.

### Accessibility
- Screen reader must announce when suggestions/results appear (autosuggest change).
- Initial focus lands on the first interactive element — usually a leading icon button (which then either activates search directly or opens a nav component); if there's no leading icon, focus lands on the text field itself.
- Keyboard: Tab/Shift+Tab → navigate between interactive elements; Space/Enter → activate the text field for input; Arrows → navigate between result items.
- Hinted search text becomes the accessibility label for the search bar. Input field role: **Text field** (Android) / **Search field** (iOS).
- Suggestions/results use the list component and are announced as a list by screen readers (follow list accessibility guidelines for item labels).

### Source URLs
https://m3.material.io/components/search/overview
https://m3.material.io/components/search/guidelines
https://m3.material.io/components/search/specs
https://m3.material.io/components/search/accessibility
https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/SearchBarTokens.kt
https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/SearchViewTokens.kt

---

## Checkbox

### Status
No "M3 Expressive update" section on the checkbox pages (absence noted, not asserted as unchanged). Differences from M2: new color mappings/dynamic color; new **indeterminate** state plus **error** states for unselected/selected/indeterminate.

### Anatomy
(site, checkbox/guidelines and specs, 2 elements): 1. Container, 2. Icon.

### Variants and configurations
Three states: **Selected**, **Unselected**, **Indeterminate** (used for a parent checkbox when only some children are checked). No separate "variant" table on the site — checkbox has a single visual form with these three logical states plus error variants of each (error-selected, error-unselected, error-indeterminate — per androidx tokens, not called out as a table on the site).

### Specs
Full numeric table present directly in site text (checkbox/specs):

| Attribute | Value |
| --- | --- |
| Container size | 18dp |
| Container corner shape | 2dp |
| Icon size | 18dp |
| Icon alignment | Center-aligned |
| Target size | 48dp |
| State-layer size | 40dp |

Cross-checked against androidx `CheckboxTokens.kt`: `ContainerSize` 18dp, `ContainerShape = RoundedCornerShape(2dp)`, `IconSize` 18dp, `StateLayerSize` 40dp, `StateLayerShape` CornerFull. Additional numbers only in the token file (not on the site): unselected outline width 2dp (all interaction states — enabled/hover/focus/pressed/error all use 2dp); selected fill has no outline (0dp, it's a filled shape instead); disabled selected/unselected opacity 0.38.

Colors (site, checkbox/specs): Checkbox (container), State-layer, Icon — light/dark role diagram; adjacent text label always uses **On surface**, regardless of selection state.
States (site): Enabled, Disabled, Hovered, Focused, Pressed.

### Behaviour and guidelines
- Use checkboxes (not switches or radio buttons) when **multiple, related options** can be selected from a list; checkboxes visually group similar items and take less space than switches for that use case.
- Alternate-control guidance: checkboxes = select multiple related options; radio buttons = select exactly one option; switches = standalone/verbose settings.
- Selecting either the checkbox icon or its adjacent text label toggles it.
- Parent/child relationship: checking the parent checks all children; unchecking the parent unchecks all children; if some (not all) children are checked, the parent becomes **indeterminate** — selecting an indeterminate parent checks all children.
- Selection state must be communicated clearly and instantly; if used to turn a setting on/off, the action executes immediately (no separate "save" step implied).
- Responsive: in expanded breakpoints (≥840dp), group checkboxes inside a contained region (e.g., a side sheet) to keep related controls together.

### Accessibility
- Users must be able to navigate to a checkbox, toggle it, and select via either the checkbox or its text label.
- Don't apply density by default — this drops targets below the 48x48 CSS px minimum; offer an explicit density opt-in instead, keeping opt-out targets at ≥48x48 CSS px.
- Keyboard table (site, verbatim — note: this table's content is copy-pasted chip terminology, an apparent site content bug, but is reproduced exactly as published):

| Keys | Actions |
| --- | --- |
| Tab | Moves focus to enabled chip or chip group |
| Space or Enter | Activates, selects, or deselects the focused chip |
| Backspace or Delete | Removes currently focused input chip |
| Arrows | Moves focus between chips |

(Given the checkbox-specific behavior described in "Interaction & style" on the same page — select via label or checkbox, tri-state parent/child — the *intended* keyboard behavior is almost certainly Tab to focus, Space/Enter to toggle; treat the table above as a probable site error rather than checkbox-specific guidance, and verify against the live site before relying on it.)
- Accessibility label = adjacent text label, read by screen readers together with the component's role.

### Source URLs
https://m3.material.io/components/checkbox/overview
https://m3.material.io/components/checkbox/guidelines
https://m3.material.io/components/checkbox/specs
https://m3.material.io/components/checkbox/accessibility
https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/CheckboxTokens.kt

---

## Chips

### Status
No "M3 Expressive update" section (only an "Updates" note: Aug 2024, stroke color changed from **outline** to **outline variant** to soften visual hierarchy vs. buttons). Four variants, unchanged from M3 baseline: **Assist**, **Filter**, **Input**, **Suggestion**. Differences from M2: new color mappings/dynamic color; rounded-rectangle shape; M2's "action chips" split into assist + suggestion; M2's "choice chips" folded into filter chips.

### Anatomy
Common (site, chips/guidelines, 4 elements): 1. Container, 2. Label text, 3. Leading icon or image (optional), 4. Trailing icon (required for input chips, optional for filter chips).
Per-variant element counts (site, chips/specs): Assist 3 (Container, Label text, Leading icon); Filter 4 (+ Trailing icon); Input 4 (Container, Label text, Trailing icon, Leading icon); Suggestion 2 (Container, Label text only).

### Variants and configurations
| Purpose | Chip variant | Rationale |
| --- | --- | --- |
| Action | Assist chip | Represents smart/automated actions, can span apps |
| Filter | Filter chip | Filters for a collection |
| Information, user-authored | Input chip | Discrete info entered by a person |
| Information, product-authored | Suggestion chip | Dynamically-generated suggestions |

- Filter chips: multi-select (tap toggles a leading checkmark) or single-select (selecting one deselects the rest) — never mix single/multi-select behavior across chip sets on the same page.
- Input chips: editable (revert to a text string in edit mode); backspace with cursor before a chip selects the whole chip, backspace again deletes it; can expand to show more info via a container-transform transition.
- All chips can be elevated (default elevation 0) when placed over an image or complex background for extra separation.

### Specs
Full numeric tables present directly in site text (chips/specs) for all four variants:

Assist chip:
| Attribute | Value |
| --- | --- |
| Height | 32dp |
| Shape | 8dp corner radius |
| Icon size | 18dp |
| Vertical label alignment | Center-aligned |
| Horizontal label alignment | Start-aligned |
| Left/right padding | 16dp |
| Left/right padding with icon | 8dp |
| Padding between elements | 8dp |

Filter chip: identical to assist (Height 32dp, Shape 8dp, Icon 18dp, Left/right padding 16dp / 8dp with icon, Padding between elements 8dp).

Input chip:
| Attribute | Value |
| --- | --- |
| Container height | 32dp |
| Container shape | 8dp corner radius |
| Icon size | 18dp |
| Avatar shape | 12dp corner radius |
| Avatar size | 24dp |
| Left padding for avatar | 4dp |
| Right padding for avatar | 8dp |
| Left/right padding for icon | 8dp |
| Padding between elements | 8dp |
| Target size for close icon | Min 48dp |

Suggestion chip:
| Attribute | Value |
| --- | --- |
| Container height | 32dp |
| Container shape | 8dp corner radius |
| Icon size | 18dp |
| Left/right padding without icon | 16dp |
| Left/right padding with icon | 8dp |
| Padding between elements | 8dp |

Colors (site, chips/specs):
- Assist (4 roles): Surface container low (optional elevation fill), On surface (label), Outline (stroke — note: site's Aug 2024 update says default stroke is Outline variant, this diagram may show the interactive/emphasis state), Primary (icon).
- Filter (5 roles): On surface variant (unselected label), On secondary container (selected label), Secondary container (selected fill), Outline variant (stroke), Surface container low (optional elevation).
- Input (9 roles): On surface variant ×3, Surface container low (optional), Outline variant, Primary, Secondary container, On secondary container ×2.
- Suggestion (3 roles): Outline, Surface container low (optional), On surface variant.

States (site, all 4 variants): Enabled, Disabled, Hovered, Focused, Pressed, **Dragged** (chips are the only Group-B component whose state list includes Dragged).

Minimum chip-to-chip spacing (site, guidelines, text): 8dp; minimum target size 48dp regardless of placement/density (target may extend beyond the visible chip container).

### Behaviour and guidelines
- Chips ≠ buttons: chips are dynamic/contextual and appear as a set; buttons are persistent/consistent UI fixtures for significant, linear actions. Never replace a primary/progressing action with a chip.
- Never show a single chip alone — chips always appear in a set (can scroll horizontally).
- Label text: ≤20 characters; can skip conventional grammar (articles) to save space.
- Assist: write like a button, starting with a verb ("Get", "Add"); can show progress/confirmation feedback (e.g., "Save" → "Saved"); displayed after primary content (e.g., under a card, or persistently at the screen bottom).
- Filter: write with nouns describing what to **include**, never negative phrasing ("Exclude images"); trailing icon (remove or open-a-menu) available at medium/expanded breakpoints — at compact breakpoints, make the whole chip the tap target if it opens a menu, since the icon-only target is too small.
- Input: converted from user text (e.g., email → contact chip); supports multiple chips per field, reordering, moving between fields (e.g., "To" → "CC").
- Suggestion: write as nouns/short phrases, ≤20 characters when possible.
- Layout: place inline as a single row, wrapping to new lines when needed, or scroll horizontally if the field is only one row tall; labels truncate when wrapped or wider than the window.
- Trailing icon position flips for RTL (right in LTR, left in RTL).

### Accessibility
- Chip label needs ≥3:1 contrast with the background.
- An action chip must present the same semantics as a **button** to the platform's accessibility API.
- Horizontal overflow: use either a leading "Show all" filter chip that reflows the list downward, or a leading button that opens a menu of all chip options (don't use the menu method on chips that also carry a second action like remove).
- Don't apply density by default — keep targets ≥48x48 CSS px, with an explicit opt-in for denser layouts.
- Keyboard: Tab → focus an enabled chip/chip group; Space/Enter → activate/select/deselect the focused chip; Backspace/Delete → remove the focused input chip; Arrows → move focus between chips.
- Labeling table (site, verbatim):

| Element | A11y label | Role (Web) | Role (MDC-Android) | Role (Compose) |
| --- | --- | --- | --- | --- |
| Image/Icon within chip | Hide image | - | - | - |
| Basic chip (one action) | "{chip content}" | gridcell | button | button |
| Selectable chip | "{chip content}" | gridcell | radio button | checkbox |
| Remove icon (no other action) | "Remove {chip content}" | - | - | - |
| Two actions (select + remove) | "{chip content}." then "Remove {chip content}." | button or checkbox | button or checkbox | button or checkbox |

- Multi-select: Space/Enter toggles the focused chip on/off; only one chip can be in focus even though many can be selected.
- Interactivity must be signaled by a secondary cue beyond color for low-vision/cognitive-disability users: an introductory label ("Select type"), page context ("Filter results"), the darker **Outline** role instead of Outline variant (≥3:1 contrast), or an interactive-sounding label/leading icon.

### Source URLs
https://m3.material.io/components/chips/overview
https://m3.material.io/components/chips/guidelines
https://m3.material.io/components/chips/specs
https://m3.material.io/components/chips/accessibility
https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/AssistChipTokens.kt (+ FilterChipTokens.kt, InputChipTokens.kt, SuggestionChipTokens.kt, ChipsTokens.kt)

---

## Radio Button

### Status
No "M3 Expressive update" section — only a "What's new" note: new color mappings + dynamic color compatibility. Single component form (no variants table).

### Anatomy
(site, radio-button/guidelines, 3 elements): 1. Selected icon, 2. Adjacent label text, 3. Unselected icon.

### Variants and configurations
No variant/configuration tables on the site — radio buttons have one visual form (selected/unselected/disabled states only). Always grouped; only one radio in a group can be selected at a time.

### Specs
Full numeric table present directly in site text (radio-button/specs):

| Attribute | Value |
| --- | --- |
| Icon size | 20dp |
| State layer size | 40dp |
| Target size | 48dp |

Cross-checked against androidx `RadioButtonTokens.kt`: `IconSize` 20dp, `StateLayerSize` 40dp (no explicit target-size token — 48dp comes from the site table). Disabled opacity: selected 0.38, unselected 0.38 (androidx only, not on site).

Colors (site, radio-button/specs, 2 roles): Primary (selected icon), On surface variant (unselected icon). Adjacent label always uses **On surface**, regardless of selection.
States (site): Enabled, Hover, Focus, Pressed, Disabled.

### Behaviour and guidelines
- Use radio buttons (not switches) when **exactly one** option must be selected from a list, and all options should be exposed at once.
- Never nest radio buttons; never let a radio group allow multiple selections.
- Recommended for **five or fewer** options; beyond that, consider a drop-down menu instead — noting the tradeoff that menus cost extra clicks and cognitive effort per selection.
- Always vertically stacked (never horizontal — flagged as a "Caution", not an outright "Don't").
- One option should always be pre-selected in a radio group.
- Selecting either the icon or the adjacent label text activates the radio button; effect is immediate unless inside a dialog/page that explicitly requires a Save step.
- Alternate-control guidance mirrors checkbox/switch: radio buttons = single choice from a set; checkboxes = multi-select; switches = binary settings.

### Accessibility
- Once a radio button is selected, the group cannot be fully deselected by clicking within the group — provide an explicit "Not applicable"/"No option" radio, or a separate "Clear selection" control, if opt-out is needed.
- Don't apply density by default — keep targets ≥48x48 CSS px with an explicit denser-layout opt-in.
- Initial focus: **Tab** (from outside the group) moves focus to the selected radio, or the first one if none are selected; **Shift+Tab** moves focus to the selected radio, or the **last** one if none are selected. Arrows navigate between options once inside the group.
- Keyboard table (site, verbatim):

| Keys | Actions |
| --- | --- |
| Tab | Moves focus into the group to the selected radio button, or the first if none are selected |
| Shift + Tab | Moves focus into the group to the selected radio button, or the last if none are selected |
| Arrows | Moves focus and selects the previous/next radio button; wraps between first and last |
| Space | Selects the focused radio button; does nothing if already selected |

- Group accessibility label = the group's title, role **Radio group**; individual button label = its adjacent text label.

### Source URLs
https://m3.material.io/components/radio-button/overview
https://m3.material.io/components/radio-button/guidelines
https://m3.material.io/components/radio-button/specs
https://m3.material.io/components/radio-button/accessibility
https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/RadioButtonTokens.kt

---

## Sliders

### Status
M3 Expressive (May 2025): added expressive orientation, shape-size, and inset-icon configurations. Naming changes: **continuous** slider → **standard** slider; **discrete** slider → **stops** configuration. New configurations: horizontal/vertical orientation; optional inset icon (standard slider only); five sizes (XS default/S/M/L/XL). Prior "Visual refresh to improve non-text contrast" update (Dec 2023): added centered configuration + range selection; new track/handle shapes with shape-shifting on selection; handle width narrows on press; refreshed colors.
Variant table (site, sliders/specs, verbatim):

| Variant | M3 | M3 Expressive |
| --- | --- | --- |
| Standard | Available as "continuous" slider | Available |
| Centered | Available (web only) | Available |
| Range | Available | Available |
| Discrete | Available | Available as "stops" configuration |

### Anatomy
(site, sliders/guidelines and specs, 6 elements): 1. Value indicator (optional), 2. Stop indicators (optional), 3. Active track, 4. Handle, 5. Inactive track, 6. Inset icon (optional).

### Variants and configurations
Configuration table (site, sliders/specs, verbatim):

| Category | Configuration | M3 | M3 Expressive |
| --- | --- | --- | --- |
| Inset icon | No (default) | Available | Available |
| Yes | -- | Available |
| Orientation | Horizontal (default) | Available | Available |
| Vertical | -- | Available |
| Size | XS (default) | Available | Available |
| S, M, L, XL | -- | Available on Android Views (MDC-Android). Available as tokens on other platforms.* |
| Stop indicators | No (default), Yes | Available as "discrete" slider | Available |
| Value Indicator | No (default), Yes | Available | Available |

*Non-default sizes are token-only on some platforms — no ready-made preset component; swap the `md.comp.slider.xsmall.*` default size tokens for the desired size's tokens.

- **Standard**: value from zero/beginning of a sequence. **Centered**: value from a positive/negative range around a middle zero/default. **Range**: two handles select a min/max range — never use range sliders vertically (too much cognitive load).
- Inset icon: only on Standard sliders sized M/L/XL (never XS/S, and never on centered/range sliders — ambiguous where the slider "starts"). Icon relocates from active to inactive track when there's insufficient room (e.g., value near zero).

### Specs
Full numeric table present directly in site text (sliders/specs):

| Attribute | XS | S | M | L | XL |
| --- | --- | --- | --- | --- | --- |
| Track height | 16dp | 24dp | 40dp | 56dp | 96dp |
| Label container height | 44dp (all sizes) |
| Label container width | 48dp (all sizes) |
| Handle height | 44dp | 44dp | 52dp | 68dp | 108dp |
| Handle width | 4dp (all sizes) |
| Track shape (corner radius) | 8dp | 8dp | 12dp | 16dp | 28dp |
| Inset icon size | -- | -- | 24dp | 24dp | 32dp |

Cross-checked against androidx `SliderTokens.kt` (default/XS-equivalent values): active/inactive track height 16dp, handle width 4dp, handle height 44dp, active handle leading/trailing space 6dp, focus/hover/pressed handle width 2dp (focused/pressed) vs 4dp (hover — matches unpressed default), stop indicator size 4dp, stop indicator trailing space 6dp, value indicator active bottom space 12dp, value-indicator label font Label large.

Colors (site, sliders/specs, 9 roles): Inverse surface / Inverse on surface (value indicator), Primary ×2 (handle, active track), On primary, Secondary container / On secondary container ×2 (inactive track, stop), On primary (again, stop-on-active-track).
States (site): Enabled, Disabled, Hovered, Focused, Pressed.

### Behaviour and guidelines
- Changes must take effect **immediately** so users see the effect of dragging in real time.
- Stop indicators: slider handle snaps to the closest stop; avoid too many stops (visual crowding); all sliders get end-of-inactive-track stops for ≥3:1 contrast unless the inactive track itself already meets that contrast.
- Orientation: horizontal or vertical, per use case; range sliders should stay horizontal only.
- Value indicator: appears while dragging/pressing the handle; for range sliders only one value shows at a time. Can be replaced by an external text-input field kept in sync with the slider (make sure Tab reaches that field directly after the slider).
- Inset icon can swap at the zero value (e.g., volume icon → mute icon).
- Behaviors: **Select & drag** (smooth or stop-snapping), **Select jump** (tap the track to jump/snap the handle), **Select & arrow** (keyboard: Tab focuses the handle, Arrows step by one value/stop, Space+Arrows step by a larger interval/stop).
- XL sliders are reserved for "hero moments" where the slider is the single most important element on the page.

### Accessibility
- Handle shrinks in width and shows its value while pressed/dragged, both on touch and cursor interaction.
- Initial focus lands directly on the handle (primary interactive element); value then adjusts via arrow keys.
- Color contrast: the inactive track's end needs ≥3:1 contrast with the background — a stop indicator or an end-icon satisfies this even when the inactive track itself doesn't meet the ratio.
- Keyboard table (site, verbatim):

| Keys | Actions |
| --- | --- |
| Tab | Moves focus to the slider handle |
| Arrows | Increase/decrease the value by one value or one stop indicator |
| Space & Arrows | Increase/decrease the value by one interval or one stop indicator |
| Home or End | Set the slider to the first and last values |

- Accessibility label = adjacent text label, role **slider**; icon-button steppers placed outside the slider get the **button** role.

### Source URLs
https://m3.material.io/components/sliders/overview
https://m3.material.io/components/sliders/guidelines
https://m3.material.io/components/sliders/specs
https://m3.material.io/components/sliders/accessibility
https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/SliderTokens.kt

---

## Switch

### Status
No "M3 Expressive update" section — differences are all "from M2": more accessible visual presentation; new color mappings meeting non-text-contrast requirements + dynamic color; optional icon inside the handle; taller/wider track than M2.

### Anatomy
(site, switch/guidelines, 3 elements): 1. Track, 2. Handle, 3. Icon (optional).

### Variants and configurations
No formal variant table — configuration is by icon presence (site, switch/specs, "Configurations"): 1. Without icons, 2. Icon on selected switch only, 3. Icon on both selected and unselected switch.

### Specs
Full numeric table present directly in site text (switch/specs):

| Element | Attribute | Value |
| --- | --- | --- |
| Track | Height | 32dp |
| | Width | 52dp |
| | Outline width | 2dp |
| | Shape | Full (stadium) |
| Handle | Height (unselected) | 16dp |
| | Height (with icon) | 24dp |
| | Height (selected) | 24dp |
| | Height (pressed) | 28dp |
| | Width (unselected) | 16dp |
| | Width (with icon) | 24dp |
| | Width (selected) | 24dp |
| | Width (pressed) | 28dp |
| | Shape | Full (stadium) |
| State layer | Size | 40dp |
| Target | Size | 48dp |
| Icon | Size (selected) | 16dp |
| Icon | Size (unselected) | 16dp |

Cross-checked against androidx `SwitchTokens.kt`: `TrackHeight` 32dp, `TrackWidth` 52dp, `TrackOutlineWidth` 2dp, `UnselectedHandleHeight/Width` 16dp, `SelectedHandleHeight/Width` 24dp, `PressedHandleHeight/Width` 28dp, `SelectedIconSize`/`UnselectedIconSize` 16dp, `IconHandleHeight/Width` (icon variant handle) 24dp, `StateLayerSize` 40dp — all match the site table exactly.

Colors (androidx, not itemized as a numbered diagram on the accessible text of the specs page): selected track Primary, selected handle On primary, selected focus/hover/pressed handle Primary container; unselected track Surface container highest, unselected handle Outline, unselected track outline Outline; disabled selected track/handle On surface at 0.12/0.38 opacity respectively, disabled unselected icon/track Surface container highest at 0.38 opacity.

### Behaviour and guidelines
- Best for adjusting **settings/standalone options** — a binary (on/off, true/false) selection; effect takes place **immediately**, no save step.
- Switches control **binary** options, not **opposing** options (e.g., List view vs. Map view is opposing — use a connected button group there instead, not a switch).
- Alternate-control guidance: switches = standalone/verbose settings; checkboxes = multiple related options in a list; radio buttons = single choice from a list.
- Icon inside the handle (optional) must clearly, unambiguously signal on/off (e.g., X vs. checkmark) — avoid ambiguous/non-binary icons (e.g., moon vs. pencil).
- Never put label text inside the switch itself (too small to be accessible) — always pair with an adjacent inline label describing what the switch controls when on.
- A switch can never replace a button — people expect a call-to-action to be a button, and expect a switch's effect to apply immediately (never require a separate save action).

### Accessibility
- Handle grows in size on tap/drag (touch) and on hover/click (cursor) to signal interactivity.
- Don't apply density by default — keep targets ≥48x48 CSS px with an explicit opt-in for denser layouts.
- Initial focus lands directly on the switch handle (its only interactive element).
- Keyboard table (site, verbatim):

| Keys | Actions |
| --- | --- |
| Tab | Focus lands on the switch handle |
| Space or Enter | Toggles the handle on and off |

- Accessibility label = adjacent label text; make more descriptive when the visible label is ambiguous (e.g., "Photo album" → "Photo album access").

### Source URLs
https://m3.material.io/components/switch/overview
https://m3.material.io/components/switch/guidelines
https://m3.material.io/components/switch/specs
https://m3.material.io/components/switch/accessibility
https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/SwitchTokens.kt

---

## Text Fields

### Status
No "M3 Expressive update" section — only "Differences from M2": new color mappings + dynamic color compatibility. Two variants: **Filled** and **Outlined**, both current, no deprecations.

### Anatomy
Filled text field (site, text-fields/guidelines and specs, 10 elements): 1. Container, 2. Leading icon (optional), 3. Label text in empty field, 4. Label text in populated field, 5. Trailing icon (optional), 6. Focused active indicator, 7. Caret, 8. Input text, 9. Supporting text (optional), 10. Enabled active indicator.
Outlined text field (9 elements): 1. Enabled container outline, 2. Label text in empty field, 3. Leading icon (optional), 4. Label text in populated field, 5. Trailing icon (optional), 6. Focused container outline, 7. Caret, 8. Input text, 9. Supporting text (optional).

### Variants and configurations
- **Filled**: more visual emphasis — rounded top corners, square bottom corners, bottom-edge active indicator (a colored/thickening stroke on focus); often used in dialogs and short forms.
- **Outlined**: less visual emphasis — fully rounded corners, full-perimeter outline stroke; used in long forms to reduce visual noise. Both variants have identical functionality — the choice is purely stylistic.
- Both variants also support: prefix/suffix text, supporting text + character counter, error state (replaces supporting text, never shown alongside it), single-line / multi-line / text-area input modes, read-only mode, leading/trailing icons (signifier, valid/error, clear, voice input, dropdown, or a 24dp image).
- Must not intermix filled and outlined fields within the same region/form — separate them by section if both are used in one UI (e.g., outlined in a dialog over an otherwise-filled form).

### Specs
Full numeric tables present directly in site text (text-fields/specs) for both variants:

Filled text field:
| Attribute | Value |
| --- | --- |
| Default container height | 56dp |
| Label alignment (unpopulated) | Vertically centered |
| Top/bottom padding | 8dp |
| Left/right padding without icons | 16dp |
| Left/right padding with icons | 12dp |
| Icon alignment | Vertically centered |
| Padding between icons and text | 16dp |
| Supporting text/counter top padding | 4dp |
| Padding between supporting text and counter | 16dp |
| Target size | 56dp |

Outlined text field:
| Attribute | Value |
| --- | --- |
| Container height | 56dp |
| Left/right padding without icons | 16dp |
| Left/right padding with icons | 12dp |
| Padding between icons and text | 16dp |
| Icon alignment | Vertically centered |
| Supporting text/counter top padding | 4dp |
| Padding between supporting text and counter | 16dp |
| Label alignment | Vertically centered |
| Left/right padding, populated label text | 4dp |
| Target size | 56dp |

Outline/indicator widths — not stated on the site, sourced from androidx `OutlinedTextFieldTokens.kt` / `FilledTextFieldTokens.kt`:
- Outlined: `OutlineWidth` (enabled) 1dp, `HoverOutlineWidth` 1dp, `FocusOutlineWidth` 2dp, `DisabledOutlineWidth` 1dp; container shape `CornerExtraSmall` = 4dp all corners.
- Filled: `ActiveIndicatorHeight` (enabled) 1dp, `HoverActiveIndicatorHeight` 1dp, `FocusActiveIndicatorHeight` 2dp; container shape `CornerExtraSmallTop` = 4dp top corners only, square bottom.

Colors (site, text-fields/specs):
- Filled (10 roles): Surface container highest (container), On surface variant ×2, Primary (focused indicator/label), On surface variant, Primary ×2, On surface, On surface variant, On surface.
- Outlined (9 roles): Outline (enabled outline), On surface variant ×2, Primary (focused outline/label), On surface variant, Primary ×2, On surface, On surface variant.

States (site, both variants): Enabled (empty/populated), Focused (empty/populated), Hovered (empty/populated), Disabled (empty/populated) — plus separate error-state diagrams for Enabled/Focused/Hovered (empty/populated), no Disabled-error state shown.

### Behaviour and guidelines
- Label text: every field needs a label (or an adjacent separate label if the field's purpose is otherwise clear); never truncate, never wrap to multiple lines; moves from mid-field to the top when the field is focused/populated.
- Required fields: show an asterisk (*) next to the label, and explain the convention once via supporting text or a single form-level note; match the asterisk color to any custom required-text color.
- Input modes: **Single-line** (auto-scrolls left at the edge — not for long responses), **Multi-line** (grows to fit content, initially appears single-line — good for compact layouts), **Text area** (fixed height, scrolls vertically, used instead of multi-line fields on web; keep the height within mobile screen bounds).
- Prefix/suffix text: e.g., currency symbol prefix, unit-of-measurement or email-domain suffix.
- Supporting text + character counter: ideally one line (can wrap if needed); can be always-visible or focus-only; counter shows used/limit ratio.
- Error text **replaces** supporting text (never both — avoids layout shift); if multiple errors are possible, describe how to avoid the most likely one; strongly recommended to pair with a trailing error icon for a second, non-color-dependent cue.
- Read-only fields: same visual style as an editable field, but clearly labeled read-only.
- Density: don't apply density by default — keeps targets below the 48x48 CSS px minimum; offer an explicit opt-in instead.
- Adaptive: compact breakpoints can let a text field span full width; medium/expanded should bound it with flexible margins/other containers — never let it span the full width of a large screen.

### Accessibility
- Filled and outlined variants provide identical functionality; color/stroke-thickness changes are the only interaction cue — outlined fields can improve perceived contrast (≥3:1 between outline and background) in some contexts.
- Keyboard table (site, verbatim):

| Keys | Actions |
| --- | --- |
| Tab | Focus lands on (non-disabled) text field |

- Accessibility label = the field's own label text, role **textbox**.
- Interactive trailing icons need a functional label (e.g., "Show password" / "Hide password"); non-actionable icons (e.g., an error icon) get the label "Error."
- Prefix/suffix need their own unique accessibility label (e.g., "Euro" for a currency prefix, "At gmail dot com" for an email suffix).
- Error state: apply role **alert** to the error message; if both supporting text and error text exist, the label states supporting text first, then error text.
- Character counter's label clarifies the count (e.g., "Character count, 5/20").
- Required fields: the label must include the asterisk (e.g., "Username*").

### Source URLs
https://m3.material.io/components/text-fields/overview
https://m3.material.io/components/text-fields/guidelines
https://m3.material.io/components/text-fields/specs
https://m3.material.io/components/text-fields/accessibility
https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/FilledTextFieldTokens.kt
https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/OutlinedTextFieldTokens.kt

---

## Date Pickers

### Status
No "M3 Expressive update" section — only "Differences from M2": larger typography/spacing to accommodate the 48dp target size; new color mappings/dynamic color; the three variants were renamed to be device-independent (former "desktop" picker → **Docked**; former "mobile" picker/input → **Modal date picker** / **Modal date input**).
Three variants: **Docked date picker**, **Modal date picker**, **Modal date input**.

### Anatomy
Docked date picker (site, guidelines, 7 elements): 1. Text field, 2. Menu button, 3. Icon button, 4. Label text, 5. Menu, 6. Text buttons, 7. Container.
Modal date picker, day-selection view (12 elements): Headline, Supporting text, Container, Icon button, Previous/next month buttons, Day of week labels, Today's date, Unselected date, Text buttons, Selected date, Menu button, Divider.
Modal date picker, year-selection view (9 elements): Headline, Supporting text, Container, Icon button, Unselected year, Selected year, Text buttons, Divider, Menu button.
Modal date input (7 elements): Headline, Supporting text, Container, Icon button, Date input, Text buttons, Divider.
Full-screen date picker (range-selection, 14 elements): Headline, Supporting text, Icon button, Container, Text button, Icon button, Divider, Day of week labels, Today's date, Selected date range, Unselected date, Text buttons, Selected date range start date, Month label.

### Variants and configurations
- **Docked**: displays a date-input text field by default; a dropdown calendar appears on tap. Best for near/distant past or future dates since it offers multiple entry methods. Used at **medium/expanded** breakpoints.
- **Modal date picker**: full-screen calendar view; swipe horizontally to change months, scroll vertically to change years, tap the year to open a year picker. Not recommended for distant-past/future dates (e.g., date of birth) — use Docked or Modal input instead there. Supports single date or date-range selection (range: tap start/end dates; scroll vertically across months).
- **Modal date input**: manual numeric keyboard entry, in a dialog; the default view when a calendar isn't needed; users can toggle between Modal picker ↔ Modal input via an edit/calendar icon toggle.
- Used at **compact** breakpoints as a full-screen dialog (covers the whole screen for readability/touch-target size); date pickers don't scale responsively beyond that — sizing is fixed, not fluid, across breakpoints.

### Specs
Site's own measurement diagrams are images with no accompanying text tables; numbers below are sourced from androidx `DatePickerModalTokens.kt` (Compose's "modal" date picker, corresponding to the site's calendar-view components) and `DateInputModalTokens.kt` (the manual-entry dialog).

Modal date picker container (androidx):
- Container width 360dp, height 568dp, shape CornerExtraLarge = 28dp corners, elevation Level3 = 6dp, color Surface container high.
- Header: 360dp × 120dp; headline font Headline large; range-selection header height 128dp, headline font Title large.
- Date cell: 40dp × 40dp, shape CornerFull; state layer 40dp × 40dp; today's-date outline width 1dp.
- Year-selection cell: 72dp × 36dp.
- Range-selection active-indicator (in-range highlight) height 40dp, shape CornerFull.

Modal date input container (androidx): width 328dp, height 512dp, shape CornerExtraLarge = 28dp, elevation Level3 = 6dp, color Surface; header 328dp × 120dp.

Colors — docked date picker (site, date-pickers/specs, 11 roles): Primary, On surface variant ×2, On surface ×2, Primary, On surface variant, Primary, Surface container high, Primary, On primary. Docked menu (7 roles): Primary, On surface variant, On surface, Outline variant, Surface container high, Surface variant, On surface.
Modal date picker, day view (12 roles): On surface, On surface variant ×3, Surface container high, On surface, Primary ×3, On surface, On surface variant, Outline variant. Year view (9 roles): On surface, On surface variant ×3, Surface container high, Primary ×2, Outline variant. Range selector (14 roles): includes Secondary container / On secondary container for the in-range highlight, plus the day-view roles.
Modal date input (7 roles): On surface, On surface variant, Surface container high, On surface variant, Primary ×2, Outline variant.
States (site): Default (enabled), Disabled, Hovered, Focused, Pressed (ripple).

### Behaviour and guidelines
- Docked date pickers can be embedded in dialogs (compact) or text-field dropdowns (medium/expanded).
- Month/year selection navigable via back/next arrows or by tapping the dropdown menu (docked variant).
- Selection is indicated by color; in a date range, start/end dates are fully selected while in-between dates show a subtler "connected" highlight.
- Modal date pickers use an enter/exit transition pattern; dismissible by confirming (**OK**), canceling (**Cancel**), or interacting outside the dialog — otherwise it retains focus. Mobile full-screen pickers add a close (x) icon button and a **Save** confirmation.
- Toggling between calendar and manual-entry views uses the edit/calendar icon.

### Accessibility
- Both entry methods (manual typing and the picker UI) must be available; the calendar icon is the exclusive entry point into the date-picker UI, keeping keyboard/screen-reader interaction optional and minimizing required key presses.
- Touch targets: 48×48dp minimum for all elements — increasing density would hurt accessibility.
- Accessible date input: auto-format the date only after Enter or losing focus — never apply input masks (auto-inserted slashes, etc.) while typing, since that confuses screen-reader users about what they typed. Accept a range of separator formats (dashes, spaces, slashes, dots) plus optional leading zero.
- Optional **Clear** button can be removed if unneeded, to reduce keyboard tab stops.
- Keyboard shortcuts should be exposed via tooltips, readable by screen readers on focus.
- Truncated day-of-week labels get tooltips on hover/focus (though the day-of-week header itself isn't keyboard-focusable — tooltip is pointer-hover only).
- Date-cell color contrast: ≥4.5:1 between date text and background.
- Keyboard table (site, verbatim):

| Keys | Actions |
| --- | --- |
| Enter/return | Closes the calendar and saves the selected date |
| Page up/down | Move to the same date on next/previous month |
| Home/End | Move to the first day of the month |
| Shift + Page up/down | Moves to the same date in the next/previous year |
| Shift + M | Moves to the month list dropdown |
| Shift + Y | Moves to the year list dropdown |

- Labeling table (site, verbatim):

| Element | A11y label | Role |
| --- | --- | --- |
| Previous/next month and year | "{label}" | Button |
| Month and year dropdowns | "{label}" | Button |
| Days of the week | — | Column header |
| Month grid | — | Grid |

- Screen readers verbalize the full date ("Monday, August 17") rather than just the day number.

### Source URLs
https://m3.material.io/components/date-pickers/overview
https://m3.material.io/components/date-pickers/guidelines
https://m3.material.io/components/date-pickers/specs
https://m3.material.io/components/date-pickers/accessibility
https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/DatePickerModalTokens.kt
https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/DateInputModalTokens.kt

---

## Time Pickers

### Status
No "M3 Expressive update" section — only "Differences from M2": new color mappings + dynamic color compatibility. Two variants: **Dial** (drag a handle around a clock face) and **Input** (keyboard entry, reachable from the dial via a keyboard icon).

### Anatomy
Dial time picker (site, guidelines, 17 elements): Label (headline), Time selector separator, Input field, Input text, Period selector (selected), Period selector text (selected), Container, Period selector outline, Period selector text, Dial selector track, Dial label (selected), Text buttons, Icon button, Dial label (unselected), Clock dial, Input text (selected), Input field (selected).
Input time picker (13 elements): Label (headline), Time selector separator, Input field, Input text, Period selector (selected), Period selector text (selected), Container, Period selector outline, Period selector text (unselected), Text buttons, Icon button, Input text (selected), Input field (selected).
Specs page anatomy (dial, 14 elements / input, 10 elements) uses slightly different naming (Headline, Time selector separator, Container, Period selector container, Period selector label text, Clock dial selector center, Clock dial selector track, Text button, Icon button, Clock dial selector container, Clock dial label text, Clock dial container, Time selector label text, Time selector container).

### Variants and configurations
- **Dial**: mimics a round watch face; tap a number or drag the track to select. 12-hour dial: all numbers on one outer ring. 24-hour dial: even numbers on an inner ring, odd numbers on an outer ring (24-hour mode is a system-level setting, not a per-component toggle).
- **Input**: keyboard-only entry; reachable from the dial via the keyboard icon (and vice versa via a clock icon).
- Vertical vs. horizontal (landscape) orientation: in landscape, the stacked input/selector layout becomes side-by-side.
- Hours and minutes always use separate inputs; a 12-hour clock adds an AM/PM selector to the right of minutes (24-hour clock omits it).

### Specs
Full numeric tables present directly in site text (time-pickers/specs) — vertical and horizontal dial layouts share the same values:

| Element | Attribute | Value |
| --- | --- | --- |
| Container | Top/bottom padding | 24dp |
| | Left/right padding | 24dp |
| | Headline alignment | Left |
| Time selector container | Width | 96dp |
| | Width (24h vertical) | 114dp |
| | Height | 80dp |
| Period selector container | Width (vertical layout) | 52dp |
| | Height (vertical layout) | 80dp |
| | Width (horizontal layout) | 216dp |
| | Height (horizontal layout) | 38dp |
| Clock dial container | Size | 256dp |
| Clock dial selector handle | Size | 48dp |
| Clock dial selector center | Size | 8dp |
| Clock dial selector track | Width | 2dp |

Time picker input:
| Element | Attribute | Value |
| --- | --- | --- |
| Container | Top/bottom padding | 24dp |
| | Left/right padding | 24dp |
| | Headline alignment | Left |
| Time input field container | Width | 96dp |
| | Height | 72dp |
| Period selector container | Width | 52dp |
| | Height | 72dp |

Colors — dial (site, 17 roles): On surface variant, On surface ×2, Surface container highest, Tertiary container, On tertiary container, Surface container high, Outline, On surface, Primary, On primary, Primary, On surface variant, On surface, Surface container highest, On primary container, Primary container.
Colors — input (13 roles): same family, condensed (no clock-dial-specific roles).
States (site): Enabled, Hover, Focus, Pressed.

### Behaviour and guidelines
- Modal, dialog-based presentation, with a scrim over the rest of the screen — never obscured by other elements; reorients or changes variant (dial ↔ input) to avoid being cropped by the screen edge.
- Not intended for granular/nuanced time selection (e.g., stopwatch milliseconds) — for hours/minutes only.
- Adaptive: swaps orientation/variant based on device orientation and viewport height; falls back to the Input variant when there isn't enough vertical room for the dial in landscape. Never apply density to the dial when the viewport is constrained — switch to the input variant instead.
- Selecting time: type directly into hour/minute fields, or select a field then adjust the dial (both update the field simultaneously).
- Confirms with **OK** / dismisses with **Cancel**; interacting outside the dialog also dismisses it; otherwise the picker retains focus (same "enter and exit" transition family as other dialogs).
- Never scrolls — reorients or swaps variant instead of scrolling with page content.

### Accessibility
- Manual text entry must be available, not just the dial — important for keyboard-only users; if the screen is too small for the dial, the Input variant can become the default (Android Views currently always shows the dial regardless).
- Dial selector touch targets: 48×48dp.
- Keyboard table (site, verbatim):

| Keys | Actions |
| --- | --- |
| Tab | Focus lands on (non-disabled) time slot |
| Space or Enter | Activates the (non-disabled) time slot |

- Dial selector announces a total, e.g. "Hour 7 of 12."
- Labeling tables (site, verbatim):

Dial selector:
| Element | A11y label | Role (Wiz/Compose) | Role (Android Views) |
| --- | --- | --- | --- |
| Hour input (input picker) | Hour | Text input | - |
| Minutes input | Minute | Text input | - |
| AM/PM selection | AM or PM | Radio button (in list) | Checkbox (in list) |
| Keyboard button | Toggle input picker | Button | Button |
| Cancel button | Cancel | Button | Button |
| OK button | OK | Button | Button |
| Clock dial time selection | {Value} Hours or minutes of {Total} | Button | - |

Input selector:
| Element | A11y label | Role (Wiz/Compose) | Role (Android Views) |
| --- | --- | --- | --- |
| Hour input | Hour | Text input | - |
| Minutes input | Minute | Text input | - |
| Clock button | Toggle dial picker | Button | Button |
| Cancel button | Cancel | Button | Button |
| OK button | OK | Button | Button |

### Source URLs
https://m3.material.io/components/time-pickers/overview
https://m3.material.io/components/time-pickers/guidelines
https://m3.material.io/components/time-pickers/specs
https://m3.material.io/components/time-pickers/accessibility
https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/TimePickerTokens.kt
https://raw.githubusercontent.com/androidx/androidx/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens/TimeInputTokens.kt

---

## Data Tables

### Status
**Not part of the M3 design spec** — data tables have no page on m3.material.io (confirmed: not present in the site's component index at https://m3.material.io/components, nor findable via search). The only first-party documentation is the material-components-android (MDC-Android) stub page, which itself says the component is unfinished:

> "The DataTable component is yet to be completed, please follow the tracking issue for more information." (material-components-android/docs/components/DataTable.md, verbatim, 241-byte file — this is the entire page content)
> Tracking issue: https://github.com/material-components/material-components-android/issues/76

No androidx Compose Material3 token file exists for data tables either (not present in the `tokens/` directory browsed for this reference). Any data-table implementation in a Material 3 Expressive component library is therefore necessarily **not spec-derived** — there is no Google-published anatomy, measurements, color roles, or accessibility guidance for this component in the M3 or M3 Expressive design system as of this audit. Treat any data-table component in the audited library as custom/unspecified rather than as an M3 deviation.

### Anatomy
Not documented by Google for M3.

### Variants and configurations
Not documented by Google for M3.

### Specs
Not documented by Google for M3. (Not on the site; no source available — do not substitute M2 data-table specs, since M3 has never published its own.)

### Behaviour and guidelines
Not documented by Google for M3.

### Accessibility
Not documented by Google for M3.

### Source URLs
https://raw.githubusercontent.com/material-components/material-components-android/master/docs/components/DataTable.md
(checked and absent: https://m3.material.io/components — no "Data table" entry in the component index)

---

## Appendix: fetch notes for auditors

- Several M3 pages render their real body content under an `##` (H2) heading rather than `# ` (H1) even though the page clearly has full content (Title/URL Source/Markdown Content headers present, real anatomy/spec/behavior text follows). Affected in this batch: `app-bars/overview`, `app-bars/guidelines`, `app-bars/specs`, `toolbars/accessibility`. These were verified by manual inspection to be complete, not truncated or rate-limited, despite an automated "# " heading check flagging them.
- True fetch failures (HTTP 429 rate-limit JSON bodies, or a jina.ai "cached snapshot ... shadow DOM" warning page) were retried and succeeded on retry for: `navigation-rail/guidelines`, `navigation-rail/specs`, `navigation-rail/accessibility` (plain retry), and `sliders/overview` (required an `x-no-cache: true` header to bypass a stale jina.ai cache entry).
- All 60 requested M3 site pages for this component group are now present and verified non-empty/non-error in `$SCRATCH/m3/raw/`.