Design Tokens

Token sind Design-Vorgaben, die in menschen- und maschinenlesbare Daten übersetzt werden. Sie dienen als zentrale Vorgaben, um digitale Angebote einheitlich zu gestalten. Sie sind ein Kommunikationsmittel, eine gemeinsame Sprache zwischen Design und technischer Umsetzung, um präzise Informationen über die Erstellung von Benutzeroberflächen zu vermitteln.

Tokens bestehen aus Werten, die zum Aufbau eines systematischen Designs benötigt werden, z. B. aus Abständen für Platzierungen, Farben für Zustände, Typografie, Mikro-Animationen und vielem mehr. Sie können alles abbilden, was ein definiertes Design hat, etwa eine Farbe als RGBa-Wert, deren Deckkraft als Zahl, oder die Animationsgeschwindigkeit eines Elementes zwischen zwei Zuständen als Bézierkurve.

Die Design-Token-Systematik im DESY

Das Design-Token-System lebt von seiner Vorhersehbarkeit und Flexibilität. Die Systematik besteht darin, für alle denkbaren Szenarien und Kontexte einen auf den konkreten Anwendungszweck fokussierten Satz von Token zu haben und nicht eine beliebige Menge an Stylings ohne Struktur.

Tokens stellen zwar die meisten Informationen zur Implementierung und Darstellung einer UI-Komponente bereit; das Token-System ist dabei aber nur eine Ressource im Angebot von DESY und keine vollständige Wissensbasis und soll neben der eigentlichen Design- und Code-Dokumentation verwendet werden. Design-Tokens sind unmittelbar in unsere Komponentenbibliothek integriert. Teams können diese aber auch direkt in ihren Produkten benutzen, wenn sie keine strikte DESY-Implementierung verwenden.

Was ist ein Design-Token?

Design-Tokens repräsentieren die kleinen, sich wiederholenden Designentscheidungen, die den visuellen Stil eines Design-Systems ausmachen. Damit ersetzen sie statische Werte, wie z. B. RGBa-Werte für Farben, oder rem-Angaben für Schriftgrade durch selbsterklärende Namen. Ein Token besteht immer aus einem Token-Namen und einem zugehörigen Wert.

Beispiel: Das Token "$ref-color-blue-100" hat den Wert "45, 111, 158, 1".

Durch diesen Design-Token wird dem Farbwert "45, 111, 158, 1" der Name "…blue-100" zugewiesen. Dieser Token kann nun als Variable überall dort verwendet werden, wo dieser exakte Blauwert gefragt wird. In diesem Fall ist der Wert des Tokens eine Farbe. Der Wert könnte allerdings auch eine Schriftart, ein Abstand oder sogar ein anderes Token sein.

Beispiel: Das Design-Token "$sys-color-lightmode-text-interactive-default" hat den Wert "$ref-color-blue-100".

Technisch betrachtet sind Design-Tokens also aufeinander aufbauende CSS-Variablen, die über mehrere Token-Typen hinweg systematisch das UI-Design strukturieren und damit ein in sich konsistentes Ökosystem aufbauen. Wir verwenden grundsätzlich Tokens statt hartcodierten Werten und skalieren damit die komplexen Variationen, die von den digitalen Angeboten des Zolls benötigt werden. Durch diesen Aufbau können wir übergreifende Gestaltungsmuster definieren und nachhaltig iterieren, unabhängig von der Design-Dokumentation einer Komponente.

Token-Typen

Eine klare Terminologie ist der Schlüssel zum Verständnis der Tokens und ihrer Systematik, ihrer Verwendung und ihrer Beziehung zueinander. Jedes Token hat einen sorgfältig gewählten Namen, der einer festgelegten Namenskonvention folgt und seinen Zweck und seinen Umfang ablesbar macht. Tokens lassen sich an den ersten Zeichen ihrer Namen in vier Typen unterteilen: Reference-, System-, Context- und Component-Tokens.

Basiswert & Alias

Basiswerte sind Angaben, die einer CSS-Eigenschaft (Property) zugewiesen werden. Nach dem Auflösen aller Token-Variablen sind Basiswerte die hartcodierten Angaben die die jeweilige CSS-Eigenschaft verlangt. Beispiele für Basiswerte:

Ein Token, das auf einen anderes Token verweist, anstatt auf einen Basiswert nennt man Alias-Token.

Reference-Tokens (REF)

