Mappatura degli stili per la composizione del tema

Figma consente ai designer di applicare uno stile a un elemento di design. Uno stile è una raccolta riutilizzabile di proprietà, come colori o elementi tipografici. Poiché è definito centralmente, un team può definire e aggiornare le proprietà di tutti i progetti quando si aggiorna un singolo elemento di design. Puoi configurare Relay in modo che traduca gli stili Figma in temi di Jetpack Compose.

La mappatura tra gli stili Figma e i temi di Compose viene specificata tramite un file di configurazione.

Ad esempio, il design Figma mostrato di seguito utilizza gli stili del kit di design Material 3 di Google. Per il testo Principale - Titolo grande, il carattere è M3/title/large e il colore è M3/sys/light/primary.

Se importiamo il design con la traduzione degli stili M3 Design Kit attivata, viene generato il seguente codice per il testo Principale - Titolo grande:

@Composable
fun PrimaryTitleLarge(modifier: Modifier = Modifier) {
    Text(
        content = "Primary - Title large",
        fontSize = MaterialTheme.typography.titleLarge.fontSize,
        fontFamily = MaterialTheme.typography.titleLarge.fontFamily,
        color = MaterialTheme.colorScheme.primary,
        height = MaterialTheme.typography.titleLarge.lineHeight,
        letterSpacing = MaterialTheme.typography.titleLarge.letterSpacing,
        textAlign = TextAlign.Left,
        fontWeight = MaterialTheme.typography.titleLarge.fontWeight,
        modifier = modifier
    )
}

Per usare questa funzionalità, usa gli stili come faresti normalmente in Figma. In Android Studio, vai a File > Nuovo > Importa pacchetti UI... e seleziona Traduci stili Figma in tema Scrivi.

A questo punto, devi scegliere una configurazione per tradurre gli stili del tuo progetto:

• Se provengono direttamente dal Material 3 Design Kit di Google per Figma (con il formato M3/body/medium or M3/sys/light/primary), seleziona l'opzione Configurazione di Material 3 Design Kit.
• Se provengono direttamente dal Material 2 Design Kit di Google per Figma (che ha il formato 01. Primary/500 or Subtitle 1), seleziona l'opzione Configurazione di Material 2 Design Kit.

• Se hai definizioni di stile personalizzate, seleziona l'opzione Configurazione personalizzata e scegli il file che contiene le mappature tra gli stili Figma e i temi di Compose (descritti in questa sezione).

  

Se nel design Figma sono presenti stili che non sono presenti nella configurazione selezionata, la finestra di dialogo Importa mostra un avviso per ogni stile non mappato. Ogni stile non mappato viene invece tradotto nel suo valore letterale. Gli avvisi vengono inizialmente compressi; fai clic sul banner degli avvisi per espanderli. Ogni avviso include un link al livello specifico nel file Figma che causa l'avviso.

Dopo l'importazione, la configurazione dello stile si trova nel progetto Android Studio. Cercali nella directory ui-package-resources/style-mappings.

File di configurazione per le traduzioni personalizzate

La traduzione degli stili Figma in temi di Compose richiede due passaggi:

1. Uno stile Figma in un pacchetto UI viene convertito in un token di progettazione nel file JSON di definizione del pacchetto UI, all'interno della cartella Pacchetto UI nel progetto Android Studio.
2. Un token di progettazione in un file di definizione del pacchetto UI viene tradotto in uno snippet di codice del tema di Scrivi nel tuo progetto Android Studio.

Il formato del file di configurazione personalizzato (in formato JSON) riflette questi due passaggi. Ecco un esempio di file di configurazione personalizzata semplice che gestisce solo gli stili di colore:

{
  "figma": {
    "colors": {
      "my-app-theme/sys/light/primary": "myapp.sys.color.primary",
      "my-app-theme/sys/light/primary-container": "myapp.sys.color.primary-container",
      "my-app-theme/sys/light/background": "myapp.sys.color.background",
      "my-app-theme/sys/light/on-background": "myapp.sys.color.on-background",
      "my-app-theme/sys/dark/background": "myapp.sys.color.background",
      "my-app-theme/sys/dark/on-background": "myapp.sys.color.on-background"
    }
  },
  "compose": {
    "colors": {
      "myapp.sys.color.primary": "MaterialTheme.colorScheme.primary",
      "myapp.sys.color.primary-container": "MaterialTheme.colorScheme.primaryContainer",
      "myapp.sys.color.background": "MaterialTheme.colorScheme.background",
      "myapp.sys.color.on-background": "MaterialTheme.colorScheme.onBackground"
    },
    "options": {
      "packages": {
        "MaterialTheme": "androidx.compose.material3"
      }
    }
  }
}

