wear-compose-m3

Prerequisites and compatibility

Current Wear OS Compose version in-use: To find the installed library version, read
```
gradle/libs.versions.toml
```
or
```
build.gradle.kts
```
directly. Don't run
```
./gradlew dependencies
```
or other shell commands to resolve versions.
Wear OS Compose Material3 version: If an internal tool is available to establish the latest stable version
```
{VERSION}
```
of
```
androidx.wear.compose:compose-material3
```
, use that tool.
- Otherwise, fetch the official Maven metadata XML to identify
```
{VERSION}
```
  (highest number, ignoring
```
-alpha
```
  ,
```
-beta
```
  , or
```
-rc
```
  ).
Strict compliance: If a version is listed as stable, you MUST use it, unless overridden by the user. Do not downgrade based on initial "Unresolved reference" errors in the editor or outdated web search results.
Kotlin version: For Wear Compose Material3, use Kotlin 2.0.0 or higher.
Compose compiler:
- If Kotlin version is 2.0.0+ , the project must use the
```
org.jetbrains.kotlin.plugin.compose
```
 Gradle plugin.
- If Kotlin version is < 2.0.0 , the project must use
```
kotlinCompilerExtensionVersion
```
 in
```
composeOptions
```
 , matching the Compose to Kotlin Compatibility Map.
Min SDK: Ensure
```
minSdk
```
is at least 25.
Sample extraction mandate: Wear Compose libraries ship with an additional JAR file which contains individual samples for each and every component. You mustn't propose code changes, other than previews or basic changes such as color changes, until the samples in Capability 3 are extracted to the local cache. Library source files are incomplete and NOT a substitute for these samples; bypassing extraction is an environment setup failure.

Gotchas

Mandatory sync and validation: After updating versions in
```
libs.versions.toml
```
or
```
build.gradle.kts
```
, you must perform a Gradle sync before refactoring any code. This ensures the environment has resolved the libraries correctly.
Prohibition of guessing (error protocol): If you encounter an 'Unresolved Reference' or API mismatch after a successful sync, do not attempt to 'fix' it by downgrading the library version.

Capabilities and tools

Capability 1: Migration

Use this guidance when migrating from an older version of Wear OS Compose or Horologist.

Unless otherwise indicated by the developer, use the latest stable version of Wear Compose Material3 from
```
{VERSION}
```
.
Read the migration guide.
Use the official component mappings from the migration guide.
Before refactoring any component (for example,
```
Chip
```
->
```
Button
```
), check the parameter names, slot types, and "Expressive" design tokens.
Do not use the Horologist Composables, Compose Layout, or Compose Material libraries.
Always check against the component guidance in Capability 4.
Expect screenshot tests to fail when a migration has been performed: Even when migrating to very similar components, expected defaults for padding and positioning will have changed. Do not seek to artificially match the pre-migration screenshot, but give preference to the Material3 defaults.

Capability 2: Adding Wear OS Compose Material3 features or updating the app

Use this guidance when the developer asks to update a project which is using an earlier version of Wear OS Compose Material3, or when they ask to add further features.

Unless otherwise indicated by the developer, use the latest stable version of Wear Compose Material3 from
```
{VERSION}
```
.
Do not use the Horologist Composables, Compose Layout, or Compose Material libraries.
Always check against the component guidance in Capability 4.
Expect screenshot tests to fail when a migration has been performed: Even when migrating to very similar components, expected defaults for padding and positioning will have changed. Do not seek to artificially match the pre-migration screenshot, but give preference to the Material3 defaults.

Capability 3: Component samples

Use this table of reference to find canonical samples for Wear Compose components. When working with a Wear Compose component, you must use the samples linked from the table to ensure you know how to correctly use it.

Material 3 components in

androidx.wear.compose.material3.*

