Zum Hauptinhalt springen

Gestalten von benutzerdefinierten Komponenten

Der Design-Token-Transformationsmechanismus kann verwendet werden, um ein Theme sowohl auf Jutro-Komponenten der Basiskonfiguration als auch auf benutzerdefinierte, anwendungsspezifische Komponenten und Elemente anzuwenden.

Um Komponenten aus dem Jutro Design System zu gestalten, befolgen Sie einfach die auf dieser Seite beschriebenen Schritte. Jutro enthält alle notwendigen Zuordnungen, damit Design-Token nahtlos mit den Komponenten verwendet werden können, sodass keine zusätzliche Konfiguration erforderlich ist.

Sie können benutzerdefinierte Komponenten und Elemente in Ihrer Anwendung mit den folgenden Methoden gestalten:

  1. Definieren Sie benutzerdefinierte Design-Token, mit denen benutzerdefinierte CSS-Variablen zur Verwendung in der Anwendung generiert werden.

  2. Ordnen Sie Jutro-Design-Token („jds“) benutzerdefinierten CSS-Variablen zu.

  3. Verwenden Sie die generierten --JDS--CSS-Variablen direkt.

Warning: Besondere Überlegungen bei Verwendung von benutzerdefinierten Zuordnungen und generierten CSS-Variablen zum Gestalten von benutzerdefinierten Elementen.

  • Wenn Sie ein „jds“-Design-Token in Ihren benutzerdefinierten Zuordnungen verwenden, ist darauf zu achten, dass das entsprechende Design-Token bei der Theme-Generierung vorhanden ist.

  • Wenn Sie im Code auf --JDS--Variablen verweisen, stellen Sie sicher, dass das entsprechende Design-Token bei der Theme-Generierung vorhanden ist.

  • Design-Token unter dem Namensraum „jds“ sind Teil der offiziellen API-Oberfläche von Jutro und werden von der NBC-Richtlinie (Non-Breaking Changes) abgedeckt. Die aus diesen Token automatisch generierten CSS-Variablen (mit dem Präfix --JDS-) sind jedoch nicht Teil der API-Oberfläche und werden nicht durch die NBC-Richtlinie garantiert.

  • Jede generierte CSS-Variable ist nur verfügbar, wenn ein übereinstimmendes Design-Token vorhanden ist. Weitere Informationen finden Sie im Abschnitt Benennungsmuster für CSS-Variablen.

  • In Jutro Design System-Komponenten werden intern --JDS--Variablen verwendet. Diese internen Variablen können sich ändern, ohne dass dies als Breaking Change angesehen wird. „jds“-Design-Token innerhalb von Komponenten (und wie sie angewendet werden) sind jedoch stabil und entsprechen der NBC-Richtlinie.

Weitere Informationen zur API-Oberfläche von Jutro finden Sie hier.

Benutzerdefinierte Token​

UX-Designer können einen Satz benutzerdefinierter Token erstellen, die in der Anwendung verwendet werden. Diese benutzerdefinierten Token müssen unter einem anderen Namensraum als „jds“ hinzugefügt werden, z. B. „my-custom-application“.

{
  "my-custom-application": {
    "some-component": {
      "color": {
        "background": {
          "value": "{jds.color.background.neutral}",
          "type": "color",
          "description": "Background color for SomeComponent"
        },
        "text": {
          "value": "#fff",
          "type": "color",
          "description": "Text color for SomeComponent"
        }
      }
    }
  }
}

Benutzerdefinierte Design-Token können alle in einer Datei hinzugefügt oder auf mehrere Dateien aufgeteilt werden - Design-Token in CSS-Variablen: Der Transformationsmechanismus transformiert alle Design-Token aus einem bestimmten Verzeichnis, sodass die Anzahl der Dateien keine Rolle spielt. Die einzigen zwei Regeln sind:

  1. Es dürfen nicht zwei Token mit demselben Pfad in einem Verzeichnis vorhanden sein
  2. Alle referenzierten Token müssen auch im Theme-Verzeichnis definiert werden