Esistono due sezioni di primo livello: figma (che specifica il passaggio 1) e compose (che specifica il passaggio 2). Entrambi includono una sezione colors:

• La sezione colors di figma specifica uno stile Figma e il token di progettazione corrispondente che deve essere scritto nel file di definizione del pacchetto UI.
• La sezione colors di compose specifica un token di progettazione nel file di definizione del pacchetto UI e lo snippet di codice corrispondente che deve essere scritto nel codice di Compose.

Nella configurazione di esempio riportata sopra, per qualsiasi elemento che utilizza il colore my-app-theme/sys/light/primary in Figma il colore è scritto come myapp.sys.color.primary nel file di definizione del pacchetto UI. Poi, durante la generazione del codice, il colore viene scritto come MaterialTheme.colorScheme.primary in Scrivi.

La sezione compose contiene anche una sezione options, in cui viene indicato in quale pacchetto si trova un determinato simbolo di codice. L'esempio riportato sopra indica che MaterialTheme si trova nel pacchetto androidx.compose.material3, che deve quindi essere importato in qualsiasi codice generato.

La mappatura degli stili tipografici è un po' più complessa rispetto agli stili di colore. Ecco lo stesso esempio di cui sopra, ma con l'aggiunta di stili tipografici:

{
  "figma": {
    "colors": {
      "my-app-theme/sys/light/primary": "myapp.sys.color.primary",
      "my-app-theme/sys/light/primary-container": "myapp.sys.color.primary-container",
      "my-app-theme/sys/light/background": "myapp.sys.color.background",
      "my-app-theme/sys/light/on-background": "myapp.sys.color.on-background",
      "my-app-theme/sys/dark/background": "myapp.sys.color.background",
      "my-app-theme/sys/dark/on-background": "myapp.sys.color.on-background"
    },
    "typography": {
      "symbols": {
        "my-app-theme/headline/large": "myapp.sys.typescale.headline-large",
        "my-app-theme/body/medium": "myapp.sys.typescale.body-medium"
      },
      "subproperties": {
        "fontFamily": "font",
        "fontWeight": "weight",
        "fontSize": "size",
        "letterSpacing": "tracking",
        "lineHeightPx": "line-height"
      }
    }
  },
  "compose": {
    "colors": {
      "myapp.sys.color.primary": "MaterialTheme.colorScheme.primary",
      "myapp.sys.color.primary-container": "MaterialTheme.colorScheme.primaryContainer",
      "myapp.sys.color.background": "MaterialTheme.colorScheme.background",
      "myapp.sys.color.on-background": "MaterialTheme.colorScheme.onBackground"
    },
    "typography": {
      "symbols": {
        "myapp.sys.typescale.headline-large": "MaterialTheme.typography.headlineLarge",
        "myapp.sys.typescale.body-medium": "MaterialTheme.typography.bodyMedium"
      },
      "subproperties": {
        "font": "fontFamily",
        "weight": "fontWeight",
        "size": "fontSize",
        "tracking": "letterSpacing",
        "line-height": "lineHeight"
      }
    },
    "options": {
      "packages": {
        "MaterialTheme": "androidx.compose.material3"
      }
    }
  }
}

La struttura delle sezioni tipografiche riflette il fatto che uno stile tipografico è costituito da molte proprietà secondarie. In Figma e Compose, uno stile tipografico include, ad esempio, nome, spessore del carattere, dimensioni, spaziatura tra le lettere e altezza della riga del carattere. Anziché dover mappare più volte le singole proprietà secondarie di ogni stile, mappamo gli stili complessivi a token e temi e poi mappamo separatamente ogni singola proprietà secondaria.

L'esempio precedente indica che quando un elemento di testo Figma con lo stile my-app-theme/headline/large viene scritto nel file di definizione del pacchetto UI, il carattere del testo è myapp.sys.typescale.headline-large.font, le dimensioni sono myapp.sys.typescale.headline-large.size e così via. Quando viene generato il codice di Compose, viene quindi creato un componibile RelayText (che aggrega il componibile Text nel materiale di Compose), dove il parametro font è MaterialTheme.typography.headlineLarge.fontFamily, il parametro size è MaterialTheme.typography.headlineLarge.fontSize e così via.

Per esempi di file di configurazione, puoi esaminare le configurazioni integrate di Material 3 e Material 2 Design Kit, che utilizzano esattamente lo stesso formato. Puoi scaricare i file qui:

• Configurazione del Material Design Kit

Limitazioni

Attualmente, gli stili non vengono tradotti in temi in diverse situazioni:

• Stili di testo applicati solo a una parte di un elemento di testo (come descritto nella sezione Più stili nel testo)
• Se sono stati applicati stili diversi a varianti diverse di un componente, viene tradotto un solo stile.