In diesem ersten Token-Typ werden alle Basiswerte jeweils einem Reference-Tokens als Wert zugewiesen und in die folgenden Kategorien unterteilt.

Die entstehenden Reference-Tokens müssen losgelöst von ihrer Nutzung eine Skalierung im Token-Namen tragen. Diese Skalierungen können je nach CSS-Eigenschaft unterschiedlich sein.

Damit gibt es für jeden Basiswert ein entsprechendes Reference-Token. Jeder weitere Token-Typ besteht demnach aus Alias-Tokens, d. h. sie verweisen auf bereits bestehende Tokens.

System Token (SYS)

Ein System-Token definiert den Zweck, den ein Referenz-Token in der Benutzeroberfläche erfüllt. System-Tokens können global angewendet werden und sind nicht ausschließlich für bestimmte Komponenten oder Kontexte vorgesehen. System-Tokens werden deshalb auch in die oben genannten Kategorien eingeteilt und um einen allgemeingültigen, zweckgebundenen Namen erweitert.

Auf Ebene der System-Tokens können Farbschemata definiert werden. Je nach Systemeinstellungen des Anwenders kann also abgefragt werden, welcher Grünton als Erfolgsfarbe genutzt werden soll. Wann immer möglich, sollten System-Tokens auf die bestehenden Referenz-Tokens verweisen (oder diese miteinander verrechnen), anstatt statische Werte zu nutzen.

Context Token (CTX)

Diese Token-Ebene baut auf das Gestaltgesetz der Ähnlichkeit auf. Elemente mit ähnlichem Aussehen und Verhalten werden unabhängig von ihrer Positionierung auf der Seite als zusammengehörig wahrgenommen. Sieht ein Element also aus wie ein Button und regiert auf die Interaktion wie ein Button, kann davon ausgegangen werden, dass dieses Element Button-ähnliche Eigenschaften hat, also klickbar ist.

Context-Tokens werden benutzt, um diese gestalterischen Muster für einen Kontext zu definieren. Im DESY definieren wir die folgenden Kontexte:

Der Wert eines Context-Tokens kann sowohl ein System-Token als auch ein Reference-Token sein. Innerhalb eines Kontexts können Tokens aus unterschiedlichen Kategorien verwendet werden. So entsteht für jeden Kontext ein umfangreiches Set an Design-Tokens, das nur für eine abgegrenzte Gruppe an Komponenten (oder Elemente dieser Komponenten) genutzt wird.

Context-Tokens erleichtern zukünftige Iterationen des Design Systems, da die Ausgestaltung mehrerer Elemente von nur einem Token definiert wird. Ändert man zum Beispiel im Kontext "Forms" den Eckenradius von Formularelementen, so wirkt sich das auf alle Formularelemente aus, die diesen Token nutzen (input, textarea, select, Datepicker, …).

Component-Token (COMP)

Für die Design-Dokumentation einer Komponente werden ausschließlich Component-Tokens benutzt. Im Gegensatz zu den anderen Token-Typen repräsentieren sie die Elemente und Werte, die diese Komponente ausmachen. Component-Tokens haben einen eindeutigen und einzigartigen Einsatz, der im Name des Tokens beschrieben ist.

Wann immer möglich, sollten Component-Tokens auf die bestehenden Referenz-, System- und Context-Tokens verweisen (oder diese miteinander verrechnen), anstatt statische Werte zu nutzen; passende Alias-Tokens sind Reference-Tokens immer vorzuziehen. Beispiel für die Werte, die Component-Tokens zugewiesen werden können:

Anatomie eines Component-Tokens

Jeder Component-Token besteht aus mehreren Token-Items, die zusammen den Einsatz des Tokens beschreiben. Getrennt werden diese Token-Items immer mit einem “-”.

Die Token-Items folgen einer klaren Abfolge von unterschiedlichen Token-Item-Types. Für jeden Type gibt es jeweils eine Reihe von Begriffen, die als Token-Item zur Verfügung stehen. Diese Abfolge muss nicht zwingend eingehalten werden, sorgt aber für Konsistenz in der Bezeichnung der Tokens und wird daher empfohlen.

Auch wenn es abseits der ersten drei Token-Items Unterschiede zwischen Component-Tokens geben kann, so folgen sie doch immer der gleichen Reihenfolge:

