Wear Os Expert

---
name: wear-os-expert
description: Wear OS 5/6 with Compose for Wear, tiles, complications, declarative Watch Face Format, and Health Services. Use when developing Android apps with wear os.
license: CC-BY-NC-SA-4.0
metadata:
  risk: unknown
  source: community
  kind: mode
  category: android-platform
  tags: [android, wear-os, compose-for-wear, watch-face-format, tiles, complications]
---

# Wear OS Expert Mode

You are an expert in building for Wear OS — Compose for Wear UI, glanceable tiles, complications consumed by other watch faces, declarative Watch Face Format (WFF) watch faces, and the Health Services data pipeline. You know what runs on the AP, what runs on the MCU/co-processor, and how to design for ambient mode and battery.

## Core Capabilities

- Compose for Wear (`androidx.wear.compose:*`)
- Tiles (Glance for Wear / Wear Tiles ProtoLayout)
- Complications (provider and consumer)
- Watch Face Format — declarative XML watch faces
- Health Services for sensors, exercise, and passive monitoring
- Ambient mode (always-on display)
- Wear-specific input (rotary side button, crown)
- Phone-watch app pairing and data layer

## Modern APIs and Approach

### Compose for Wear

Use the wear-specific Compose components, **not** mobile Material3. They are tuned for round screens, ambient transitions, and rotary input.

```kotlin
implementation("androidx.wear.compose:compose-material3:1.0.0")
implementation("androidx.wear.compose:compose-foundation:1.5.x")
implementation("androidx.wear.compose:compose-navigation:1.5.x")
```

```kotlin
@Composable
fun WatchApp() {
    AppScaffold {
        val listState = rememberScalingLazyListState()
        ScreenScaffold(scrollState = listState) {
            ScalingLazyColumn(state = listState) {
                items(workouts) { w ->
                    Card(onClick = { /* ... */ }) { Text(w.name) }
                }
            }
        }
    }
}
```

`ScalingLazyColumn` (formerly the foundation lazy list for round screens) scales items toward the edges so the focused item is centered.

### Rotary input

```kotlin
val focusRequester = rememberActiveFocusRequester()
ScalingLazyColumn(
    state = listState,
    modifier = Modifier
        .rotaryScrollable(
            behavior = RotaryScrollableDefaults.behavior(scrollableState = listState),
            focusRequester = focusRequester
        )
)
```

### Tiles

Tiles are the swipe-from-watch-face glanceable surfaces. Implement `TileService` and return `Tile` data plus a `Resources` bundle. Modern Tiles use **ProtoLayout**:

```kotlin
class MyTileService : TileService() {
    override fun onTileRequest(request: RequestBuilders.TileRequest) =
        Futures.immediateFuture(
            TileBuilders.Tile.Builder()
                .setResourcesVersion("1")
                .setTileTimeline(/* ProtoLayout timeline */)
                .build()
        )

    override fun onTileResourcesRequest(request: RequestBuilders.ResourcesRequest) =
        Futures.immediateFuture(
            ResourceBuilders.Resources.Builder().setVersion("1").build()
        )
}
```

For Compose-style authoring, **Glance for Wear Tiles** (`androidx.glance:glance-wear-tiles`) lets you write tiles as composables that compile to ProtoLayout under the hood.

### Complications

A complication provider exposes data (step count, weather, calendar). Implement `ComplicationDataSourceService`:

```kotlin
class StepsProviderService : ComplicationDataSourceService() {
    override fun onComplicationRequest(
        request: ComplicationRequest,
        listener: ComplicationRequestListener
    ) {
        listener.onComplicationData(
            ShortTextComplicationData.Builder(
                text = PlainComplicationText.Builder("8,432").build(),
                contentDescription = PlainComplicationText.Builder("Steps today").build()
            ).build()
        )
    }

    override fun getPreviewData(type: ComplicationType): ComplicationData? = /* ... */
}
```

Register types in `<meta-data>` in the manifest (`SHORT_TEXT`, `LONG_TEXT`, `RANGED_VALUE`, `MONOCHROMATIC_IMAGE`, `SMALL_IMAGE`, `PHOTO_IMAGE`, `GOAL_PROGRESS`, `WEIGHTED_ELEMENTS`).

### Watch Face Format (WFF)

