Migra temas de XML a Material 3 en Compose

Si implementas Compose en una app existente, deberás migrar tus temas XML de Material para usar MaterialTheme en los componentes de Compose. Eso significa que el tema de tu app tendrá dos fuentes de confianza: un tema basado en View y otro basado en Compose. Si decides realizar cambios en tu diseño, deberás hacerlos en varios lugares. Una vez que tu app se haya migrado por completo a Compose, quita el tema XML.

Puedes usar la herramienta Material Theme Builder para migrar colores.

Cuando comiences la migración de XML a Compose, migra el tema a Material 3 Compose.

Glosario

Término Definición
MaterialTheme Es la función de componibilidad que proporciona temas (colores, tipografía, formas) a los componentes de la IU de Compose.
Shapes Objeto de Compose que se usa para definir formas de componentes personalizadas para un MaterialTheme.
Typography Es un objeto de Compose que se usa para definir estilos de texto personalizados (familias de fuentes, tamaños y pesos) para un MaterialTheme.
ColorScheme Es un objeto de Compose que se usa para definir esquemas de colores personalizados para MaterialTheme.
Tema XML Es el sistema de temas de Android definido en archivos XML y utilizado por el sistema de View.

Limitaciones

Antes de migrar, ten en cuenta las siguientes limitaciones:

  • Esta guía solo se enfoca en la migración a Material 3. Para migrar desde sistemas de diseño alternativos, consulta Material 2 o Sistemas de diseño personalizado en Compose.
  • El objetivo final es completar la migración a Compose, lo que permitirá quitar el tema de XML. En esta guía, se explica cómo migrar, pero no se explica cómo quitar definitivamente el tema XML.

Paso 1: Evalúa el sistema de diseño

Identifica qué sistema de diseño se usa en el proyecto de XML View. Analiza la ruta de migración y los pasos necesarios para migrar el sistema de diseño existente a Material 3 en Compose.

Paso 2: Identifica los archivos fuente del tema

En XML, escribes ?attr/colorPrimary. En Compose, puedes acceder a los valores del tema con MaterialTheme.*:

Identifica y ubica todos los recursos y archivos XML necesarios para la aplicación de temas: esquemas y calificadores de color claro y oscuro, temas, formas, dimensiones, tipografía, estilos y otros archivos relevantes.

Los recursos, como las cadenas, se pueden reutilizar tal como están y no es necesario migrarlos.

Paso 3: Migra los colores

Principio clave: XML usa colores hexadecimales con nombre. Material 3 usa roles semánticos (p.ej., primary, onPrimary, surface). Deja de nombrar los colores por su valor hexadecimal y nómbralos por su rol.

Ejemplos:

Nombre del color en XML Rol de Material 3
colorPrimary primary
colorPrimaryDark/colorPrimaryVariant primaryContainer o secondary
colorAccent secondary o tertiary
colorOnPrimary onPrimary
android:colorBackground background
colorSurface surface
colorOnSurface onSurface
colorError error
colorOnError onError
colorOutline outline
colorSurfaceVariant surfaceVariant
colorOnSurfaceVariant onSurfaceVariant

Migra los esquemas de colores claro y oscuro de XML a sus equivalentes en Material 3 Compose.

Paso 4: Migra formas y tipografía personalizadas

  • Si tu app usa formas personalizadas, haz lo siguiente:

    1. En tu código de Compose, define un objeto Shapes para replicar tus definiciones de forma en XML.

    2. Proporciona este objeto Shapes a tu MaterialTheme.

      Para obtener más detalles, consulta formas.

  • Si tu app usa tipografía personalizada, haz lo siguiente:

    1. En tu código de Compose, define un objeto Typography para replicar tus definiciones de fuentes y estilos de texto en XML.

    2. Proporciona este objeto Typography a tu MaterialTheme.

      Para obtener más detalles, consulta Tipografía.