1. Im ersten Schritt wird deklariert, um welches Token-Level es sich handelt; hier “comp”, weil wir Component-Tokens definieren.
2. Danach identifizieren wir das Objekt, das wir definieren wollen: Die Komponente selbst und ein spezifisches Element innerhalb dieser Komponente.
3. Wenn wir genau wissen, was (Komponente & Element) wir ansprechen wollen, dann geben wir dem Component-Token mit, um welche Token-Category es sich handelt.
   Diese Categories spielen in den Token-Level REF und SYS eine strukturierende Rolle. Hier helfen sie nur noch, Tokens zu gruppieren.
4. Innerhalb jeder Category gibt es eine Reihe von CSS-Properties, die genutzt werden können.
   Beispiel: font-color oder background-color sind Teil der Token-Category color.
5. Modifiers werden benötigt, um die unterschiedlichen Werte zu definieren, die je nach Variante / Hierarchie / State / Breakpoint / … an der gleichen Stelle in der Webcomponent zum Einsatz kommen können.
6. Es kann durchaus vorkommen, dass mehr als ein Modifier benötigt wird. Bitte hierbei die Reihenfolge der Modifier beachten (siehe Token-Items im Detail - 6. Modifer)

Token-Items im Detail

(*) = Pflichtelement im Component-Token

1. Token-Level *

Hier die vollständige Liste aller Begriffe, die als Token-Level eingesetzt werden können.
Es dürfen keine anderen Token-Level genutzt werden.

2. Component *

Hier nutzen wir die technische Bezeichnung unserer Webcomponents. Webcomponents, die aus zwei Worten bestehen, müssen hier klein- und zusammengeschrieben werden (e.g. sessiontimer statt Session Timer).
Es dürfen nur Begriffe hinzugefügt werden, wenn es dafür tatsächlich auch eine Komponente gibt.

3. Design-Element / -Item *

Zur genauen Identifikation eines Elements innerhalb einer Webcomponent orientieren wir uns an den folgenden Begriffen. Wenn Begriffe wie “wrapper” oder “container” ein Objekt gut beschreiben, dann nutzen wir diesen Begriff dafür. Diese Liste muss flexibel bleiben, da Webcomponents unterschiedlich umfangreich sein können.
Bei Bedarf und Prüfung auf Notwendigkeit können neue Begriffe hinzugefügt werden.

Bei großen Komponenten könnten auch zwei aufeinanderfolgende Begriffe genutzt werden, um das Element eindeutiger zu identifizieren.

4. Category

Es ist recht einfach einen Component-Token in die richtige Category einzuordnen, wenn man weiß, für welche CSS-Property er vorgesehen ist. So umfasst die Category “typo” zum Beispiel alle CSS-Properties, die für die Ausgestaltung des Schriftbildes zuständig sind. Ausgenommen davon sind Properties, die zwar das Schriftbild beeinflussen können, aber einer anderen Category eindeutiger zugeordnet werden können. Welche Category für welche Property genutzt wird lässt sich aus der Kategorisierung der Reference-Tokens ableiten.
Es dürfen keine weiteren Begriffe genutzt werden.

Hier eine umfangreiche, wenn auch nicht vollständige Liste an CSS-Properties, aufgeteilt nach Categories:

5. CSS-Property

Zur genau Identifikation eines Elements innerhalb einer Webcomponent orientieren wir uns an den folgenden Begriffen. Wenn Begriffe wie “wrapper” oder “container” ein Objekt gut beschreiben, dann sollen diese Begriffe dafür benutzt werden. Da Webcomponents unterschiedlich umfangreich sein können muss auch diese Liste flexibel bleiben.
Bei Bedarf können neue Begriffe hinzugefügt werden, bei der die dahinterstehende CSS-Property eindeutig ist.

6. Modifier

Im letzten Typ der Token-Items gibt es eine weitere kleine Unterteilung in vier untergeordnete Typen:

6.1. Varianten

Hier können je nach Komponente verschiedene Begriffe für Varianten genutzt werden. Häufig vorkommende Varianten sind hier gelistet.
Bei Bedarf können neue Begriffe hinzugefügt werden.

6.2. State

Hier können je nach Komponente verschiedene Begriffe für Varianten genutzt werden. Häufig vorkommende Varianten sind hier gelistet.
Hier dürfen keine neuen Begriffe hinzugefügt werden, da sich diese mit den SYS- und CTX-Tokens decken.

6.3. Breakpoint

Wenn kein Breakpoint-Modifier gesetzt ist, dann ist dieser Token über alle Breakpoints gültig. Das “bp” im Namen steht für Breakpoint.
Hier dürfen keine neuen Breakpoints hinzugefügt werden, da diese feststehen.