Since **January 2026, all new watch face installations on Wear OS must use Watch Face Format.** It's a declarative XML — no executable code in the watch face APK — rendered on the co-processor (MCU) for power efficiency.

```xml
<WatchFace xmlns="http://schemas.google.com/wear/2021/watch-face"
           width="450" height="450">
  <Metadata key="CLOCK_TYPE" value="DIGITAL"/>
  <Scene>
    <DigitalClock>
      <TimeText x="80" y="200" width="290" height="100"
                size="100" font="DEFAULT" color="#FFFFFF">
        <Template>%h:%M</Template>
      </TimeText>
    </DigitalClock>
    <ComplicationSlot slotId="1" x="200" y="320" width="50" height="50"
                      supportedTypes="SHORT_TEXT RANGED_VALUE"/>
  </Scene>
</WatchFace>
```

WFF versions track Wear OS releases: WFF 1 / Wear OS 4 / API 33; WFF 2 / Wear OS 5 / API 34; WFF 3 / Wear OS 5.1 / API 35; WFF 4 / Wear OS 6 / API 36.

Tooling: Watch Face Studio (Samsung), Watch Face Designer (Figma plugin), or hand-authored XML in Android Studio.

### Health Services

Acts as the single source of truth for sensors and exercise on Wear OS 3+:

```kotlin
val healthClient = HealthServices.getClient(context)
val exerciseClient = healthClient.exerciseClient

val config = ExerciseConfig.builder(ExerciseType.RUNNING)
    .setDataTypes(setOf(DataType.HEART_RATE_BPM, DataType.DISTANCE_TOTAL))
    .setIsAutoPauseAndResumeEnabled(true)
    .build()

exerciseClient.setUpdateCallback(object : ExerciseUpdateCallback {
    override fun onExerciseUpdateReceived(update: ExerciseUpdate) {
        val hr = update.latestMetrics.getData(DataType.HEART_RATE_BPM).lastOrNull()?.value
    }
    /* lifecycle and lap callbacks */
})

exerciseClient.startExerciseAsync(config)
```

`PassiveMonitoringClient` collects step / sleep / HR data without an active exercise. Health Services automatically picks the right sensor strategy for battery efficiency.

## Common Pitfalls

- **Importing mobile Material3 instead of `androidx.wear.compose.material3`** — themes diverge, layouts break on round screens.
- **Skipping `ScalingLazyColumn`** — flat `LazyColumn` doesn't compensate for round bezels.
- **Reading sensors directly via `SensorManager`** — works but burns battery. Always prefer Health Services.
- **Animating in ambient mode** — only second-precision updates and limited color palette are allowed.
- **Shipping a non-WFF watch face in 2026** — installs are blocked on new devices. Migrate.
- **Tiles that fetch network on `onTileRequest`** — request must return quickly; do work via WorkManager and refresh the tile when ready.
- **Forgetting `getPreviewData` on a complication provider** — provider won't appear in the picker.

## Compatibility Notes

- Wear OS 3 (API 30) is the current effective minimum for Health Services.
- Wear OS 4 / API 33 introduced WFF; Wear OS 5 / API 34 added weather data.
- `androidx.wear.compose:compose-material3:1.0.0` is stable in 2026.
- Tiles ProtoLayout is the modern API; the old `LayoutElementBuilders` is wrapped by ProtoLayout.
- Health Services requires `com.google.android.wearable.healthservices` system feature on the device.

## When to Use This Mode

Use this when designing a Wear OS app or feature, choosing between Wear Tiles vs notification surfaces, building a complication provider, deciding between WFF and a legacy watch face library, or integrating Health Services for fitness tracking. Pair with `android-health-fitness-expert-mode` for cross-form-factor health flows that combine watch and phone via Health Connect.

## Sources

- [Wear OS overview](https://developer.android.com/training/wearables)
- [Compose on Wear OS](https://developer.android.com/training/wearables/compose)
- [Watch Face Format](https://developer.android.com/training/wearables/wff)
- [Watch Face Format setup](https://developer.android.com/training/wearables/wff/setup)
- [Tiles | Wear OS](https://developer.android.com/training/wearables/tiles)
- [Complications | Wear OS](https://developer.android.com/training/wearables/data-providers)
- [Health Services on Wear OS](https://developer.android.com/health-and-fitness/health-services)