Richtlinien

Sprache

Der Code, die Dokumentation im Code sowie Branches und Commit Messages werden in Englisch verfasst.

Branching und Commit Messages

Commit-Typen

Zur Strukturierung von Branches und Commit Messages halten wir uns an einen Standard, der folgende Fälle unterscheidet:

• feat - Neues Feature für User
• fix - Bugfix für User
• docs - Änderungen an der Dokumentation
• style - Formatierungen im Code
• refactor - Verbesserungen am Code
• test - fehlende Tests hinzufügen, Tests verbessern
• chore - Updates, die nicht Features für User betreffen

Branching

Neue Features oder Verbesserungen können nur über Merge Requests im Design System eingebracht werden. Daher muss vom aktuellen "develop" Branch ein neuer Branch erstellt werden. Je nach Typ wird dieser Branch in diesem Ordner erstellt.

Beispiel

typ/ticket_beschreibung

feat/DESY-123_neues-feature

Commit Messages

typ(projekt/komponente): beschreibung des commits

feat(components/button): add new variant

Development Standards

Technologien

Die Komponenten des Design Systems werden mit TypeScript, StencilJS und Tailwind CSS in Form von Web Components entwickelt. Dadurch können sie sowohl in React, Angular, Vue als auch direkt als Web Components verwendet werden. Darüber hinaus wird für die Entwicklung, visuelle Testung und zur Dokumentation der Komponenten Storybook verwendet.

Style Guide

Als Style Guide wird der Stencil Style Guide herangezogen. Die wichtigsten Punkte werden hier im Folgenden kurz erklärt:

Ordner Struktur

Für jede Komponente gibt es einen eigenen Ordner. In diesem befinden sich neben der Implementierung der Komponente selbst auch Styles und Tests. Das readme File wird während des Builds der Komponenten automatisch generiert und beinhaltet die notwendige Dokumentation für Storybook.

Beispiel einer Button Komponente:

1components
2├── s-button
3│   ├── s-button.pcss
4│   ├── s-button.tsx
5│   ├── s-button.spec.tsx
6|   ├── s-button.stories.js
7│   └── readme.md

Naming

Web-Komponenten benötigen einen einzigartigen HTML Tag, damit es nicht zu Konflikten kommen kann. Alle Komponenten des Schrack Seconet Design Systems haben daher das Präfix "s-".

Beispiel:

• <s-pill>

Beispiel mit Modifier:

• <s-pill-interactive>

Auch der Name der TS Class sollte denselben Namen wie die Komponente tragen:

1@Component({
2  tag: 's-pill',
3  styleUrl: 's-pill.pcss',
4  shadow: true,
5})
6export class SPill {

Dokumentation

Die Dokumentation der Komponenten erfolgt in Storybook. Dort kann der Funktionsumfang der Komponenten getestet werden und die Attribute jeder Komponente sind genau beschrieben.

Die Kommentare der in der Komponente verwendeten Properties, Events, Methoden, etc. werden dabei automatisch in Storybook übernommen. Daher sollten deren Nutzen immer mit Kommentaren erklärt werden.

1  /**
2   * Sets light/dark mode. Overrides global state.
3   */
4  @Prop({ reflect: true }) public colorMode?: 'light' | 'dark';
5
6  /**
7   * Sets the variant. Default is 'primary'.
8   */
9  @Prop({ reflect: true }) public variant: 'primary' | 'secondary' | 'info' | 'error' | 'warning' | 'success' =
10    'primary';
11

Styling

Für das Styling der Komponenten wird Tailwind CSS in Kombination mit CSS Modules verwendet. Dadurch können die Tailwind Klassen in eigenen Klassen gruppiert und auf die jeweiligen Elemente angewendet werden.

1:host,
2* {
3  @apply font-Roboto;
4}
5
6.pill {
7  @apply relative;
8  @apply inline-block;
9  @apply border border-transparent;
10
11  @apply rounded-[34px];
12
13  @apply text-label-02 tracking-1 font-medium;
14  @apply text-center;
15}
16
17/* VARIANTS */
18.pill--variant-primary {
19  @apply text-light-heading dark:text-dark-heading;
20  @apply bg-light-component dark:bg-dark-component;
21  @apply border-light-interaction dark:border-dark-interaction;
22}

Light/Dark Mode

Alle Komponenten sind sowohl im Light-, als auch im Dark-Mode verfügbar. Mit Tailwind kann das Styling für den Dark-Mode mit der dark:tailwind-class Variante angewendet werden, wie auch im CSS Beispiel oben zu sehen.

Will man den Colour-Mode der Komponenten später wechseln, muss nur die Klasse dark auf den HTML Tag der jeweiligen Seite gesetzt werden. Bzw. kann man den Colour-Mode jeder Komponente auch manuell mit der colorMode Property überschreiben.

Da die Komponenten Shadow DOM verwendet werden, muss hier immer beachtet werden, die Komponenten in ein Div-Element oder ein Span-Element zu wrappen und auf dieses den aktuellen Colour-Mode anzuwenden. Dieser ist im globalen State der Komponenten verfügbar. Passiert das nicht, können die Komponenten nicht automatisch zwischen Light- und Dark-Mode wechseln. Außerdem benötigt jede Component die colorMode Property, um den globalen Colour-Mode bei Bedarf überschreiben zu können.

1import state from '../../store';
2
3@Component({
4  tag: 's-pill',
5  styleUrl: 's-pill.pcss',
6  shadow: true,
7})
8export class SPill {
9  /**
10   * Sets light/dark mode. Overrides global state.
11   */
12  @Prop({ reflect: true }) public colorMode?: 'light' | 'dark';
13
14
15render() {
16    return (
17      // Div which wraps the actual component to apply the global color mode or the set color mode from the colorMode prop.
18      <div class={this.colorMode ? this.colorMode : state.colorMode}>
19        <div class={pillClasses}>
20          <slot />
21        </div>
22      </div>
23    );
24  }
25}
26}

Testing

Die Komponenten des Design Systems werden Test Driven (TDD) entwickelt, dadurch kann eine kontinuierliche Funktionalität der Komponenten auch bei späteren Änderungen und Anpassungen leichter sichergestellt werden.

Für jede Komponente wird bei der Entwicklung ein zusätzliches s-component-name.spec.tsx File erstellt in dem die Unit Tests für diese Komponente geschrieben werden.

Stencil stellt dazu einen out of the box Testing Support mit Jest als Testing Library zur Verfügung. Genauere Details zu Unit Tests mit Stencil können in der Stencil Dokumentation nachgelesen werden.

Die Tests können mit npm run test components ausgeführt werden, bzw. kann mit npm run test components -- --watch der Watch-Mode gestartet werden.