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.

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 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.

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
• Interop Patterns