XML To Compose Migrator

XML to Jetpack Compose migrator and verifier

Use this skill when converting Android XML layouts into Jetpack Compose, or when auditing and aligning Compose screens against legacy XML layouts.

It covers full screens (Activities and Fragments), modal layouts (Dialogs and Bottom Sheets), repeated items (RecyclerView list items), and modular partials (includes and custom compound views).

1. Plan-first workflow for batch or project-wide migrations

When asked to migrate all XML layouts, a large group of screens, or an entire module, prepare a plan first before modifying or deleting any existing code.

Step 1: Inventory and dependency audit

Scan all layout directories across the app and modules:

• res/layout
• res/layout-land
• Module layout folders (such as shared UI modules)

Group each XML file by component type:

1. Activities (activity_*.xml)
2. Fragments (fragment_*.xml)
3. Dialogs and Bottom Sheets (dialog_*.xml, bottom_sheet_*.xml)
4. List/Grid Items (item_*.xml, list_item_*.xml)
5. Partials and Compounds (view_*.xml, layout_*.xml, header_*.xml)

Step 2: Document the migration plan in <workspace>/docs/

Save the plan as a Markdown file in the project's documentation folder: <workspace>/docs/xml_to_compose_migration_plan.md

The document must detail:

• Current inventory table (layout file, host class, migration status, target composable path).
• Wave order (order of execution: items and dialogs first, then fragments, then host activities).
• Shared state and ViewModel bindings needed per screen.
• Theme and typography tokens mapped from XML attributes.
• Risk factors (such as third-party View dependencies, custom drawables, or legacy animations).

Step 3: User approval

Present the plan document path to the user and request confirmation before touching code. Once approved, proceed wave by wave.

Step 4: Subagent delegation (optional for parallel tasks)

For large migrations with independent screens (for example, five separate activity layouts that share no state), launch subagents using invoke_subagent:

• Assign one subagent per independent screen or feature module.
• Provide each subagent with the exact target file path, XML reference path, and verification instructions.
• Aggregate build results once all subagents finish.

2. Single layout migration workflow

When migrating or verifying a single layout file or screen, follow this four-step sequence:

1. Analyze the XML layout, associated themes, attributes, and host component (Activity, Fragment, Adapter, or Dialog).
2. Find or create the target Composable file following project conventions.
3. Translate view elements, styling, layout constraints, and interactions line by line.
4. Run Kotlin build verification and fix any compile or lint errors.

3. Deep XML analysis checklist

Before writing any Compose code, inspect these core areas:

View to Compose element mappings

Styling and theme tokens

Never hardcode hex values when color tokens exist in your theme:

• ?attr/colorPrimary translates to MaterialTheme.colorScheme.primary
• ?attr/colorSurface translates to MaterialTheme.colorScheme.surface
• ?attr/colorSurfaceContainerHigh translates to MaterialTheme.colorScheme.surfaceContainerHigh
• ?attr/colorOnErrorContainer translates to MaterialTheme.colorScheme.onErrorContainer
• Custom project theme extensions translate to corresponding MaterialTheme extension properties
• Ripple effects and highlights (?attr/colorControlHighlight) use default Material 3 interactions

Typography and strings

• Map android:textAppearance="?attr/textAppearanceTitleLarge" to MaterialTheme.typography.titleLarge.
• Map android:textStyle="bold" to fontWeight = FontWeight.Bold.
• Map android:fontFamily to the project's configured font family.
• Always load strings using stringResource(R.string.your_string_name) instead of hardcoding English text.

Interactive states and accessibility

• android:textIsSelectable="true": Wrap the Text composable inside SelectionContainer { Text(...) }. Crucial for stack traces, error reports, and IDs.
• android:contentDescription: Always supply a descriptive string or null for decorative elements.
• android:enabled="false": Pass enabled = false to the composable.
• android:maxLines="N": Pass maxLines = N, overflow = TextOverflow.Ellipsis.

4. Handling different layout types

Type A: Full screen Activity layouts (activity_*.xml)

1. Add enableEdgeToEdge() in the Activity's onCreate() before setContent.
2. Wrap content in Scaffold.
3. Pass innerPadding from Scaffold to scroll containers using contentPadding = innerPadding or .padding(innerPadding).consumeWindowInsets(innerPadding) to prevent content from hiding beneath navigation and status bars.

Type B: Fragment layouts (fragment_*.xml)

1. Create the screen composable Screen.kt.
2. In Fragment.onCreateView, return ComposeView:

override fun onCreateView(
    inflater: LayoutInflater,
    container: ViewGroup?,
    savedInstanceState: Bundle?
): View {
    return ComposeView(requireContext()).apply {
        setViewCompositionStrategy(ViewCompositionStrategy.DisposeOnViewTreeLifecycleDestroyed)
        setContent {
            YourFragmentScreen(...)
        }
    }
}

Type C: Bottom sheets and dialogs

1. Map BottomSheetDialogFragment to ModalBottomSheet(onDismissRequest = { ... }).
2. Map AlertDialog to AlertDialog or custom Dialog composable.
3. Use FilledTonalButton or TextButton for dismiss and confirm actions.

Type D: RecyclerView item layouts (item_*.xml, list_item_*.xml)

1. Convert the XML into a standalone item composable (for example UserListItem(...)).
2. Supply clear callback parameters for user interactions like onClick: (Item) -> Unit and onLongClick: (() -> Unit)? = null.
3. Keep the item composable stateless. Pass data through model objects.

Type E: Compound views and included layouts (view_*.xml, layout_*.xml)

1. Convert each <include layout="@layout/header_view" /> into an independent composable function.
2. Group related UI state into plain data classes if more than four parameters are passed.

5. Detection and target naming rules

Search existing files before generating new ones:

• activity_profile.xml maps to ProfileScreen.kt in ui/profile/
• activity_manage_project.xml maps to ManageProjectScreen.kt in ui/project/
• item_product.xml maps to ProductItem.kt or ProductListItem.kt in ui/store/components/
• dialog_alert_warning.xml maps to WarningAlertDialog.kt in ui/components/

When in doubt, search the codebase with git or directory tools to verify whether an existing composable already serves the screen.

6. Verification and build checks

After making code changes, verify your work:

./gradlew :app:compileDebugKotlin

Resolve any compile errors immediately, including:

• Deprecated composables or modifiers (such as menuAnchor() or TabRow).
• Missing extended Material icons (ensure material-icons-extended is imported if needed).
• Unconsumed window insets causing duplicate padding.