Component / Symbol	Reference Samples
`AlertDialog` , `AlertDialogDefaults`	AlertDialogSample
`AnimatedPage` , `HorizontalPagerScaffold` , `VerticalPagerScaffold`	OneHandedGestureSamples, PageIndicatorSample, PagerScaffoldSample
`AnimatedText` , `rememberAnimatedTextFontRegistry`	AnimatedTextSample
`AppCard`	CardSample
`AppScaffold`	ListHeaderSample, PagerScaffoldSample, ScaffoldSample, SurfaceTransformationSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample
`ArcProgressIndicator` , `ArcProgressIndicatorDefaults` , `CircularProgressIndicator` , `CircularProgressIndicatorDefaults` , `ProgressIndicatorDefaults` , `SegmentedCircularProgressIndicator` , `drawCircularProgressIndicator`	ProgressIndicatorSample
`Button`	AlertDialogSample, AnimatedTextSample, ButtonGroupSample, ButtonSample, DatePickerSample, DynamicColorSchemeSample, FadingExpandingLabelSample, ListHeaderSample, OneHandedGestureSamples, PageIndicatorSample, PagerScaffoldSample, PickerSample, ScaffoldSample, ScrollIndicatorSample, StepperSample, SurfaceTransformationSample, SwipeToRevealSample, TimePickerSample, TransformationSpecSample, TransformingLazyColumnSample, TransformingLazyColumnSample
`ButtonDefaults`	ButtonSample, CurvedTextSamples, DynamicColorSchemeSample, EdgeButtonSample, ListHeaderSample, PlaceholderSample, ScaffoldSample, ScrollAwaySample, ScrollIndicatorSample, SurfaceTransformationSample, TextButtonSample, TransformationSpecSample, TransformingLazyColumnSample, TransformingLazyColumnSample
`ButtonGroup`	ButtonGroupSample, TransformationSpecSample
`Card`	CardSample, SwipeToRevealSample, TransformingLazyColumnSample
`CardDefaults`	CardSample, SurfaceTransformationSample, SwipeToRevealSample, TransformingLazyColumnSample, TransformingLazyColumnSample
`CheckboxButton`	CheckboxButtonSample, SwipeToDismissBoxSample
`ChildButton` , `OutlinedButton`	ButtonSample
`ColorScheme` , `dynamicColorScheme`	DynamicColorSchemeSample
`CompactButton` , `CompactButtonDefaults`	ButtonSample, TransformingLazyColumnSample
`ConfirmationDialog` , `ConfirmationDialogDefaults` , `FailureConfirmationDialog` , `FavoriteIcon` , `SuccessConfirmationDialog` , `confirmationDialogCurvedText`	ConfirmationDialogSample
`CurvedTextDefaults`	CurvedTextSamples
`DatePicker` , `DatePickerType`	DatePickerSample
`EdgeButton`	EdgeButtonSample, OneHandedGestureSamples, ScaffoldSample, TransformingLazyColumnSample
`EdgeButtonSize`	EdgeButtonSample
`FadingExpandingLabel`	FadingExpandingLabelSample
`FilledIconButton` , `FilledTonalIconButton` , `IconButtonColors` , `IconButtonShapes` , `OutlinedIconButton`	IconButtonSample
`FilledTonalButton`	AlertDialogSample, ButtonSample, ConfirmationDialogSample, OpenOnPhoneDialogSample, PlaceholderSample, ScrollAwaySample, SwipeToDismissBoxSample
`GestureAction` , `OneHandedGestureClickIndicator` , `OneHandedGestureClickIndicatorState` , `oneHandedGesture` , `rememberOneHandedGestureConfiguration`	ButtonSample, CardSample, OneHandedGestureSamples
`GesturePriority` , `LocalOneHandedGestureEnabled` , `OneHandedGestureDefaults` , `OneHandedGestureHorizontalPageIndicator` , `OneHandedGesturePageIndicatorState` , `OneHandedGestureScrollIndicator` , `OneHandedGestureScrollIndicatorState` , `OneHandedGestureVerticalPageIndicator`	OneHandedGestureSamples
`HeadphoneIcon` , `Stepper` , `StepperLevelIndicator` , `rangeSemantics`	StepperSample
`HorizontalPageIndicator` , `VerticalPageIndicator`	PageIndicatorSample
`Icon`	AlertDialogSample, ButtonSample, CardSample, CheckboxButtonSample, ConfirmationDialogSample, CurvedTextSamples, DatePickerSample, EdgeButtonSample, IconButtonSample, ListHeaderSample, PlaceholderSample, ProgressIndicatorSample, RadioButtonSample, SwipeToRevealSample, SwitchButtonSample, TimePickerSample
`IconButton`	IconButtonSample, LevelIndicatorSample, ProgressIndicatorSample
`IconButtonDefaults`	IconButtonSample, ProgressIndicatorSample
`IconToggleButton` , `IconToggleButtonDefaults` , `WifiOffIcon` , `WifiOnIcon`	IconToggleButtonSample
`LevelIndicator`	LevelIndicatorSample
`LinearProgressIndicator`	LinearProgressIndicatorSample
`ListHeader`	ListHeaderSample, ScrollAwaySample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample
`ListHeaderDefaults`	ListHeaderSample, ScrollAwaySample, TransformingLazyColumnSample
`ListSubHeader`	ListHeaderSample
`MaterialTheme`	AlertDialogSample, ButtonSample, CardSample, CurvedTextSamples, DynamicColorSchemeSample, LinearProgressIndicatorSample, PagerScaffoldSample, ProgressIndicatorSample, SwipeToDismissBoxSample, TimeTextSample, TransformingLazyColumnNotificationsSample
`OpenOnPhoneDialog` , `OpenOnPhoneDialogDefaults` , `openOnPhoneDialogCurvedText`	OpenOnPhoneDialogSample
`OutlinedCard`	CardSample, TransformingLazyColumnSample
`PagerScaffoldDefaults`	PageIndicatorSample, PagerScaffoldSample
`Picker`	PickerSample
`PickerGroup`	PickerGroupSample
`RadioButton` , `SplitRadioButton`	RadioButtonSample
`ResponsiveTransformationSpec` , `TransformationVariableSpec`	SurfaceTransformationSample, TransformationSpecSample
`RevealValue` , `SwipeToReveal` , `SwipeToRevealDefaults` , `rememberRevealState`	SwipeToRevealSample
`ScreenScaffold`	ListHeaderSample, OneHandedGestureSamples, PagerScaffoldSample, ScaffoldSample, SurfaceTransformationSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample
`ScreenScaffoldDefaults` , `ScrollIndicator`	ScrollIndicatorSample
`ScreenStage` , `scrollAway`	ScrollAwaySample
`Slider` , `SliderDefaults`	SliderSample
`SplitCheckboxButton`	CheckboxButtonSample
`SplitSwitchButton`	SwitchButtonSample
`StepperDefaults` , `VolumeDownIcon` , `VolumeUpIcon`	LevelIndicatorSample, StepperSample
`SurfaceTransformation`	AlertDialogSample, DynamicColorSchemeSample, ListHeaderSample, ScaffoldSample, SurfaceTransformationSample, TransformationSpecSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample, TransformingLazyColumnSample
`SwipeToDismissBox`	SwipeToDismissBoxSample
`SwitchButton`	AlertDialogSample, OneHandedGestureSamples, SwitchButtonSample
`Text`	AlertDialogSample, AnimatedTextSample, ButtonGroupSample, ButtonSample, CardSample, CheckboxButtonSample, ConfirmationDialogSample, DatePickerSample, DynamicColorSchemeSample, EdgeButtonSample, ListHeaderSample, OneHandedGestureSamples, OpenOnPhoneDialogSample, PageIndicatorSample, PagerScaffoldSample, PickerGroupSample, PickerSample, PlaceholderSample, RadioButtonSample, ScaffoldSample, ScrollAwaySample, ScrollIndicatorSample, StepperSample, SurfaceTransformationSample, SwipeToDismissBoxSample, SwipeToRevealSample, SwitchButtonSample, TextButtonSample, TextToggleButtonSample, TimePickerSample, TransformationSpecSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample
`TextButton`	TextButtonSample
`TextButtonDefaults`	TextButtonSample, TextToggleButtonSample
`TextToggleButton` , `TextToggleButtonDefaults` , `touchTargetAwareSize`	TextToggleButtonSample
`TimePicker` , `TimePickerType`	TimePickerSample
`TimeText`	ScrollAwaySample, ScrollIndicatorSample, TimeTextSample
`TimeTextDefaults` , `timeTextCurvedText`	TimeTextSample
`TitleCard`	CardSample, SurfaceTransformationSample, SwipeToRevealSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample
`TransformationSpec`	TransformationSpecSample
`curvedText`	CurvedTextSamples, ScrollAwaySample, TimeTextSample
`firstVisibleItemLayoutItemInfo` , `layoutItemInfoOf` , `rememberTransformingLazyColumnFirstLayoutItemProvider`	TransformingLazyColumnSample
`placeholder` , `placeholderShimmer` , `rememberPlaceholderState`	PlaceholderSample
`rememberPickerState`	PickerGroupSample, PickerSample
`rememberTransformationSpec` , `transformedHeight`	AlertDialogSample, DynamicColorSchemeSample, ListHeaderSample, ScaffoldSample, SurfaceTransformationSample, SwipeToRevealSample, TransformationSpecSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample, TransformingLazyColumnSample
`timeTextSeparator`	ScrollAwaySample, TimeTextSample