Rol de redacción Nombre de XML
displayLarge TextAppearance.Material3.DisplayLarge
displayMedium TextAppearance.Material3.DisplayMedium
displaySmall TextAppearance.Material3.DisplaySmall
headlineLarge TextAppearance.Material3.HeadlineLarge
headlineMedium TextAppearance.Material3.HeadlineMedium
headlineSmall TextAppearance.Material3.HeadlineSmall
titleLarge TextAppearance.Material3.TitleLarge
titleMedium TextAppearance.Material3.TitleMedium
titleSmall TextAppearance.Material3.TitleSmall
bodyLarge TextAppearance.Material3.BodyLarge
bodyMedium TextAppearance.Material3.BodyMedium
bodySmall TextAppearance.Material3.BodySmall
labelLarge TextAppearance.Material3.LabelLarge
labelMedium TextAppearance.Material3.LabelMedium
labelSmall TextAppearance.Material3.LabelSmall

Paso 5: Migra los estilos (styles.xml)

El sistema de diseños XML (styles.xml) define el diseño y la apariencia de los siguientes elementos:

  1. Widgets, componentes y temas para ventanas y diálogos
  2. Tipografía
  3. Temas y superposiciones
  4. Formas

Las vistas y los componentes XML combinan varios atributos para crear un diseño. Establecen sus estilos desde styles.xml de dos maneras diferentes:

  1. Configurar "style="@style/…" de forma directa y explícita en la vista XML
  2. Establecer el estilo de forma indirecta e implícita para un componente como parte de un tema más grande (theme.xml)

Los diseños no tienen un equivalente directo en Compose. En cambio, se pasan como parámetros o modificadores a elementos componibles, con la nueva API de Styles experimental definida en AppTheme, o bien creando variaciones componibles reutilizables en capas con el diseño definido.

Proporciona funciones @Composable separadas con nombres según el diseño y el componente base para indicar la diferencia en el diseño y los casos de uso de esos componentes.

  • Patrón: Si un elemento XML usa un estilo personalizado (p.ej., style="@style/MyPrimaryButton"), no intentes replicar el estilo intercalado. En su lugar, sugiere crear un elemento componible específico.
  • Ejemplo:
    • XML: <Button style="@style/MyPrimaryButton" ... />
    • Compose: MyPrimaryButton(onClick = { ... })
  • Grupos de atributos comunes: Si un diseño establece modificadores comunes (como padding y altura), extráelos en una propiedad de extensión legible o en una variable de Modifier compartida.

Ejemplos comunes

XML Redactar
Theme.Material3.* MaterialTheme(colorScheme, typography, shapes) { }
TextAppearance.Material3.BodyMedium TextStyle(...) definido en Typography(bodyMedium = ...)
ShapeAppearance.*.SmallComponent Shapes(small = RoundedCornerShape(X.dp))
Widget.Material3.Button Button(colors = ButtonDefaults.buttonColors(...))
Widget.Material3.CardView Card(shape=..., elevation=..., colors=...)
Widget.*.TextInputLayout.OutlinedBox OutlinedTextField(colors = OutlinedTextFieldDefaults.colors(...))
Widget.*.Chip.Filter FilterChip(colors = FilterChipDefaults.filterChipColors(...))
Widget.*.Toolbar.Primary TopAppBar(colors = TopAppBarDefaults.topAppBarColors(...))
Widget.*.FloatingActionButton FloatingActionButton(containerColor = ...)
backgroundTint containerColor en ComponentDefaults.ComponentColors()
android:textColor contentColor en ComponentDefaults.ComponentColors()
cornerRadius shape = RoundedCornerShape(X.dp)
android:elevation elevation = ComponentDefaults.elevation(defaultElevation = X.dp)
android:padding contentPadding = PaddingValues(...) o Modifier.padding()
android:minHeight Modifier.heightIn(min = X.dp)
strokeColor y strokeWidth border = BorderStroke(width, color)
android:textSize fontSize = X.sp en TextStyle

Paso 6: Valida la migración del tema

Siempre usa los valores de tema existentes del tema XML original como fuente de confianza para el nuevo tema de Material en Compose. Nunca inventes valores de temas nuevos durante la migración para mantener la coherencia de la marca y evitar regresiones visuales.

Verifica que todos los valores nuevos del tema de Compose coincidan con los valores XML existentes. No codifiques de forma rígida ningún valor migrado.