Das bedeutet, dass benutzerdefinierte Token in ihren Werten auf Jutro Design System-Design-Token verweisen können, jedoch nur, wenn „jds“-Token-Definitionen ebenfalls im selben Verzeichnis gespeichert sind.

Benennungsmuster für CSS-Variablen​

Alle Design-Token werden gemäß der folgenden Konvention in CSS-Variablen umgewandelt:

  1. Alle .-Punkte werden durch Bindestriche ersetzt -
  2. Alle Buchstaben werden in Großbuchstaben geschrieben
  3. Am Anfang werden zwei Bindestriche -- eingefügt

Ein Token mit dem Pfad von my-custom-application.some-component.color.background wird beispielsweise in --MY-CUSTOM-APPLICATION-SOME-COMPONENT-COLOR-BACKGROUND umgewandelt.

Typografie-Token sind eine Ausnahme von dieser Regel. Da es sich bei Typografie-Token um zusammengesetzte Token handelt, müssen sie während des Transformationsprozesses in mehrere separate CSS-Variablen aufgeteilt werden. Ein Beispiel für ein Typografie-Token ist unten zu sehen:

{
  "my-custom-application": {
    "font": {
      "heading-1": {
        "value": {
          "fontFamily": "'Source Sans 3', 'Helvetica', 'Arial', sans-serif",
          "fontWeight": "600",
          "lineHeight": "40px",
          "fontSize": "32px",
          "letterSpacing": "0",
          "paragraphSpacing": "0",
          "textCase": "none",
          "textDecoration": "none"
        },
        "type": "typography",
        "description": "Font properties for heading 1 text"
      }
    }
  }
}

Design-Token my-custom-application.font.heading-1 wird in die folgenden CSS-Variablen umgewandelt:

--MY-CUSTOM-APPLICATION-FONT-HEADING-1-FONT-FAMILY: 'Source Sans 3', 'Helvetica', 'Arial', sans-serif;
--MY-CUSTOM-APPLICATION-FONT-HEADING-1-FONT-SIZE: 32px;
--MY-CUSTOM-APPLICATION-FONT-HEADING-1-FONT-WEIGHT: 600;
--MY-CUSTOM-APPLICATION-FONT-HEADING-1-LETTER-SPACING: 0;
--MY-CUSTOM-APPLICATION-FONT-HEADING-1-LINE-HEIGHT: 40px;
--MY-CUSTOM-APPLICATION-FONT-HEADING-1-PARAGRAPH-SPACING: 0;
--MY-CUSTOM-APPLICATION-FONT-HEADING-1-TEXT-CASE: none;
--MY-CUSTOM-APPLICATION-FONT-HEADING-1-TEXT-DECORATION: none;

Benutzerdefinierte Zuordnungen​

Es ist nicht erforderlich, einen völlig neuen Satz benutzerdefinierter Design-Token zu erstellen, um benutzerdefinierte CSS-Variablen zu generieren, Sie können stattdessen die Funktionalität des Hinzufügens benutzerdefinierter Zuordnungen verwenden. Dazu müssen Sie eine neue JSON-Datei erstellen, z. B. customMappings.json, und diese mit CSS-Variablen/Design-Token-Paaren füllen. Denken Sie daran, dass alle referenzierten Token dem angegebenen Theme-Verzeichnis hinzugefügt werden müssen.

Beispielzuordnung:

{
  "--CUSTOM-BUTTON-BACKGROUND-ERROR-COLOR": "jds.color.background.error",
  "--CUSTOM-BUTTON-TEXT-COLOR": "jds.color.text.regular"
}

Sie müssen auch einen neuen custom-mappings-Eintrag zu Ihrer .themesConfig.json hinzufügen. Weitere Informationen finden Sie .themesConfig.json hier.

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

Nach dem Ausführen des Transformationsprozesses werden die in der Zuordnung definierten Variablen an die tokenOverrides.css-Datei angehängt.