Foundation components in

androidx.wear.compose.foundation.*

Component / Symbol	Reference Samples
`AmbientMode` , `AmbientTickEffect` , `LocalAmbientModeManager` , `rememberAmbientModeManager`	AmbientModeSample
`AutoCenteringParams` , `ScalingLazyColumnDefaults` , `ScalingLazyListAnchorType`	ScalingLazyColumnSample
`BasicSwipeToDismissBox`	SwipeToDismissBoxSample
`CurvedAlignment` , `CurvedTextStyle` , `angularGradientBackground` , `angularSize` , `basicCurvedText` , `clearAndSetSemantics` , `curvedColumn` , `padding` , `radialGradientBackground` , `radialSize` , `semantics` , `size`	CurvedWorldSample
`CurvedDirection` , `CurvedLayout` , `angularSizeDp` , `background` , `curvedBox` , `curvedComposable` , `curvedRow`	CurvedTextSamples, CurvedWorldSample
`CurvedModifier`	CurvedTextSamples, CurvedWorldSample, TimeTextSample
`ExperimentalWearFoundationApi` , `RevealValue` , `SwipeToReveal` , `rememberRevealState`	SwipeToRevealSample
`HorizontalPager` , `VerticalPager` , `rememberPagerState`	OneHandedGestureSamples, PageIndicatorSample, PagerSamples, PagerScaffoldSample
`ItemEdge` , `TransformingLazyColumnDefaults`	TransformingLazyColumnSample
`PagerDefaults`	PagerScaffoldSample
`RotaryScrollableDefaults`	PagerScaffoldSample, RotarySamples, ScalingLazyColumnSample, TransformingLazyColumnSample
`RotarySnapLayoutInfoProvider` , `rotaryScrollable`	RotarySamples
`ScalingLazyColumn`	ExpandableSample, HierarchicalFocusSample, OneHandedGestureSamples, ScalingLazyColumnSample, SwipeToRevealSample, SwipeToRevealSample
`ScrollInfoProvider`	ScrollAwaySample
`SwipeToDismissValue` , `edgeSwipeToDismiss` , `rememberSwipeToDismissBoxState`	SwipeToDismissBoxSample, SwipeToDismissBoxSample
`TransformingLazyColumn`	DynamicColorSchemeSample, ListHeaderSample, OneHandedGestureSamples, ScaffoldSample, ScrollAwaySample, ScrollIndicatorSample, SurfaceTransformationSample, SwipeToRevealSample, TransformationSpecSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample, TransformingLazyColumnSample
`TransformingLazyColumnFirstLayoutItemProvider`	TransformingLazyColumnSample, TransformingLazyColumnSample
`TransformingLazyColumnItemScrollProgress`	TransformationSpecSample
`expandableButton` , `expandableItems`	ExpandableSample
`expandableItem` , `rememberExpandableState`	ExpandableSample, SwipeToRevealSample
`hierarchicalFocusGroup`	HierarchicalFocusSample
`items`	SwipeToRevealSample, TransformingLazyColumnNotificationsSample
`itemsIndexed`	TransformingLazyColumnSample
`rememberScalingLazyListState`	OneHandedGestureSamples, ScalingLazyColumnSample, SwipeToRevealSample
`rememberTransformingLazyColumnState`	ListHeaderSample, OneHandedGestureSamples, ScaffoldSample, ScrollAwaySample, ScrollIndicatorSample, SurfaceTransformationSample, SwipeToRevealSample, TransformingLazyColumnNotificationsSample, TransformingLazyColumnSample, TransformingLazyColumnSample
`requestFocusOnHierarchyActive`	HierarchicalFocusSample, RotarySamples
`weight`	CurvedWorldSample, TimeTextSample

