Transformation in CSS-Variablen

Design-Token bieten Designern und Entwicklern eine gemeinsame Sprache zur Kommunikation von Designentscheidungen. Design-Token müssen in CSS-Variablen transformiert werden, damit die jeweilige Theme-Definition in der Anwendung verwendet werden kann. Guidewire stellt einen auf dem Stilwörterbuch basierenden Transformationsbefehl bereit, der diese Transformation durchführt und vordefinierte Transformationslogik für alle von Guidewire definierten Design-Token enthält.

In diesem Dokument wird die Transformation von Design-Token in CSS-Variablen erläutert, nachdem ein Entwickler die definierten Token vom Designer erhalten hat.

Warning: Die Verfügbarkeit jeder generierten CSS-Variable hängt vom Vorhandensein eines übereinstimmenden Design-Tokens oder der Definition einer benutzerdefinierten Zuordnung ab. Informationen zur Verwendung von Token für benutzerdefinierte Komponenten finden Sie auf der Seite Gestalten von benutzerdefinierten Komponenten.

Allgemeiner Prozess bei der Verwendung von Design-Token

1. Der UX-Designer definiert die Design-Token und die zugehörigen Werte mithilfe des Plugins „Tokens Studio for Figma“ (oder eines anderen unterstützten Tools).
2. Der UX-Designer exportiert die Token in ein JSON-Format und übermittelt sie an den Entwickler.
3. Der Entwickler wandelt die Design-Token in CSS-Variablen um, sodass sie zur Steuerung des Theming in einer Anwendung verwendet werden können. Dieser Schritt kann bei der Erstellung der Anwendung manuell oder automatisch ausgeführt werden. Dieser Transformationsprozess wird im Folgenden erläutert.

Definieren der Design-Token und der zugehörigen Werte

Guidewire stellt eine Liste mit allen Token bereit, die in den Komponenten von Jutro Design System verwendet werden. Der UX-Designer konfiguriert anhand dieser Liste die geeigneten Werte entsprechend den Anforderungen des jeweiligen Theme.

Wenn für das Projekt benutzerdefinierte Komponenten erstellt werden müssen, können der ursprünglichen Liste zusätzliche Design-Token hinzugefügt werden. So werden alle Themes für die von Guidewire bereitgestellten sowie für benutzerdefinierte Komponenten einheitlich gehandhabt.

Exportieren von Design-Token

Wenn der UX-Designer die Token-Definition mit dem Plugin „Tokens Studio for Figma“ exportiert, werden drei separate JSON-Dateien für die verschiedenen Design-Token-Typen erstellt. Nachfolgend ein Beispiel aus einer JSON-Datei mit Design-Token für eine Komponente:

{
  "jds": {
    "color": {
      "background": {
        "neutral": {
          "value": "{jds.color.palette-neutral.20}",
          "type": "color",
          "description": "Neutral background color"
        },
        "neutral-hover": {
          "value": "{jds.color.palette-neutral.30}",
          "type": "color",
          "description": "Neutral background color hover state"
        }
      }
    }
  },
  "custom": {
    "some-component": {
      "color": {
        "background": {
          "value": "{jds.color.background.neutral}",
          "type": "color",
          "description": "Background color for SomeComponent"
        }
      }
    }
  }
}

Vorbereitung der Transformation

Vor der Transformation von Design-Token in CSS-Variablen müssen Sie zunächst die folgenden Vorbereitungsschritte ausführen:

• Die Design-Token-Definitionsdateien sind verfügbar.
• Die Parameter des Transformationsprozesses sind ordnungsgemäß festgelegt.
• Die CLI ist installiert.

Hinzufügen von Definitionsdateien für Design-Token

Fügen Sie die JSON-Dateien der Design-Token in der Codebasis der Anwendung ein, z. B. unter src/tokens/yourThemeName/.... Aktualisieren Sie diese Dateien immer, wenn eine neue Version der Design-Token erstellt wird.

Diese Dateien werden in der Konfigurationsdatei referenziert, wie weiter unten in diesem Dokument erläutert.

Warning: Entwickler dürfen die Werte der Design-Token in der exportierten JSON-Datei oder die CSS-Variablen niemals ändern. Ein Designer muss diese Werte immer in dem Repository festlegen, das den Quellcode der Design-Token enthält.