/**
 * 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;
--JDS-COLOR-BACKGROUND-ERROR: #012345;
--JDS-COLOR-TEXT-REGULAR: #28333f;
...
--CUSTOM-BUTTON-BACKGROUND-ERROR-COLOR: var(--JDS-COLOR-BACKGROUND-ERROR);
--CUSTOM-BUTTON-TEXT-COLOR: var(--JDS-COLOR-TEXT-REGULAR);
}
Warning: Guidewire stellt die Zuordnung für jedes Guidewire-Design-Token zur Guidewire CSS-Variablen bereit. Verwenden Sie keine benutzerdefinierten Zuordnungen zum Überschreiben oder Ändern von --JDS--Variablen. CSS-Variablen sind nicht Teil der API-Oberfläche, daher ändern sie sich von Version zu Version, und Ihre benutzerdefinierte Zuordnung kann beschädigt werden.
Note: Nicht alle Komponentenstile werden mit Design-Token definiert: In einigen Komponenten werden stattdessen hartcodierte Werte oder CSS-Variablen mit hardcodierten Werten (mit dem Präfix --JDS-) verwendet. Wenn Sie einen dieser Stile ohne Token ändern möchten, wenden Sie sich an unser Team. Wir werden prüfen, ob neue Design-Token erstellt werden sollten, um Ihren Anforderungen gerecht zu werden.

Benutzerdefinierte Transformationen​

In einigen Fällen ist die Transformation eines Design-Token-Werts in einen CSS-Variablenwert nicht direkt und erfordert eine bestimmte Logik, um den Wert oder die Werte zu erhalten, die aufgelöst werden sollen. Zu diesem Zweck stellt Guidewire eine Reihe vordefinierter Transformationen bereit, die grundlegende Transformationen von Rahmen, Typografie, Schatten, Berechnungen usw. abdecken. Wenn weitere Transformationen durchgeführt werden müssen, können Sie eine benutzerdefinierte Transformationsfunktion schreiben und diese über einen custom-transformations-Eintrag in .themesConfig.json an den Transformationsprozess übergeben. Weitere Informationen finden Sie .themesConfig.json hier.

Der folgende Codeausschnitt zeigt Beispiele für benutzerdefinierte Transformationen von Werten und Namen:

module.exports = {
  customValueTransform: {
    type: 'value',
    transitive: true,
    matcher: token => token.type === 'my-type',
    transformer: token => `"Value of my token: ${token.value}"`
  },
  customNameTransform: {
    type: 'name',
    transformer: token => `CUSTOM-PREFIX-${token.path.join('-').toUpperCase()}`
  }
};

Weitere Informationen zum Schreiben von benutzerdefinierten Transformationen finden Sie in der Dokumentation zum Stilwörterbuch.

Warning: Benutzerdefinierte Transformationen werden nur auf benutzerdefinierte Token angewendet, bei denen es sich um Token mit einem anderen Präfix als jds handelt. Wenn keine benutzerdefinierten Transformationen definiert sind, die mit einem bestimmten benutzerdefinierten Token übereinstimmen, wird das Token mithilfe der Jutro-Transformationen transformiert, sofern dieser Tokentyp von Jutro verarbeitet wird. Die Transformation von jds-Token kann nicht überschrieben werden.

In der folgenden Liste finden Sie Design-Token-Typen, die von Jutro verarbeitet werden:

  • 'sizing'
  • 'spacing'
  • 'borderRadius'
  • 'borderWidth'
  • 'fontSizes'
  • 'letterSpacing'
  • 'paragraphSpacing'
  • 'dimension'
  • 'typography'
  • 'boxShadow'
  • 'border'
  • 'composition'
  • 'fontFamilies'
  • 'lineHeights'

Wenn eine Transformation fehlt, informieren Sie den zuständigen Guidewire-Mitarbeiter, damit sie in einer künftigen Version berücksichtigt werden kann.