Capability 4: Component guidance

Mandatory: Use this capability as a checklist against any component use. It provides more holistic guidance on how to use each component in practice, beyond the component syntax.

```
AppScaffold
```
and
```
ScreenScaffold
```
- [ ] Use
```
AppScaffold
```
  as the outer container, with
```
ScreenScaffold
```
  children.
- [ ] Use only ONE
```
AppScaffold
```
  and any number of
```
ScreenScaffold
```
  .
```
ScalingLazyColumn
```
- Use
```
TransformingLazyColumn
```
instead.

TransformingLazyColumn

- You will need the following imports:

kotlin

import androidx.wear.compose.foundation.lazy.TransformingLazyColumn
import androidx.wear.compose.foundation.lazy.TransformingLazyColumnDefaults
import androidx.wear.compose.foundation.lazy.rememberTransformingLazyColumnState
// ...
import androidx.wear.compose.material3.lazy.rememberTransformationSpec
import androidx.wear.compose.material3.lazy.transformedHeight

Canonical example:

kotlin

val columnState = rememberTransformingLazyColumnState()
val transformationSpec = rememberTransformationSpec()
ScreenScaffold(
    scrollState = columnState
) { contentPadding ->
    TransformingLazyColumn(
        state = columnState,
        contentPadding = contentPadding
    ) {
        item {
            ListHeader(
                modifier = Modifier
                    .fillMaxWidth()
                    .transformedHeight(this, transformationSpec)
                    .minimumVerticalContentPadding(ListHeaderDefaults.minimumTopListContentPadding),
                transformation = SurfaceTransformation(transformationSpec)
            ) {
                Text(text = "Header")
            }
        }
        // ... other items
        item {
            Button(
                modifier = Modifier
                    .fillMaxWidth()
                    .transformedHeight(this, transformationSpec)
                    .minimumVerticalContentPadding(ButtonDefaults.minimumVerticalListContentPadding),
                transformation = SurfaceTransformation(transformationSpec),
                onClick = { /* ... */ },
                icon = {
                    Icon(
                        imageVector = Icons.Default.Build,
                        contentDescription = "build",
                    )
                },
            ) {
                Text(
                    text = "Build",
                    maxLines = 1,
                    overflow = TextOverflow.Ellipsis,
                )
            }
        }
    }
}