Bei der automatischen Methode übertragen Sie diese Dateien zusammen mit dem restlichen Anwendungscode und der Konfiguration in das Quellcode-Repository.

Bei der manuellen Methode müssen Sie diese Dateien nicht in das Quellcode-Repository übertragen, da sie nicht verwendet werden. Es empfiehlt sich jedoch, sie einzufügen, um die Rückverfolgbarkeit der Version der Design-Token sicherzustellen, die zum Generieren des Themes verwendet wurde.

Datei „.themesConfig.json“

Voraussetzung für funktionierende Themes ist die Konfiguration der .themesConfig.json-Datei. Diese Datei wird automatisch erstellt, wenn Sie eine neue Jutro-Anwendung erstellen. Sie können sie auch mit einem CLI-Befehl erstellen. Weitere Informationen finden Sie im Abschnitt Generieren der Datei „.themesConfig.json“.

.themesConfig.json enthält Folgendes:

• Die für die Anwendung erforderlichen Theme-Informationen.
• Die für die Transformation von Design-Token in CSS-Variablen erforderlichen Informationen.

Die Datei sieht in etwa wie folgt aus:

{
  "sampleTheme": {
    "name": "sampleTheme",
    "tokens": {
      "input-path": "src/tokens/sampleTheme/**/*.json",
      "output-file-name": "tokenOverrides.css",
      "custom-mappings": "src/tokens/customMappings.json",
      "custom-transformations": "src/tokens/customTransformations.js"
    }
  }
}

Beachten Sie, dass die Datei .themesConfig.json alle Themes für Ihre Anwendung enthalten muss (wenn sie mehrere umfasst).

Für jedes definierte Theme können Sie die folgenden Eigenschaften festlegen:

Eigenschaft	Verwendet in Theme-Definition	Verwendet in Transformationsprozess	Beschreibung
name	Ja	Ja	Erforderlich. Name zur Identifizierung des Themes.
tokens/input-path	Nein	Ja	Erforderlich. Der Pfad (relativ zum Projektstammverzeichnis) in der Anwendung, unter dem Sie die Token gespeichert haben.
tokens/output-file-name	Ja	Ja	Erforderlich. Die Datei, in der die CSS-Variablenüberschreibungen, die sich aus der Transformation ergeben, gespeichert werden. Diese Datei wird immer unter src/assets/ erstellt.
tokens/custom-mappings	Nein	Ja	Zuordnung der Token zu benutzerdefinierten CSS-Variablen (Pfad relativ zum Projektstammverzeichnis). Weitere Informationen finden Sie hier.
tokens/custom-transformations	Nein	Ja	Benutzerdefinierte Transformationsfunktionen für die benutzerdefinierten Token-Typen (Pfad relativ zum Projektstammverzeichnis) Weitere Informationen finden Sie hier.

Ausführen der Transformation

Sie können den Transformationsprozess manuell auslösen oder die automatische Option verwenden. Das Ergebnis ist unabhängig von der gewählten Option dasselbe: eine CSS-Datei mit generierten CSS-Variablen, die in der vordefinierten Ausgabedatei im Verzeichnis assets gespeichert werden.

/**
 * Do not edit directly
 * Generated on Mon, 25 Mar 2024 15:35:16 GMT
 */

.themeRoot,
.themeRoot.dynamicRoot {
--JDS-COLOR-BACKGROUND-NEUTRAL: #f0f3f6;
--JDS-COLOR-BACKGROUND-NEUTRAL-HOVER: #dfe5ec;
--CUSTOM-SOME-COMPONENT-COLOR-BACKGROUND: #f0f3f6;
}

Warning: Bearbeiten Sie die generierten Dateien niemals manuell. Aktualisieren Sie bei Fehlern oder fehlenden Elementen die Definition der Design-Token und führen Sie den Transformationsprozess erneut durch.

Manuelle Transformation

Sie können die manuelle Transformation auslösen, indem Sie das Skript build-themes über die package.json-Datei oder über den CLI-Befehl jutro generate:themes ausführen. Diese Option wird hauptsächlich für den Entwicklungsmodus empfohlen, da Sie dann das Ergebnis der Theme-Transformation und die Verwendung in der Anwendung überprüfen können.

