Umwandlung in CSS-Variablen

Design-Token bieten Designern und Entwicklern eine gemeinsame Sprache zur Kommunikation von Designentscheidungen. Design-Token müssen in CSS-Variablen umgewandelt werden, damit die Anwendung mit der Theme-Definition funktioniert. Guidewire stellt einen auf dem Stilwörterbuch basierenden Umwandlungsbefehl bereit, der eine vordefinierte Umwandlungslogik für alle von Guidewire definierten Design-Token enthält.

In diesem Dokument wird die Umwandlung 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 Tokens in ein JSON-Format und übermittelt das Ergebnis an den Entwickler.
3. Der Entwickler wandelt die Design-Token in CSS-Variablen um, sodass sie zur Steuerung der Themes in einer Anwendung verwendet werden können. Dieser Schritt kann manuell oder automatisch während des Buildvrgangs der Anwendung ausgeführt werden. Dieser Umwandlungsprozess wird im Folgenden erläutert.

Definieren der Design-Token und der zugehörigen Werte

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

Falls das Projekt die Erstellung einiger benutzerdefinierter Komponenten erfordert, können der ursprünglichen Liste zusätzliche Design-Token hinzugefügt werden. So werden alle Themes sowohl für die von Guidewire bereitgestellten als auch 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-Tokentypen 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 Umwandlung

Vor der Umwandlung 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 Umwandlungsprozesses sind ordnungsgemäß festgelegt.
• Die CLI ist installiert.

Hinzufügen von Definitionsdateien für Design-Token

Positionieren Sie die JSON-Design-Token-Dateien in der Codebasis Ihrer Anwendung, z. B. an einem Speicherort wie src/tokens/yourThemeName/.... Aktualisieren Sie diese Dateien jedes Mal, 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 von Design-Token in den exportierten JSON-Dateien oder den CSS-Variablen niemals ändern. Ein Designer muss diese Werte immer in dem Repository festlegen, das die Quelle dieser Design-Token enthält.

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

Wenn Sie die manuelle Methode verwenden, müssen Sie diese Dateien nicht in das Quellcode-Repository übertragen, da sie nicht verwendet werden. Es ist jedoch eine bewährte Praxis, sie einzubinden, um die Rückverfolgbarkeit der Design-Token-Version zu ermöglichen, die zum Generieren des Designs verwendet wurde.

Datei „.themesConfig.json“

Damit die Themes funktionieren, müssen Sie die .themesConfig.json-Datei konfigurieren. 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 .themesConfig.json.

.themesConfig.json enthält Folgendes:

• Die für die Anwendung erforderlichen Theme-Informationen.
• Die für die Umwandlung 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 sollte (wenn sie mehr als eins umfasst).

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

Eigenschaft	Verwendet von Theme-Definition	Verwendet von Umwandlungsprozess	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 Umwandlung ergeben, gespeichert werden. Diese Datei wird immer unter src/assets/ erstellt.
tokens/custom-mappings	Nein	Ja	Zuordnung der Tokens zu benutzerdefinierten CSS-Variablen (Pfad relativ zum Projektstammverzeichnis). Weitere Informationen finden Sie hier.
tokens/custom-transformations	Nein	Ja	Benutzerdefinierte Transformationsfunktionen für die benutzerdefinierten Tokens (Pfad relativ zum Projektstammverzeichnis) Weitere Informationen finden Sie hier.

Ausführen der Umwandlung

Sie können den Umwandlungsprozess manuell auslösen oder die automatische Variante nutzen. 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 assetsgespeichert 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. Wenn etwas falsch ist oder fehlt, aktualisieren Sie die Design-Token-Definition und führen Sie den Umwandlungsvorgang erneut aus.

Manuelle Umwandlung

Sie können die manuelle Umwandlung 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-Umwandlung und die Verwendung in der Anwendung überprüfen können.

CLI-Befehl **generate:themes **

USAGE
  $ jutro generate:themes

OPTIONS
  -c, --configPath=configPath  Defines the path of the directory that contains the .themesConfig.json file
  -s, --encapsulateThemes      When the app is used as a micro frontend, generated themes will be scoped to this app, not the shell app. CSS selector will include JUTRO_APP_ID value.
  --clearCache                 Clear cache. Use this to log in as a different user.
  --cliInfo                    Information about config and cache file location.
  --help                       show CLI help
  --reset                      Reset config to default and clear cache

Weitere Informationen zur JUTRO_APP_ID-Verwendung finden Sie im Abschnitt Micro-Frontend in eine Shell-App einbetten für Modulföderation.

Automatische Transformation

Der Transformationsvorgang wird bei der Erstellung der Anwendung automatisch ausgeführt, wenn Sie das Skript "build-themes" : "jutro generate:themes" zur package.json-Datei hinzufügen. Das Ergebnis der Umwandlung wird in das generierte Bündel aufgenommen, sodass es für die Anwendung zur Verwendung 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 Umwandlung wird empfohlen. Dadurch, dass der Umwandlungsvorgang während des Build-Vorgangs der Anwendung ausgeführt wird, ist sichergestellt, dass das generierte Theme aktuell ist und die neuesten CSS-Variablen verwendet. 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 mit den folgenden Schritten eine neue Konfiguration erstellen:

1. Geben Sie den Namen des zu konfigurierenden Themes an.
2. Definieren Sie die Eingabepfadvariable, z. B. „src/tokens/*.json“.
3. Geben Sie den Namen der Ausgabedatei ohne die Erweiterung „.css“ an.
4. Legen Sie den Pfad zur benutzerdefinierten Zuordnungsdatei fest (falls erforderlich).
5. Legen Sie bei Bedarf den Pfad zur benutzerdefinierten Umwandlungsdatei fest.

Auf diese Weise können Sie auch mehrere Theme-Konfigurationen erstellen.