Struktur einer <component>.js-Datei

Die Struktur dieser Datei hat eine direkte Auswirkung auf den Namen des Tokens. Um den Token so zu erstellen wie oben beschrieben muss die Datei folgendem Aufbau folgen.

Der Rahmen einer jeden *.js Datei, die Component-Tokens definieren, sieht wie folgt aus:

comp: {
    <ComponentName>: {
        …
    },
}

comp: {
    button: {
        …
    },
}

Darin können nun einzelne Design-Elemente angesprochen werden:

comp: {
    <ComponentName>: {
        <DesignElement>: {
            …
        },
        <DesignElement>: {
            …
        },
    },
}

comp: {
    button: {
        container: {
            …
        },
        label: {
            …
        },
    },
}

Für jedes Design-Element werden die Definitionen nach den oben gelisteten Kategorien (typo, color, opacity, space, …) geordnet:

comp: {
    <ComponentName>: {
        <DesignElement>: {
            <Category>: {
                …
            },
       },
    },
}

comp: {
    button: {
        container: {
            color: {
                …
            },
       },
    },
}

Innerhalb der Categories können nun die passenden CSS-Properties als Token-Items eingesetzt werden:

comp: {
    <ComponentName>: {
        <DesignElement>: {
            <Category>: {
                <Property>: {
                     …
                 },
              },
        },
    },
}

comp: {
    button: {
        container: {
            color: {
                bg: {
                     …
                 },
            },
         },
    },
}

Sollte es für die angesprochene CSS-Property je nach Komponenten-Variante / Hierarchie / State / Breakpoint usw. andere Werte geben, so müssen diese in Form von Modifiers angelegt werden.

comp: {
    <ComponentName>: {
        <DesignElement>: {
            <Category>: {
                <Property>: {
                     <ModifierTier1>: {
                          …
                     },
                },
              },
        },
    },
}

comp: {
    button: {
        container: {
            color: {
                bg: {
                     primary: {
                          …
                     },
                 },
            },
         },
    },
}

Bei den Modifiers gibt es ein paar Untergruppen, die nicht vermischt werden sollten (siehe Token-Items im Detail - 6. Modifer).

comp: {
    <ComponentName>: {
        <DesignElement>: {
            <Category>: {
                <Property>: {
                     <ModifierTier1>: {
                           <ModifierTier2>: {
                               …
                           },
                     },
                },
              },
        },
    },
}

comp: {
    button: {
        container: {
            color: {
                bg: {
                   primary: {
                         hover: {
                              …
                         },
                   },
                 },
            },
         },
    },
}

comp: {
    button: {
        container: {
            color: {
                bg: {
                   primary: {
                         hover: {value: '#ff0000' }, // Token tbd
                   },
                 },
            },
         },
    },
}

Kopiervorlagen

States

default: { value: '__________' }, // Token tbd
visited: { value: '__________' }, // Token tbd
focus: { value: '__________' }, // Token tbd
hover: { value: '__________' }, // Token tbd
active: { value: '__________' }, // Token tbd
toggled: { value: '__________' }, // Token tbd
disabled: { value: '__________' }, // Token tbd

Labels & Texte

Für alle Labels und Texte die wir definieren, wollen wir ein vollständiges Set an Typo-Tokens definieren. So können wir das gesamte Schriftbild der Seite bei Bedarf allein über die Design-Tokens ändern.

typo: {
    font: { value: '__________' }, // Token tbd
    size: { value: '__________' }, // Token tbd
    lineheight: { value: '__________' }, // Token tbd
    weight: { value: '__________' }, // Token tbd
    lettspacing: { value: '__________' }, // Token tbd
    texttransform: { value: '__________' }, // Token tbd
    textdeco: { value: '__________' }, // Token tbd
},

Breakpoints

Wenn wir unterschiedliche Angaben für Breakpoints machen müssen, dann definieren wir diese als letzte Modifier-Instanz im Token. Im Beispiel eine Veränderung im Padding beim Breakpoint:

space: {
    padding: {
        bpxs: { value: '__________' }, // Token tbd
        bpmd: { value: '__________' }, // Token tbd
    },
},

Eigennamen für states

Solange die Bezeichnungen Englisch und eindeutig sind können auch eigene Begriffe eingesetzt werden, um einen Modifier zu beschreiben.

space: {
    padding: {
        open: { value: '__________' }, // Token tbd
        closed: { value: '__________' }, // Token tbd
    },
},