Weitere Informationen finden Sie im Abschnitt „Theme-Definitionen für Jutro-Apps generieren“ in der CLI-Dokumentation.

Weitere Informationen zur Verwendung von JUTRO_APP_ID finden Sie im Abschnitt Ein Micro Frontend in eine Shell-App einbetten für Module Federation.

Automatische Transformation

Der Transformationsprozess wird bei der Erstellung der Anwendung automatisch ausgeführt, nachdem Sie das Skript "build-themes" : "jutro generate:themes" in der Datei package.json hinzugefügt haben. Das Ergebnis der Transformation wird in das generierte Bundle eingefügt, sodass es zur Verwendung in der Anwendung verfügbar ist.

Warning: Das Skript build-themes muss vor dem Skript build-webpack in package.json hinzugefügt werden, sonst ist es nicht im Paket enthalten.

Warning: Wenn die definierte Ausgabedatei bereits eine Theme-Definition enthält, wird diese während des Build-Prozesses überschrieben.

Die automatische Transformation wird empfohlen. Dadurch, dass der Transformationsprozess während des Build-Prozesses der Anwendung ausgeführt wird, ist sichergestellt, dass das generierte Theme aktuell ist und die neuesten CSS-Variablen verwendet werden. Dies erleichtert das Upgrade der Anwendung ohne Aufwand und ohne manuelle Eingriffe.

Generieren der Datei „.themesConfig.json“

Wenn Sie den CLI-Befehl jutro generate:themes ausführen, aber die Datei .themesConfig.json nicht gefunden wird, können Sie eine neue Konfigurationsdatei erstellen.

Weitere Informationen finden Sie im Abschnitt „Theme-Definitionen für Jutro-Apps generieren“ in der CLI-Dokumentation.

Transformieren der Design-Token für die Zeilenhöhe

Die Design-Token für die Zeilenhöhe können entweder als eigenständige Token des Typs lineHeights definiert werden, wobei der Wert direkt die Zeilenhöhe darstellt, oder als Teil von zusammengesetzten typography-Token, wobei lineHeight zusammen mit anderen Schrifteigenschaften wie fontSize angegeben wird.

Deren Transformationen folgen je nach Einheit und Typ bestimmten Regeln:

Einheitenlose Zeilenhöhen

Unabhängig von der Art der Zeilenhöhendefinition werden die einheitenlosen Zeilenhöhen als Pixelwerte behandelt. px wird während des Transformationsprozesses zum Wert hinzugefügt. Wenn z. B. der Wert eines Design-Tokens 14 ist, dann ist der Wert der resultierenden CSS-Variablen 14px.

Prozentuale Zeilenhöhen

• Wenn es sich bei dem Token um ein eigenständiges Token des Typs lineHeightshandelt, bleibt die Einheit %. Wenn der Wert des Tokens beispielsweise 80% ist, ist der Wert der resultierenden CSS-Variable ebenfalls 80%.
• Wenn das Token während der Transformation mit einer lineHeight-Eigenschaft als Teil eines zusammengesetzten Tokens vom Typ typography angegeben wird, wird der Wert für die Zeilenhöhe basierend auf der fontSize-Eigenschaft berechnet. Die Einheit der berechneten Zeilenhöhe entspricht der Einheit der fontSize-Eigenschaft. Beispiel:
  • Wenn die lineHeight-Eigenschaft auf 150% und die fontSize-Eigenschaft auf 16pxfestgelegt ist, ist der Wert der resultierenden CSS-Variablen 24px.
  • Wenn die lineHeight-Eigenschaft auf 125% und die fontSize-Eigenschaft auf 1remfestgelegt ist, ist der Wert der resultierenden CSS-Variablen 1.25rem.

Zeilenhöhen mit anderen Einheiten

Unabhängig von der Art der Zeilenhöhendefinition bleiben für andere Einheiten nach der Transformation die Einheit und der Wert identisch mit der Definition im Design-Token. Wenn z. B. der Wert eines Design-Tokens 1rem ist, dann ist der Wert der resultierenden CSS-Variablen 1rem.