[ ] Use
```
TransformingLazyColumn
```
instead of
```
ScalingLazyColumn
```
.

[ ] You must pass the

contentPadding

parameter from

ScreenScaffold

to the

TransformingLazyColumn

[ ] Use the
```
minimumVerticalContentPadding
```
modifier to achieve required padding top and bottom.
- This expects a value from defaults, such as
```
ButtonDefaults
```
  ,
```
CardDefaults
```
  , `ListHeaderDefaults.
- Note: This is a scoped modifier available within
```
TransformingLazyColumnItemScope
```
  .
[ ] Ensure the list morphs and scales.
[ ] Use
```
transformedHeight
```
modifier.
[ ] Use
```
transform = SurfaceTransform(...)
```
.
[ ] If configuring a list for snapping, use
```
flingBehavior
```
and
```
rotaryScrollableBehavior
```
together:

kotlin

val columnState = rememberTransformingLazyColumnState()
ScreenScaffold(scrollState = columnState) { contentPadding ->
    TransformingLazyColumn(
        state = columnState,
        flingBehavior = TransformingLazyColumnDefaults.snapFlingBehavior(columnState),
        rotaryScrollableBehavior = RotaryScrollableDefaults.snapBehavior(columnState)
    ) {
        // ...
        // ...
    }
}

ScreenScaffold

[ ] Guard the

scrollIndicator

with

!LocalScrollCaptureInProgress.current

EdgeButton

[ ] Do NOT use as the final item within a
```
TransformingLazyColumn
```
. Instead, use the slot in
```
ScreenScaffold
```
.
[ ] When used in a
```
TransformingLazyColumn
```
, add the required overscroll behavior:

kotlin

val columnState = rememberTransformingLazyColumnState()
ScreenScaffold(
    scrollState = columnState,
    edgeButton = {
        EdgeButton(
            onClick = { /* TODO */ },
            modifier = Modifier.scrollable(
                columnState,
                orientation = Orientation.Vertical,
                reverseDirection = true,
                // Apply overscroll to the EdgeButton for proper scrolling behavior.
                overscrollEffect = rememberOverscrollEffect(),
            )
        ) {
            Text("More")
        }
    }
) { contentPadding ->
    TransformingLazyColumn(
        contentPadding = contentPadding,
        state = columnState,
    ) {
        // ...
        // ...
    }
}

```
Column
```
- [ ] USE as a direct child of
```
ScreenScaffold
```
  if the screen is will never scroll, even with the largest system font.
- [ ] Use
```
TransformingLazyColumn
```
  instead for all other cases.
Styles
- [ ] Do NOT hard-code text sizes, use
```
typography
```
  from
```
MaterialTheme
```
  .
- [ ] Do NOT hard-code colors, use
```
colorScheme
```
  from
```
MaterialTheme
```
  .
Use component defaults:
- [ ] Components such as
```
Button
```
  have a corresponding
```
ButtonDefaults
```
  object.
- [ ] Check for and use the
```
*Defaults
```
  object for any component when working with padding and styling values, in preference to hard-coded values.
Use Wear specific previews:
- [ ]
```
WearPreviewDevices
```
- [ ]
```
WearPreviewFontScales
```

Ambient mode

[ ] Use

LocalAmbientModeManager

instead of

AmbientLifecycleObserver

Navigation
- [ ] When adding navigation fresh, use Navigation3.
- [ ] For Navigation3 in Wear OS, use
```
SwipeDismissableSceneStrategy()
```
  from the Wear Compose
```
compose-navigation3
```
  library.
Comments
- [ ] Where any Kotlin file has been modified, ensure that the existing comments are up to date and accurately reflect any changes to the implementation.

HorizontalPager

VerticalPager

[ ] Use the Composable hierarchy in this order:

AppScaffold

HorizontalPagerScaffold

HorizontalPager

AnimatedPage

ScreenScaffold

. Or similarly for

VerticalPager

wear-compose-m3

NPX Install

Tags

SKILL.md Content

Prerequisites and compatibility

Gotchas

Capabilities and tools

Capability 1: Migration

Capability 2: Adding Wear OS Compose Material3 features or updating the app

Capability 3: Component samples

Material 3 components in
`androidx.wear.compose.material3.*`

Foundation components in
`androidx.wear.compose.foundation.*`

Capability 4: Component guidance