/android-compose-migration

name: android-compose-migration
description: Migrate an Android XML View to Jetpack Compose following a structured 10-step workflow. Use when converting XML layouts to Compose, setting up Compose in an existing View-based project, or incrementally adopting Compose.
metadata:
  triggers:
    files:
    - 'layout/*.xml'
    - '**/*Fragment.kt'
    - '**/*Activity.kt'
    keywords:
    - migrate to compose
    - xml to compose
    - compose migration
    - ComposeView
    - AndroidView
    - interoperability

XML to Jetpack Compose Migration

**Priority: P1 (HIGH)**

Structured 10-step workflow for migrating XML layouts to Compose.

Step 1: Identify the migration candidate

If the user specified a target XML layout, proceed to Step 2. Otherwise, pick the best candidate:

• Prefer leaf layouts (not deeply nested in other XMLs).
• Prefer layouts with few custom Views.
• Avoid layouts with complex RecyclerView adapters as a first migration.

Step 2: Analyze the layout

Examine the XML structure: list all Views, data bindings, click listeners, style references, and custom Views needing `AndroidView` wrappers.

Step 3: Create a plan

Generate a checklist of every View → Composable mapping. Present to user for approval.

Step 4: Capture baseline UI

Ask the user for a screenshot, or take one via emulator for visual comparison.

Step 5: Set up Compose dependencies

Check `build.gradle.kts` or `libs.versions.toml` for Compose BOM and compiler. If missing, add them. See [dependency setup](references/dependency-setup.md).

Step 6: Set up Compose theming

If missing, initialize minimum required theme — map XML colors/styles to Compose. Do NOT migrate the entire theme.

Step 7: Migrate the XML layout

Convert each View to its Compose equivalent. See [interop patterns](references/interop-patterns.md) for the View→Composable mapping table, ComposeView, and AndroidView usage. Include a `@Preview` for every new Composable. Use `LazyColumn` or `LazyRow` for list-heavy screens instead of flattening them into one large static composable.

Step 8: Replace usages

Use `ComposeView` to host Compose in Views, or `AndroidView` for Views in Compose. See [interop patterns](references/interop-patterns.md).

Step 9: Validate

Compare baseline screenshot with Compose Preview. Focus on layout and styling. Iterate until visual parity.

Step 10: Clean up

Delete the migrated XML file and legacy tests. Only remove code not referenced elsewhere.

Verification

• [ ] Compose Preview renders correctly.
• [ ] Visual parity with original XML layout.
• [ ] `./gradlew build` succeeds.
• [ ] No broken references to deleted XML files.

Anti-Patterns

• **No full theme migration**: Only migrate what the target layout needs.
• **No new View instances in AndroidView update**: Mutate existing, don't recreate.
• **No missing ViewCompositionStrategy**: Always set it on ComposeView to avoid leaks.

References

• [Dependency Setup](references/dependency-setup.md)
• [Interop Patterns](references/interop-patterns.md)