Ga naar inhoud

👨🏻‍💻 Start als developer

Om goed gebruik te kunnen maken van het NDW design system, zijn er een aantal richtlijnen opgesteld. Deze richtlijnen zijn bedoeld om de kwaliteit van de applicaties te waarborgen en de samenwerking tussen verschillende teams te bevorderen.

Let op, je applicatie moet op de nieuwste versie van Angular (18.0.1) draaien om componenten te kunnen gebruiken. Het design system is hierbij leidend, zodat alle applicaties consistent en up-to-date zijn.

We maken gebruik van Google API om fonts in te laden. Verderop in deze documentatie staat waarom we dit dynamisch inladen en hoe we hier binnen applicaties mee om gaan.

Download de laatste NPM package

Aan de slag

Introductie

Welkom bij de Storybook van het NDW design system! Dit design system bevat basaal het volgende:

  • components: herbruikbare Angular componenten
  • core: CSS en SCSS thema's met variabelen, kleuren en typografie.

Installatie

Package installeren

Installeer het NDW design system in je project:

npm install -d @ndwnu/design-system

De laatste versie van de package wordt automatisch geïnstalleerd.

Op zoek naar een specifieke versie? Bekijk NPM voor alle versies.

Styles importeren

Om het NDW thema te gebruiken, importeer je de NDW styles in je angular.json:

{
  "projects": {
    "[projectnaam]": {
      "architect": {
        "build": {
          "options": {
            "styles": [
              "node_modules/@ndwnu/design-system/core/styles/ndw-styles.scss",
              [...]
            ]
          }
        }
      }
    }
  }
}

Wanneer je gebruik maakt van NWB+ componenten, importeer je de NWB+ styles in je angular.json:

"styles": [
  "node_modules/@ndwnu/design-system/core/styles/nwb-styles.scss",
  [...]
]

Gebruik

Icons toevoegen aan je applicatie

Vrijwel alle componenten maken gebruik van icons. Het is dus goed om als eerste stap de icons te importeren in je applicatie. Voeg de icons toe in de app.component.ts:

import { IconService } from '@ndwnu/design-system';
import icons from '@ndwnu/design-system/assets/icons/icons.json';

ngOnInit() {
  this.iconService.setIcons(icons);
}

Indien nodig, is het is ook mogelijk om je eigen icons toe te voegen. Hiervoor maak je een custom json bestand die je vervolgens toevoegt aan de service, als volgt:

// your/custom/path/icons.json
[
  {
    "name": "icon-name",
    "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" [...] fill=\"currentColor\" /></svg>"
  }
]

// app.component.ts
import { IconService } from '@ndwnu/design-system';
import icons from '@ndwnu/design-system/assets/icons/icons.json';
import customIcons from 'your/custom/path/icons.json';

ngOnInit() {
  this.iconService.setIcons([...icons, ...customIcons]);
}

Je eerste component importeren

Importeer het NDW component dat je wilt gebruiken in je Angular app en gebruik het component in je template:

import { Component } from '@angular/core';
import { FormFieldComponent, InputDirective } from '@ndwnu/design-system';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [FormFieldComponent, InputDirective],
  template: `
    <ndw-form-field
      info="Een korte hulpbeschrijving"
      label="Label"
      tooltip="Tooltip"
      style="max-width: 20rem;"
    >
      <input
        ndwInput
        placeholder="Placeholder"
        type="text"
        [required]="undefined"
      />
    </ndw-form-field>
  `,
})
export class AppComponent {}

Ben je niet zeker hoe je het beste een component kunt gebruiken? Bekijk de individuele componenten in Storybook voor meer informatie over het gebruik. Per component kun je ook de code bekijken en kopiëren.

Inladen van fonts via Google API

We maken nu gebruik van een regulier font en een icon font, wat het voordeel heeft dat we niet meer overal handmatig lettertypes en icons hoeven te definieren met een service.

We halen deze nu op via de API van Google om de volgende redenen;

  • Up-to-date blijven met de nieuwste icons en icon changes
  • We hebben toegang tot de volledige icon set, waardoor we niet constant de icon set hoeven uit te breiden wanneer er een wens is voor een nieuwe icon (alle icons aan het project toevoegen is onnodig veel data)
  • Geen issues met relative paths binnen de library, wat hiervoor een probleem was wanneer we een build maakten
  • Het onnodig inladen van extra data in een applicatie; niet elk project heeft elke icon nodig, zelfs vaak maar een klein scala

Toevoegingen aan de Content Security Policy (CSP)

Vanuit Google Fonts moeten er een aantal onderdelen aan de Content Security Policy (CSP) headers toegevoegd worden. Dit zijn: 

font-src https://fonts.gstatic.com; 
style-src https://fonts.googleapis.com;
Aangezien wij de angular service worker gebruiken moet https://fonts.googleapis.com ook bij de connect-src in de content security policy opgenomen worden. Het verversen van de CSP in de angular service worker gaat niet automatisch. Dit hebben wij getriggerd door de Service Worker te hernoemen waardoor hij opnieuw geregistreerd wordt.

Toegankelijkheid

We hebben de toegankelijkheid van de componenten getest met de volgende tools:

Storybook Accessibility

Per component kan bekeken worden of de toegankelijkheid voldoet aan de richtlijnen. Dit kan door de Storybook Accessibility tool te gebruiken, welke te vinden is in de Storybook toolbar.

Versies

Versie van de NDW design system package

Alle componenten in de package worden gezamenlijk gereleased onder het zelfde versienummer. Dit betekent dat wanneer er een nieuwe component wordt toegevoegd, of een bestaande component wordt aangepast, de versie van de package wordt verhoogd. Het wordt dan ook aangeraden om de laatste versie van de NDW design system package te gebruiken.

Versie van Angular en overige dependencies

Het NDW design system maakt gebruik van de laatste, stabiele versie van Angular. De versies vind je in de package.json onder de peer dependencies van de NDW design system library. Zorg ervoor dat deze dependencies ook in je project aanwezig zijn, zodat je volledig gebruik kunt maken van alle functionaliteiten.